发布时间：2026 年 5 月 12 日
登录的即时界面模式是一种旨在简化登录流程的 Web 功能。借助此功能，当用户需要登录时（例如点击登录或结账按钮），您可以主动直接向用户提供通行密钥和受管理的密码。
摘要
如果本地没有可用的凭据，立即界面模式会提供一种快速失败的模式。此行为与 Android 和 iOS 等移动平台上的 preferImmediatelyAvailableCredentials API 类似。如果存在凭据，浏览器会立即向用户显示登录对话框。否则，它会以静默方式拒绝 Promise，让您提供替代登录方法（例如登录表单），而不会中断用户体验。
截至 2026 年 5 月，Chrome 是唯一支持立即模式界面的浏览器。
查看前提条件
如需使用即时界面模式，用户必须已在设备本地拥有符合条件的凭据。在 Chrome 中，这些凭据包括：
- 保存在通行密钥提供程序（例如 Google 密码管理工具、Windows Hello 或 iCloud 钥匙串）中的通行密钥。
- 保存在 Google 密码管理工具中的密码。
如果不存在本地凭据，API 会拒绝请求，而不会显示即时登录对话框。
检测功能支持
在调用立即模式界面之前，请使用 PublicKeyCredential.getClientCapabilities() 方法验证浏览器是否支持 immediateGet 功能。如果不支持，则回退到现有的登录方法，例如电子邮件和密码表单、电话号码验证或社交登录。
async function checkImmediateAvailability() {
try {
const capabilities = await PublicKeyCredential.getClientCapabilities();
if (capabilities.immediateGet) {
console.log("Immediate UI mode is supported.");
} else {
console.log("Immediate UI mode is NOT supported.");
}
} catch (error) {
console.error("Error checking client capabilities:", error);
}
}
如需获得更广泛的浏览器支持，请使用 WebAuthn Polyfills GitHub 代码库中提供的填充区。
请求凭据
如需触发即时登录流程，请调用 navigator.credentials.get() 并将 uiMode 字段设置为 'immediate'。
通过在请求中添加 password: true，如果浏览器支持密码凭据，用户就可以享受这种体验。
// This call must follow a user gesture, like a button click
button.addEventListener('click', async (event) => {
event.preventDefault();
try {
const cred = await navigator.credentials.get({
password: true,
publicKey: {
challenge: serverGeneratedChallenge,
rpId: 'example.com'
},
uiMode: 'immediate',
});
// Handle successful sign-in
} catch (error) {
if (error.name === 'NotAllowedError') {
// Provide a fallback sign-in experience
showFallbackUI();
}
}
});
您必须在 catch 代码块中处理 NotAllowedError，以提供后备登录体验。
处理登录流程
您可以在以下两种主要场景中实现立即界面模式。
使用按钮登录
提供专用登录按钮，带来简洁的体验，不会出现意外提示。
- 用户点击登录按钮。
- 您的网站使用
uiMode: "immediate"调用navigator.credentials.get()。 - 浏览器会检查本地凭据。
- 如果浏览器找到凭据，则会立即显示登录对话框，供用户选择账号。
- 如果浏览器未找到凭据，或者用户关闭了即时登录对话框，则会抛出
NotAllowedError。 - 如果抛出
NotAllowedError，您的网站随后会继续显示其标准登录页面。
结账前请先登录
在用户执行需要进行身份验证才能获益的操作（例如在网上店面开始结账流程）之前，主动提供凭据。
在电子商务中，访客用户通常会在登录现有账号和以访客身份结账之间进行选择。提供即时登录对话框可以简化回头客的结账流程。
- 用户发起操作，例如在购物流程中点击结账按钮。
- 您的网站使用
uiMode: "immediate"调用navigator.credentials.get()。 - 如果存在凭据，用户可以选择一个凭据来完成登录。
- 如果凭据不存在，浏览器会抛出错误，并且不会立即显示登录对话框。用户体验保持不变，您可以将用户引导至现有的结账界面，该界面可能会提供其他登录选项或访客结账表单。
检查隐私和安全措施
浏览器会采取关键措施来保护用户隐私：
- 用户手势要求：您必须通过用户手势（例如点击）来发起 API 调用，以防止静默探测。该调用不会消耗激活。
- 无痕模式限制：无痕会话或私密会话中的请求始终会抛出
NotAllowedError。 - 无许可名单：如果请求包含非空
allowCredentials列表，则会抛出NotAllowedError以防止跨会话跟踪。 - 无法以程序化方式取消：您无法使用
signal参数以程序化方式关闭即时登录对话框。