Español – América Latina Português – Brasil Google Identity 此参考页面介绍了 Google 登录 JavaScript API，该 API 用于在网页上显示“使用 Google 账号登录”按钮或“一键快捷功能”提示。 方法：google.accounts.id.initialize google.accounts.id.initialize 方法会根据配置对象初始化使用 Google 账号登录客户端。请参阅以下方法代码示例： 以下代码示例使用 onload 函数实现了 google.accounts.id.initialize 方法： google.accounts.id.initialize 方法会创建一个“使用 Google 账号登录”客户端实例，同一网页中的所有模块都可以隐式使用该实例。 即使您在同一网页中使用多个模块（例如一键快捷功能、个性化按钮、撤消等），也只需调用一次 google.accounts.id.initialize 方法。 如果您多次调用 google.accounts.id.initialize 方法，系统只会记住并使用最后一次调用中的配置。 实际上，每当您调用 google.accounts.id.initialize 方法时，系统都会重置配置，并且同一网页中的所有后续方法都会立即使用新配置。 数据类型：IdConfiguration 下表列出了 IdConfiguration 数据类型的字段和说明： 此字段是应用的客户端 ID，可在 Google Cloud 控制台中找到并创建。如需了解详情，请参阅下表： 此字段是应用于“一键快捷功能”提示的配色方案。如需了解详情，请参阅下表： 下表列出了可用的配色方案及其说明。 此字段用于确定在只有 1 个 Google 会话之前批准过您的应用时，是否自动返回 ID 令牌而无需任何用户互动。默认值为 false 。如需了解详情，请参阅下表： 此字段是用于处理从一键快捷功能提示或弹出式窗口返回的 ID 令牌的 JavaScript 函数。如果使用 Google 一键快捷功能或“使用 Google 账号登录”按钮 popup 界面模式，则必须添加此属性。如需了解详情，请参阅下表： 该值必须与 OAuth 2.0 客户端的某个已获授权的重定向 URI 完全一致，您需要在 Google Cloud 控制台中 配置 该 URI，并且该 URI 必须符合我们的 重定向 URI 验证规则 。 如果当前页面是您的登录页面，则可以省略此属性，在这种情况下，凭据默认会发布到此页面。 当用户点击“使用 Google 账号登录”按钮并使用重定向用户体验模式时，系统会将 ID 令牌凭据响应发布到您的登录端点。 您的 登录端点 必须处理包含 credential 参数（正文中包含 ID 令牌值）的 POST 请求。 native_callback 此字段是 JavaScript 函数的名称，该函数用于处理从浏览器的内置凭据管理器返回的密码凭据。如需了解详情，请参阅下表： cancel_on_tap_outside 此字段用于设置在用户点击提示框外部时是否取消一键快捷功能请求。默认值为 true 。您可以将该值设置为 false 以停用该功能。如需了解详情，请参阅下表： prompt_parent_id 此属性用于设置容器元素的 DOM ID。如果未设置，系统会在窗口右上角显示“一键快捷功能”提示。如需了解详情，请参阅下表： 此字段是 ID 令牌使用的一个随机字符串，用于防止重放攻击。 如需了解详情，请参阅下表： 随机数长度受环境支持的最大 JWT 大小以及各个浏览器和服务器 HTTP 大小限制的约束。 essential_claims 此字段是一个字符串，用于请求在 Google 返回的 ID 令牌中包含其他声明。如需查看 Google 接受的声明的完整列表，请参阅 支持的声明 。 此字段会更改单次点按提示中显示的标题和消息的文本，但对 ITP 浏览器没有影响。默认为 signin 。 下表列出了 所有 可用的上下文及其说明： state_cookie_domain 如果您需要在父网域及其子网域中显示一键快捷功能，请将父网域传递给此字段，以便使用单个共享状态 Cookie。如需了解详情，请参阅下表： 使用此字段设置“使用 Google 账号登录”按钮所用的用户体验流程。默认值为 popup 。此属性对 OneTap 用户体验没有任何影响。如需了解详情，请参阅下表： 下表列出了可用的用户体验模式及其说明。 allowed_parent_origin 允许嵌入中间 iframe 的来源。如果存在此字段，则“一键快捷功能”会在中间 iframe 模式下运行。如需了解详情，请参阅下表： 下表列出了支持的值类型及其说明。 系统还支持使用通配符前缀。例如， "https://*.example.com" 会匹配 example.com 及其所有级别的子网域（例如 news.example.com 、 login.news.example.com ）。使用通配符时，请注意以下事项： 模式字符串不能仅由通配符和顶级网域组成。例如， https:// .com 和 https:// .co.uk 无效，因为 "https:// .example.com" 与 example.com 及其所有子网域匹配。使用以逗号分隔的列表来表示两个不同的网域。例如， "https://example1.com,https:// .example2.com" 与网域 example1.com 、 example2.com 以及 example2.com 的子网域匹配 通配符网域必须以安全的 https:// 方案开头，因此 "*.example.com" 被视为无效。 如果 allowed_parent_origin 字段的值无效，则中间 iframe 模式的“一键快捷功能”初始化会失败并停止。 intermediate_iframe_close_callback 当用户通过点按“一键快捷功能”界面中的“X”按钮手动关闭“一键快捷功能”时，此方法会替换默认的中间 iframe 行为。默认行为是立即从 DOM 中移除中间 iframe。 intermediate_iframe_close_callback 字段仅在中间 iframe 模式下生效。并且仅对中间 iframe（而非一键快捷功能 iframe）产生影响。在调用回调之前，系统会移除“一键快捷功能”界面。 此字段用于确定是否应在支持智能跟踪防范 (ITP) 的浏览器上启用 升级版一键快捷功能用户体验 。默认值为 false 。如需了解详情，请参阅下表： 如果您的应用预先知道应该登录哪个用户，则可以向 Google 提供登录提示。如果成功，则跳过账号选择。 可接受的值包括：电子邮件地址或 ID 令牌 sub 字段值。 如需了解详情，请参阅 OpenID Connect 文档中的 login_hint 字段。 当用户有多个账号，但只能使用其 Workspace 账号登录时，请使用此属性向 Google 提供域名提示。成功后，账号选择期间显示的用户账号将仅限于所提供的网域。 通配符值： * 在账号选择期间仅向用户提供 Workspace 账号，并排除个人用户账号 (user@gmail.com)。 如需了解详情，请参阅 OpenID Connect 文档中的 hd 字段。 use_fedcm_for_prompt 允许浏览器控制用户登录提示，并在您的网站与 Google 之间协调登录流程。默认值为 false。如需了解详情，请参阅 迁移到 FedCM 页面。 use_fedcm_for_button 此字段用于确定是否应在 Chrome（桌面版 M125 及更高版本和 Android 版 M128 及更高版本）上使用 FedCM 按钮用户体验。默认值为 false 。如需了解详情，请参阅下表： button_auto_select 此字段用于确定是否为 FedCM 按钮流程启用 自动选择 选项。如果启用此功能，系统会自动登录具有有效 Google 会话的回访用户，从而绕过账号选择器提示。默认为 false 。您需要在选择启用时明确启用按钮自动登录功能。如需了解详情，请参阅下表： 方法：google.accounts.id.prompt 在调用 initialize() 方法后， google.accounts.id.prompt 方法会显示“一键快捷功能”提示或浏览器内置的凭据管理器。请参阅以下方法代码示例： 通常，系统会在网页加载时调用 prompt() 方法。由于 Google 端的会话状态和用户设置，可能不会显示一键快捷功能提示界面。如需在不同时刻收到界面状态通知，请传递一个函数来接收界面状态通知。 展示时刻 ：在调用 prompt() 方法后发生。通知包含一个布尔值，用于指示界面是否显示。 跳过的时刻 ：当用户因自动取消、手动取消或 Google 无法发放凭据（例如，当所选会话已退出 Google 账号时）而关闭一键登录提示时，就会出现这种情况。 在这种情况下，我们建议您继续使用下一个身份提供方（如果有）。 跳过的时刻 ：当用户因自动取消、手动取消或 Google 无法发放凭据（例如，当所选会话已退出 Google 账号时）而关闭一键登录提示时，就会出现这种情况。 在这种情况下，我们建议您继续使用下一个身份提供方（如果有）。 关闭时刻 ：当 Google 成功检索到凭据或用户想要停止凭据检索流程时，系统会触发此事件。例如，当用户开始在登录对话框中输入用户名和密码时，您可以调用 google.accounts.id.cancel() 方法来关闭一键快捷功能提示并触发关闭时刻。 关闭时刻 ：当 Google 成功检索到凭据或用户想要停止凭据检索流程时，系统会触发此事件。例如，当用户开始在登录对话框中输入用户名和密码时，您可以调用 google.accounts.id.cancel() 方法来关闭一键快捷功能提示并触发关闭时刻。 以下代码示例实现了跳过的时刻： 数据类型：PromptMomentNotification 下表列出了 PromptMomentNotification 数据类型的方法和说明： 界面未显示的详细原因。可能的值如下： browser_not_supported missing_client_id opt_out_or_no_session secure_http_required

