# @developer\.notchatbot/webchat 中文文档

规范地址：https://npmcn.com/package/%40developer.notchatbot/webchat/

版本：2\.8\.4
npm 元数据更新时间：2026-11-11T17:22:51.584Z
中文译文更新时间：2026-11-12T02:49:08.739Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40developer.notchatbot/webchat
原文对照：https://npmcn.com/package/%40developer.notchatbot/webchat/?lang=original

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

- 包体积（解压后）：1.6 MB，69 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2025-06-11T11:21:15.642Z
- 最新版本发布：2026-11-11T17:22:51.408Z
- 近 30 天下载量：4453（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：65（近 12 个月 30 个）

## 中文简介

具有单文件捆绑的漂亮回放聊天器部件

## 安装

```sh
npm install @developer.notchatbot/webchat
```

也可以使用：`pnpm add @developer.notchatbot/webchat`、`yarn add @developer.notchatbot/webchat`、`bun add @developer.notchatbot/webchat`

## README

# QQ WebChat - 嵌入式聊天

Webchat 2.0.0使用自来源访问者证书,需要匹配的NotChatbot后端和Cloudflare存在服务. 见 [推出指南](https://npmcn.com/package/%40developer.notchatbot/next/docs/webchat-v2-rollout.md) 在升级现有安装之前.

## QQ 快速启动

### 1\. 将部件添加到您的网站

```html
<div id="webchat-component"></div>

<script src="https://your-cdn.com/webchat-bundle.min.umd.cjs"></script>
<script>
WebChat.initialize({
    title: "Customer Support",
    placeholder: "Ask us anything...",
    primaryColor: "#667eea"
});
</script>
```

### 2,就是这样

聊天机按钮将出现在您页面右下角 。 CSS自动注射!

## QQ 配置选项

```typescript
interface WebChatConfig {
  title?: string;                       // Chat window title
  placeholder?: string;                 // Input placeholder text
  primaryColor?: string;                // Primary theme color (also the user bubble)
  bubbleBotColor?: string;              // Bot bubble background ('' / omitted = #f1f2f4; text contrast adapts)
  apiKey?: string;                      // Your chatbot UID (required for API)
  position?: 'bottom-right' | 'bottom-left'; // Widget position
  initialMessage?: string;              // Custom initial bot message
  closeButtonIcon?: 'default' | 'text' | 'custom'; // Close button type
  closeButtonText?: string;             // Text for close button (when type is 'text')
  closeButtonCustomIcon?: string;       // Custom icon SVG or URL (when type is 'custom')
  marginBottom?: number;                // Distance from bottom edge in pixels (default: 16)
  marginSide?: number;                  // Distance from left/right edge in pixels (default: 16)
  mobile?: WebChatPositionConfig;       // Mobile-specific position settings
  desktop?: WebChatPositionConfig;      // Desktop-specific position settings
  whatsapp?: {                          // Integrated WhatsApp Options
    phoneNumber: string;                // WhatsApp phone number
    message?: string;                   // Optional default message text
    active?: boolean;                   // Enable or disable the button (default: true)
    color?: string;                     // Customize the internal WhatsApp button color
  };
  apiBaseUrl?: string;                  // Backend override (see "Targeting a non-production backend")
  realtimeUrl?: string;                 // Convex deployment override (same section)
}

interface WebChatPositionConfig {
  position?: 'bottom-right' | 'bottom-left';
  marginBottom?: number;
  marginSide?: number;
}
```

示例

```js
WebChat.initialize({
    title: "Chat Assistant",
    placeholder: "Type your message...",
    primaryColor: "#007bff",
    apiKey: "your-chatbot-uid",        // Chatbot UID from admin panel
    position: "bottom-right",
    initialMessage: "Hi! 👋 I'm your virtual assistant. How can I help you today?",
    closeButtonIcon: "default", // or "text" or "custom"
    marginBottom: 20,           // Distance from bottom edge (default: 16px)
    marginSide: 20,             // Distance from side edge (default: 16px)
    // Device-specific overrides
    mobile: {
        position: "bottom-left",
        marginBottom: 80,
        marginSide: 15
    },
    desktop: {
        position: "bottom-right", 
        marginBottom: 30,
        marginSide: 30
    },
    whatsapp: {                        // Adds a dual-button menu for WhatsApp & WebChat
        phoneNumber: "YOUR_PHONE_NUMBER",
        message: "Hello! I need help...",
        active: true,
        color: "#25D366"
    }
});
```

## \* 瞄准非生产后端

默认情况下, 部件会从它运行的页面主机名中选择其后端 关于: `localhost` → `http://localhost:3000`生产 (单位:千美元)`https://next.notchatbot.com`) (中文(简体) ). 这对商人来说是正确的 页面本身是非生产部署 vercel预览, `dev.notchatbot.com`,或者其它端口的本地 dev 服务器 超过三千. 没有覆盖,在预览中键入的消息会降落在 **生产** 收发箱.

