点击此处了解 Web Chat 的最新功能

Bot Framework Web Chat

本仓库包含 Bot Framework Web Chat 组件的代码。Bot Framework Web Chat 组件是一个高度可定制的、基于 Web 的客户端，用于 Bot Framework v4 SDK。Bot Framework SDK v4 使开发者能够建模对话并构建复杂的机器人应用。

本仓库是 Microsoft Bot Framework 的一部分 —— 这是一个用于构建企业级对话式 AI 体验的综合性框架。

Web Chat 支持 内容安全策略（Content Security Policy, CSP）。建议 Web 开发者启用 CSP 以提升安全性并保护对话内容。您可以在这篇文章中了解更多关于 CSP 的信息。

注意：Bot Framework SDK 已于 2025 年 12 月在 GitHub 上归档。但 本 Web Chat 组件 并未 归档，仍可在 GitHub 上获取，并遵循本 README 中所述的相关许可证。

---

版本说明

本节指出重要的版本说明。如需进一步信息，请参阅相关链接并查看 CHANGELOG.md

我们的成就

注意：建议 Web 开发者使用 ~（波浪号范围） 来选择次版本号，其中包含新功能和/或修复。使用 ^（脱字符范围） 来选择主版本号，其中可能包含破坏性变更。

4.19.0 主要变更

• 在 直播流（livestreaming） 中支持信息性消息

4.18.0 主要变更

本次发布聚焦于性能改进，包括内存和加载时间的优化。

4.17.0 主要变更

支持直播流响应

机器人现在可以直播其响应内容。在 Bot Framework SDK 正式支持此功能之前，机器人开发者可参考 LIVESTREAMING.md 中的详细说明来构造直播流响应。

ES 模块（ES Modules）首次亮相

Web Chat 现在同时导出 ES 模块（命名导出）和 CommonJS（命名及未命名导出）。

文件上传体验改进

最终用户现在可以在将文件上传给机器人之前添加消息并确认。若要禁用此新体验，可在样式选项中传入 sendAttachmentOn: 'send'。

主题包（Theme pack）支持

我们很高兴地宣布新增主题包支持。开发者现在可以将其所有自定义内容打包成一个单独的包并发布到 NPM。

实验性 Fluent UI 主题包

我们很高兴地宣布 Fluent UI 主题包正在开发中，目前处于实验阶段。该主题包专为希望为其客户带来原生 Copilot 用户体验的 Web 开发者设计。

我们将继续添加新功能，并确保白标（white-label）体验与 Fluent UI 体验具有同等水平的功能支持。

您可以通过 <FluentThemeProvider> 包裹 Web Chat 来试用新体验：

import ReactWebChat from 'botframework-webchat';
import { FluentThemeProvider } from 'botframework-webchat-fluent-theme';

export default function MyComponent() {
   return (
      <FluentThemeProvider>
         <ReactWebChat />
      </FluentThemeProvider>
   );
}

支持 Markdown 中嵌入 HTML（HTML-in-Markdown）

Web Chat 现在将渲染 Markdown 中嵌入的 HTML。我们已将清理器（sanitizer）和无障碍修复器移植到 HTML 层级工作。Markdown 和 Markdown 中嵌入的 HTML 将受到相同的处理，并满足我们的安全性和无障碍要求。

您可以通过将 styleOptions.markdownRenderHTML 设置为 false 来关闭此选项。

4.16.1 主要变更

Web Chat 现在支持 最高至 1.6 版本的 Adaptive Cards schema。Adaptive Cards 中的部分功能处于预览状态，或专为 Bot Framework 之外的场景设计。Web Chat 不支持这些功能。

4.16.0 主要变更

从 4.16.0 版本开始，不再支持 Internet Explorer。在 Internet Explorer 11 官方退役一年多之后，我们决定停止对其支持。这将帮助我们为 Web Chat 引入新功能。4.15.9 是最后一个以有限方式支持 Internet Explorer 的版本。

4.12.1 补丁：新增样式属性 adaptiveCardsParserMaxVersion

Web Chat 4.12.1 补丁新增了一个样式属性，允许开发者选择 Adaptive Cards schema 的最大版本。有关代码变更，请参见 PR #3778。

要指定不同的最大版本，您可以调整样式选项，如下所示：

window.WebChat.renderWebChat(
   {
      directLine,
      store,
      styleOptions: {
         adaptiveCardsParserMaxVersion: '1.2'
      }
   },
   document.getElementById('webchat')
);

