Skip to main content
欢迎使用 LangChat Widget —— 一个即插即用的 Web 聊天组件，基于 Vue 3 + TypeScript 构建，支持以 NPM 包形式集成到 Vue 工程，也支持在纯 HTML 页面通过 UMD 方式直接引入使用。

​
安装

pnpm add langchat-widget
# 或者
npm install langchat-widget
建议在现代项目中优先使用 ESM 安装与引入（如 Vite、Nuxt、Vue CLI 新版本）。

​
快速开始（Vue 工程）

以下示例展示在 Vue 3 项目中如何初始化和使用组件。建议在业务初始化逻辑中创建实例。 
// main.ts 或任意业务入口文件
import { LangChatBot } from 'langchat-widget';
import 'langchat-widget/dist/langchat-widget.css';

const widget = new LangChatBot({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://api.siliconflow.cn/v1',
  modelName: 'Qwen/Qwen2.5-72B-Instruct',
  header: { title: 'LangChat' },
  autoOpen: false,
  position: 'bottom-right',
  enableStreaming: true,
  enableHistory: true,
});

// 可选：监听事件
widget.on('open', () => console.log('widget opened'));
widget.on('close', () => console.log('widget closed'));
在需要时可以通过以下方法控制： 
widget.open();
widget.close();
widget.toggle();
widget.updateConfig({ theme: { mode: 'dark' } });
请勿在生产环境将真实 apiKey 暴露在浏览器源码中。推荐通过服务端代理或安全的 KV/Edge Config 注入方式下发临时令牌。

​
纯 HTML 使用（UMD）

无需构建工具，直接在 HTML 中引入 UMD 与 CSS 文件并创建实例。
注意：由于我们的CDN域可能在你们的内部网络无法访问，我们已经将 langchat-widget.css 和 langchat-widget.umd.js 放在你们自己的 CDN 上，你可以直接使用。这两个静态文件已经存放在项目根目录的 docs/widget/ 目录下，自行把这两个文件放到内部的CDN域（或者放到服务器上用nginx映射一下），然后修改前端的 langchat-ui/apps/langchat/index.html 文件的静态资源引用即可
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <!-- 引入样式 -->
    <link rel="stylesheet" href="http://cdn.tycoding.cn/langchat-widget.css" />
  </head>
  <body>
    <!-- 容器可选；若不提供将自动创建并挂载到 body -->
    <div id="langchat-widget-container"></div>

    <!-- 引入 UMD 文件 -->
    <script src="http://cdn.tycoding.cn/langchat-widget.umd.js"></script>
    <script>
      // UMD 导出对象为 LangChatWidget，主类为 LangChatBot
      const { LangChatBot } = window.LangChatWidget;

      const widget = new LangChatBot({
        apiKey: 'YOUR_API_KEY',
        baseUrl: 'https://api.siliconflow.cn/v1',
        modelName: 'Qwen/Qwen2.5-72B-Instruct',
        header: { title: 'LangChat Widget' },
        position: 'bottom-right',
        enableStreaming: true,
      });

      widget.on('open', () => console.log('opened'));
    </script>
  </body>
  </html>
项目内已提供演示文件：apps/widget/examples/basic-usage.html。
UMD 模式无需打包工具，适合静态站点或简单嵌入场景；框架工程推荐使用 ESM 安装，以获得更好的 Tree-Shaking 与类型支持。

​
配置项（Config）

