# @evolve-packages/chat-widget 中文文档

规范地址：https://npmcn.com/package/%40evolve-packages/chat-widget/

版本：0\.5\.1
npm 元数据更新时间：2026-10-23T11:39:18.716Z
中文译文更新时间：2026-11-14T02:36:29.008Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40evolve-packages/chat-widget
原文对照：https://npmcn.com/package/%40evolve-packages/chat-widget/?lang=original
项目主页：https://github.com/labdigital-evolve/evolve-chat#readme
源码仓库：https://github.com/labdigital-evolve/evolve-chat

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：16.6 MB，85 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2025-12-17T16:14:31.452Z
- 最新版本发布：2026-10-23T11:39:17.514Z
- 近 30 天下载量：6386（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

Evolve 电子商务平台可嵌入的聊天部件

## 安装

```sh
npm install @evolve-packages/chat-widget
```

也可以使用：`pnpm add @evolve-packages/chat-widget`、`yarn add @evolve-packages/chat-widget`、`bun add @evolve-packages/chat-widget`

## README

# 演化聊天部件

Evolve 电子商务平台可嵌入聊天部件 。 允许客户在您的网站上直接与AI购物助理互动.

## 特征

-   浮动按钮或内嵌模式
-   有图像、价格和数量的产品卡
-   购物车和愿望名单整合
-   可配置品牌和标签
-   从 JWT 自动提取用户名
-   使用共享饼干的跨源支持

## 安装

### 脚本标记( 最轻松)

将部件脚本添加到您的 HTML 中 :

```html
<script src="https://chat.evolve-platform.com/widget.js"></script>
<script>
  EvolveChat.init({
    tenantId: 'evolve',
    mode: 'floating',
    position: { horizontal: 'right', vertical: 'bottom' },
  });
</script>
```

### pnpm 软件包

```bash
pnpm install @evolve-packages/chat-widget
```

```tsx
import { EvolveChatWidget } from '@evolve-platform/chat-widget';

function App() {
  return (
    <EvolveChatWidget
      tenantId="evolve"
      mode="floating"
      branding={{ primaryColor: '#f97316' }}
    />
  );
}
```

## 配置

### 需要的选项

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `tenantId` | `string` | 多租户支持的租户标识符 |

### 显示选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `mode` | `'floating' | 'inline'` | `'floating'` | 显示模式 |
| `container` | `string` | \- 说吧 | 内置模式容器的 CSS 选择器 |
| `position` | `WidgetPosition` | 见下文 | 浮动模式的位置 |
| `zIndex` | `number` | `9999` | 浮动部件的 z 索引 |

#### 位置配置

```typescript
interface WidgetPosition {
  horizontal: 'left' | 'right';  // default: 'right'
  vertical: 'top' | 'bottom';    // default: 'bottom'
  offsetX?: number;              // default: 20
  offsetY?: number;              // default: 20
}
```

### 标记选项

```typescript
interface WidgetBranding {
  primaryColor?: string;      // Primary color (default: '#f97316')
  primaryTextColor?: string;  // Text on primary (default: '#ffffff')
  accentColor?: string;       // Call-to-action colour (default: primaryColor)
  accentTextColor?: string;   // Text on accent (default: primaryTextColor)
  headerTitle?: string;       // Widget header title
  logoUrl?: string;           // Custom logo URL
  avatarUrl?: string;         // Avatar for assistant messages
  showHeader?: boolean;       // Inline only: header bar with logo and title (default: true)
}
```

### 标签选项

```typescript
interface WidgetLabels {
  placeholder?: string;  // Input placeholder text
  greeting?: string;     // Greeting message (use {name} for user name)
  thinking?: string;     // "Thinking" indicator text
  close?: string;        // Close button label
  sendLabel?: string;    // Accessible name of the send button (default: 'Send message')
}
```

### 背景选项

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `apiBaseUrl` | `string` | API 基础 URL( 默认: 当前来源) |
| `cartId` | `string` | 购物车的车牌 |
| `firstName` | `string` | 个人化问候的用户名 |
| `modelId` | `string` | 要使用的AI 型号 ID |

### 回电

```typescript
interface WidgetCallbacks {
  onOpen?: () => void;              // Called when widget opens
  onClose?: () => void;             // Called when widget closes
  onMessage?: (message: string) => void;  // Called when user sends message
  onError?: (error: Error) => void; // Called on error
}
```

## 项目助理

