# @chatcops/widget 中文文档

规范地址：https://npmcn.com/package/%40chatcops/widget/

版本：1\.1\.0
npm 元数据更新时间：2026-10-31T15:58:42.824Z
中文译文更新时间：2026-10-31T19:28:23.959Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40chatcops/widget
原文对照：https://npmcn.com/package/%40chatcops/widget/?lang=original
项目主页：https://chat.codercops.com/
源码仓库：https://github.com/codercops/chatcops

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

- 包体积（解压后）：385 kB，99 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-03-07T16:45:21.797Z
- 最新版本发布：2026-10-31T15:58:42.508Z
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

可嵌入的AI聊天机器人小部件-零依赖，影子DOM隔离

## 安装

```sh
npm install @chatcops/widget
```

也可以使用：`pnpm add @chatcops/widget`、`yarn add @chatcops/widget`、`bun add @chatcops/widget`

## README

# @chatcops /部件

可嵌入的AI聊天机器人小部件。零依赖，影子DOM隔离，~13KB压缩。

## 安装

### 脚本标签（最简单）

```html
<script
  src="https://cdn.jsdelivr.net/npm/@chatcops/widget@1/dist/chatcops.min.js"
  data-api-url="https://your-api.com/chat"
  data-accent="#6366f1">
</script>
```

小部件自动初始化 `data-*` 属性 `DOMContentLoaded`.

### npm

```bash
npm install @chatcops/widget
```

```typescript
import ChatCops from '@chatcops/widget';

ChatCops.init({
  apiUrl: 'https://your-api.com/chat',
  theme: { accent: '#6366f1' },
});
```

## 模式

### 弹出(默认)

角落的浮动动作按钮（FAB）。单击它将打开一个聊天面板。

```typescript
ChatCops.init({
  apiUrl: '/chat',
  mode: 'popup',                    // default
  theme: { position: 'bottom-right' }, // or 'bottom-left'
});
```

### 内联

直接在容器元素中呈现。没有FAB，就没有欢迎泡沫。

```typescript
ChatCops.init({
  apiUrl: '/chat',
  mode: 'inline',
  container: '#chat-container',  // CSS selector or HTMLElement
});
```

## 配置

```typescript
ChatCops.init({
  // Required
  apiUrl: 'https://your-api.com/chat',

  // Display mode
  mode: 'popup',                        // 'popup' | 'inline'
  container: '#chat',                   // required for inline mode

  // Theme
  theme: {
    accent: '#6366f1',                  // primary color
    textColor: '#ffffff',
    bgColor: '#0a0a0a',
    fontFamily: 'system-ui, sans-serif',
    borderRadius: '12px',
    tokens: {
      border: '#d0d4da',
      'panel-width': '440px',
    },
    position: 'bottom-right',           // 'bottom-right' | 'bottom-left'
  },

  // Branding
  branding: {
    name: 'Support Bot',
    avatar: 'https://example.com/avatar.png',
    subtitle: 'Online',
  },

  // Messages
  welcomeMessage: 'Hi! How can I help?',
  welcomeBubble: {
    text: 'Need help? Chat with us!',
    delay: 3000,                        // ms before showing
    showOnce: true,                     // once per browser ('local'), per tab ('session'), every load ('none')
  },
  placeholder: 'Type a message...',

  // Behavior
  persistence: 'local',                 // 'local' | 'session' | 'none', default: 'local'
  historyTtlDays: 30,                   // drop saved chats older than this
  maxMessages: 50,                      // max persisted messages
  pageContext: true,                     // send page URL/title to API
  autoOpen: 5000,                       // auto-open after ms (popup only)
  locale: 'en',
  privacyUrl: 'https://example.com/privacy', // link in header menu (https: or http:)

  // Callbacks
  onOpen: () => {},
  onClose: () => {},
  onMessage: (msg) => {},
  onError: (err) => {},
});
```

## API

```text
ChatCops.init(config)         // Initialize the widget
ChatCops.open()               // Open the chat panel (popup mode)
ChatCops.close()              // Close the chat panel
ChatCops.destroy()            // Remove widget and clean up
ChatCops.on(event, handler)   // Subscribe to events (returns unsubscribe function)
ChatCops.off(event, handler)  // Unsubscribe
```

事件: `open`， `close`， `message`， `error`， `leadCaptured`， `preChatSubmit`.

## 脚本标签属性

所有配置都可以通过 `data-*` 属性:

```html
<script
  src="https://cdn.jsdelivr.net/npm/@chatcops/widget@1/dist/chatcops.min.js"
  data-api-url="/chat"
  data-mode="popup"
  data-accent="#6366f1"
  data-text-color="#ffffff"
  data-bg-color="#0a0a0a"
  data-font-family="system-ui"
  data-border-radius="12px"
  data-position="bottom-right"
  data-brand-name="Support Bot"
  data-brand-avatar="https://example.com/avatar.png"
  data-brand-subtitle="Online"
  data-welcome-message="Hi! How can I help?"
  data-welcome-bubble="Need help?"
  data-welcome-bubble-delay="3000"
  data-placeholder="Type here..."
  data-locale="en"
  data-auto-open="true"
  data-privacy-url="https://example.com/privacy">
</script>
```

## 功能

-   **DOM的影子** -完全隔离CSS/DOM，不与主机站点冲突
-   **上交所流** -实时流响应通过服务器发送的事件
-   **减价** -显示粗体、斜体、代码块、链接和列表
-   **会话持久性** —localStorage表示历史记录，sessionStorage表示会话ID
-   **主题** - CSS自定义属性，自动派生表面颜色 `bgColor`
-   **移动响应** - 768px以下屏幕的全屏面板
-   **i18n** -船舶在英语与自定义覆盖支持任何语言
-   **可使用的** ARIA标签，语义HTML，键盘导航

## 许可证

麻省理工学院

## 常见问题

### @chatcops/widget 是什么？

可嵌入的AI聊天机器人小部件-零依赖，影子DOM隔离

### 如何安装 @chatcops/widget？

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

### @chatcops/widget 支持 TypeScript 吗？

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

### @chatcops/widget 支持 ESM 还是 CommonJS？

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

### @chatcops/widget 需要什么版本的 Node\.js？

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

### @chatcops/widget 可以商用吗？

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

### @chatcops/widget 还在维护吗？

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