# @authup/client-web-kit 中文文档

规范地址：https://npmcn.com/package/%40authup/client-web-kit/

版本：1\.0\.0-beta\.73
npm 元数据更新时间：2026-11-01T20:46:51.969Z
中文译文更新时间：2026-11-07T06:19:33.587Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：5.9 MB，623 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=26\.0\.0
- 运行依赖：19 个
- peer 依赖：vue ^3\.5\.44，pinia ^4\.1\.0，ilingo ^6\.2\.0，validup ^2\.0\.1，vue-router ^5\.4\.0，@ilingo/vue ^6\.1\.1，@vuecs/core ^3\.6\.0，@vuecs/icon ^1\.1\.1，@vuecs/link ^2\.1\.2，@vuecs/list ^1\.3\.0，@vuecs/tree ^1\.0\.0，@validup/vue ^2\.0\.1，@vuecs/forms ^5\.4\.2，@vuecs/button ^1\.4\.2，@vuecs/design ^1\.2\.1，@vuecs/locale ^1\.1\.2，@vuecs/elements ^1\.5\.1，@vuecs/overlays ^1\.3\.1，socket\.io-client ^4\.8\.4，@vuecs/pagination ^2\.2\.1，@ilingo/validup-vue ^1\.2\.0
- 首次发布：2024-05-08T08:30:16.222Z
- 最新版本发布：2026-11-01T20:46:51.641Z
- 近 30 天下载量：2396（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：62（近 12 个月 44 个）

## 中文简介

Vue 3 组件, 一个 Pinia会话商店, 并检查与 Authup 一起签名的应用程序的权限 .

## 安装

```sh
npm install @authup/client-web-kit
```

也可以使用：`pnpm add @authup/client-web-kit`、`yarn add @authup/client-web-kit`、`bun add @authup/client-web-kit`

## README

