# @classic-homes/chat-widget 中文文档

规范地址：https://npmcn.com/package/%40classic-homes/chat-widget/

版本：0\.1\.15
npm 元数据更新时间：2026-11-12T00:02:17.851Z
中文译文更新时间：2026-11-12T07:52:47.872Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40classic-homes/chat-widget
原文对照：https://npmcn.com/package/%40classic-homes/chat-widget/?lang=original
项目主页：https://github.com/classichomes/chat/tree/main/packages/widget#readme
源码仓库：https://github.com/Classic-Homes/chat

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

- 包体积（解压后）：846 kB，29 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react \>=17\.0\.0
- 首次发布：2026-01-25T21:42:43.184Z
- 最新版本发布：2026-11-12T00:02:17.632Z
- 近 30 天下载量：2658（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：108（近 12 个月 108 个）

## 中文简介

用斯维尔特所建的高性能嵌入式聊天部件

## 安装

```sh
npm install @classic-homes/chat-widget
```

也可以使用：`pnpm add @classic-homes/chat-widget`、`yarn add @classic-homes/chat-widget`、`bun add @classic-homes/chat-widget`

## README

# @ classic-homes/ 聊天网

由斯维尔特所建的高性能嵌入式聊天部件 。 可以通过多种方法整合:香草JS,React,多克龙插件,或自定义元素.

## 安装

```bash
npm install @classic-homes/chat-widget
```

对于反应项目,请确保安装了反应 17+ :

```bash
npm install react react-dom
```

## 使用量

### 香草 Java 脚本

将部件添加到任何网站的最简单方式 :

```javascript
import { init, destroy } from '@classic-homes/chat-widget/vanilla';

// Initialize the widget
init({
  apiBase: 'https://api.example.com',
  site: 'docs',
  siteName: 'Documentation',
  title: 'Help Assistant',
  welcomeMessage: 'How can I help you today?',
  welcomeTopics: ['Getting started', 'API reference', 'Troubleshooting'],
});

// Later, to destroy the widget
destroy();
```

### 反应组件

使用反应适配器与反应应用程序进行无缝整合:

```tsx
import { ChatWidget } from '@classic-homes/chat-widget/react';

function App() {
  return (
    <ChatWidget
      apiBase="https://api.example.com"
      site="docs"
      siteName="Documentation"
      title="Help Assistant"
      welcomeMessage="How can I help you today?"
      welcomeTopics={['Getting started', 'API reference', 'Troubleshooting']}
    />
  );
}
```

反应适配器也提供 `ChatWidgetElement` 用于直接使用自定义元素:

```tsx
import { ChatWidgetElement } from '@classic-homes/chat-widget/react';

function App() {
  return (
    <ChatWidgetElement
      apiBase="https://api.example.com"
      site="docs"
      siteName="Documentation"
    />
  );
}
```

### Docusaurus 插件

对于 Docusaurus 3.x 站点:

```javascript
// docusaurus.config.js
module.exports = {
  plugins: [
    [
      '@classic-homes/chat-widget/docusaurus',
      {
        apiBase: 'https://api.example.com',
        site: 'docs',
        siteName: 'Documentation',
        title: 'Help Assistant',
      },
    ],
  ],
};
```

### 自定义元素( 网络组件)

使用 `<chat-widget>` 直接在 HTML 中的自定义元素 :

```html
<script type="module">
  import '@classic-homes/chat-widget';
</script>

<chat-widget
  api-base="https://api.example.com"
  site="docs"
  site-name="Documentation"
  title="Help Assistant"
  welcome-message="How can I help you today?"
  welcome-topics='["Getting started", "API reference"]'
></chat-widget>
```

注:属性名称使用kebab case(例如:, `api-base` 改为 `apiBase`) (中文(简体) ).

## 配置选项

