@itshixun/qchat-widget v1.1.86

@itshixun/qchat-widget 使用文档

目录

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

1. 安装指南

npm install @itshixun/qchat-widget

2. 快速入门

基础集成

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 组件集成

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' }} />;
}

3. 配置项详解

3.1 主题配置 (theme)

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)

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

3.3 功能开关 (feature)

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

3.4 服务配置 (server)

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
  }>;
}

4. 核心方法

4.1 实例方法

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

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

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

// 卸载组件
unmount();

4.2 事件控制

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

5. 事件系统

5.1 事件监听

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

5.2 事件类型

6. 主题定制

6.1 样式系统配置

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 多主题示例

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

7. 最佳实践

7.1 动态配置更新

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

7.2 服务端切换

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

8. 错误处理

8.1 常见错误

8.2 错误监听

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

9. 注意事项

1. 样式隔离

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

2. 性能优化

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

3. 安全建议

   • Token 获取方法建议使用闭包保护
   • 生产环境禁用 debugLog