XAi Web SDK

一个用于集成 AI 聊天机器人的 Web SDK。

安装

npm install @x-group/chat-sdk

使用方法

方式一：推荐写法（Coze 风格）

import XAiWebSDK from '@x-group/chat-sdk';

// 创建 SDK 实例 - 类似 Coze 的写法
const chatbot = new XAiWebSDK.initChatbot({
  url: 'https://your-api-server.com',
  token: 'your-token',
  config: {
    appNo: 'your-app-no',
  },
  componentProps: {
    id: 'chatbot-container',
    width: '400px',
    height: '600px',
  },
  onError: (error) => {
    console.error('Chatbot init error:', error);
  },
  onSuccess: (appInfo) => {
    console.log('Chatbot init success:', appInfo);
  },
});

// 销毁实例
chatbot.unmount();

方式二：兼容写法

// 使用静态方法（不推荐，但保持兼容）
const chatbot = XAiWebSDK.create({
  url: 'https://your-api-server.com',
  token: 'your-token',
  config: {
    appNo: 'your-app-no'
  },
  componentProps: {
    id: 'chatbot-container',
  },
  onError: (error) => {
    console.error('Chatbot init error:', error);
  },
  onSuccess: (appInfo) => {
    console.log('Chatbot init success:', appInfo);
  },
});

方式三：直接指定容器

const container = document.getElementById('my-chatbot');
const chatbot = new XAiWebSDK(container, {
  url: 'https://your-api-server.com',
  token: 'your-token',
  config: {
    appNo: 'your-app-no',
  },
  onError: (error) => {
    console.error('Chatbot init error:', error);
  },
  onSuccess: (appInfo) => {
    console.log('Chatbot init success:', appInfo);
  },
});

API 参数

XAiSDKProps

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | url | string | 是 | AI 服务地址 | | token | string | 是 | 认证 token | | config | object | 是 | 配置信息，包含 appNo 等 | | componentProps | object | 否 | 容器属性，支持 id 和任意 CSS 样式 | | onError | function | 否 | 错误回调函数 | | onSuccess | function | 否 | 成功回调函数 |

config 配置项

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | appNo | string | 是 | 应用编号 | | allowUpload | boolean | 否 | 是否允许上传文件，默认 false | | session.showSessionList | boolean | 否 | 是否显示会话列表，默认 false | | showFeedback | boolean | 否 | 是否显示点赞/点踩按钮，默认 true | | onFileClick | function | 否 | 点击附件卡片的回调函数 | | uploadRequest | function | 否 | 自定义文件上传函数 |

回调函数

onError(error)

• error.code: 错误代码
• error.message: 错误信息

onSuccess(appInfo)

• appInfo: 应用信息对象，包含应用配置等

onFileClick(file)

点击对话中的附件卡片时触发（非图片、非音视频文件）。

• file: 文件信息对象
  • fileName: 文件名
  • fileId: 文件ID
  • tempUrl: 文件临时URL
  • mimeType: 文件MIME类型
  • fileSize: 文件大小

uploadRequest(options)

自定义文件上传函数，用于覆盖默认上传行为。

• options.file: 要上传的 File 对象
• options.onProgress: 进度回调，参数 { percent: number }
• options.onSuccess: 上传成功回调，参数为服务器返回的文件信息
• options.onError: 上传失败回调，参数为 Error 对象

示例：

const chatbot = new XAiWebSDK.initChatbot({
  token: 'your-token',
  config: {
    appNo: 'your-app-no',
    allowUpload: true,
    // 自定义上传
    uploadRequest: async ({ file, onProgress, onSuccess, onError }) => {
      try {
        const formData = new FormData();
        formData.append('file', file);
        const response = await fetch('/api/upload', {
          method: 'POST',
          body: formData,
        });
        const data = await response.json();
        onSuccess({
          data: {
            fileName: data.fileName,
            fileId: data.fileId,
            tempUrl: data.fileUrl,
            fileType: data.fileType,
            fileSize: data.fileSize,
            mimeType: data.mimeType,
          },
        });
      } catch (error) {
        onError(error);
      }
    },
    // 文件预览回调
    onFileClick: (file) => {
      console.log('点击文件:', file);
      // 可以在此处触发文件预览弹窗
    },
  },
});

错误代码

| 代码 | 说明 | |------|------| | APP_NOT_ENABLE | 应用未启用 | | APP_DELETED | 应用已下架 | | APP_NOT_FOUND | 应用未找到 | | API_ERROR | API 调用错误 |