# @ciromaciel/auth-react 中文文档

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

版本：1\.16\.0
npm 元数据更新时间：2026-11-05T10:12:32.889Z
中文译文更新时间：2026-11-09T17:01:53.988Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ciromaciel/auth-react
原文对照：https://npmcn.com/package/%40ciromaciel/auth-react/?lang=original
项目主页：https://myinfrastructure.click/products/auth

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

- 包体积（解压后）：1.5 MB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，zustand ^5\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@mantine/core ^8\.0\.0，@mantine/form ^8\.0\.0，@mantine/hooks ^8\.0\.0，react-router-dom ^6\.0\.0 \|\| ^7\.0\.0，@tabler/icons-react ^3\.0\.0
- 首次发布：2026-09-20T14:50:49.491Z
- 最新版本发布：2026-11-05T10:12:32.709Z
- 近 30 天下载量：3453（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

Auth SDK for React:JWT会话,无密码的签入,以及现成的曼汀屏幕.

## 安装

```sh
npm install @ciromaciel/auth-react
```

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

## README

# @ ciramaciel/ auth- react

[![npm version](https://img.shields.io/npm/v/@ciromaciel/auth-react.svg)](https://www.npmjs.com/package/@ciromaciel/auth-react) [![npm downloads](https://img.shields.io/npm/dm/@ciromaciel/auth-react.svg)](https://www.npmjs.com/package/@ciromaciel/auth-react) [![license](https://img.shields.io/npm/l/@ciromaciel/auth-react.svg)](https://www.npmjs.com/package/@ciromaciel/auth-react)

React的无密码认证:一个代码通过电子邮件到达,它成为了JWT会话.

有一条路可以进去 没有密码, 没有注册屏幕, 没有重置流量 —— 该账户是创建的 验证代码。 申请时可进行社会登录 拥有者允许提供商.

## 安装

```bash
bun add @ciromaciel/auth-react
```

同伴依赖性 : `react`, (中文(简体) ), `react-dom`, (中文(简体) ), `react-router-dom` 财务报告和审定财务报表 `zustand`。预建屏幕 还需要 `@mantine/core`, (中文(简体) ), `@mantine/form`, (中文(简体) ), `@mantine/hooks` 财务报告和审定财务报表 `@tabler/icons-react` —— 全体 (简体中文) 如果您从钩子中构建了自己的UI,则可以选择.

## 快开始

```jsx
import { AuthProvider, Protect, SignIn, SignedIn, SignedOut, SignInButton } from '@ciromaciel/auth-react'

function App() {
    return (
        <AuthProvider apiKey="your-api-key">
            <Routes>
                <Route path="/login" element={<SignIn />} />
                <Route element={<Protect redirectTo="/login" />}>
                    <Route path="/" element={<Home />} />
                </Route>
            </Routes>
        </AuthProvider>
    )
}

function Header() {
    return (
        <header>
            <SignedIn>
                <UserMenu />
            </SignedIn>
            <SignedOut>
                <SignInButton />
            </SignedOut>
        </header>
    )
}
```

`AuthProvider` 带 `apiKey` (必须), `apiUrl`, (中文(简体) ), `internal`, (中文(简体) ), `onError`, (中文(简体) ), `appearance` 财务报告和审定财务报表 `optimistic`内 `internal` 模式,不需要 API 密钥,即用于同源应用程序.

与 `optimistic` (默认值, 自 1. 1.0 起) 未过期的存储会话打开屏幕 然后Auth在背景中确认:一个会话Auth一经拒绝就退出 答对. 过 `optimistic={false}` 以保留加载屏幕,直到 Auth 回复。 一个冒充的 届会总是等待.

## 签名于

两个步骤,没有别的:

```jsx
import { useSignIn } from '@ciromaciel/auth-react'

const { requestCode, verifyCode, sending, verifying, error } = useSignIn()

await requestCode(email) // a code goes out by email
await verifyCode(email, code) // the code becomes a session
```

或者用现成的屏幕:

```jsx
<SignIn
    authenticatedRedirect="/" // where to send someone who already has a session
    onCodeSent={email => notify(`Code sent to ${email}`)}
    onSuccess={(user, { result, redirectHandled }) => notify(`Welcome ${user?.email}`)}
    onError={(error, { isShownOnCard }) => {
        // A wrong, expired or exhausted code is already explained on the card
        if (!isShownOnCard) notify(error.message) // error.code carries the stable identifier
    }}
/>
```

-   `onSuccess` 接收 **用户** 首先;原始 API 响应是 `result`。 。 。 .
-   `redirectHandled` 实值 `true` 当 a `?redirect=` 在 URL 中已经应用。 构成部分 默认遵守,以 API 源码和当前源码验证目的地; `redirectOrigins` 添加域和 `handleRedirect={false}` 手控制回应用程序.
-   错误的代码失败 `error.details.attemptsLeft`5个错误尝试摧毁请求 这个人要求一个新的代码.
-   在代码步骤上,卡片本身解释每一次失败:有多少次尝试,或者一旦 代码已耗尽或过期,一个发送新代码的按钮. `onError` 仍然开火,还有一秒钟 参数 `{ step: 'request' | 'verify', isShownOnCard }`; 跳过您自己的通知时 `isShownOnCard` 实值 `true`,或者这个人读过同样的失败两次.

### 社会注册

`<SignIn />` 使提供者按键独立化 : `socialLogin` 默认为 `'auto'`,哪个 显示应用程序所有者所允许的,当它们没有启用时则一无所有.

```jsx
<SignIn />                      {/* buttons appear when a provider is live */}
<SignIn socialLogin={false} />  {/* emailed code only */}
```

自己盖屏幕? `getSocialProviders()` 列出什么是活的, `startSocialSignIn(provider, { redirect })` 给供养者的假期,以及 `consumeSocialToken()` 在 URL 片断中读取回调值的符号 —— `AuthProvider` 已经叫这个了 给你的. `startSocialLink()`, (中文(简体) ), `unlinkSocialProvider()` 财务报告和审定财务报表 `getLinkedProviders()` 管理 已经签名的账户的连接.

### 近期账户

`<SignIn />` 记得在这个浏览器上签名的账户,并在下次访问时显示 在电子邮件字段之前 在账户上点击一次即可发送代码( 或返回到提供者) 打开代码步骤。 没有东西保存,屏幕就是平地 电子邮件表.

-   账户仅在会话存在后保存: 代码确认, 或提供者的代号 回来 错误的电子邮件永远不会成为建议 .
-   名单保留了最近五个账户。 每个条目都有电子邮件、入口和地址 上次登录的时间.
-   同一应用程序的每个应用程序都共享该列表,即使来自多个来源: Auth 工人保留 它在Http Only cookie上在自己的主机上,只回答应用程序的出处 允许。 一份副本 `localStorage` (单位:千美元)`auth:recent-accounts`)在共享列表时一次性制作 货物,当工人无法到达时,就站在那里.
-   签名保存名单 。 屏幕上的"Gerenciar"从每个应用程序中删除一个账户 应用程序; 该账户没有其他更改.

```jsx
<SignIn />                         {/* shows and saves recent accounts */}
<SignIn recentAccounts={false} />  {/* shared computers: neither shows nor saves */}
```

自己盖屏幕? `fetchRecentAccounts()`, (中文(简体) ), `saveRecentAccount(method)` 财务报告和审定财务报表 `deleteRecentAccount(email)` 与共享列表交谈; `listRecentAccounts()`, (中文(简体) ), `rememberAccount(email, method)`, (中文(简体) ), `forgetAccount(email)` 财务报告和审定财务报表 `adoptRecentAccounts(list)` 管理 本地副本.

### 多个账户, 一个浏览器

有两个账户的人不签字进入另一个账户。 每个签名的账户 在浏览器上保持签名,在浏览器之间切换需要点击一次,没有代码.

-   **没有电线.** `<UserInformation />` 显示“ Outras contas” 和 a 下的其他账户 "Adicionar Conta"一行;有多个账户,出口变为"Sair desta Conta"并 "以相机为相". `<SignIn />` 提供仍然作为行签入的账户 与"Conectada . entra sem código"相接相接,高于近期的.
-   **添加账户** 打开您的登录路由 `?mode=add`。 。 。 . `<GuestOnly>` 财务报告和审定财务报表 `<SignIn>` 让一个签入的人通过这个模式,而活期账户则保持签名。 应用程序 上面写着: `isAddingAccount()` 是真的,通过这个 页为 `signInUrl`。 。 。 .
-   **切换是一个身份切换**: 您的应用程序为上一个保存的所有信息 账户被擦去(如假冒,见 `IDENTITY_CHANGED_EVENT`),其他标签 随后,页面在 `afterSwitchUrl` (默认) `/`),因为屏幕上的地址可能 只有上一个账户才能打开资源.
-   每个浏览器每次有一个账户活动;每个请求仍带一个符号,所以您 后端不会改变任何东西.
-   在月台的区,名单 住在一个HttpOnly饼干后面。 在您自己的领域 SDK 保留浏览器的秘密 `localStorage` (单位:千美元)`auth:browser`在会话符号旁边.