• Web Chat 默认会根据 Adaptive Cards 版本应用可用的最大 schema（截至此补丁，默认为 schema 1.3）。
• 如果指定无效版本，则会回退到 Web Chat 的默认值。

Web Chat 4.12.0 中对话记录（transcript）的视觉焦点变更

从 PR #3703 开始，Web Chat 新增了一项无障碍更新。此变更默认为对话记录添加视觉焦点（粗黑边框），并为 aria-activedescendent 聚焦的活动项添加黑色虚线边框。在适用的情况下，transcriptVisualKeyboardIndicator... 的值也会应用于轮播图（CarouselFilmStrip.js）的子元素，以匹配当前 Adaptive Cards 的默认焦点样式（Adaptive Cards 可能是轮播图的子元素）。

要修改这些样式，您可以通过 styleOptions 更改以下属性：

  transcriptActivityVisualKeyboardIndicatorColor: DEFAULT_SUBTLE,
  transcriptActivityVisualKeyboardIndicatorStyle: 'dashed',
  transcriptActivityVisualKeyboardIndicatorWidth: 1,
  transcriptVisualKeyboardIndicatorColor: 'Black',
  transcriptVisualKeyboardIndicatorStyle: 'solid',
  transcriptVisualKeyboardIndicatorWidth: 2,

以上代码展示了 Web Chat 中的默认值。

Web Chat 4.11.0 中的 API 重构为新包

Web Chat API 已被重构为一个独立的包。欲了解更多信息，请参阅 API 重构摘要。

Web Chat 4.7.0 中的 Direct Line Speech 支持

从 Web Chat 4.7.0 开始，支持 Direct Line Speech（直连语音），这是在 Web Chat 中提供集成语音功能的推荐方式。我们正在努力弥合 Direct Line Speech 与 Web Speech API（包括认知服务和浏览器提供的语音功能）之间的功能差距。

升级到 4.6.0

从 Web Chat 4.6.0 开始，Web Chat 要求 React 版本为 16.8.6 或更高。

尽管我们建议您尽早升级宿主应用，但我们理解某些宿主应用（尤其是大型应用）可能需要一些时间才能更新其 React 依赖项。

如果您的应用尚未准备好升级到 React 16.8.6，可以参考 混合 React 示例，在您的应用中同时托管两个 React 版本。

Web Chat 4.5.0 中的语音变更

Web Chat 中关于语音和输入提示（input hint）的行为期望存在一项破坏性变更。详情请参阅 4.5.0 之前的输入提示行为 章节。

从 Web Chat v3 迁移到 v4

请查看迁移文档，了解如何从 Web Chat v3 迁移。

---

如何使用

首先，使用 Azure Bot Service（Azure 机器人服务） 创建一个机器人。
创建完成后，您需要在 Azure 门户中获取机器人的 Web Chat 密钥（secret）。然后使用该密钥生成令牌（token），并将其传递给您的 Web Chat。

将客户端应用连接到机器人

Web Chat 在 Direct Line 和 Direct Line Speech 通道之上提供了用户界面。有两种方式可通过客户端的 HTTP 调用连接到您的机器人：直接发送机器人密钥，或通过密钥生成令牌。

我们强烈建议使用令牌 API，而不是将密钥直接提供给应用。要了解原因，请参阅关于令牌 API 和客户端安全性的身份验证文档。

更多阅读材料，请参见以下链接：

• 使用 Web Chat 与 Azure Bot Services 身份验证

• 增强的 Direct Line 身份验证功能

通过 JavaScript 集成

Web Chat 设计用于通过 JavaScript 或 React 与您现有的网站集成。使用 JavaScript 集成可提供中等程度的样式和自定义选项。

您可以使用包含最常用功能的完整版 Web Chat 包（称为全功能捆绑包，full-feature bundle）。

以下是将 Web Chat 控件添加到您网站的方法：

<!DOCTYPE html>
<html>
  <head>
    <script
      crossorigin="anonymous"
      src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"
    ></script>
    <style>
      html,
      body {
         height: 100%;
      }

      body {
        margin: 0;
      }

      #webchat {
        height: 100%;
        width: 100%;
      }
    </style>
  </head>
  <body>
    <div id="webchat" role="main"></div>
    <script>
      window.WebChat.renderWebChat(
        {
          directLine: window.WebChat.createDirectLine({
            token: 'YOUR_DIRECT_LINE_TOKEN'
          }),
          userID: 'YOUR_USER_ID',
          username: 'Web Chat User',
          locale: 'en-US'
        },
        document.getElementById('webchat')
      );
    </script>
  </body>
</html>