| 选项 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `apiBase` | `string` | 对 | \- 说吧 | 聊天 API 的基础 URL |
| `site` | `string` | 对 | \- 说吧 | 站点标识符(如"docs","营销"等) |
| `siteName` | `string` | 对 | \- 说吧 | 显示当前站点的名称 |
| `title` | `string` | 没有 | "聊天助手" | 部件标题 |
| `logoUrl` | `string` | 没有 | \- 说吧 | 信头的标记 URL |
| `primaryColor` | `string` | 没有 | \- 说吧 | 主品牌颜色( CSS 颜色值) |
| `position` | `"bottom-right"` | `"bottom-left"` | 没有 | `"bottom-right"` | 部件位置 |
| `fullscreen` | `boolean` | 没有 | `false` | 启用全屏模式 |
| `welcomeMessage` | `string` | 没有 | \- 说吧 | 欢迎消息文本 |
| `welcomeTopics` | `string[]` | 没有 | \- 说吧 | 以欢迎方式提出的专题 |
| `disclaimerHtml` | `string` | 没有 | \- 说吧 | 以下显示的 HTML 免责声明 |
| `storagePrefix` | `string` | 没有 | `"chat_"` | 本地密钥的前缀 |
| `sentryDsn` | `string` | 没有 | \- 说吧 | 用于跟踪错误的哨兵 DSN |
| `environment` | `"development"` | `"production"` | 没有 | `"production"` | 环境名称 |
| `sites` | `Record<string, SiteConfig>` | 没有 | \- 说吧 | 跨地点配置 |
| `onNavigate` | `(url: string) => void` | 没有 | \- 说吧 | 自定义导航处理器 |
| `onOpen` | `() => void` | 没有 | \- 说吧 | 部件打开时调用 |
| `onClose` | `() => void` | 没有 | \- 说吧 | 部件关闭时调用 |
| `getAuthToken` | `() => string | null | Promise<string | null>` | 没有 | \- 说吧 | CHAI 账户无记名标志提供商(参见 [账户登录](https://npmcn.com/package/%40classic-homes/chat-widget/#readme-account-login)(中文(简体) ) |

## 账户登录

部件是 **默认匿名** ——历史范围为每个浏览器动能 符号 。 将历史范围扩大至一个登录的CHAPI账户 **主机页面拥有 登录** 并交出部件 a `getAuthToken` 回调返回当前 无记账凭证(或 `null` 当记录出来的时候, 部件附加为 `Authorization: Bearer <token>` 并且,在首次核实的入境时,声称 访客的肛门历史进入账户.

部件捆绑 **没有** 登录 UI - 嵌入页面负责 对CHAMI进行认证(它已经必须,因此其来源为SSO的白名单).

**程序/ 香草/ 多库龙** - 通过 `getAuthToken` 在配置中:

```js
const widget = initChatWidget(element, {
  apiBase: 'https://api.example.com',
  site: 'docs',
  siteName: 'Documentation',
  getAuthToken: () => myAuthClient.getAccessToken(), // string | null | Promise<...>
});
```

**反应** - 通过 `getAuthToken` 作为道具。 使用一个 **稳定参考** (单位:千美元)`useCallback`); 表示提供者被故意排除在重新挂起的道具之外, 因此其身份更改不会重挂部件 :

```tsx
const getAuthToken = useCallback(() => myAuthClient.getAccessToken(), []);
<ChatWidget apiBase={...} site="docs" siteName="Documentation" getAuthToken={getAuthToken} />
```

**自定义元素 `<chat-widget>`** 函数不能是一个 HTML 属性,所以设置它 作为 **属性** 在元素连接前 :

```html
<chat-widget id="chat" api-base="https://api.example.com" site="docs" site-name="Documentation"></chat-widget>
<script type="module">
  import '@classic-homes/chat-widget';
  const el = document.getElementById('chat');
  el.getAuthToken = () => myAuthClient.getAccessToken();
</script>
```

在元素添加到 DOM 之前设定属性( 或设置, 然后重新附加) 部件挂起时它就存在.

**登录/ 登录后** - 账户在挂上 如果主机的认证状态 部件已挂载时更改, 调用 `widget.refresh()` 重新挂载和 重新用新代号管理账户索赔.

## 部件 API

这个 `initChatWidget` 函数返回 a `ChatWidgetAPI` 对象,使用下列方法:

### 对话管理

```typescript
const widget = initChatWidget(element, config);

// List all conversations
const conversations = await widget.listConversations();

// Get a specific conversation with messages
const conversation = await widget.getConversation(id);

// Switch to a conversation
await widget.selectConversation(id);

// Start a new conversation
await widget.startNewConversation();

// Delete a conversation
await widget.deleteConversation(id);

// Rename a conversation
await widget.renameConversation(id, 'New Title');
```

### 状态计

```typescript
// Get current conversation ID (null if new chat)
const currentId = await widget.getCurrentConversationId();

// Get current conversation title
const title = await widget.getCurrentTitle();
```

### 生命周期方法

```typescript
// Clear messages and reset chat
widget.clearMessages();

// Refresh widget (reload from storage)
widget.refresh();

// Destroy the widget
widget.destroy();
```

## 活动

使用 `on` 方法 :

```typescript
const widget = initChatWidget(element, config);

// Subscribe to events
const unsubscribe = widget.on('message:received', ({ message }) => {
  console.log('New message:', message.content);
});

// One-time subscription
widget.once('ready', () => {
  console.log('Widget is ready');
});

// Unsubscribe
unsubscribe();
```

### 可用事件

| 活动 | 有效载荷 | 说明 |
| --- | --- | --- |
| `ready` | `undefined` | 部件已初始化 |
| `conversation:created` | `{ id: string, title: string | null }` | 创建新对话 |
| `conversation:selected` | `{ id: string | null, title: string | null }` | 选定/已切换 |
| `conversation:deleted` | `{ id: string }` | 对话已删除 |
| `conversation:titleChanged` | `{ id: string, title: string }` | 重命名为对话 |
| `conversations:updated` | `{ conversations: ConversationPreview[] }` | 对话列表已更改 |
| `message:sent` | `{ message: Message }` | 用户发送信件 |
| `message:received` | `{ message: Message }` | 收到助理答复 |
| `error` | `{ message: string, error?: Error }` | 发生错误 |

## 类型脚本支持

包含全部类型脚本定义. 视需要导入类型:

```typescript
import type {
  ChatWidgetConfig,
  ChatWidgetAPI,
  PageContext,
  Message,
  ConversationPreview,
} from '@classic-homes/chat-widget';
```

## 样式

部件是一个自成一体的经典主题岛. 其样式表(主题) 符号 `--chat-*` 需要桥和Tailwind公用事业主题组件) 范围为 `.chat-widget`因此,它既不取决于 或渗入主机 页面的CSS。 脚本在第一次渲染前自动注入; 主机 也可能装入 `@classic-homes/chat-widget/styles.css` 带有 `<link>` 为避免 脚本运行前的闪光( 装入两者都无害) .

部件没有网络字体: 它在主机页面加载时使用 Figtree 倒回系统的UI字体.

品牌颜色: 通过 `primaryColor` 输入时, 设置 `--chat-primary` 内入于 部件根。 其它 `--chat-*` 变量在 `.chat-widget`; 改为 覆盖它们,用更具体的选择器瞄准该元素:

```css
body .chat-widget {
  --chat-radius: 12px;
  --chat-header-bg: #f2f3ee;
}
```

## 浏览器支持

-   克罗梅/第88号+
-   Firefox 78+ (英语)
-   萨法里14+

装饰性锡和阴影 `color-mix()` (Safari 16.2+、Chrome 111+、, Firefox 113+);更古老的浏览器在没有它们的情况下渲染.

部件需要支持 :

-   自定义元素 v1
-   ES 模块
-   CSS 自定义属性

## 许可证

麻省理工学院

## 常见问题

### @classic-homes/chat-widget 是什么？

用斯维尔特所建的高性能嵌入式聊天部件

### 如何安装 @classic-homes/chat-widget？

在项目目录运行 npm install @classic-homes/chat-widget，或使用 pnpm add / yarn add / bun add。

### @classic-homes/chat-widget 支持 TypeScript 吗？

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

### @classic-homes/chat-widget 支持 ESM 还是 CommonJS？

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

### @classic-homes/chat-widget 可以商用吗？

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

### @classic-homes/chat-widget 的下载量有多少？

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

### @classic-homes/chat-widget 还在维护吗？

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