```jsx
<AuthProvider apiKey="pu_..." afterSwitchUrl="/" signInUrl="/auth/signin">
<UserInformation hasAccountSwitcher={false} />  {/* one account per browser */}
<AccountSwitcher onSignedOut={goToSignIn} />    {/* the same group, inside your own menu */}

const { accounts, otherAccounts, switchAccount, addAccount, signOutAccount, signOutAll } = useAccounts()
```

### 车主的时间轴

没有电线: `AuthProvider` 应用程序的所有人看到每个用户 在 Auth 面板的一页中,显示此人来自何处以及他们做了什么.

-   **访问:** 来自别处的裁判, `utm_*`广告的点击id和登陆页, 保持在第一个屏幕上 并在一个登录后发送.
-   **诸相道:** 每个打开的路由,只有路由, ids倒塌, 最多每个路由一次 5分钟.
-   **行动:** 每个人的应用软件都会与 API( POST, PUT, PATCH, DELETE) 一同发送到自己的API 个人的象征,一旦成功。 只有方法 和地址旅行, 从来没有身体或地址 答话 给Auth的书信被排除在外.
-   `<AuthProvider activity={false}>` 关闭屏幕和动作。 更丰富的标签或动作 没有浏览器( CLI, 任务) , 后端可以调用 `reportActivity` 从 `@ciromaciel/contract/activity` 用申请的秘密钥匙.

