# @dloizides/auth-web 中文文档

规范地址：https://npmcn.com/package/%40dloizides/auth-web/

版本：1\.31\.0
npm 元数据更新时间：2026-11-09T23:19:27.259Z
中文译文更新时间：2026-11-12T12:46:46.781Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dloizides/auth-web
原文对照：https://npmcn.com/package/%40dloizides/auth-web/?lang=original
项目主页：https://github.com/openmindednewby/auth-web#readme
源码仓库：https://github.com/openmindednewby/auth-web

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.2 MB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- peer 依赖：react \>=17\.0\.0，react-native \>=0\.70\.0，@dloizides/ui-buttons \>=1\.9\.0，@tanstack/react-query ^5\.0\.0，@dloizides/auth-client \>=4\.2\.0
- 首次发布：2026-05-23T10:10:23.900Z
- 最新版本发布：2026-11-09T23:19:27.142Z
- 近 30 天下载量：2914（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 41 个）

## 中文简介

可主题,为dloizides.com组合的品牌Auth UI. 原生LoginForm / ForgotPasswordForm / 重置PasswordForm组件,无头钩,同源 BffAuthClient,以及基于角色的后登录路由器. 由@dloizides/auth-client所建

## 安装

```sh
npm install @dloizides/auth-web
```

也可以使用：`pnpm add @dloizides/auth-web`、`yarn add @dloizides/auth-web`、`bun add @dloizides/auth-web`

## README

# @dloizides/自动网络

Dloizides.com 组合的可主题,品牌化的 Auth UI ——前端一半 统一自动计划.

每个应用程序都有一个 **本土、品牌登录经验**: 登录 / 忘记 / 重置表单在应用程序的前端内直播; 用户是 **从未重定向 到 Keycloak 的主机登录 UI**。所有证书交换都发生在服务器侧 a 每个应用程序 **妇女事务局** (单位:千美元)`bff-katalogos`, (中文(简体) ), `bff-erevna`(中文(简体) ). 这个包只讲 发源地 `/bff/*` —— 说 **没有秘密,没有象征性的处理,没有Keycloak的电话 在浏览器中.**

建造在 [`@dloizides/auth-client`](https://www.npmjs.com/package/@dloizides/auth-client), (中文(简体) ), 提供低级 `BffAuthClient`。 。 。 .

## 安装

```bash
npm install @dloizides/auth-web
```

同伴依赖性 : `react`, (中文(简体) ), `react-native` (可选), `@tanstack/react-query`, (中文(简体) ), `@dloizides/auth-client` (单位:千美元)`>=3.0.0`) (中文(简体) ).

## 食用它有两个方法

### 1\. 现成主题组件

```tsx
import {
  AuthThemeProvider,
  LoginForm,
  createBffAuthClient,
  resolvePostLoginRoute,
} from '@dloizides/auth-web';

import { katalogosAuthTheme } from './theme';      // your AuthTheme token bag
import { roleRoutes } from './roleRoutes';          // your RoleRouteTable
import { authLabels } from './authLabels';          // your localised labels

const client = createBffAuthClient();               // same-origin /bff/*

function LoginScreen() {
  const router = useRouter();
  return (
    <AuthThemeProvider theme={katalogosAuthTheme}>
      <LoginForm
        client={client}
        labels={authLabels.login}
        onForgotPassword={() => router.push('/forgot-password')}
        onSuccess={(user) => {
          const route = resolvePostLoginRoute(user, roleRoutes);
          router.replace(route ?? '/no-access');
        }}
      />
    </AuthThemeProvider>
  );
}
```

`<ForgotPasswordForm>` 财务报告和审定财务报表 `<ResetPasswordForm>` 跟着同样的形状.

### 电子邮件-OTP 登录 - `<OtpForm>`

一个本地品牌的"签入代码"表面——用户从未被反弹到 Keycloak主持UI. 这是两步的形式:第一步收集电子邮件并询问 bFF 以电子邮件方式发送一次性代码;步骤2收集代码,验证代码,以及 提供"转发代码" /"使用不同的电子邮件".