userID、username 和 locale 都是传递给 renderWebChat 方法的可选参数。要了解更多关于 Web Chat 属性（props）的信息，请查阅 Web Chat API 参考文档。

不建议将 userID 设置为静态值，因为这会导致所有用户共享相同的状态。更多信息请参阅 API userID 条目。

有关本地化的更多信息，请参阅 本地化（Localization） 文档。

请参阅 完整 Web Chat 捆绑包 的工作示例。

通过 React 集成

如需完全自定义，您可以使用 React 重新组合 Web Chat 的组件。

要从 NPM 安装生产版本，请运行 npm install botframework-webchat。有关如何选择版本的信息，请参阅我们的版本说明。

import React, { useMemo } from 'react';
import ReactWebChat, { createDirectLine } from 'botframework-webchat';

export default () => {
  const directLine = useMemo(() => createDirectLine({ token: 'YOUR_DIRECT_LINE_TOKEN' }), []);

  return <ReactWebChat directLine={directLine} userID="YOUR_USER_ID" />;
};

您也可以运行 npm install botframework-webchat@main 来安装与 Web Chat GitHub main 分支同步的开发版本。

请参阅通过 React 渲染的 Web Chat 工作示例。

Redux DevTools 的实验性支持

Web Chat 内部使用 Redux 进行状态管理。Redux DevTools 在 NPM 构建版本中作为可选功能启用。

此功能仅用于快速了解 Web Chat 的内部工作原理。它不是 API 探索工具，也不推荐通过 Redux store 以编程方式访问 UI。应改用 hooks API。

要使用 Redux DevTools，请使用 createStoreWithDevTools 函数来创建启用了 Redux DevTools 的 store。

  import React, { useMemo } from 'react';
- import ReactWebChat, { createDirectLine, createStore } from 'botframework-webchat';
+ import ReactWebChat, { createDirectLine, createStoreWithDevTools } from 'botframework-webchat';

  export default () => {
    const directLine = useMemo(() => createDirectLine({ token: 'YOUR_DIRECT_LINE_TOKEN' }), []);
-   const store = useMemo(() => createStore(), []);
+   const store = useMemo(() => createStoreWithDevTools(), []);

    return <ReactWebChat directLine={directLine} store={store} userID="YOUR_USER_ID" />;
  };

使用 Redux DevTools 时存在一些限制：

• Redux store 通过 redux-saga 使用副作用（side-effects）。时间旅行（time-traveling）可能会破坏 UI。
• 许多 UI 状态存储在 React context 和 state 中，并未暴露在 Redux store 中。
• 某些对时间敏感的 UI 基于实时时钟，不受时间旅行影响。
• 分发（dispatching）action 未被官方支持。请改用 hooks API。
• action 和 reducer 可能在不同版本间移入或移出 Redux store。Hooks API 是访问 UI 的官方 API。

自定义 Web Chat UI

Web Chat 的设计目标是在无需 fork 源代码的情况下实现高度自定义。下表列出了在以不同方式导入 Web Chat 时可实现的自定义类型。此列表并非详尽无遗。

	CDN bundle	React
更改颜色	✔	✔
更改尺寸	✔	✔
更新/替换 CSS 样式	✔	✔
监听事件	✔	✔
与宿主网页交互	✔	✔
自定义渲染活动（activities）		✔
自定义渲染附件（attachments）		✔
添加新的 UI 组件		✔
重组整个 UI		✔

查看更多关于 自定义 Web Chat 的内容，了解如何进行自定义。

Web Chat 客户端支持的 Activity 类型

Bot Framework 提供了多种 activity 类型，但并非全部都在 Web Chat 中受支持。查看 activity 类型文档 以了解更多信息。

示例列表

查看完整的 Web Chat 示例列表，获取更多关于自定义 Web Chat 的灵感。

延伸阅读

API 参考

查看 API 文档 以了解如何实现 Web Chat。

浏览器兼容性

Web Chat 支持 Chrome、Microsoft Edge 和 Firefox 等现代浏览器的最新两个版本。
如果您需要在 Internet Explorer 11 中使用 Web Chat，请参阅 ES5 bundle 示例。

但请注意：

• Web Chat 不支持 Internet Explorer 11 之前的版本。
• 非 ES5 示例中展示的自定义功能不支持 Internet Explorer。由于 IE11 是非现代浏览器，不支持 ES6，许多使用箭头函数和现代 Promise 的示例需要手动转换为 ES5。如果您的应用需要大量自定义，我们强烈建议为 Google Chrome 或 Microsoft Edge 等现代浏览器开发应用。
• Web Chat 没有计划为 IE11（ES5）提供示例支持。
  • 对于希望手动重写我们的其他示例以在 IE11 中运行的客户，我们建议使用 polyfill 和转译器（如 babel）将 ES6+ 代码转换为 ES5。

