# @batoanng/oidc 中文文档

规范地址：https://npmcn.com/package/%40batoanng/oidc/

版本：3\.1\.0
npm 元数据更新时间：2026-05-01T09:44:18.573Z
中文译文更新时间：2026-11-08T03:12:18.301Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40batoanng/oidc
原文对照：https://npmcn.com/package/%40batoanng/oidc/?lang=original

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

- 包体积（解压后）：51.6 kB，25 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：0 个
- peer 依赖：@batoanng/mui-components ^3\.6\.0，@emotion/react ^11\.14\.0，@mui/material 9\.0\.0，axios 1\.15\.2，oidc-client-ts ^3\.5\.0，react ^19\.2\.5，react-hook-form 7\.74\.0，react-oidc-context ^3\.3\.1，react-router-dom ^7\.14\.2，react-use ^17\.4\.0
- 首次发布：2025-07-11T06:02:10.886Z
- 最新版本发布：2026-05-01T09:44:18.463Z
- 近 30 天下载量：1922（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 22 个）

## 中文简介

[![npm version](https://img.shields.io/npm/v/@batoanng/oidc)](https://www.npmjs.com/package/@batoanng/oidc) [![install size](https://packagephobia.com/badge?p=@batoanng/oidc)](https://packagephobia.com/result?p=@batoanng/oidc)

## 安装

```sh
npm install @batoanng/oidc
```

也可以使用：`pnpm add @batoanng/oidc`、`yarn add @batoanng/oidc`、`bun add @batoanng/oidc`

## README

# @batoanng/oidc (韩语)

[![npm version](https://img.shields.io/npm/v/@batoanng/oidc)](https://www.npmjs.com/package/@batoanng/oidc) [![install size](https://packagephobia.com/badge?p=@batoanng/oidc)](https://packagephobia.com/result?p=@batoanng/oidc)

`@batoanng/oidc` 包装 [`react-oidc-context`](https://github.com/authts/react-oidc-context) 包含路由器-意识回调路由,共享授权上下文,登录后浓缩帮助器,以及反应单页应用程序的即时认证状态屏幕.

## 特征

-   环绕 `react-oidc-context` 包括登录、登录和过期密码路由.
-   显示共享授权上下文 `useOidcAuthorisationContext`, (中文(简体) ), `useChallenge`,以及 `useChallengeResult`。 。 。 .
-   提供 `OidcAuthorisationCallback` 用于登录后配置和特权加载.
-   可以给一个轴线客户端 `Authorization` 头和单个无声再试 `401`。 。 。 .
-   船舶重置密码、错误和状态显示屏 [`@batoanng/mui-components`](https://www.npmjs.com/package/@batoanng/mui-components)。 。 。 .

## 安装

```bash
pnpm add @batoanng/oidc
```

同伴依赖关系包括 `react`, (中文(简体) ), `react-router-dom`, (中文(简体) ), `react-oidc-context`, (中文(简体) ), `oidc-client-ts`, (中文(简体) ), `axios`, (中文(简体) ), `@mui/material`, (中文(简体) ), `@emotion/react`, (中文(简体) ), `react-hook-form`, (中文(简体) ), `react-use`,以及 `@batoanng/mui-components`。 。 。 .

如果使用内置屏幕 `@batoanng/mui-components`,同时安装该套件所需的任何额外的同位素.

## 使用量

将您的应用程序的路由部分包入 `OidcAuthorisationProvider`。提供者必须住在反光路由器内 `<Router>` 因为它注入回调路线 `<Routes>`。 。 。 .

```tsx
import { OidcAuthorisationProvider } from '@batoanng/oidc';

export function AppShell() {
  return (
    <OidcAuthorisationProvider
      userManagerSettings={{
        authority: 'https://your-idp.example.com',
        client_id: 'web-app',
        redirect_uri: 'http://localhost:3000/oidc/callback',
        post_logout_redirect_uri: 'http://localhost:3000/oidc/logout',
      }}
    >
      <AppRoutes />
    </OidcAuthorisationProvider>
  );
}
```

登录回调完成后, 加载用户配置和权限, 然后交给 `OidcAuthorisationCallback` 在您保护的UI 创建之前, 共享授权背景已覆盖 .

```tsx
import axios from 'axios';
import {
  OidcAuthorisationCallback,
  useOidcAuthorisationContext,
  useEnsureOidcLoginToken,
} from '@batoanng/oidc';

const apiClient = axios.create({
  baseURL: '/api',
});

export function PostLoginGate() {
  const userInformation = {
    shortName: 'T. User',
    fullName: 'Test User',
    email: 'test@example.com',
  };

  const privileges = {
    'activityLog.read': true,
  };

  return (
    <OidcAuthorisationCallback apiClient={apiClient} userInformation={userInformation} privileges={privileges}>
      <ProtectedApp />
    </OidcAuthorisationCallback>
  );
}

export function ProtectedPage() {
  useEnsureOidcLoginToken();
  const { isAuthenticated, onLogout, token } = useOidcAuthorisationContext();

  return (
    <section>
      <div>{isAuthenticated ? 'Signed in' : 'Signed out'}</div>
      <div>{token}</div>
      <button onClick={() => void onLogout()}>Logout</button>
    </section>
  );
}
```

## 自动流量

```mermaid
flowchart TD
  A["App Router"] --> B["OidcAuthorisationProvider"]
  B --> C["react-oidc-context AuthProvider"]
  B --> D["/oidc/callback -> OidcLoginCallback"]
  B --> E["/oidc/logout -> OidcLogoutCallback"]
  B --> F["* -> OidcAuthorisationContextProvider"]
  D --> G{"Expired password response?"}
  G -- "Yes" --> H["/expired -> OidcResetPasswordPage"]
  G -- "No" --> I["Navigate to postLoginUrl or /"]
  F --> J["AuthorisationContext"]
  J --> K["useOidcAuthorisationContext / useChallenge"]
  I --> L["Load user profile and privileges"]
  L --> M["OidcAuthorisationCallback"]
  M --> N["Update user information and privilege state"]
  M --> O["Optional axios header + 401 retry wiring"]
  N --> P["Protected application UI"]
  O --> P
```

## 道具

### `OidcAuthorisationProvider`

| Prop | 类型 | 页:1 |
| --- | --- | --- |
| `userManagerSettings` | `UserManagerSettings` | 路过 `react-oidc-context`是因为 `AuthProvider`。 。 。 . |
| `loginCallbackRelativeUrl` | `string` | 登录回调路径的可选更改 。 路径名的默认值 `redirect_uri`,或 `/oidc/callback`。 。 。 . |
| `logoutCallbackRelativeUrl` | `string` | 登录召回路由的可选更改 。 路径名的默认值 `post_logout_redirect_uri`,或 `/oidc/logout`。 。 。 . |
| `onLoggingIn` | `(options?: LoginOptions) => void | boolean | Promise<void | boolean>` | 返回时 `false` 以取消登录尝试. |
| `onLoggingOut` | `() => void | boolean | Promise<void | boolean>` | 返回时 `false` 取消登录尝试. |
| `onPasswordReset` | `(email: string) => void | boolean | Promise<void | boolean>` | 当过期的 Password 流程提交或重发重设邮件时调用 . |

### `OidcAuthorisationCallback`

| Prop | 类型 | 页:1 |
| --- | --- | --- |
| `apiClient` | `AxiosInstance` | 可选的轴式实例 `Authorization` 页眉更新和一次无声- 新鲜重试 `401`。 。 。 . |
| `userInformation` | `UserInformation | string` | 提供已装入的用户配置文件, 或重定向 URL 字符串在登录后导航. |
| `privileges` | `UserPrivileges` | 当前用户的解析特权映射 . |
| `error` | `Error | null` | 渲染内置登录出错状态并让用户登录出错. |
| `authScheme` | `string` | 在使用时使用的授权方案 `Authorization` 头曰. 默认为 `Bearer`。 。 。 . |

## 综合说明

### 默认路径

| 路线 | 目的 |
| --- | --- |
| `/oidc/callback` | 处理 OIDC 登录重定向 . |
| `/oidc/logout` | 处理 OIDC 日志重定向 . |
| `/expired` | 显示 IdP 报告已过期密码响应时的密码重置流量 . |

### Axios 行为

-   `setBearerToken` 在 arxios 实例上存储当前访问符并保存 `defaults.headers.common.Authorization` 同步.
-   `OidcAuthorisationCallback` 为所提供安装一个响应截取器 `apiClient`。 。 。 .
-   A 类 `401` 触发一个 `signinSilent()` 尝试。 如果还回了新的令牌, 失败的请求会经过一次刷新 `Authorization` 头曰.

### 相关软件包

-   [`@batoanng/mui-components`](https://www.npmjs.com/package/@batoanng/mui-components) 提供内置屏幕所使用的状态、通知和形式原始.
-   [`@batoanng/utils`](https://www.npmjs.com/package/@batoanng/utils) 是一个相关的工作空间工具包,但是 `@batoanng/oidc` 现在使用 `react-use` 直接用于其本地的钩子助手.

## 发展

```bash
pnpm --dir packages/oidc lint
pnpm --dir packages/oidc type-check
pnpm --dir packages/oidc test
pnpm --dir packages/oidc build
```

关键文件 :

-   `src/OidcAuthorisationProvider.tsx`
-   `src/OidcAuthorisationContextProvider.tsx`
-   `src/OidcAuthorisationCallback.tsx`
-   `src/hooks.ts`
-   `src/types.ts`

## 常见问题

### 如何安装 @batoanng/oidc？

在项目目录运行 npm install @batoanng/oidc，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@batoanng/mui-components（^3\.6\.0）、@emotion/react（^11\.14\.0）、@mui/material（9\.0\.0）、axios（1\.15\.2）、oidc-client-ts（^3\.5\.0）、react（^19\.2\.5）、react-hook-form（7\.74\.0）、react-oidc-context（^3\.3\.1）、react-router-dom（^7\.14\.2）、react-use（^17\.4\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @batoanng/oidc 支持 TypeScript 吗？

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

### @batoanng/oidc 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @batoanng/oidc 需要什么版本的 Node\.js？

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

### @batoanng/oidc 可以商用吗？

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

### @batoanng/oidc 的下载量有多少？

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

### @batoanng/oidc 还在维护吗？

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