![Authup logo](https://raw.githubusercontent.com/authup/authup/master/.github/assets/logo.svg)

# @authup/客户端-web-kit

**Vue 3 组件, 一个 Pinia会话商店, 并检查与 Authup 一起签名的应用程序的权限 .**  
登录表单,授权流,令牌刷新和管理员实体屏幕,每Authup客户端写一次.

[![npm version](https://img.shields.io/npm/v/@authup/client-web-kit)](https://www.npmjs.com/package/@authup/client-web-kit) [![CI](https://github.com/authup/authup/actions/workflows/main.yml/badge.svg)](https://github.com/authup/authup/actions/workflows/main.yml) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://npmcn.com/package/%40authup/client-web-kit/LICENSE)

[**安装**](https://npmcn.com/package/%40authup/client-web-kit/#readme-installation) • 妇女 [使用量](https://npmcn.com/package/%40authup/client-web-kit/#readme-usage) • 妇女 [API 密码](https://npmcn.com/package/%40authup/client-web-kit/#readme-api) • 妇女 [文档](https://authup.org/)

* * *

## 为什么?

一个在 Authup 上签名的 Vue 应用程序每次需要相同客户端的一半:一个在重新加载后幸存的会话,一个重新自我更新的会话,一个知道签名用户可能做什么的守护符,以及Authup 管理的实体的表格. Authup自己的管理员,账户和Auth控制台都是从这个软件包中构建的,你的应用程序也可以是.

| 关切 | 没有它 | 用这个 |
| --- | --- | --- |
| **会议** | 自己存信物,决定何时失效,在过期前刷新 | 一个比尼亚商店 `login()`, (中文(简体) ), `resolve()`, (中文(简体) ), `logout()` (单位:千美元) `status` 参考; HTTP 客户端在 401 上更新访问令牌并重试 |
| **签名** | 构建 PKCE 配对 `/authorize` URL 和代码交换 | `createPKCE()`, (中文(简体) ), `buildAuthorizeURL()`, (中文(简体) ), `saveAuthorizationRequest()` 财务报告和审定财务报表 `store.exchangeAuthorizationCode()` |
| **权限** | 模板中的手写角色检查 | `usePermissionCheck({ name })`,关闭失败 `Ref<boolean>` 由服务器对登录用户的判定解答 |
| **屏幕** | 用户、角色、客户、政策、会议的格式和清单 | `A*` 每个实体的组件,加上登录、外交部、登记、密码和设备工作流程表 |
| **服务器渲染** | 在服务器上获取的列表, 然后在水合时再次获取 | 可选 `hydrationStore` 将服务器的行和判断交给浏览器 |

## 安装

```shell
npm install @authup/client-web-kit
```

一揽子措施仅限无害环境管理,需要节点 `>=26.0.0` 用于构建和服务器渲染.

消费者用该应用程序安装套餐股(第二版将拆分):

```shell
npm install vue vue-router pinia ilingo @ilingo/vue @ilingo/validup-vue validup @validup/vue socket.io-client \
    @vuecs/core @vuecs/design @vuecs/button @vuecs/elements @vuecs/forms @vuecs/icon @vuecs/link \
    @vuecs/list @vuecs/overlays @vuecs/pagination @vuecs/tree
```

`@vuecs/locale` 是一个可选的对等点: 语言切换器在安装时使用它, 否则会掉回工具箱自己的地块 .

组件没有自己的CSS。 他们的风格生活在 [`@authup/client-web-kit-theme`](https://github.com/authup/authup/tree/master/packages/client-web-kit-theme),而奥特普的全看 [`@authup/client-web-theme`](https://github.com/authup/authup/tree/master/packages/client-web-theme)。用于 Nuxt, 使用 [`@authup/client-web-nuxt`](https://github.com/authup/authup/tree/master/packages/client-web-nuxt),用于安装工具箱.

## 使用量

### 安装插件

```typescript
import { createPinia } from 'pinia';
import { createApp } from 'vue';
import vuecs from '@vuecs/core';
import installForms from '@vuecs/forms';
import installPagination from '@vuecs/pagination';
import clientWebKitTheme from '@authup/client-web-kit-theme';
import clientWebTheme from '@authup/client-web-theme';
import { buildVuecsInstallOptions, install } from '@authup/client-web-kit';
import App from './App.vue';

const app = createApp(App);
const pinia = createPinia();
app.use(pinia);

install(app, {
    baseURL: 'https://auth.example.com',
    pinia,
});

const vuecsOptions = app.runWithContext(() => buildVuecsInstallOptions({
    themes: [clientWebKitTheme(), clientWebTheme()],
}));

app.use(vuecs, vuecsOptions);
app.use(installForms);
app.use(installPagination);

app.mount('#app');
```

-   **在 vuecs 之前安装工具包 .** `install()` 提供翻译 `buildVuecsInstallOptions()` 读来翻译提交按钮标签,所以它必须在里面运行 `app.runWithContext()` 在工具箱之后.
-   **安装 `@vuecs/forms` 财务报告和审定财务报表 `@vuecs/pagination` 自己,过了 `app.use(vuecs, ...)`。 。 。 .** 套件故意不安装,所以他们会取出你的主题.
-   `install()` 提供商店、 HTTP 客户端( 带有符号续签钩)、 翻译和 `@validup/vue` 默认( 提交空白的可选字段为 `null`) (中文(简体) ). 实体组件仅在通过时在全球注册 `components: true` 或名单.

### 读取并驱动会话

```typescript
import { StoreAuthStatus, injectStore } from '@authup/client-web-kit';

const store = injectStore(pinia);

await store.login({ name: 'admin', password: 'start123', realmId: 'master' });

if (store.status === StoreAuthStatus.AUTHENTICATED) {
    console.log(store.user?.name, store.realmName);
}

await store.resolve();
await store.logout();
```

-   `status` 来源于商店持有的: `unauthenticated` (什么都没有), `authenticating` (飞行中的登录或代码交换), `restoring` (没有完整会话的文物,例如仅凭刷新标志)和 `authenticated` (地址、域名和用户信息).
-   **`restoring` 这不是一个旋转状态.** 在某位呼叫者运行之前, 无法恢复会话 `resolve()`,它或者完成它(如果需要重新刷新)或者清除它。 等着 `resolve()` 在你的路由器警卫.
-   `lastAuthOrigin` 表示当前会话是如何在这个应用实例中开始的: `login`, (中文(简体) ), `exchange` 或者说 `restore`。 。 。 .
-   `store.user` 由符号反省并保存 `id`, (中文(简体) ), `name`, (中文(简体) ), `displayName` 财务报告和审定财务报表 `email`需要更多的时候,你自己装上完整记录.
-   `logout()` 取消令牌配对,在cookie模式中也会结束服务器侧会话. 过 `{ revoke: false }` 当拆解反应是失败而不是签出,所以瞬间出错不会破坏一个仍然好的会话.

### 在许可下打开 UI

```typescript
import { PermissionName } from '@authup/core-kit';
import { usePermissionCheck } from '@authup/client-web-kit';
import { defineComponent, h } from 'vue';

export default defineComponent({
    setup() {
        const canUpdate = usePermissionCheck({ name: PermissionName.USER_UPDATE });

        return () => h('button', { disabled: !canUpdate.value }, 'Edit');
    },
});
```

裁判说 `false` 直至评估结束,并在届会或其判决发生变化时重新进行评估。 打电话一次 `setup()`,然后通过一个得到器而不是一个对象使上下文具有反应性. `usePermissionCheckState()` 添加a `settled` 来电者必须把"拒绝"和"尚未决定"区分开来 判决来自 `POST /authorization/check`; 检查是咨询, 因为服务器再次执行每个决定 .

### 使用授权代码流签名

```typescript
import {
    buildAuthorizeURL,
    clearAuthorizationRequest,
    createPKCE,
    createState,
    injectStore,
    loadAuthorizationRequest,
    saveAuthorizationRequest,
} from '@authup/client-web-kit';

export async function startLogin() {
    const pkce = await createPKCE();
    const state = createState();
    const redirectUri = `${window.location.origin}/login/callback`;

    saveAuthorizationRequest({
        state,
        code_verifier: pkce.code_verifier,
        redirect_uri: redirectUri,
        client_id: 'my-app',
        realm_id: 'master',
    });

    window.location.href = buildAuthorizeURL({
        baseURL: 'https://auth.example.com',
        clientId: 'my-app',
        realmId: 'master',
        redirectUri,
        state,
        codeChallenge: pkce.code_challenge,
        codeChallengeMethod: pkce.code_challenge_method,
    });
}

export async function handleCallback(code: string, state: string) {
    const request = loadAuthorizationRequest();
    clearAuthorizationRequest();

    if (!request || request.state !== state) {
        throw new Error('Unexpected authorization response.');
    }

    await injectStore(pinia).exchangeAuthorizationCode(code, {
        code_verifier: request.code_verifier,
        redirect_uri: request.redirect_uri,
        client_id: request.client_id,
        realm_id: request.realm_id,
    });
}
```

-   `buildAuthorizeURL()` 默认 `scope` 改为 `global openid` 财务报告和审定财务报表 `prompt` 改为 `select_account`,所以一个遗留的会话提供"继续作为/使用另一个账户". 过 `prompt: ''` 无.
-   也发出 `ui_locales` 财务报告和审定财务报表 `ui_color_mode` 从 `vc-locale` 财务报告和审定财务报表 `vc-color-mode` cookie,所以主机页面会以您的应用所使用的语言和颜色模式打开. 过 `''` 选择退出.
-   **重播 `redirect_uri` 从保存的请求.** 符号端点比较字节的字节,到浏览器返回时 `window.location` 携带 `code` 财务报告和审定财务报表 `state`。在登录后返回页面时,将其输入回调器自己的查询(`/login/callback?redirect=%2Fusers`) (中文(简体) ).
-   `buildEndSessionURL()` 建立RP启动的登录URL; `store.idToken` 这是 `id_token_hint` 这需要.

### 创建工作流程表

```typescript
import { ALoginForm } from '@authup/client-web-kit';
import { defineComponent, h } from 'vue';

export default defineComponent({
    setup() {
        return () => h(ALoginForm, {
            onDone: () => { window.location.assign('/'); },
        });
    },
});
```

`ALoginForm` 使域拾取器、密码表、账户有验证器时的第二要素步骤和域的身份提供者 `codeRequest`它会发出 `done` 一旦商店举行会话 `failed` 错误。 其他工作流程组件是: `AAuthorize`, (中文(简体) ), `AMfaChallengeForm`, (中文(简体) ), `ARegisterForm`, (中文(简体) ), `AActivateForm`, (中文(简体) ), `APasswordForgotForm`, (中文(简体) ), `APasswordResetForm`, (中文(简体) ), `ADeviceVerifyForm` 财务报告和审定财务报表 `AEndSessionForm`。 。 。 .

### 同步账户的语言和颜色模式

```typescript
import {
    COLOR_MODE_COOKIE,
    COLOR_MODE_UNSET,
    LOCALE_COOKIE,
    LOCALE_UNSET,
    createCookieRef,
    install,
} from '@authup/client-web-kit';

install(app, {
    baseURL: 'https://auth.example.com',
    pinia,
    preferences: {
        locale: createCookieRef(LOCALE_COOKIE, undefined, LOCALE_UNSET),
        colorMode: createCookieRef(COLOR_MODE_COOKIE, undefined, COLOR_MODE_UNSET),
    },
});
```

您的应用程序已经读取了它的语言和颜色模式 。 每场比赛都要让店主从帐号上播下种子 `locale` 财务报告和审定财务报表 `color_mode` 要求; 当账户中没有任何内容时, 它会写出一个明确的浏览器值一次; 在短暂的解开后, 更改为参考符会写回用户的属性 . `createCookieRef()` 返回每个 cookie 名称的一个 ref 值,因此每个读取同一 cookie 的组件都会看到相同的值.

### 将服务器上的数据交给浏览器

```typescript
install(app, {
    baseURL: 'https://auth.example.com',
    pinia,
    isServer: true,
    hydrationStore: {
        get: <T>(key: string) => payload[key] as T | undefined,
        set: (key, value) => { payload[key] = value; },
        delete: (key) => { delete payload[key]; },
    },
});
```

`payload` 您的框架的每个请求水合有效载荷。 设有仓库, 收藏组件装入里面 `onServerPrefetch` 并记录他们的行,并记录许可判决;水利客户端采用这些判决,而不是再次取取. **没有商店,工具包就完全不执行服务器侧负载.** 用每个请求的新对象返回:密钥没有带用户,所以在请求之间共享的存储将服务于一个用户行到另一个.

## 选项

第二项论点是: `install(app, options)`数字 :

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `baseURL` | `string` | (必须) | Authup API 的 URL . |
| `httpClient` | `IClient | (() => IClient)` | `new Client({ baseURL })` | 每个套件消费者的客户端:商店,提供客户端以及更新钩的刷新和撤销. 一个功能是每个消费者使用一次;一个实例是所有消费者共享的。 偏好一个函数返回每个呼叫的新客户端: 只要有一个实例, 更新的钩子就会在客户端上刷新它所附带的功能, 它会等待自己当 `/token` 答401号。 服务器渲染会使用一个功能,在拨打内部地址时保持基站url的公开性(`createRebasedTransport`) (中文(简体) ). |
| `pinia` | `Pinia` | 活动 Pinia | Pinia实例 商店注册. |
| `isServer` | `boolean` | `false` | 在服务器渲染时设定; 禁用背景刷新计时器 . |
| `components` | `boolean | string[]` | 未登记 | 在全球登记每个实体的组成部分或名称. |
| `translatorLocale` | `string` | `en` | 内置翻译的初始语言(`en`, (中文(简体) ), `de`, (中文(简体) ), `fr`, (中文(简体) ), `es`) (中文(简体) ). |
| `cookieGet` 编号 : `cookieSet` 编号 : `cookieUnset` | 函数 | `universal-cookie` | Cookie 访问持续符号和 `realm_management`; 传递您拥有 cookie 时的框架( Nuxt) `useCookie`) (中文(简体) ). |
| `cookiePath` | `string` | `/` | 路径商店饼干 被写。 一个来源的每个认证表层都必须通过相同的值. |
| `cookieSecure` | `boolean` | 文档是否为 https | 标记商店的饼干 `Secure`。服务器渲染不能显示,所以通过请求的设置. |
| `cookieSession` | `boolean` | `false` | 在服务器上认证 `HttpOnly` 会话 cookie 而不是一个符号对 。 只研究API的自产地. |
| `preferences` | `{ locale?: Ref<string>, colorMode?: Ref<string> }` | 无 | 与账户的 UI 偏好同步 . |
| `hydrationStore` | `HydrationStore` | 无 | 给服务器到客户端的交接. |
| `realtime` 编号 : `realtimeURL` | `boolean` 编号 : `string` | 关闭/ `baseURL` | 安装套接字管理器 . |

## API 密码

| 导出 | 仁爱 | 目的 |
| --- | --- | --- |
| `install`默认导出 | 函数,插件 | 安装存储、 HTTP 客户端、 翻译和验证默认 |
| `injectStore`, (中文(简体) ), `storeToRefs`, (中文(简体) ), `StoreAuthStatus`, (中文(简体) ), `StoreAuthOrigin` | 函数、元件 | 会话商店及其状态 |
| `injectHTTPClient` | 函数 | 提供的情况 `@authup/core-http-kit` 客户端 |
| `injectStoreDispatcher`, (中文(简体) ), `StoreDispatcherEventName` | 函数, enum | 存储事件, 例如 `SESSION_EXPIRED` 在背景更新失败后 |
| `usePermissionCheck`, (中文(简体) ), `usePermissionCheckState` | 可堆叠 | 反应许可裁决 |
| `createPKCE`, (中文(简体) ), `createState`, (中文(简体) ), `buildAuthorizeURL`, (中文(简体) ), `buildEndSessionURL`, (中文(简体) ), `buildConsoleLoginURL` | 函数 | OAuth2 和 OIDC 網址 |
| `saveAuthorizationRequest`, (中文(简体) ), `loadAuthorizationRequest`, (中文(简体) ), `clearAuthorizationRequest` | 函数 | 有待批准的请求 `sessionStorage` |
| `createCookieRef`, (中文(简体) ), `createColorMode`, (中文(简体) ), `LOCALE_COOKIE`, (中文(简体) ), `COLOR_MODE_COOKIE` | 函数,常数 | Cookie 支持的偏好 |
| `buildVuecsInstallOptions` | 函数 | 图标预设和翻译默认值 `app.use(vuecs, ...)` |
| `useTranslation`, (中文(简体) ), `useTranslator`, (中文(简体) ), `useErrorTranslator`, (中文(简体) ), `syncTranslatorLocaleFromManager` | 堆肥, 函数 | 翻译从 `@authup/i18n`后续 `@vuecs/locale` |
| `AUsers`, (中文(简体) ), `AUser`, (中文(简体) ), `AUserForm`, (中文(简体) ), `ARoles`, (中文(简体) ), `AClients`, (中文(简体) ), `APolicies`, (中文(简体) ), `ASessions`,, , , , , , , , . | 组件 | 每个认证实体的清单、记录和格式组件 |
| `ALoginForm`, (中文(简体) ), `AAuthorize`, (中文(简体) ), `AMfaChallengeForm`, (中文(简体) ), `ARegisterForm`, (中文(简体) ), `ADeviceVerifyForm`,, , , , , , , , . | 组件 | 主机工作流程表 |
| `AAuthApp`, (中文(简体) ), `AAuthShell`, (中文(简体) ), `AAccountShell`, (中文(简体) ), `ALanguageSwitcherDropdown`, (中文(简体) ), `AColorModeSwitcher`, (中文(简体) ), `APagination`, (中文(简体) ), `ASearch` | 组件 | 贝壳和公用事业 |
| `Options`, (中文(简体) ), `HydrationStore`, (中文(简体) ), `StorePreferences`, (中文(简体) ), `StoreLogoutOptions` | 类型 | 选项形状 |

整个组成部分的参考文献是: [页:1](https://authup.org/)。 。 。 .

## 页:1

-   **Cookie模式只用于API的自产地.** 会话饼干是 `SameSite=Strict` 而服务器也要求 `Sec-Fetch-Site: same-origin`这样 `cookieSession: true` 在另一个原产地的API上, 在这个模式下,商店既不读也不写符号饼干.
-   **坚固的饼干是象征 `realm_management`。 。 。 .** 用户记录来源于每个 `resolve()`从来没有储存在饼干.
-   **一个会话仅用于服务器报告符号 `active`。 。 。 .** 被吊销或过期的进入令牌通过刷新,而不是作为现场会议执行.
-   **主题不是可选的.** 无 `@authup/client-web-kit-theme`组件的 CSS 生成未设置的类字符串 .

## 许可证

由 所制

现按 [Apache 2.0 许可证](https://npmcn.com/package/%40authup/client-web-kit/LICENSE)。 。 。 .

## 常见问题

### @authup/client-web-kit 是什么？

Vue 3 组件, 一个 Pinia会话商店, 并检查与 Authup 一起签名的应用程序的权限 \.

### 如何安装 @authup/client-web-kit？

在项目目录运行 npm install @authup/client-web-kit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3\.5\.44）、pinia（^4\.1\.0）、ilingo（^6\.2\.0）、validup（^2\.0\.1）、vue-router（^5\.4\.0）、@ilingo/vue（^6\.1\.1）、@vuecs/core（^3\.6\.0）、@vuecs/icon（^1\.1\.1）、@vuecs/link（^2\.1\.2）、@vuecs/list（^1\.3\.0）、@vuecs/tree（^1\.0\.0）、@validup/vue（^2\.0\.1）、@vuecs/forms（^5\.4\.2）、@vuecs/button（^1\.4\.2）、@vuecs/design（^1\.2\.1）、@vuecs/elements（^1\.5\.1）、@vuecs/overlays（^1\.3\.1）、socket\.io-client（^4\.8\.4）、@vuecs/pagination（^2\.2\.1）、@ilingo/validup-vue（^1\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @authup/client-web-kit 支持 TypeScript 吗？

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

### @authup/client-web-kit 支持 ESM 还是 CommonJS？

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

### @authup/client-web-kit 需要什么版本的 Node\.js？

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

### @authup/client-web-kit 可以商用吗？

@authup/client-web-kit 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @authup/client-web-kit 的下载量有多少？

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

### @authup/client-web-kit 还在维护吗？

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