# @connect-xyz/auth-js 中文文档

规范地址：https://npmcn.com/package/%40connect-xyz/auth-js/

版本：1\.71\.13
npm 元数据更新时间：2026-11-04T14:37:55.523Z
中文译文更新时间：2026-11-14T14:18:45.938Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40connect-xyz/auth-js
原文对照：https://npmcn.com/package/%40connect-xyz/auth-js/?lang=original

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

- 包体积（解压后）：44.4 kB，5 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-10-30T19:33:33.935Z
- 最新版本发布：2026-11-04T14:37:55.231Z
- 近 30 天下载量：2016（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：95（近 12 个月 91 个）

## 中文简介

一个JavaScript SDK,可以使前端应用与Connect Auth产品无缝地相接.

## 安装

```sh
npm install @connect-xyz/auth-js
```

也可以使用：`pnpm add @connect-xyz/auth-js`、`yarn add @connect-xyz/auth-js`、`bun add @connect-xyz/auth-js`

## README

# @ 连接- xyz/ auth- js

一个JavaScript SDK,可以使前端应用与Connect Auth产品无缝地相接.

Connect Auth为加密存款提供了安全,自定义的认证流程. 学习更多在 [连接 Auth 文档](https://docs.zerohash.com/docs/auth)。 。 。 .

## 安装

### 国家预防机制(建议)

```bash
npm install @connect-xyz/auth-js
```

```javascript
import { Auth } from '@connect-xyz/auth-js';
```

### 维娅 CDN

您可以导入索引文件中的脚本并使用它提供的 Auth 类 .

```html
<script
  type="module"
  src="https://sdk.connect.xyz/auth-web/index.js"
></script>
```

或者你可以直接导入你的javascript代码.

```javascript
import { Auth } from 'https://sdk.connect.xyz/auth-web/index.js';
```

## 开始

遵循这些简单步骤将 Connect Auth 集成到您的前端应用程序中 :

### 1\. 导入 Auth 模块

```tsx
import { Auth } from '@connect-xyz/auth-js';
```

### 1.1 通过CDN导入

```javascript
import { Auth } from 'https://sdk.connect.xyz/auth-web/index.js';
```

### 2\. 初始化 Auth 模块到您的 App

```javascript
// Create an Auth instance with configuration
const auth = new Auth({
  jwt: 'your-jwt-token',
  env: 'production', // or 'sandbox'
  theme: 'auto', // 'auto' (default), 'light', or 'dark'
  onError: ({ errorCode, reason }) => {
    console.error('Auth error:', errorCode, 'Reason:', reason);
  },
  onClose: () => {
    console.log('Auth widget closed');
  },
  onDeposit: ({ data }) => {
    console.log('Deposit completed:', data);
  },
  onEvent: ({ type, data }) => {
    console.log('Event received:', type, data);
  },
  onLoaded: () => {
    console.log('Auth widget loaded and ready');
  },
});

// Render the widget to a container element
const container = document.getElementById('auth-container');
await auth.render(container);

// Update configuration dynamically
auth.updateConfig({
  jwt: 'new-jwt-token',
  onError: newErrorHandler,
});

// Check if rendered
if (auth.isRendered()) {
  console.log('Widget is active');
}

// Clean up when done
auth.destroy();
```

### 2.1 使用打字符(可选)

```typescript
import { Auth, AuthConfig } from '@connect-xyz/auth-js';

const config: AuthConfig = {
  jwt: 'your-jwt-token',
  env: 'sandbox',
  theme: 'dark', // 'auto' (default), 'light', or 'dark'
  onError: ({ errorCode, reason }) => {
    // Handle error with type safety
  },
  onDeposit: ({ data }) => {
    // Handle deposit with type safety
  },
};

const auth = new Auth(config);
```

## API 参考

### Auth 部件道具

| Prop | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `jwt` | `string` | 对 | \- 说吧 | 连接 Auth 认证的 JWT 令牌 |
| `env` | `"production" | "sandbox"` | 没有 | `"production"` | 目标环境 |
| `theme` | `"auto" | "light" | "dark"` | 没有 | `"auto"` | 界面的主题模式 |
| `onError` | `({ errorCode, reason }) => void` | 没有 | \- 说吧 | 调用错误事件 |
| `onClose` | `() => void` | 没有 | \- 说吧 | 部件关闭时召回 |
| `onDeposit` | `({ data }) => void` | 没有 | \- 说吧 | 收回存款 |
| `onEvent` | `({ type, data }) => void` | 没有 | \- 说吧 | 召回一般活动 |
| `onLoaded` | `() => void` | 没有 | \- 说吧 | 部件装入并准备就绪时召回 |

### 构造器

```javascript
new Auth(config: AuthConfig)
```

用提供的配置创建新的 Auth 实例 .

#### 参数

-   `config` (AuthConfig):配置对象
    -   `jwt` (字符串,需要):JWT认证标志
    -   `env` (字符串,可选):环境 - “ 生产” (默认) 或“ 散装箱”
    -   `theme` (弦,可选): 主题模式 - “ 自动” (默认)、 “ 光” 或 “ 暗”
    -   `onError` (职能,可选): 回调错误
    -   `onClose` (职能,可选): 关闭回调
    -   `onDeposit` (职能,可选): 回扣存款
    -   `onEvent` (职能,可选): 一般事件召回
    -   `onLoaded` (职能,可选): 装入部件并准备就绪时召回

### 方法

#### `render(container: HTMLElement): Promise<void>`

将 Auth 部件渲染到指定的容器元素.

```javascript
await auth.render(document.getElementById('auth-container'));
```

#### `updateConfig(config: Partial<AuthConfig>): void`

更新已渲染部件的配置.

```javascript
auth.updateConfig({
  jwt: 'new-token',
  onError: newErrorHandler,
});
```

#### `destroy(): void`

从 DOM 中删除部件并清理资源.

```javascript
auth.destroy();
```

#### `isRendered(): boolean`

返回当前部件是否已打开 .

```javascript
if (auth.isRendered()) {
  // Widget is active
}
```

#### `getConfig(): AuthConfig`

返回当前配置的副本.

```javascript
const config = auth.getConfig();
console.log('Current JWT:', config.jwt);
```

## 回调函数

关于召回事件及其有效载荷的详情,见 [Auth SDK 回调文档](https://docs.zerohash.com/docs/auth-standalone#4-organization-frontend-listens-to-auth-sdk-callbacks)。 。 。 .

### 错误

当 Auth 部件出错时调用 .

```javascript
onError: ({ errorCode, reason }) => {
  // errorCode: Error code
  // reason: Human-readable error description
};
```

### 关闭

当用户关闭 Auth 部件时调用 .

```javascript
onClose: () => {
  // Handle close event
};
```

### 保存

收到押金就打电话.

```javascript
onDeposit: ({ data }) => {
  // data: Object containing deposit details
};
```

### 活动

从 Auth 部件调用一般事件 .

```javascript
onEvent: ({ type, data }) => {
  // type: Event type string
  // data: Event-specific data object
};
```

### 已登录

当 Auth 部件已完全装入并准备好用户交互时调用 。 此调用在部件初始化后显示装入状态或执行动作时有用 .

```javascript
onLoaded: () => {
  // Widget is fully loaded and ready
};
```

## 浏览器支持

-   克罗梅/第90号+
-   Firefox 88+ (英语)
-   萨法里14+
-   所有有 Web 组件支持的现代浏览器

## 更多信息与支持

欲了解有关Connect Auth的全面文献或支持,请访问 [页 次](https://docs.zerohash.com/)。 。 。 .

## 常见问题

### @connect-xyz/auth-js 是什么？

一个JavaScript SDK,可以使前端应用与Connect Auth产品无缝地相接\.

### 如何安装 @connect-xyz/auth-js？

在项目目录运行 npm install @connect-xyz/auth-js，或使用 pnpm add / yarn add / bun add。

### @connect-xyz/auth-js 支持 TypeScript 吗？

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

### @connect-xyz/auth-js 支持 ESM 还是 CommonJS？

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

### @connect-xyz/auth-js 可以商用吗？

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

### @connect-xyz/auth-js 的下载量有多少？

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

### @connect-xyz/auth-js 还在维护吗？

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