`apiBaseUrl` 财务报告和审定财务报表 `realtimeUrl` 覆盖检测 :

```js
WebChat.initialize({
    apiKey: "your-chatbot-uid",
    apiBaseUrl: window.location.origin,          // HTTP: /api/webchat, /upload, /rate
    realtimeUrl: "https://<deployment>.convex.cloud" // Convex realtime subscriptions
});
```

-   都一样 `https://` (或 `http://localhost` 编号 : `http://127.0.0.1`任何东西 其它的则以控制台警告被忽略,默认值被保存.
-   **把它们设为一对.** `apiBaseUrl` 单写到一个部署时 部件继续监听默认的 Convex, 所以代理回复从未到达 .
-   让他们保持过去的行为—— 现有的嵌入物是 不受影响,每个 `initialize()` 清除先前呼叫中的任何更改.

# QQWhatsApp 按钮

如果您想要一个没有 WebChat 的浮动WhatsApp 动作按钮, 您可以使用 `WhatsAppButtonAPI`,它将自己隔离在"阴影DOM"中来避免CSS冲突.

## \* 安装和基本使用

```html
<!-- Load the script -->
<script src="path/to/webchat.js"></script>
<script>
  WhatsAppButtonAPI.initialize({
    phoneNumber: "1234567890",
    message: "Hola, me gustaría tener más información.",
    color: "#25D366",
    position: "bottom-right",
    marginBottom: 20,
    marginSide: 20,
    active: true,
    size: 48, // Button dimension in px
    
    // Customize device-specific positioning
    desktop: {
      position: "bottom-right",
      marginBottom: 30,
      marginSide: 30
    },
    mobile: {
      position: "bottom-right",
      marginBottom: 80,
      marginSide: 15
    }
  });
</script>
```

# QQ 嵌入聊天 - 嵌入聊天

EmbedChat允许您将一个完整的聊天系统直接集成到您的网页的任何元素中,在大小,位置,和风格上完全控制.

## \* 安装和基本使用

### 直接 HTML

```html
<!-- Element to embed the chat -->
<div id="my-chat-embed"></div>

<!-- Load the script -->
<script src="path/to/webchat.js"></script>
<script>
  EmbedChat.initialize({
    elementId: "my-chat-embed",
    apiKey: "your-api-key",
    title: "Chat Assistant",
    width: 400,
    height: 500
  });
</script>
```

### Java 脚本/ Type 脚本

```javascript
import { EmbedChatAPI } from './webchat';

const chatInstance = EmbedChatAPI.initialize({
  elementId: "my-chat-embed",
  apiKey: "your-api-key",
  title: "Chat Assistant",
  width: 400,
  height: 500
});
```

## QQ 完整配置

### 必需属性

```javascript
EmbedChatAPI.initialize({
  // REQUIRED
  elementId: "my-chat-embed",              // ID of the HTML element to embed the chat
  apiKey: "your-api-key",                  // API key of the service
})
```

### 内容属性

```javascript
EmbedChatAPI.initialize({
  // Texts and content
  title: "Chat Assistant",        // Title shown in the header
  placeholder: "Type your message...",    // Input placeholder text
  initialMessage: "Hello! 👋 I'm your chat assistant. How can I help you today?", // First message from the bot
  footerText: "Powered by NotChatBot", // Footer text (optional)
  avatar: "https://example.com/avatar.jpg", // Bot avatar URL
})
```

### 大小属性

```javascript
EmbedChatAPI.initialize({
  // Main dimensions
  width: 400,                        // Width: number (px) or string ("100%", "50vw")
  height: 500,                       // Height: number (px) or string ("100%", "80vh")
  
  // Size limits
  maxWidth: 600,                     // Maximum width
  maxHeight: "90vh",                 // Maximum height (accepts CSS units)
  minWidth: 280,                     // Minimum width (default: 280px)
  minHeight: 300,                    // Minimum height (default: 300px)
})
```

### 外观属性

```javascript
EmbedChatAPI.initialize({
  // Colors
  primaryColor: "#3b82f6",           // Primary color (header, buttons, etc.)
  textColor: "#333333",              // Message text color
  bubbleUserColor: "#3b82f6",        // User message bubble background
  bubbleBotColor: "#e0f2fe",         // Bot message bubble background (default #f1f2f4)
  chatBackground: "#ffffff",         // Chat background color
  footerColor: "#f3f4f6",            // Footer background color
  
  // Borders
  borderRadius: 12,                  // Border radius: number (px) or string
  border: "2px solid #3b82f6",       // Custom border (CSS border)
  boxShadow: "0 10px 30px rgba(0,0,0,0.2)", // Custom shadow
  
  chatTransparent: false,            // If true, chat background is transparent
})
```

### 区域控制属性

```javascript
EmbedChatAPI.initialize({
  showHeader: true,                  // Show/hide header (default: true)
  showFooter: true,                  // Show/hide footer (default: true if footerText is provided)
})
```

### 输入配置

```javascript
EmbedChatAPI.initialize({
  input: {
    backgroundColor: "#ffffff",      // Input area background color
    inputBorder: "2px solid #e5e7eb", // Input field border
    inputBorderRadius: "8px",        // Input border radius
    iconColor: "#3b82f6"             // Send icon color
  }
})
```

### 自定义 CSS

```javascript
EmbedChatAPI.initialize({
  customCSS: `
    #notchatbot-embed-chat {
      /* Your custom styles here */
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
    }
  `
})
```

