npm package: @itshixun/qchat-widget
Description: 1. [安装指南](#安装指南) 2. [快速入门](#快速入门) 3. [配置项详解](#配置项详解) 4. [核心方法](#核心方法) 5. [事件系统](#事件系统) 6. [主题定制](#主题定制) 7. [最佳实践](#最佳实践) 8. [错误处理](#错误处理) 9. [注意事项](#注意事项)
Latest version: 1.1.86
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# @itshixun/qchat-widget 使用文档

## 目录

1. [安装指南](#安装指南)
2. [快速入门](#快速入门)
3. [配置项详解](#配置项详解)
4. [核心方法](#核心方法)
5. [事件系统](#事件系统)
6. [主题定制](#主题定制)
7. [最佳实践](#最佳实践)
8. [错误处理](#错误处理)
9. [注意事项](#注意事项)

---

## <a id="安装指南"></a>1. 安装指南

```bash
npm install @itshixun/qchat-widget
```

---

## <a id="快速入门"></a>2. 快速入门

### 基础集成

```typescript
import { QChatWidget } from '@itshixun/qchat-widget';

// 初始化实例
const chatWidget = new QChatWidget({
  theme: {
    title: '智能客服',
    aiName: 'AI助手',
    userName: '访客',
  },
  server: {
    type: 'api',
    api: {
      url: 'https://api.example.com/chat',
      token: () => 'your-auth-token',
    },
  },
});

// 挂载到DOM，指定对话框容器和按钮容器元素的id
chatWidget.mount('chatContainerId', 'btnContainerId');
```

### React 组件集成

```tsx
import React, { useEffect } from 'react';

function App() {
  useEffect(() => {
    const widget = new QChatWidget({
      /* 配置 */
    });
    widget.mount('chatRoot');
    return () => widget.unmount();
  }, []);

  return <div id="chatRoot" style={{ width: 400, height: '100vh' }} />;
}
```

---

## <a id="配置项详解"></a>3. 配置项详解

### 3.1 主题配置 (theme)

```typescript
theme?: {
  title: string;                   // 对话框标题 (默认: '小U学伴')
  logo?: string;                   // Logo图片URL
  subTitle?: string;               // 欢迎副标题
  description?: string[];          // 欢迎描述(支持多行)
  showName: boolean;               // 显示对话双方名称 (默认: true)
  showAvatar: boolean;             // 显示用户头像 (默认: true)
  aiAvatar?: string;               // AI头像URL
  userAvatar?: string;             // 用户头像URL
  avatarSize?: number;             // 头像尺寸(像素)
  placeholderText?: string;        // 输入框占位文字
  aiBtnConfig?: {        // 浮动按钮配置
    top?: number;        // 距顶部距离(px)
    right?: number;      // 距右侧距离(px)
    bottom?: number;     // 距底部距离(px)
    left?: number;       // 距左侧距离(px)
    zIndex?: number;     // 层级(z-index)
    tip?: string[];      // 悬浮提示文案
  };
}
```

### 3.2 功能模块 (module)

```typescript
module?: {
  attachment: boolean;    // 附件上传功能 (默认: false)
  agent: boolean;         // 人工客服转接 (默认: false)
  knowledge: boolean;     // 知识库检索 (默认: false)
  action: boolean;        // 快捷操作菜单 (默认: false)
}
```

### 3.3 功能开关 (feature)

```typescript
feature?: {
  enableChatSuggestions: boolean;  // 智能建议功能 (默认: true)
  enableHistory: boolean;          // 历史记录功能 (默认: true)
}
```

### 3.4 服务配置 (server)

```typescript
server: {
  type: 'api' | 'model';  // 服务类型

  // API模式配置
  api?: {
    url: string;          // 服务端点
    token?: () => string; // 动态令牌获取方法
    tokenKey?: string;    // 请求头Token字段 (默认: 'X-Access-Token')
  };

  // 直连模型配置
  models?: Array<{
    name: string;        // 模型名称
    apiKey: string;      // 模型API密钥
    url: string;         // 模型端点URL
  }>;
}
```

---

## <a id="核心方法"></a>4. 核心方法

### 4.1 实例方法

```typescript
// 动态更新配置
updateOptions(partialOptions: Partial<QChatWidgetOptions>);

// 触发自动提问
active(question?: {
  query: string;          // 问题内容
  type?: ChatType;        // 问题类型
  attachmentId?: string;  // 附件ID
});

// 设置推荐问题列表
setPropmts(prompts: PromptData[]);

// 卸载组件
unmount();
```

### 4.2 事件控制

```typescript
// 显示Toast提示
chatWidget.eventBus.emit('showToast', {
  message: '操作成功',
  type: 'success' | 'error',
});
```

---

## <a id="事件系统"></a>5. 事件系统

### 5.1 事件监听

```typescript
chatWidget.eventBus.on('toggleActive', ({ active }) => {
  if (!active) {
    console.log('对话框已关闭');
  }
});
```

### 5.2 事件类型

| 事件名称     | 说明                  | 数据类型                                             |
| ------------ | --------------------- | ---------------------------------------------------- |
| toggleActive | 切换对话框的显示/关闭 | { active: boolean; activeQuestion?: ActiveQuestion } |
| showToast    | 显示 toast 提示       | { message: string; type: 'success'\| 'error' }       |

---

## <a id="主题定制"></a>6. 主题定制

### 6.1 样式系统配置

```typescript
uiTheme?: {
  initQstTheme: boolean;  // 是否初始化样式系统
  themeOption: {
    namespace: string;     // CSS变量命名空间 (默认: '--qchat')
    styleTagId: string;    // 样式标签ID (默认: 'qchat_ui_system_style')
    themeList: Array<{     // 主题配色方案
      id: string;
      colors: Record<string, string>;
    }>;
  }
}
```

### 6.2 多主题示例

```typescript
const customTheme = {
  uiTheme: {
    initQstTheme: true,
    themeOption: {
      namespace: '--custom-theme',
      styleTagId: 'custom_style_tag',
      themeList: [
        // 自定义主题列表
      ],
    },
  },
};
```

---

## <a id="最佳实践"></a>7. 最佳实践

### 7.1 动态配置更新

```tsx
// React组件内更新配置示例
const updateTheme = () => {
  chatWidget.updateOptions({
    theme: {
      title: '小U',
      aiAvatar: '/night-mode-avatar.png',
      showAvatar: true,
      showName: true,
    },
  });
};
```

### 7.2 服务端切换

```typescript
// 切换API服务端点
function switchServer() {
  chatWidget.updateOptions({
    server: {
      type: 'api',
      api: {
        url: 'https://backup.api.example.com',
        token: getNewToken,
        tokenKey: 'X-New-Token',
      },
    },
  });
}
```

---

## <a id="错误处理"></a>8. 错误处理

### 8.1 常见错误

| 错误类型            | 触发条件                     | 解决方案                      |
| ------------------- | ---------------------------- | ----------------------------- |
| MissingServerConfig | 未配置 server 选项           | 检查 server.type 是否设置正确 |
| InvalidApiEndpoint  | API 类型服务缺少 url 配置    | 提供有效的 API 端点 URL       |
| ModelListRequired   | 模型类型服务缺少 models 配置 | 提供有效的 models 数组        |

### 8.2 错误监听

```typescript
try {
  new QChatWidget(invalidConfig);
} catch (error) {
  console.error('配置验证失败:', error.message);
}
```

---

## <a id="注意事项"></a>9. 注意事项

1. **样式隔离**

   - 当容器项目已使用 qst-ui-system 时，设置 `uiTheme.initQstTheme: false`来使用容器项目的 ui 配置
   - 如果希望使用独立的 qst-ui-system 配置，必须设置 `uiTheme.initQstTheme: true`

2. **性能优化**

   - 避免频繁调用 updateOptions()
   - 使用事件总线时及时清理监听器

3. **安全建议**
   - Token 获取方法建议使用闭包保护
   - 生产环境禁用 debugLog