```tsx
import { OtpForm, createBffAuthClient, resolvePostLoginRoute } from '@dloizides/auth-web';

const client = createBffAuthClient();

function OtpLoginScreen() {
  const router = useRouter();
  return (
    <OtpForm
      client={client}
      labels={authLabels.otp}
      onSuccess={(user) => {
        const route = resolvePostLoginRoute(user, roleRoutes);
        router.replace(route ?? '/no-access');
      }}
    />
  );
}
```

`<OtpForm>` 同一来源的 POST `/bff/otp/request` 财务报告和审定财务报表 `/bff/otp/verify` 终点( 加入 `Bff.AspNetCore`) (中文(简体) ). 联邦检察官办公室直接对 Keycloak 服务器侧;浏览器只接收 httpOnly 会话 cookie .

### 事件- PIN 登录 - `<PinForm>`

一个本地品牌的PIN平台 (门/DJ/媒体关于克菲). 它是一个单步形式: PIN 字段+ “ sign” 在"按钮。 这个 `eventExternalId` 是一个道具——事件上下文来自 路由/页面,从未由用户输入。 这个 `(event, pin)` 单对标识 ; 用户名/密码从不离开浏览器.

```tsx
import { PinForm, createBffAuthClient, resolvePostLoginRoute } from '@dloizides/auth-web';

const client = createBffAuthClient();

function PinLoginScreen({ eventExternalId }: { eventExternalId: string }) {
  const router = useRouter();
  return (
    <PinForm
      client={client}
      eventExternalId={eventExternalId}
      labels={authLabels.pin}
      onSuccess={(user) => {
        const route = resolvePostLoginRoute(user, roleRoutes);
        router.replace(route ?? '/no-access');
      }}
    />
  );
}
```

`<PinForm>` 同一来源的 POST `/bff/pin/login` 结束点( 加入 `Bff.AspNetCore`) (中文(简体) ). BFF运行事件范围 PIN 直接赠款对抗 Keycloak 服务器侧;浏览器只接收 httpOnly 会话 cookie .

### 2\. 无头钩(海关布局)

```tsx
import { useBffAuth, createBffAuthClient } from '@dloizides/auth-web';

const client = createBffAuthClient();

function CustomLogin() {
  const { login, isSubmitting, error } = useBffAuth({ client, probeOnMount: false });
  // ...render your own form, call login({ username, password })
}
```

对于自定义的检察官办公室版式, `useOtpLogin` 暴露出双步机:

```tsx
import { useOtpLogin, OtpLoginStep, createBffAuthClient } from '@dloizides/auth-web';

const client = createBffAuthClient();

function CustomOtpLogin() {
  const otp = useOtpLogin({ client });
  // step 1: otp.requestCode(email)  → otp.step becomes OtpLoginStep.EnterCode
  // step 2: otp.verifyCode(code)    → resolves to the signed-in BffUser
  //         otp.resend() / otp.reset() for the step-2 affordances
}
```

对于定制的 PIN 版式, `usePinLogin` 暴露单步流:

```tsx
import { usePinLogin, createBffAuthClient } from '@dloizides/auth-web';

const client = createBffAuthClient();

function CustomPinLogin({ eventExternalId }: { eventExternalId: string }) {
  const pin = usePinLogin({ client, eventExternalId });
  // pin.submit(pinValue) → resolves to the signed-in BffUser
  // pin.reset()          → clears the error
}
```

## 他们

该套装没有品牌. 每个应用程序将自己的主题系统映射到平地上 `AuthTheme` 代号袋( r)`colors`, (中文(简体) ), `radii`, (中文(简体) ), `spacing`, (中文(简体) ), `typography`)和用品 它通过 `<AuthThemeProvider>` 或一个 `theme` 单个组件的道具. 优先发言: **说明 上下文 `defaultAuthTheme`**。 。 。 .

```ts
import { defaultAuthTheme, type AuthTheme } from '@dloizides/auth-web';

export const katalogosAuthTheme: AuthTheme = {
  ...defaultAuthTheme,
  colors: { ...defaultAuthTheme.colors, primary: '#c2410c' },
};
```

因为三种形式都有一个 `useAuthStyles` 以符号形式映射, 重装 `<LoginForm>` 自动重取其他主题.

## 公开演示证书 - `<DemoCredentialsHint>`

已公布证书的 OPEN 演示账户产品 (一般在营销网站). 它显示登录时的用户名+密码 因此,非技术评估员从不复制 两个标签之间的密码 .