### 大小控制

```javascript
EmbedChatAPI.initialize({
  elementId: "mi-chat",
  
  // Main sizes
  width: 400,           // Number (px) or string ("100%", "50vw")
  height: 500,          // Number (px) or string ("100%", "80vh")
  
  // Size limits
  maxWidth: 600,        // Maximum size
  maxHeight: "90vh",    // Can use CSS units
  minWidth: 280,        // Minimum size
  minHeight: 300,
  
  // More
  width: "100%",        // Occupies the entire width of the container
  height: "50vh",       // 50% of the window height
  maxWidth: "500px",    // Maximum 500px
})
```

### 视觉自定义

```javascript
EmbedChatAPI.initialize({
  elementId: "mi-chat",
  
  // Borders and effects
  borderRadius: 12,                 // Border radius in px
  border: "2px solid #3b82f6",     // Custom border
  boxShadow: "0 10px 30px rgba(0,0,0,0.2)", // Custom shadow
  
  // Section control
  showHeader: true,                 // Show/hide header (default: true)
  showFooter: true,                 // Show/hide footer (default: true if footerText is provided)
  
  // 🆕 Custom CSS
  customCSS: `
    #notchatbot-embed-chat {
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
      border-radius: 20px !important;
    }
  `
})
```

## 完整属性参考

### 嵌入ChatConfig 配置表格