以下为常用配置项（更多字段以包内类型为准）：
键类型必填默认值说明
apiKeystring是-模型访问密钥（请勿直曝）。
baseUrlstring否SDK 默认模型服务地址，如 https://api.siliconflow.cn/v1。
modelNamestring是-模型名称，如 Qwen/Qwen2.5-72B-Instruct。
organizationstring否-组织标识。
header{ title: string }否{ title: 'LangChat' }头部标题配置。
avatars`{ ai: stringURL; user: stringURL; size?: number }`否&#123; size: 32 &#125;头像与尺寸。
theme`{ mode?: ‘light''dark’; primaryColor?; backgroundColor?; textColor?; borderRadius?; shadow?; customCSS? }`否见源码默认主题与样式。
messages{ showAudioButton?; aiBackgroundColor?; userBackgroundColor?; userTextColor?; maxHeight? }否见源码默认消息区样式与行为。
copyright{ text: string; link?: string }否Powered by LangChat Widget版权信息。
welcome{ enabled?: boolean; title?: string }否启用且含默认标题欢迎语配置。
questionsArray<{ id: string; text: string; value: string }>否[]预置问题。
backendAPI{ getWelcomeMessage?; getSuggestedQuestions? }否-后端接口扩展，用于欢迎语与智能问题。
position`‘bottom-right''bottom-left''top-right''top-left’`否bottom-right浮动位置。
zIndexnumber否9999层级。
autoOpenboolean否false初始化后是否自动打开。
enableMarkdownboolean否true开启 Markdown 渲染。
enableHistoryboolean否true本地历史持久化。
maxHistoryItemsnumber否50历史最大条数。
enableStreamingboolean否true开启流式输出。
enableAutoSuggestionsboolean否false自动推荐问题（需 backendAPI.getSuggestedQuestions）。
校验规则（节选）：缺失 apiKey 会报错；baseUrl 会进行格式校验；maxHistoryItems 必须大于 0。

​
方法（API）

方法签名说明
openopen(): void打开聊天窗口
closeclose(): void关闭聊天窗口
toggletoggle(): void切换开合
sendMessagesendMessage(content: string): Promise<void>发送用户消息，并触发流式回复
clearHistoryclearHistory(): void清空本地历史记录
isOpenisOpen(): boolean是否处于打开状态
isLoadingisLoading(): boolean是否处于加载状态
updateConfigupdateConfig(partial: Partial<LangChatConfig>): void运行时更新配置
getConfiggetConfig(): LangChatConfig获取当前配置快照
getHistorygetHistory(): ChatMessage[]获取当前消息历史
onon(event: LangChatEvent, cb: Function): void监听组件事件
offoff(event: LangChatEvent, cb: Function): void取消事件监听

​
事件（Events）

事件名触发时机回调参数
init初始化完成-
open / close窗口打开/关闭时-
message-sent用户消息已发送ChatMessage
message-receivedAI 消息接收完成ChatMessage
streaming-update流式更新增量{ messageId: string; content: string }
config-updated配置已更新Required<LangChatConfig>
questions-updated建议问题更新QuestionItem[]
error捕获到错误Error

​
Vue 进阶示例

下面演示在任意组件中发送消息与监听事件： 
import { onMounted, onBeforeUnmount } from 'vue';
import { LangChatBot } from 'langchat-widget';
import 'langchat-widget/dist/langchat-widget.css';

let widget: LangChatBot | null = null;

onMounted(() => {
  widget = new LangChatBot({
    apiKey: 'YOUR_API_KEY',
    baseUrl: 'https://api.siliconflow.cn/v1',
    modelName: 'Qwen/Qwen2.5-72B-Instruct',
    header: { title: 'Support Assistant' },
    enableStreaming: true,
  });

  widget.on('message-received', (msg) => {
    console.log('assistant replied:', msg.content);
  });
});

onBeforeUnmount(() => {
  widget?.destroy();
  widget = null;
});

​
常见问题（FAQ）

  1. 浏览器报错 “process is not defined”
  • 使用本组件打包的 UMD/ES 版本已对浏览器环境做了兼容处理；若你自行二次打包，请确保为 process.env 添加 polyfill。
  1. 报错 “OpenAI client not initialized”
  • 确认已设置 apiKey，并在创建实例时传入。
  1. 无法获取建议问题
  • 若未传入 questions 静态数组，需要提供 backendAPI.getSuggestedQuestions 方法，或关闭 enableAutoSuggestions。
  1. Markdown 样式无效
  • 确认已引入 langchat-widget/dist/langchat-widget.css 样式文件。
若在 SSR 框架中（如 Nuxt）使用，请仅在客户端生命周期创建 LangChatBot 实例，以避免服务端渲染期间访问 window 导致报错。

​
版本与打包

  • 输出文件：
    • dist/langchat-widget.css
    • dist/langchat-widget.es.js
    • dist/langchat-widget.umd.js
  • UMD 全局对象：window.LangChatWidget，主类：LangChatBot
  • 建议通过 ESM 方式在现代框架中引入，通过 UMD 方式在纯 HTML 使用

​
许可

MIT