这个 **填满了田地,没有别的了.** 登录后会穿越普通路径—— 相同的BFF,相同的Keycloak,相同的会话饼干,相同的角色. 没有认证 绕行和不在此套件内提供证书:主机提供配对 演示账号的爆炸半径是IP授权的.

演示对来自BFF(`GET /bff/config` → `config.demo`页:1 客户端 Const——BFF是唯一知道部署是否有 演示已配置, 捆绑的 const 将证书运入每个客户的 自办建筑. `useBffLoginConfig` 已获取此配置, 所以它也 携带 `demo`。 。 。 . `useDemoCredentials` 拥有提示qqform 线程 :

```tsx
import {
  AuthScreen, DemoCredentialsHint, LoginForm,
  useBffLoginConfig, useDemoCredentials,
} from '@dloizides/auth-web';

function LoginScreen() {
  const { config } = useBffLoginConfig(bffAuthClient);
  // Credentials arrive ASYNC — prefillOnMount honours a late arrival (see below).
  const demo = useDemoCredentials({ credentials: config.demo ?? undefined, prefillOnMount: true });

  return (
    <AuthScreen theme={authTheme}>
      <DemoCredentialsHint
        {...demo.hintProps}
        labels={authLabels.demo}
        testIdPrefix="zygos"
        theme={authTheme}
      />
      <LoginForm
        {...demo.loginFormProps}
        chromeless
        client={bffAuthClient}
        labels={authLabels.login}
        theme={authTheme}
        onSuccess={handleSignedIn}
      />
    </AuthScreen>
  );
}
```

`hintProps` 携带 `{ credentials, onUse }`· ; `loginFormProps` 携带 `{ initialUsername, initialPassword, prefillNonce, prefillIntent }`模块集成 演示工作也一样——通过即可 `credentials` 改为 `config.demo`。 。 。 .

> 要求数 `@dloizides/auth-client >= 4.2.0`,该表面 `demo` 打开 `BffLoginConfig` (从电线上划出) `publishedUsername` 编号 : `publishedPassword`) (中文(简体) ). `config.demo` 实值 `DemoCredentials | null`。 。 。 .

### 同步证书 : `prefillOnMount` 恭敬迟到

因为一对在上山后到达一两个, `prefillOnMount` 不能倾斜 打开 `useState`'初始值(仅在第一个渲染时反应读取). 钩子 种子窗体时 `config.demo` 解决一个可用的对-但作为一个 **机会** 种子 : `<LoginForm>` 只在两个字段都还在时才应用 空了,这么晚了 `/bff/config` 响应从不覆盖用户名真实账户 持卡人同时在打字。 窃听 _使用这些证书_ 是一个 **明确** 种子并始终适用。 种子按值入门,所以反应平滑回接 返回等值对象不重播. `useDemoCredentials` 选择 意向通过 `prefillIntent` 道具; 您只触摸 `PrefillIntent` 如果你开车 `<LoginForm>` 没有钩子.

**`prefillOnMount`** (默认) `false`选择行业:

|  | 到达时的战地 | 以演示用户身份签名 | 费用 |
| --- | --- | --- | --- |
| `false` | 空 | 窃听 _使用这些证书_,则 _签名_ | —— 说 |
| `true` | 已填满 | 窃听 _签名_ | 真实账户持有人必须先清除两个字段 |

使用 `true` 只有真正公开的演示表面。 无论是哪种方式, 这样一来就看得到 _为什么_ 田地是人口密集的.

### 无法关闭

没有证书——或半配置对(空白用户名、空白密码或 字段为 `undefined` 在运行时间,因为一个env var从未设置)——使 **没什么**\- 零DOM。 - 零DOM。 配置错误的演示文稿永远不能发布空的 全权证书委员会. `resolveDemoCredentials` 如果需要,则导出 在别处作出决定.

### 预填是种子 不是绳子

`initialUsername` 编号 : `initialPassword` 选择字段“ _开始_ 价值和 然后让开:每个字段都保持可编辑和可清除,所以是真实的 账户持有者总是可以擦去演示值,并用自己的签名. 这个 为什么 `prefillNonce` 已存在——反应忽略 `useState` 关于 重新投降,如此改变 `initial*` 单枪匹马一无所获,一无所获 窗体"没有非正弦的按钮会让窗体固执地空出. `useDemoCredentials` 为您管理它;除非您不是,否则您自己驱动它 用钩.

