PublicKeyCredential: getClientCapabilities() 静态方法

基准线 2025

新推出

自 ⁨2025 年 2 月⁩ 起，此功能已在最新设备和浏览器版本中得到支持。此功能可能在旧设备或浏览器中不起作用。

安全上下文： 此功能仅在安全上下文（HTTPS）中可用，且支持此功能的浏览器数量有限。

PublicKeyCredential 接口的 getClientCapabilities() 静态方法返回一个 Promise，该 Promise 解析为一个对象，可用于检查是否支持特定的 WebAuthn 客户端功能和扩展。

依赖方 (RP) 可以使用此信息来适当自定义其登录和注册用户界面和工作流程。

语法

PublicKeyCredential.getClientCapabilities()

返回值

一个 Promise，解析为一个对象，其中属性名称是客户端功能字符串，值是布尔值，表示相应的功能或扩展是否受支持。

WebAuthn 客户端功能字符串为

"conditionalCreate": 客户端能够创建可发现凭据。
"conditionalGet": 客户端能够使用可发现凭据进行身份验证。此功能等同于 isConditionalMediationAvailable() 解析为 true。
"hybridTransport": 客户端支持使用混合传输。这意味着客户端可以使用依赖于蓝牙、NFC 或 USB 的身份验证器。
"passkeyPlatformAuthenticator": 客户端允许使用支持多因素身份验证机制（如 PIN 或生物识别检查）的 passkey 身份验证器。身份验证器可以与客户端位于同一平台（设备）上，或通过蓝牙或 USB 等混合传输进行连接。凭据存储在身份验证器上。请参阅面向依赖方的 Passkeys 开发者指南。
userVerifyingPlatformAuthenticator: 客户端拥有一个支持多因素身份验证机制（如 PIN 或生物识别检查）的平台身份验证器（与同一设备上的客户端相同）。凭据可以存储在 RP 或身份验证器上。
relatedOrigins: 客户端支持相关源请求。这些客户端允许将 passkey 用于具有相同源的多个站点。
signalAllAcceptedCredentials: 客户端支持 PublicKeyCredential.signalAllAcceptedCredentials() 静态方法。如果不支持，RP 工作流程将需要提示用户手动删除身份验证器上的凭据。
signalCurrentUserDetails: 客户端支持 PublicKeyCredential.signalCurrentUserDetails() 静态方法。如果不支持，RP 工作流程将需要提示用户手动更新身份验证器上的用户详细信息。
signalUnknownCredential: 客户端支持 PublicKeyCredential.signalUnknownCredential() 静态方法。如果不支持，RP 工作流程将需要提示用户手动从身份验证器中删除凭据。

WebAuthn 扩展字符串的格式是在扩展标识符前面加上前缀 extension:。例如，键 extension:appid 可用于检查 appid 扩展是否受支持。

异常

返回的 Promise 可能会因以下值而被拒绝

SecurityError DOMException: RP 域无效。

描述

getClientCapabilities() 允许您检查给定功能或扩展是否受支持，并利用这些信息提供适当的用户体验。

例如，对 userVerifyingPlatformAuthenticator 功能的支持表明允许使用生物识别（如指纹传感器）。Web 应用程序可以利用此功能在支持该功能时显示指纹图标，或者在不支持时显示密码输入框。如果需要生物识别登录，则可以改为提供通知，表明该站点无法使用此浏览器或设备进行身份验证。同样，conditionalGet 表明客户端支持用户登录时的条件中介，这意味着浏览器可以在登录表单中提供自动填充的可发现凭据（例如，自动完成文本字段或下拉列表），以及一个登录按钮。

如果给定功能的值存在于返回的对象中，则 true 表示该功能当前受支持，false 表示不受支持。但是，如果某个功能缺少相应的键，则无法假定相关功能的可用性。

对于扩展，假设相同。但请注意，即使客户端支持该扩展，特定的身份验证器也可能不支持该扩展，因此 RP 不能假设这保证了将执行该扩展的身份验证器处理步骤。如果某个扩展缺少相应的键，RP 不能假设此客户端将执行该扩展的客户端处理步骤，也不能假设该扩展将转发给身份验证器。

示例

检查所有功能

此示例演示了如何获取功能对象并遍历其值。

<pre id="log"></pre>

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

#log {
  height: 230px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

JavaScript

首先，我们等待 getClientCapabilities() 返回一个包含功能的doctoral-level。然后我们遍历对象并记录结果（未显示日志记录代码）

async function checkClientCapabilities() {
  const capabilities = await PublicKeyCredential.getClientCapabilities();

  if (capabilities) {
    log("Client Capabilities:");

    for (const [key, value] of Object.entries(capabilities)) {
      log(` ${key}: ${value}`);
    }
  }
}

在调用函数之前，我们检查它是否已定义，并记录结果。

// Call the function to check capabilities.
if (PublicKeyCredential.getClientCapabilities) {
  checkClientCapabilities();
} else {
  log(
    "PublicKeyCredential.getClientCapabilities() is not supported on this browser.",
  );
}

结果

测试平台用户验证身份验证器

此示例检查单个功能 userVerifyingPlatformAuthenticator。实际应用程序可能会使用结果来配置用户界面。

<pre id="log"></pre>

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

#log {
  height: 40px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

JavaScript

代码与前面的示例类似，除了我们检查返回的特定功能，并且我们使用 try...catch 来捕获 getClientCapabilities() 不受支持的情况。

checkIsUserVerifyingPlatformAuthenticatorAvailable();

async function checkIsUserVerifyingPlatformAuthenticatorAvailable() {
  try {
    const capabilities = await PublicKeyCredential.getClientCapabilities();

    if (capabilities.userVerifyingPlatformAuthenticator) {
      log("Biometric login supported");
    } else {
      log("Biometric login not supported. Do password.");
    }
  } catch (error) {
    if (error instanceof TypeError) {
      log(
        "PublicKeyCredential.getClientCapabilities() is not supported on this browser.",
      );
    } else {
      log(`Unexpected error: ${error}`);
    }
  }
}

请注意，此处我们记录了检查的结果。在实际应用程序中，我们可能会更新用户界面以显示用于验证用户的适当选项。

结果

下面的日志显示了一个指示该方法不受支持的字符串，或者一个指示是否支持生物识别或密码登录的字符串。

规范

规范
Web Authentication：访问公钥凭证的 API - 第 3 级 # sctn-getClientCapabilities

浏览器兼容性

另见

Web Authentication API

帮助改进 MDN

了解如何贡献

此页面最后修改时间为 ⁨2025 年 10 月 9 日⁩，由 MDN 贡献者。

在 GitHub 上查看此页面 • 报告此内容的问题