登录按钮是新用户最先接触的元素，因此它必须契合您的设计、支持键盘操作、在阿拉伯语中正确显示，并且在服务器端渲染时不闪烁。@posty5/oauth-angular 为 Angular 应用提供了一个满足以上所有要求的现成“通过 Posty5 继续”按钮，以及其背后的完整登录流程。

本教程将带您从安装一直做到一个可用且已设置样式的按钮。前提是您已按照为您的网站或应用添加“使用 Posty5 登录”中的说明注册了 OAuth 应用；本文也是API 密钥与 SDK 指南所介绍的开发者平台的一部分。

首先选择模式

• startUrl——您的后端已经在运行登录流程，例如使用 @posty5/oauth。按钮只负责打开您的起始地址。这是推荐的模式，Trend Digest 使用的也是这种模式。
• codeHandler——软件包在浏览器中启动 PKCE，并将授权码发送到您的后端，由后端使用客户端密钥完成交换。
• browser——无需后端。软件包以公共客户端身份交换授权码，并使用 WebCrypto 验证 ID 令牌。OAuth 应用必须允许来自您网站源的浏览器登录。

无论哪种模式，客户端密钥都绝不会到达浏览器。

逐步添加按钮

1. 使用 npm install @posty5/oauth-angular 安装软件包。它支持 Angular 17.3 到 20。
2. 在应用配置中调用 providePosty5Auth，并传入您选择的模式。
3. 在使用按钮的地方导入 Posty5SignInButtonComponent，并将 posty5SignInButton 属性加在真正的 button 元素上，这样表单、焦点和键盘都能照常工作。
4. 对于 codeHandler 和 browser 模式，将重定向 URI 路由到一个懒加载页面，在该页面中放置 posty5Callback 组件，并在其 signedIn 和 failed 事件触发时进行导航。
5. 自己先登录一次，确认登录后会回到您开始时所在的页面。

// app.config.ts
import { providePosty5Auth } from "@posty5/oauth-angular";

export const appConfig = {
  providers: [
    providePosty5Auth({
      mode: "startUrl",
      startUrl: "/api/auth/posty5/start",
    }),
  ],
};

<button posty5SignInButton theme="outline" shape="pill" [width]="320" returnUrl="/dashboard"></button>

让按钮契合您的设计

• theme——filled（Posty5 蓝色）、outline（白色），或用于深色页面的 filledDark。
• size——large、medium 或 small；shape——rectangular、pill、circle 或 square（仅显示徽标）。
• text——“通过 Posty5 继续”“使用 Posty5 登录”“使用 Posty5 注册”或“登录”；label 可完全替换按钮文字。
• 每个按钮可单独设置 logoAlignment、width 和 locale；如果想完全自己设计样式，可使用 unstyled。

.login-card .posty5-btn {
  --posty5-btn-radius: 9999px;
  --posty5-btn-font-family: "Cairo", sans-serif;
  --posty5-btn-hover-bg: #1a6bff;
}

内置样式的优先级（specificity）为零，因此您的任何规则都能生效，无需 !important；所有颜色和尺寸都是 CSS 自定义属性。阿拉伯语按钮会自动采用从右到左的布局，而 Posty5 始终以拉丁字母书写。

按姓名问候回访用户

登录之后，按钮可以显示用户的头像、带有用户姓名的“以某某身份继续”字样以及部分隐藏的电子邮箱，就像其他登录服务提供商的个性化按钮一样。在 browser 模式下，这一切会自动完成；在其他模式下，请使用后端返回的数据调用 rememberUser，并在退出登录时调用 forgetUser。

被记住的用户信息只包含姓名、一个 HTTPS 头像地址和部分隐藏的电子邮箱，不包含任何令牌。个性化按钮只会在激活（hydration）之后出现，因此服务器渲染的 HTML 永远不会出现不一致。

注意事项

• 该软件包可安全用于服务器端渲染：在服务器上，按钮显示通用文字，登录流程绝不会在服务器上运行。
• 它通过 fetch 调用 Posty5，因此您的 HTTP 拦截器绝不会把您自己的 Authorization 请求头添加到 Posty5 的端点上。
• 进行中的登录保存在单个标签页的会话存储（session storage）中，并在 10 分钟后过期。
• 在 browser 模式下，请将令牌保存在内存中。对于长时间会话，建议使用 startUrl 或 codeHandler，并配合 HttpOnly Cookie。

常见问题