## 国际化

`@dloizides/auth-web` 船舶 **没有** i18n框架. 每一个用户化字符串是 通过类型提供 `labels` 道具 (英语). Apps 传送已本地化的字符串 他们自己的 `FM()` 编号 : `t()`。每个标签袋是部分的——未指明的密钥 回到英语 `DEFAULT_*` 常数.

## 基于角色的登录后路由

```ts
import { resolvePostLoginRoute, type RoleRouteTable } from '@dloizides/auth-web';

const roleRoutes: RoleRouteTable = {
  routes: [
    { role: 'superUser', route: '/admin/super' },
    { role: 'admin',     route: '/admin' },
    { role: 'user',      route: '/dashboard' },
  ],
  fallback: '/no-access',
};

// The first table entry whose role the user holds wins — list most privileged first.
const route = resolvePostLoginRoute(user, roleRoutes);
```

## API 表面

| 导出 | 仁爱 |
| --- | --- |
| `LoginForm`, (中文(简体) ), `ForgotPasswordForm`, (中文(简体) ), `ResetPasswordForm`, (中文(简体) ), `OtpForm`, (中文(简体) ), `PinForm` | 构成部分 |
| `AuthScreen`, (中文(简体) ), `DemoCredentialsHint`, (中文(简体) ), `PreferredMethodHint` | 组成+登录地表板 |
| `useDemoCredentials`, (中文(简体) ), `resolveDemoCredentials`, (中文(简体) ), `DemoCredentials`, (中文(简体) ), `PrefillIntent` | 公开演示证书 |
| `AuthThemeProvider`, (中文(简体) ), `useAuthTheme`, (中文(简体) ), `defaultAuthTheme`, (中文(简体) ), `AuthTheme` | 他们 |
| `DEFAULT_LOGIN_LABELS`, (中文(简体) ), `DEFAULT_FORGOT_PASSWORD_LABELS`, (中文(简体) ), `DEFAULT_RESET_PASSWORD_LABELS`, (中文(简体) ), `DEFAULT_OTP_LABELS`, (中文(简体) ), `DEFAULT_PIN_LABELS` | 标签袋 |
| `useBffAuth`, (中文(简体) ), `useBffForgotPassword`, (中文(简体) ), `useBffResetPassword`, (中文(简体) ), `useResetPasswordForm`, (中文(简体) ), `useOtpLogin`, (中文(简体) ), `usePinLogin` | 无头钩 |
| `OtpLoginStep` | 检察官办公室 |
| `createBffAuthClient`, (中文(简体) ), `BffAuthClient` (再出口) | 客户端 |
| `resolvePostLoginRoute`, (中文(简体) ), `collectUserRoles`, (中文(简体) ), `RoleRouteTable` | 路由器 |
| `validatePasswordPolicy`, (中文(简体) ), `isPasswordValid`, (中文(简体) ), `PasswordPolicyError` | 密码策略 |
| `AuthTestIds`, (中文(简体) ), `withTestIdPrefix` | 测试标识 |

## 许可证

麻省理工学院

## 常见问题

### @dloizides/auth-web 是什么？

可主题,为dloizides\.com组合的品牌Auth UI\. 原生LoginForm / ForgotPasswordForm / 重置PasswordForm组件,无头钩,同源 BffAuthClient,以及基于角色的后登录路由器\. 由@dloizides/auth-client所建

### 如何安装 @dloizides/auth-web？

在项目目录运行 npm install @dloizides/auth-web，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=17\.0\.0）、@dloizides/ui-buttons（\>=1\.9\.0）、@tanstack/react-query（^5\.0\.0）、@dloizides/auth-client（\>=4\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dloizides/auth-web 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dloizides/auth-web 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @dloizides/auth-web 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dloizides/auth-web 可以商用吗？

@dloizides/auth-web 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dloizides/auth-web 的下载量有多少？

根据 npm 官方下载统计，@dloizides/auth-web 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,914 次，日均约 97 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dloizides/auth-web 还在维护吗？

最新版本 1\.31\.0 发布于 2026/11/10（2 天前）；至今共发布 41 个版本，其中过去 12 个月发布了 41 个；首次发布于 2026/05/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。