| 财产 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `elementId` | `string` | ✅ | \- 说吧 | 挂载聊天的 HTML 元素的标识 |
| `apiKey` | `string` | ✅ | \- 说吧 | 聊天服务的 API 密钥 |
| `title` | `string` | ❌ | `"Chat"` | 聊天头中显示的标题 |
| `placeholder` | `string` | ❌ | `"Type your message..."` | 输入字段占位符文本 |
| `primaryColor` | `string` | ❌ | `"#3b82f6"` | 主颜色(标题、按钮、链接) |
| `avatar` | `string` | ❌ | \- 说吧 | Bot avatar URL( 可选的) |
| `initialMessage` | `string` | ❌ | \- 说吧 | 机器人显示的第一个消息 |
| `footerText` | `string` | ❌ | \- 说吧 | 页脚文本( 如果提供了, 则显示) |
| `width` | `string | number` | ❌ | `"100%"` | 聊天宽度( px 或 CSS 单位) |
| `height` | `string | number` | ❌ | `400` | 聊天高度( px 或 CSS 单位) |
| `maxWidth` | `string | number` | ❌ | `"100%"` | 最大聊天宽度 |
| `maxHeight` | `string | number` | ❌ | `"100vh"` | 最大聊天高度 |
| `minWidth` | `string | number` | ❌ | `280` | 最小聊天宽度 |
| `minHeight` | `string | number` | ❌ | `300` | 最小聊天高度 |
| `showHeader` | `boolean` | ❌ | `true` | 显示/隐藏信头 |
| `showFooter` | `boolean` | ❌ | `true` | 显示/ 隐藏页脚( 如果提供页脚文本) |
| `borderRadius` | `string | number` | ❌ | `12` | 集装箱边界半径 |
| `border` | `string` | ❌ | `"1px solid #e5e7eb"` | 集装箱边界(CSS边界) |
| `boxShadow` | `string` | ❌ | `"0 10px 25px..."` | 容器阴影 |
| `chatTransparent` | `boolean` | ❌ | `false` | 如果真实, 聊天背景是透明的 |
| `chatBackground` | `string` | ❌ | `"#ffffff"` | 聊天背景颜色 |
| `textColor` | `string` | ❌ | \- 说吧 | 信件文本颜色 |
| `bubbleUserColor` | `string` | ❌ | \- 说吧 | 用户信息泡背景颜色 |
| `bubbleBotColor` | `string` | ❌ | `"#f1f2f4"` | 瓶口信息泡背景颜色. 空字符串 = 默认;文本对比自动调整 |
| `footerColor` | `string` | ❌ | \- 说吧 | 页脚背景颜色 |
| `input` | `EmbedChatInputConfig` | ❌ | \- 说吧 | 输入组合 |
| `customCSS` | `string` | ❌ | \- 说吧 | 聊天自定义 CSS |

* * *

## 通过 API 和事件的动态控制

WebChat 让一个全局API和自定义事件从应用程序的任何地方或浏览器控制台动态控制部件的位置、粘贴和能见度 .

### WebChat 全球方法

```js
window.openWebChat();           // Open the floating chat
window.closeWebChat();          // Close the floating chat
window.toggleWebChat();         // Toggle open/close
window.unmountWebChat();        // Unmount the floating chat
window.mountWebChat();          // Mount the floating chat if it was unmounted
window.hideWebChat();           // Hide the chat (display: none)
window.showWebChat();           // Show the chat if it was hidden
window.injectWebChatCSS(css);   // Inject custom CSS into the shadow DOM
window.removeWebChatCSS();      // Remove custom CSS
window.setWebChatPosition(obj); // Change position/padding dynamically
```

### 嵌入式全球方法

```js
window.unmountEmbedChat(elementId); // Unmount the EmbedChat instance for the given elementId
window.mountEmbedChat(elementId);   // Mount the EmbedChat instance again (with the last used config)
```

-   `window.unmountEmbedChat(elementId)`: 从指定的元素中卸载 EmbedChat 实例。 最后一个配置已保存 .
-   `window.mountEmbedChat(elementId)`: 使用该元素所用的最后一个配置在指定的元素中重载 EmbedChat 实例。 如果之前没有使用配置,则在控制台中显示警告.

#### 示例

```js
window.unmountEmbedChat('embed-small'); // Unmounts the chat from the element with id 'embed-small'
window.mountEmbedChat('embed-small');   // Remounts the chat in the same element with the last config
```

### 全球方法

您可以从 Global 窗口对象中编程显示、隐藏或销毁独立的WhatsApp 按钮.

```js
window.WhatsAppButton.initialize(config); // Initializes the standalone widget
window.hideWhatsApp();                    // Hides WhatsApp button (display: none)
window.showWhatsApp();                    // Unhides it
window.unmountWhatsApp();                 // Removes from DOM entirely
```

* * *

### 倾听生命周期消息事件( X)

我们发射 **自定义浏览器事件** 所以,你可以捕捉到相互作用,把它们输入Google Tag管理器,Google分析器,Meta像素,或任何其他分析工具.