suppressed_by_user unregistered_origin 跳过时刻的详细原因。可能的值如下： 解雇的详细原因。可能的值如下： credential_returned 返回时刻类型的字符串。可能的值如下： 数据类型：CredentialResponse 当您的 callback 函数被调用时，系统会传递一个 CredentialResponse 对象作为参数。下表列出了凭据响应对象中包含的字段： 此字段是采用 base64 编码的 JSON Web 令牌 (JWT) 字符串形式的 ID 令牌。 解码 后，JWT 如下例所示： sub 字段是 Google 账号的全局唯一标识符。 仅 使用 sub 字段作为用户的标识符，因为该字段在所有 Google 账号中都是唯一的，并且永远不会重复使用。 通过使用 email 、 email_verified 和 hd 字段，您可以确定 Google 是否托管某个电子邮件地址并对其具有权威性。如果 Google 是权威机构，则可确认用户是合法账号所有者。 Google 具有权威性的情况： email 带有 @gmail.com 后缀，则为 Gmail 账号。 email_verified 为 true 且设置了 hd ，则表示这是 Google Workspace 账号。 用户可以注册 Google 账号，而无需使用 Gmail 或 Google Workspace。 如果 email 不包含 @gmail.com 后缀且缺少 hd ，则 Google 不具有权威性，建议使用密码或其他质询方法来验证用户。 email_verfied 也可能为 true，因为 Google 最初在创建 Google 账号时验证了用户，但第三方电子邮件账号的所有权可能已发生变化。 exp 字段显示了您在 服务器端验证令牌 的过期时间。对于通过“使用 Google 账号登录”获取的 ID 令牌，有效期为 1 小时。您需要在令牌过期之前 验证令牌 。 请勿使用 exp 进行会话管理 。ID 令牌过期 并不 意味着用户已退出账号。您的应用负责用户的会话管理。 下表列出了 select_by 字段的可能值。所用按钮的类型以及会话和同意情况用于设置值， 用户按下了“一键快捷功能”或“使用 Google 账号登录”按钮，或者使用了无接触的自动登录流程。 用户按下了“一键快捷功能”或“使用 Google 账号登录”按钮，或者使用了无接触的自动登录流程。 系统找到了现有会话，或者用户选择并登录了 Google 账号以建立新会话。 系统找到了现有会话，或者用户选择并登录了 Google 账号以建立新会话。 在与您的应用分享 ID 令牌凭据之前，用户需要 按下了“确认”按钮，同意分享凭据，或者 之前已授予同意声明，并使用“选择账号”选择了一个 Google 账号。 在与您的应用分享 ID 令牌凭据之前，用户需要 按下了“确认”按钮，同意分享凭据，或者 之前已授予同意声明，并使用“选择账号”选择了一个 Google 账号。 此字段的值设置为以下类型之一， 仅当用户点击“使用 Google 账号登录”按钮进行登录，且点击的按钮指定了 state 属性时，此字段才会被定义。此字段的值与您在按钮的 state 属性中指定的值相同。 由于同一网页上可以呈现多个“使用 Google 账号登录”按钮，因此您可以为每个按钮分配一个唯一的字符串。因此，您可以使用此 state 字段来确定用户点击了哪个按钮进行登录。 方法：google.accounts.id.renderButton google.accounts.id.renderButton 方法会在网页中呈现“使用 Google 账号登录”按钮。 数据类型：GsiButtonConfiguration 下表列出了 GsiButtonConfiguration 数据类型的字段和说明： 以下部分详细介绍了每种属性类型，并提供了一个示例。 按钮类型。默认值为 standard 。 下表列出了可用的按钮类型及其说明： 按钮主题。默认值为 outline 。如需了解详情，请参阅下表： 下表列出了可用的主题及其说明： 按钮大小。默认值为 large 。如需了解详情，请参阅下表： 下表列出了可用的按钮大小及其说明： 按钮文字。默认值为 signin_with 。对于具有不同 text 属性的图标按钮，其文本在视觉上没有区别。 唯一的例外情况是为屏幕无障碍功能读取文本。 下表列出了 所有 可用的按钮文本及其说明： 按钮形状。默认值为 rectangular 。如需了解详情，请参阅下表： 下表列出了可用的按钮形状及其说明： Google 徽标的对齐方式。默认值为 left 。此属性仅适用于 standard 按钮类型。如需了解详情，请参阅下表： 下表列出了可用的对齐方式及其说明： 按钮的最小宽度（以像素为单位）。宽度上限为 400 像素。 可选。使用指定的语言区域显示按钮文字，否则默认使用用户的 Google 账号或浏览器设置。在加载库时，向 src 指令添加 hl 参数和语言代码，例如： gsi/client?hl=<iso-639-code> 。 如果未设置，则使用浏览器的默认语言区域或 Google 会话用户的偏好设置。因此，不同的用户可能会看到不同版本的本地化按钮，并且按钮的大小可能也会有所不同。 您可以使用 click_listener 属性定义在点击“使用 Google 账号登录”按钮时要调用的 JavaScript 函数。 在此示例中，当点击“使用 Google 账号登录”按钮时，系统会将消息 Sign in with Google button clicked… 记录到控制台。 可选，由于可以在同一网页上呈现多个“使用 Google 账号登录”按钮，因此您可以为每个按钮分配一个唯一的字符串。该字符串会与 ID 令牌一起返回，因此您可以确定用户点击了哪个按钮进行登录。 当您的 native_callback 函数被调用时，系统会传递一个 Credential 对象作为参数。下表列出了对象中包含的字段： 方法：google.accounts.id.disableAutoSelect 当用户退出您的网站时，您需要调用方法 google.accounts.id.disableAutoSelect 以在 Cookie 中记录状态。这可防止出现用户体验死循环。请参阅以下方法代码段： 以下代码示例使用 onSignout() 函数实现了 google.accounts.id.disableAutoSelect 方法： 方法：google.accounts.id.storeCredential 此方法是浏览器内置凭据管理器 API 的 store() 方法的封装容器。因此，它只能用于存储密码凭据。请参阅以下方法代码示例： 以下代码示例使用 onSignIn() 函数实现了 google.accounts.id.storeCredential 方法： 方法：google.accounts.id.cancel 如果您从信赖方 DOM 中移除提示，则可以取消“一键快捷功能”流程。如果已选择凭据，则忽略取消操作。请参阅以下方法代码示例： 以下代码示例使用 onNextButtonClicked() 函数实现了 google.accounts.id.cancel() 方法： 库加载回调：onGoogleLibraryLoad 您可以注册 onGoogleLibraryLoad 回调。在加载“使用 Google 账号登录”JavaScript 库后，系统会通知它： 此回调只是 window.onload 回调的快捷方式。行为方面没有任何差异。 以下代码示例实现了 onGoogleLibraryLoad 回调： 方法：google.accounts.id.revoke google.accounts.id.revoke 方法会撤消用于共享指定用户的 ID 令牌的 OAuth 授权。请参阅以下方法代码段： javascript google.accounts.id.revoke(login_hint, callback) 以下代码示例展示了如何使用带有 ID 的 revoke 方法。 数据类型：RevocationResponse 当您的 callback 函数被调用时，系统会传递一个 RevocationResponse 对象作为参数。下表列出了撤消响应对象中包含的字段： 此字段是一个布尔值，如果撤消方法调用成功，则设置为 true；如果失败，则设置为 false。 此字段是一个字符串值，如果撤消方法调用失败，则包含详细的错误消息；如果调用成功，则此字段未定义。 如未另行说明，那么本页面中的内容已根据 知识共享署名 4.0 许可 获得了许可，并且代码示例已根据 Apache 2.0 许可 获得了许可。有关详情，请参阅 Google 开发者网站政策 。Java 是 Oracle 和/或其关联公司的注册商标。 最后更新时间 (UTC)：2026-09-01。