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 上檢視此頁面 • 報告此內容的問題