### 户口卡

`<UserInformation />` 是从侧边栏的页脚上打开的: 谁在其中签名 以及哪个计划, 然后一个行动列表 与"楼梯"最后.

```jsx
<UserInformation
    user={user}
    signOut={signOut}
    onAccountClick={openAccount}
    onBillingClick={openBilling}
    items={[{ id: 'docs', label: 'Documentação', icon: IconFileText, onClick: openDocs }]}
    plan={{ name: 'Pro', used: 8, limit: 9, unit: 'projetos', canUpgrade: true, onClick: openPlans }}
    organization={{ name: 'Acme', role: 'owner' }}
/>
```

-   标题是用户的名字,或者没有电子邮件时的电子邮件——从来没有两者都这么说过 东西.
    
-   `items` 您的应用程序是自己的行, 作为数据传递( name`{ id, label, icon, onClick }`),在其中显示 计费后的自有组。 组件没有JSX,因此每个app的卡保持了相同的形状. 可添加一行 `description` (一行说它做什么)和 `tone: 'danger'` (红色,为什么) 无法被撤销); `itemsLabel` 标题组:
    
    ```jsx
    itemsLabel="Seus dados"
    items={[
        { id: 'export', label: 'Exportar', description: 'Uma cópia de tudo, em JSON', icon: IconDownload, onClick: exportAll },
        { id: 'erase', label: 'Apagar tudo', description: 'Sem volta', tone: 'danger', icon: IconTrash, onClick: eraseAll },
    ]}
    ```
    
-   `plan` 财务报告和审定财务报表 `organization` 绘制上下文条; 把它们放出而不画出 . `limit: null` 隐藏使用栏.
    
-   条条告知;"Assinatura"是计费的方式. 条子上加了"Fazer升级" 仅在 `canUpgrade` 实值 `true` (这个上面有一个计划) 使用率为80% 限制。 在极限,酒吧和倒数会变出红色并"Limite atingido"出现在徽章的行上. `plan.onClick` 是邀请所打开的; `actionLabel` 改名取来.
    
-   脚本读作"Protegido por Auth",并有"Termos"的链接,与登录的同名词相同 引用. `termsUrl` 说到别的地方, `termsUrl={null}` 丢弃链接,并 `branded={false}` 删除页脚.
    

### 账户屏幕

`<UserProfile />` 账户卡上的"Conta"是打开的:相片,名字和电子邮件; 通道; 带有公开会话的设备.

```jsx
<UserProfile opened={opened} onClose={close} />
```

-   每个文本默认为葡萄牙语. `labels` 更改单词( e)`labels={{ edit: 'Editar' }}`(三); 一个面板不需要它来翻译屏幕.
-   名称和相片编辑到位 : “ Alterar” 打开同一行的字段, Enter saves, Esc取消并关闭屏幕。 电子邮件没有改变 签入密码到达的地方.
-   "Formas de entrar"列出了电子邮件编码,它总是有效的,而提供商是 应用程序已启用,有“Conectar”和“Desconectar”。 没有启用, 组不是 画出. `showSignInMethods={false}` 藏来.
-   会话坐一行("2 sessões abertas"),哪个是这个设备;单击 打开下面的列表。 目前设备先来,不能从这里结束—— 这是"楼梯"。 "Encerrar as outras"在结束他们之前问起.
-   失败在屏幕上显示, 在失败的旁边 . `onError` 仍然收到错误, 与 `{ section, isShownOnScreen: true }`; 不要再次显示它.