无障碍（Accessibility）

查看 无障碍文档。

本地化（Localization）

查看 本地化文档，了解如何在 Web Chat 中实现本地化。

通知（Notifications）

查看 通知文档，了解如何在 Web Chat 中实现通知功能。

遥测（Telemetry）

查看 遥测文档，了解如何在 Web Chat 中实现遥测功能。

技术支持指南

在提交新 issue 前，请先查阅 技术支持指南，获取 Web Chat 仓库中故障排查的指导和帮助。

语音（Speech）

Web Chat 支持多种语音引擎，以提供与机器人自然对话的体验。本节概述了支持的不同引擎：

• Direct Line Speech
• Cognitive Services Speech Services
• 浏览器提供的引擎或其他引擎

集成 Direct Line Speech

Direct Line Speech 是在 Web Chat 中添加语音功能的首选方式。详情请参阅 Direct Line Speech 文档。

集成 Cognitive Services Speech Services

您可以使用 Cognitive Services Speech Services 为 Web Chat 添加语音功能。详情请参阅 Cognitive Services Speech Services 文档。

浏览器提供的引擎或其他引擎

你也可以使用任何支持 W3C Web Speech API 标准 的语音引擎。部分浏览器支持 Speech Recognition API（语音识别 API） 和 Speech Synthesis API（语音合成 API）。你可以混合搭配不同的引擎——包括 Cognitive Services Speech Services（认知服务语音服务）——以提供最佳的用户体验。

---

如何使用 Web Chat 的最新版本进行测试

Web Chat 的最新版本可在 Web Chat 每日发布页面 获取。

当有代码提交到 main 分支后，每日构建版本将在太平洋标准时间凌晨 3:00 之后发布。

贡献代码

有关如何构建项目以及 Pull Request（拉取请求）的仓库规范，请参阅我们的 贡献指南页面。

有关 Microsoft 行为准则的详细信息，请参阅我们的 行为准则页面。

报告安全问题

请查看安全文档以了解如何报告安全问题。

BotFramework-WebChat 快速上手指南

环境准备

• 浏览器要求：支持现代浏览器（Chrome、Edge、Firefox、Safari 等），从 v4.16.0 起不再支持 Internet Explorer
• React 项目：若使用 React 集成，需 React 16.8.6 或更高版本
• Bot 服务：需已通过 Azure Bot Service 创建机器人，并获取 Direct Line 密钥或令牌

⚠️ 强烈建议通过后端服务生成 Direct Line 令牌（而非直接在前端使用密钥），以保障安全性。

安装步骤

方式一：CDN 引入（推荐用于简单集成）

无需安装，直接在 HTML 中引入：

<script
  crossorigin="anonymous"
  src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"
></script>

国内访问 CDN 可能较慢，可考虑自行托管 webchat.js 文件或使用国内 CDN 加速服务。

方式二：npm 安装（适用于 React 项目）

npm install botframework-webchat

建议使用 ~（波浪号）指定次要版本以避免破坏性变更，例如："botframework-webchat": "~4.19.0"

基本使用

1. 使用 JavaScript 集成（最简示例）

<!DOCTYPE html>
<html>
  <head>
    <script
      crossorigin="anonymous"
      src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"
    ></script>
    <style>
      html, body { height: 100%; margin: 0; }
      #webchat { height: 100%; width: 100%; }
    </style>
  </head>
  <body>
    <div id="webchat" role="main"></div>
    <script>
      window.WebChat.renderWebChat(
        {
          directLine: window.WebChat.createDirectLine({
            token: 'YOUR_DIRECT_LINE_TOKEN' // 替换为你的 Direct Line 令牌
          }),
          userID: 'user-id',
          username: '用户',
          locale: 'zh-CN'
        },
        document.getElementById('webchat')
      );
    </script>
  </body>
</html>

2. 在 React 项目中使用

import React from 'react';
import ReactWebChat from 'botframework-webchat';

export default function WebChat() {
  return (
    <ReactWebChat
      directLine={window.WebChat.createDirectLine({ token: 'YOUR_DIRECT_LINE_TOKEN' })}
      userID="user-id"
      username="用户"
      locale="zh-CN"
    />
  );
}

请将 YOUR_DIRECT_LINE_TOKEN 替换为通过 Azure Bot Service 获取的有效令牌。