@ classic-homes/ 聊天网

由斯维尔特所建的高性能嵌入式聊天部件 。 可以通过多种方法整合:香草JS,React,多克龙插件,或自定义元素.

安装

npm install @classic-homes/chat-widget

对于反应项目,请确保安装了反应 17+ :

npm install react react-dom

使用量

香草 Java 脚本

将部件添加到任何网站的最简单方式 :

import { init, destroy } from '@classic-homes/chat-widget/vanilla';

// Initialize the widget
init({
  apiBase: 'https://api.example.com',
  site: 'docs',
  siteName: 'Documentation',
  title: 'Help Assistant',
  welcomeMessage: 'How can I help you today?',
  welcomeTopics: ['Getting started', 'API reference', 'Troubleshooting'],
});

// Later, to destroy the widget
destroy();

反应组件

使用反应适配器与反应应用程序进行无缝整合:

import { ChatWidget } from '@classic-homes/chat-widget/react';

function App() {
  return (
    <ChatWidget
      apiBase="https://api.example.com"
      site="docs"
      siteName="Documentation"
      title="Help Assistant"
      welcomeMessage="How can I help you today?"
      welcomeTopics={['Getting started', 'API reference', 'Troubleshooting']}
    />
  );
}

反应适配器也提供 ChatWidgetElement 用于直接使用自定义元素:

import { ChatWidgetElement } from '@classic-homes/chat-widget/react';

function App() {
  return (
    <ChatWidgetElement
      apiBase="https://api.example.com"
      site="docs"
      siteName="Documentation"
    />
  );
}

Docusaurus 插件

对于 Docusaurus 3.x 站点:

// docusaurus.config.js
module.exports = {
  plugins: [
    [
      '@classic-homes/chat-widget/docusaurus',
      {
        apiBase: 'https://api.example.com',
        site: 'docs',
        siteName: 'Documentation',
        title: 'Help Assistant',
      },
    ],
  ],
};

自定义元素( 网络组件)

使用 <chat-widget> 直接在 HTML 中的自定义元素 :

<script type="module">
  import '@classic-homes/chat-widget';
</script>

<chat-widget
  api-base="https://api.example.com"
  site="docs"
  site-name="Documentation"
  title="Help Assistant"
  welcome-message="How can I help you today?"
  welcome-topics='["Getting started", "API reference"]'
></chat-widget>

注:属性名称使用kebab case(例如:, api-base 改为 apiBase) (中文(简体) ).

配置选项

账户登录

部件是 默认匿名 ——历史范围为每个浏览器动能 符号 。 将历史范围扩大至一个登录的CHAPI账户 主机页面拥有 登录 并交出部件 a getAuthToken 回调返回当前 无记账凭证(或 null 当记录出来的时候, 部件附加为 Authorization: Bearer <token> 并且,在首次核实的入境时,声称 访客的肛门历史进入账户.

部件捆绑 没有 登录 UI - 嵌入页面负责 对CHAMI进行认证(它已经必须,因此其来源为SSO的白名单).

程序/ 香草/ 多库龙 - 通过 getAuthToken 在配置中:

const widget = initChatWidget(element, {
  apiBase: 'https://api.example.com',
  site: 'docs',
  siteName: 'Documentation',
  getAuthToken: () => myAuthClient.getAccessToken(), // string | null | Promise<...>
});

反应 - 通过 getAuthToken 作为道具。 使用一个 稳定参考 (单位:千美元)useCallback); 表示提供者被故意排除在重新挂起的道具之外, 因此其身份更改不会重挂部件 :

const getAuthToken = useCallback(() => myAuthClient.getAccessToken(), []);
<ChatWidget apiBase={...} site="docs" siteName="Documentation" getAuthToken={getAuthToken} />

自定义元素 <chat-widget> 函数不能是一个 HTML 属性,所以设置它 作为 属性 在元素连接前 :

<chat-widget id="chat" api-base="https://api.example.com" site="docs" site-name="Documentation"></chat-widget>
<script type="module">
  import '@classic-homes/chat-widget';
  const el = document.getElementById('chat');
  el.getAuthToken = () => myAuthClient.getAccessToken();
</script>

在元素添加到 DOM 之前设定属性( 或设置, 然后重新附加) 部件挂起时它就存在.

登录/ 登录后 - 账户在挂上 如果主机的认证状态 部件已挂载时更改, 调用 widget.refresh() 重新挂载和 重新用新代号管理账户索赔.

部件 API

这个 initChatWidget 函数返回 a ChatWidgetAPI 对象,使用下列方法:

对话管理

const widget = initChatWidget(element, config);

// List all conversations
const conversations = await widget.listConversations();

// Get a specific conversation with messages
const conversation = await widget.getConversation(id);

// Switch to a conversation
await widget.selectConversation(id);

// Start a new conversation
await widget.startNewConversation();

// Delete a conversation
await widget.deleteConversation(id);

// Rename a conversation
await widget.renameConversation(id, 'New Title');

状态计

// Get current conversation ID (null if new chat)
const currentId = await widget.getCurrentConversationId();

// Get current conversation title
const title = await widget.getCurrentTitle();

生命周期方法

// Clear messages and reset chat
widget.clearMessages();

// Refresh widget (reload from storage)
widget.refresh();

// Destroy the widget
widget.destroy();

活动

使用 on 方法 :

const widget = initChatWidget(element, config);

// Subscribe to events
const unsubscribe = widget.on('message:received', ({ message }) => {
  console.log('New message:', message.content);
});

// One-time subscription
widget.once('ready', () => {
  console.log('Widget is ready');
});

// Unsubscribe
unsubscribe();

可用事件

类型脚本支持

包含全部类型脚本定义. 视需要导入类型:

import type {
  ChatWidgetConfig,
  ChatWidgetAPI,
  PageContext,
  Message,
  ConversationPreview,
} from '@classic-homes/chat-widget';

样式

部件是一个自成一体的经典主题岛. 其样式表(主题) 符号 --chat-* 需要桥和Tailwind公用事业主题组件) 范围为 .chat-widget因此,它既不取决于 或渗入主机 页面的CSS。 脚本在第一次渲染前自动注入; 主机 也可能装入 @classic-homes/chat-widget/styles.css 带有 <link> 为避免 脚本运行前的闪光( 装入两者都无害) .

部件没有网络字体: 它在主机页面加载时使用 Figtree 倒回系统的UI字体.

品牌颜色: 通过 primaryColor 输入时, 设置 --chat-primary 内入于 部件根。 其它 --chat-* 变量在 .chat-widget; 改为 覆盖它们,用更具体的选择器瞄准该元素:

body .chat-widget {
  --chat-radius: 12px;
  --chat-header-bg: #f2f3ee;
}

浏览器支持

• 克罗梅/第88号+
• Firefox 78+ (英语)
• 萨法里14+

装饰性锡和阴影 color-mix() (Safari 16.2+、Chrome 111+、, Firefox 113+);更古老的浏览器在没有它们的情况下渲染.

部件需要支持 :

• 自定义元素 v1
• ES 模块
• CSS 自定义属性

许可证

麻省理工学院