## API 密码

### 构成部分

| 构成部分 | 说明 |
| --- | --- |
| `<SignIn />` | 整个入口:问电子邮件,然后取代码 |
| `<UserProfile />` | 账户屏幕:配置、方式、开放会话 |
| `<UserInformation />` | 账户卡:谁,在哪里,谁的计划,然后行动 |
| `<SocialButtons />` | 启用应用程序的供应商的签名按钮 |
| `<AuthCard />` | 屏幕上的卡片壳 |
| `<Wordmark />` | 应用程序单词标记 |

### 路线

| 构成部分 | 说明 |
| --- | --- |
| `<Protect />` | 路由包装; 重定向到 `redirectTo` 无会话 |
| `<GuestOnly />` | 对应方: 保留登录屏幕上的签名人 |

### 有条件渲染

| 构成部分 | 说明 |
| --- | --- |
| `<SignedIn>` | 只有在得到认证时才生孩子 |
| `<SignedOut>` | 只有在未认证的情况下才生孩子 |
| `<AuthLoading>` | Auth 正在装入时渲染孩子 |
| `<AuthLoaded>` | 一旦装入认证文件, 便会让孩子产生效果 |

### 未设置的按钮

| 构成部分 | 说明 |
| --- | --- |
| `<SignInButton />` | 要登录的页面导航 |
| `<SignOutButton />` | 签名用户 |

### 钩子

```jsx
const { user, loading, error, isAuthenticated, requestCode, verifyCode, signOut } = useAuth()
const { user, updateProfile, loadingUpdateProfile } = useUser()
const { requestCode, verifyCode, sending, verifying, error } = useSignIn()
const { getSession, user, setUser } = useSession()
const { sessions, listSessions, revokeSession, revokeOtherSessions } = useSessions()
const loadingStates = useAuthLoading()
const impersonation = useImpersonation() // the borrowed session, or null
const { accounts, otherAccounts, switchAccount, addAccount } = useAccounts() // the accounts of this browser
const logo = useApplicationLogo()
const signOut = useSignOut()
const checkToken = useCheckToken()
```

### 直接 SDK 电话

对于 React 以外的代码, HTTP 层也会导出 : `configure`, (中文(简体) ), `requestCode`, (中文(简体) ), `verifyCode`, (中文(简体) ), `pollCode`, (中文(简体) ), `signOut`, (中文(简体) ), `refreshToken`, (中文(简体) ), `getSession`, (中文(简体) ), `listSessions`, (中文(简体) ), `revokeSession`, (中文(简体) ), `revokeOtherSessions`, (中文(简体) ), `updateProfile`, (中文(简体) ), `getApplicationInfo`, (中文(简体) ), `isAuthenticated`, (中文(简体) ), `getCurrentUser`, (中文(简体) ), `decodeJWT`, (中文(简体) ), `setStoredToken`,以及上述社会帮助者.

## 特征

-   **无密码** - 一个电子邮件编码,供人员和特工使用;没有密码可以泄露
-   **JWT会议** 自动刷新
-   **犹太人** 通过 `/.well-known/jwks.json`
-   **交叉调制同步** - 在一个标签上签名,每个标签都跟着
-   **公路保护** 结束 `<Protect />` 财务报告和审定财务报表 `<GuestOnly />`
-   **有利于安全部门改革**

## 链接

-   [权威文档](https://myinfrastructure.click/products/auth)
-   [Npm 的软件包](https://www.npmjs.com/package/@ciromaciel/auth-react)

麻省理工学院 [西罗·塞萨尔·马西埃尔](https://ciromaciel.click/)

## 常见问题

### @ciromaciel/auth-react 是什么？

Auth SDK for React:JWT会话,无密码的签入,以及现成的曼汀屏幕\.

### 如何安装 @ciromaciel/auth-react？

在项目目录运行 npm install @ciromaciel/auth-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、zustand（^5\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）、react-router-dom（^6\.0\.0 \|\| ^7\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ciromaciel/auth-react 支持 TypeScript 吗？

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

### @ciromaciel/auth-react 支持 ESM 还是 CommonJS？

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

### @ciromaciel/auth-react 可以商用吗？

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

### @ciromaciel/auth-react 的下载量有多少？

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

### @ciromaciel/auth-react 还在维护吗？

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