| 部件 | 事件名称 | 发射时 | `detail` 有效载数 |
| --- | --- | --- | --- |
| 网络聊天 | `notchatbot-webchat-open` | 浮动聊天打开 | `{ conversationId }` |
| 网络聊天 | `notchatbot-webchat-closed` | 浮式聊天已经关闭 | `{ conversationId }` |
| 网络聊天 | `notchatbot-webchat-message-sent` | 用户发送一个或多个信件 | `{ messages: Message[] }` |
| 网络聊天 | `notchatbot-webchat-message-received` | 从服务器收到信件 | `{ message: Message, role: 'assistant' | 'employee' }` |
| 网络聊天 | `notchatbot-webchat-button-click` | 点击圆形聊天部件激活器按钮 | 不详 |
| 网络聊天 | `notchatbot-chatbubble-popover-click` | 初始演示文稿聊天泡被点击 | 不详 |
| 网络聊天 | `notchatbot-webchat-menu-whatsapp-click` | WebChat 多选项菜单中的WhatsApp 按钮被点击 | 不详 |
| 网络聊天 | `notchatbot-webchat-menu-webchat-click` | 多选项菜单中的标准 Webchat 按钮被点击 | 不详 |
| 怎样 | `notchatbot-whatsapp-button-click` | 单击独立的WhatsApp部件 | 不详 |
| 嵌入聊天器 | `notchatbot-embedchat-message-sent` | 用户发送消息 | `{ message: Message }` |
| 嵌入聊天器 | `notchatbot-embedchat-message-received` | 收到一个消息 | `{ message: Message, role: 'assistant' | 'employee' }` |

`Message` 遵循部件内部使用的相同接口(id、文本、发送者、时间戳等).

#### 快速实例

```js
window.addEventListener('notchatbot-webchat-open',  e => console.log('WebChat opened', e.detail));
window.addEventListener('notchatbot-webchat-closed',  e => console.log('WebChat closed', e.detail));
window.addEventListener('notchatbot-webchat-message-sent', e => console.log('Sent', e.detail.messages));
window.addEventListener('notchatbot-webchat-message-received', e => {
  const { role, message } = e.detail;
  console.log('Received', role, message);
});
```

#### Google 标签管理器 / Google 分析( GA4)

**新来的:** 上面列举的所有事件都会自动推向 **数据 Layer** 与此同时,与窗口事件同时发生! 这意味着你可以在 GTM 中创建触发器 `notchatbot-webchat-message-sent` 或者说 `notchatbot-whatsapp-button-click` 右出盒子, 不写手动JS事件听众.

如果您更喜欢自定义的数据结构,或者您需要清晰地映射信件内容,您仍然可以听 `window` 事件并手动推入数据Layer:

```js
window.addEventListener('notchatbot-webchat-message-sent', e => {
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: 'webchat_message_sent',
    messages: e.detail.messages,
    conversationId: e.detail.messages[0]?.conversationId || null
  });
});
```

在GTM中,加一个 **自定义事件** 调用触发 `webchat_message_sent` (或 `notchatbot-webchat-message-sent` 并链接到 GA4 事件标记.

#### Meta / Facebook 像素

```js
window.addEventListener('notchatbot-webchat-open', () => {
  if (window.fbq) {
    fbq('trackCustom', 'WebChatOpened');
  }
});

window.addEventListener('notchatbot-webchat-message-received', e => {
  if (window.fbq) {
    fbq('trackCustom', 'WebChatMessageReceived', {
      role: e.detail.role
    });
  }
});
```

这些事件使得在不修改源代码的情况下,很容易测量由聊天部件驱动的约定和转换.

### 动态改变位置并加载( WebChat)

#### 1\. 全球情况变化和比值(平面)

```js
window.setWebChatPosition({
  position: 'bottom-left',
  marginBottom: 40,
  marginSide: 30
});
```

#### 2\. 仅用于移动的更改

```js
window.setWebChatPosition({
  mobile: {
    position: 'bottom-right',
    marginBottom: 100,
    marginSide: 20
  }
});
```

#### 3\. 只更改桌面

```js
window.setWebChatPosition({
  desktop: {
    position: 'bottom-left',
    marginBottom: 60,
    marginSide: 40
  }
});
```

#### 4\. 使用设备格式进行更改

```js
window.setWebChatPosition({
  device: 'mobile',
  marginBottom: 120,
  marginSide: 15
});
```

### 使用自定义事件( addCustomPadding并打开/ 关闭控制)

您可以在应用程序的任意位置发送事件以更改粘贴/边距或打开/关闭聊天:

#### 1\. 打开、关闭或切换浮动的网络聊天

```js
window.dispatchEvent(new CustomEvent('openWebChatbot'));
window.dispatchEvent(new CustomEvent('closeWebChatbot'));
window.dispatchEvent(new CustomEvent('toggleWebChatbot'));
```

#### 2\. 改变两个设备的垫(平面)

```js
window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { y: 100, x: 30 } }));
```

#### 3\. 仅用于移动的更改

```js
window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { device: 'mobile', marginBottom: 120, marginSide: 20 } }));
```

#### 4\. 只更改桌面

```js
window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: { device: 'desktop', marginBottom: 60, marginSide: 40 } }));
```

#### 5\. 使用嵌入对象更改

```js
window.dispatchEvent(new CustomEvent('addCustomPadding', { detail: {
  mobile: { marginBottom: 90, marginSide: 10 },
  desktop: { marginBottom: 50, marginSide: 30 }
}}));
```

### 接受对象格式

-   **平地 :** `{ marginBottom, marginSide, position }` (如果移动/台式电脑没有覆盖,则适用于两者)
-   **通过设备:** `{ device: 'mobile'|'desktop', marginBottom, marginSide }`
-   **嵌入:** `{ mobile: { ... }, desktop: { ... } }`
-   **别名:** `{ y, x }` (单位:千美元)`y` - 比特顿, `x` • 差值

您可以根据需要合并这些格式.

### 在 WebChat 中注入并删除自定义 CSS

您可以使用全球 API 在浮动 WebChat 中注入热CSS :

```js
// Change the header background color
window.injectWebChatCSS(`
  #notchatbot-webchat-header {
    background: #111 !important;
    color: #fff !important;
  }