项目助理是一个选入功能,可以使后端的项目协助工具转出(`ask_user`, (中文(简体) ), `select_product`, (中文(简体) ), `present_kit`, (中文(简体) ), `offer_help`,.)入交互式卡:问牌,出品道,有推车/列表动作的材料列表,手动链接联系表,快速启动屏幕和进度栏.

```tsx
<EvolveChatWidget
  tenantId="evolve"
  features={["projectAssistant"]}
  isAuthenticated={isLoggedIn}
  labels={{
    projectAssistant: {
      quickStartJobs: [
        { id: "roof", emoji: "🏠", title: "Solar panels on a roof", prompt: "I want to install solar panels on my roof" },
      ],
      questSteps: ["Roof", "Panels", "Inverter", "Materials list"],
    },
  }}
/>
```

-   `features={["projectAssistant"]}` 打开特性;没有它,部件将像以前一样使这些工具生效. `WidgetFeatureId` 用于输入列表.
-   `isAuthenticated` 决定提供哪些材料列表动作:签名的购物者获得"添加来推"和"保存为列表",匿名购物者仅获得"共享列表".
-   `loadShoppingLists` (可选, `() => Promise<WidgetShoppingList[]>`,每个 `{ id, version, name }`) 将被签入的"拯救为列表"变成最爱的菜单. 部件每次打开菜单时都会调用它, 并且从不获取列表本身, 因此主机会用自己的会话加载它们 。 选择列表发送 `save_list` 与该列表 `listId` 财务报告和审定财务报表 `version`; "新共享列表"发送时没有 `listId`。没有回电,"保存为列表"发送 `save_list` 直去如来所.
-   `createShoppingList` (可选, `(name: string) => Promise<WidgetShoppingList>`)在该菜单中放出"新列表"而不是"新可共享列表":shopper输入一个名称,主机用自己的会话创建客户账户中的列表并返回 `{ id, version, name }`,然后部件发送 `save_list` 与那个 `listId` 财务报告和审定财务报表 `version`。被拒绝的许诺会打开菜单 `receiptNewListError`。没有它,菜单会保留匿名的“新共享列表”.
-   `labels.projectAssistant` (单位:千美元)`ProjectAssistantLabels`)覆盖任何副本。 包件一般默认,没有目录内容,所以主机用品 `quickStartJobs` (在空状态上; `prompt` 以第一句话发出)和 `questSteps` (进度栏;其名称必须与 `questStep` 值值后端工具会出。 留空会隐藏元素 .
-   何时 `quickStartJobs` 是非空的,快速启动屏幕将替换主机 `greeting` 在空闲聊天中。 它显示 `quickStartTitle`, (中文(简体) ), `quickStartSubtitle`, (中文(简体) ), `quickStartQuestion`,工作牌和 `quickStartHint`;一个空字符串会隐藏任何文本.
-   虽然其特性是活性的,作曲者是一个有圆形发送按钮的大圆形场. `branding.primaryColor` 驱动脚步器、链接、瓦片边框、牌头条和发泡条; `branding.accentColor` 驱动调用动作:发送按钮,收件的第一个动作和帮助提供的联系按钮,次要收件动作以主色调来概述. 没有口音,两者都回到了主色调. 两者皆可能是CSS变量,例如 `var(--brand-main)`。 。 。 .
-   聊天可以通过的页名 `branding={{ showHeader: false }}` 内入模式中;然后部件也会降低其卡片阴影和半径,从而使主机容器框框中它.

### 后端合同

工程助理卡发送的每个回答都是普通用户信息,其文本为JSON对象带有一个 `pa_action` 字段。 后端系统提示必须理解这六个动作:

| `pa_action` | 字段 |
| --- | --- |
| `answer` | `question`, (中文(简体) ), `values: string[]` |
| `product_selected` | `sku`, (中文(简体) ), `name` |
| `product_entered` | `text` |
| `add_to_cart` | `items: { sku, quantity }[]` |
| `save_list` | `items: { sku, quantity }[]`, (中文(简体) ), `version`选项 `listId` |
| `contact` | `firstName`, (中文(简体) ), `lastName`, (中文(简体) ), `email`, (中文(简体) ), `companyName`, (中文(简体) ), `phone`, (中文(简体) ), `question` |

部件将这些消息显示为短徽而非生 JSON.

### AI SDK 版本

部件运行于AI SDK 7. 以 AI SDK 7 为基础的聊天后端发布 `toolMetadata` 转到旧部件拒绝的 MCP 工具块,因此将这个软件包与 `@evolve-framework/chat-backend` (ai-7释放)。 部件仍然从 AI SDK 6 后端剖析流出 .

## 实例

### 浮动部件( 右下方)

```javascript
EvolveChat.init({
  tenantId: 'evolve',
  mode: 'floating',
  position: {
    horizontal: 'right',
    vertical: 'bottom',
    offsetX: 20,
    offsetY: 20,
  },
  branding: {
    primaryColor: '#f97316',
  },
});
```

### 浮动部件( 从下到左)

```javascript
EvolveChat.init({
  tenantId: 'evolve',
  mode: 'floating',
  position: {
    horizontal: 'left',
    vertical: 'bottom',
  },
});
```

### 内嵌

```html
<div id="chat-container" style="width: 400px; height: 600px;"></div>

<script>
  EvolveChat.init({
    tenantId: 'evolve',
    mode: 'inline',
    container: '#chat-container',
  });
</script>
```

### 用 Cart 整合

```javascript
EvolveChat.init({
  tenantId: 'evolve',
  mode: 'floating',
  cartId: 'abc123-cart-id',
  firstName: 'Jan',
});
```

### 自定义品牌

```javascript
EvolveChat.init({
  tenantId: 'evolve',
  mode: 'floating',
  branding: {
    primaryColor: '#1e40af',
    primaryTextColor: '#ffffff',
    headerTitle: 'Shop Assistant',
  },
  labels: {
    placeholder: 'Stel je vraag...',
    greeting: 'Hoi {name}! Hoe kan ik je helpen?',
    thinking: 'Even denken...',
  },
});
```

## 发展

### 构建

```bash
pnpm run build
```

产出:

-   `dist/widget.js` - UMD 捆绑(用于脚本标记,包括反应)
-   `dist/widget.css` - 被提取的样式
-   `dist/index.esm.js` - 无害环境管理捆绑(用于pnpm,作为对等处理)
-   `dist/index.js` - CJS 捆绑(用于 pnpm, 反应为 pal dep)

### 发展模式

```bash
pnpm run dev     # Watch mode with auto-rebuild
pnpm run serve   # Serve dist folder for testing
```

### 类型检查

```bash
pnpm run typecheck
```

## 建筑

```
widget/
├── src/
│   ├── index.ts              # pnpm package entry
│   ├── init.ts               # Script tag entry (EvolveChat.init)
│   ├── components/
│   │   ├── ChatWidget.tsx    # Main wrapper
│   │   ├── FloatingButton.tsx
│   │   ├── ChatPanel.tsx
│   │   ├── WidgetChat.tsx    # Chat UI (no Next.js deps)
│   │   ├── WidgetProductCard.tsx
│   │   └── WidgetToolQuery.tsx
│   ├── context/
│   │   └── WidgetProvider.tsx
│   ├── styles/
│   │   └── widget.css
│   ├── types/
│   │   └── config.ts
│   └── utils/
│       ├── api.ts
│       └── graphql-product-mapper.ts
├── dist/                     # Build output
├── package.json
├── rollup.config.js
└── tsconfig.json
```

## Cookie 需求

要进行跨域认证,必须配置 cookie :

1.  **Cookie 域名**数字 : `.evolve-platform.com` (子域有主点)
2.  **同一地点**数字 : `Lax` 或者说 `None` (与 `Secure` 旗帜)
3.  **(简体中文)**: 服务器必须发送 `Access-Control-Allow-Credentials: true`

## 浏览器支持

-   克罗姆80+
-   Firefox 75+ (英语)
-   萨法里13+
-   边80+

## 许可证

麻省理工学院

## 常见问题

### @evolve-packages/chat-widget 是什么？

Evolve 电子商务平台可嵌入的聊天部件

### 如何安装 @evolve-packages/chat-widget？

在项目目录运行 npm install @evolve-packages/chat-widget，或使用 pnpm add / yarn add / bun add。

### @evolve-packages/chat-widget 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @evolve-packages/chat-widget 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @evolve-packages/chat-widget 可以商用吗？

@evolve-packages/chat-widget 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @evolve-packages/chat-widget 的下载量有多少？

根据 npm 官方下载统计，@evolve-packages/chat-widget 在 2026/10/14 – 2026/11/12 这 30 天内被下载 6,386 次，日均约 213 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @evolve-packages/chat-widget 还在维护吗？

最新版本 0\.5\.1 发布于 2026/10/23（21 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2025/12/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。