`);

// Hide the floating button
window.injectWebChatCSS(`#notchatbot-webchat-button { display: none !important; }`);

// Change the chat window width
window.injectWebChatCSS(`#notchatbot-webchat-window { width: 500px !important; }`);

// Change the floating button color
window.injectWebChatCSS(`#notchatbot-webchat-button { background: #f59e0b !important; }`);

// Remove all custom styles
window.removeWebChatCSS();
```

#### WebChat 的内部元素ID

您可以使用这些ID来选择和样式部件的特定部分 :

-   `#notchatbot-webchat-button` — 浮动聊天按钮
-   `#notchatbot-webchat-header` —聊天窗口头
-   `#notchatbot-webchat-window` —主聊天窗口

修改标题和按钮颜色的示例 :

```js
window.injectWebChatCSS(`
  #notchatbot-webchat-header { background: #222 !important; color: #fff !important; }
  #notchatbot-webchat-button { background: #f59e0b !important; }
`);
```

您可以把这些选择器组合起来, 完全定制部件 .

#### 信息泡的稳定类

信息泡(WebChat and EmbedChat) 搭载稳定类,安全可瞄准来自 `injectWebChatCSS` 或者说 `customCSS`数字 :

-   `.nbc-bot-bubble` ——瓶/剂信息泡
-   `.nbc-user-bubble` - 访客信息泡泡
-   `.nbc-bubble-tail` - 每个气泡上角的小尾巴

泡泡背景画有 `var(--nbc-bubble-bg, <configured color>)`,尾部和可选菜单会逐渐消失。 文本(信息、时间、回复引文和菜单图标)用 `var(--nbc-bubble-fg, <computed text color>)`设置自定义属性,而不是 `background` 编号 : `color` 所以一切都会一起改变,没有 `!important`数字 :

```js
window.injectWebChatCSS(`
  .nbc-bot-bubble { --nbc-bubble-bg: #e0f2fe; }
  .nbc-user-bubble { --nbc-bubble-bg: #1e293b; --nbc-bubble-fg: #ffffff; }
`);
```

默认文本颜色是从所配置的颜色计算出来的( )`bubbleBotColor` / 主色调),不是来自 CSS 覆盖. 当覆盖变化很大时, 也会设置 `--nbc-bubble-fg` 在同一类(平地) `color` 或更喜欢 `bubbleBotColor` 选项,可自动选择可读文本.

* * *

## 常见问题

### @developer\.notchatbot/webchat 是什么？

具有单文件捆绑的漂亮回放聊天器部件

### 如何安装 @developer\.notchatbot/webchat？

在项目目录运行 npm install @developer\.notchatbot/webchat，或使用 pnpm add / yarn add / bun add。

### @developer\.notchatbot/webchat 支持 TypeScript 吗？

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

### @developer\.notchatbot/webchat 支持 ESM 还是 CommonJS？

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

### @developer\.notchatbot/webchat 可以商用吗？

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

### @developer\.notchatbot/webchat 的下载量有多少？

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

### @developer\.notchatbot/webchat 还在维护吗？

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