BotFramework 网络聊天

单击此处了解网络聊天中的新增功能

Bot 框架网络聊天

此存储库包含 Bot Framework Web 聊天组件的代码。 Bot Framework Web 聊天组件是 Bot Framework v4 SDK 的高度可定制的基于 Web 的客户端。 Bot Framework SDK v4 使开发人员能够对对话进行建模并构建复杂的机器人应用程序。

该存储库是 Microsoft Bot Framework 的一部分，这是一个用于构建企业级对话式 AI 体验的综合框架。

Web 聊天支持内容安全策略 (CSP)。建议 Web 开发人员启用 CSP 以提高安全性并保护对话。您可以在本文中阅读有关 CSP 的更多信息。

---

版本说明

本节指出重要的版本注释。有关更多信息，请参阅相关链接并查看CHANGELOG.md

注意：建议 Web 开发人员使用~ （波形符范围）来选择次要版本，其中包含新功能和/或修复。使用^ （插入符号范围）选择主要版本，其中可能包含重大更改。

4.19.0 显着变化

• 支持直播中的信息提示

4.18.0 显着变化

在此版本中，我们专注于性能改进，包括内存和加载时间优化。

4.17.0 显着变化

支持直播回复

机器人现在可以直播他们的回答。在 Bot Framework SDK 支持此功能之前，机器人作者可以按照 LIVESTREAMING.md 中的详细信息构建直播响应。

ES模块首次亮相

Web Chat 现在与 CommonJS（命名和未命名导出）一起导出为 ES 模块（命名导出）。

改进文件上传体验

最终用户现在可以在将文件上传到机器人之前添加消息并确认。要选择退出新体验，请在样式选项中传递sendAttachmentOn: 'send' 。

主题包支持

我们很高兴添加主题包支持。开发人员现在可以将所有自定义打包到一个包中并将其发布到 NPM。

实验性 Fluent UI 主题包

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

我们将继续添加新功能，并以同等水平支持白标体验和 Fluent UI 体验。

您可以使用封装 Web Chat 来尝试新体验。

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

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

支持 HTML-in-Markdown

Web Chat 现在将在 Markdown 中呈现 HTML。我们已经将我们的清理程序和辅助功能修复程序移植到 HTML 级别。 Markdown 和 HTML-in-Markdown 都将受到相同的处理，并满足我们的安全性和可访问性要求。

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

4.16.1 显着变化

Web Chat 现在支持高达 1.6 的自适应卡架构。自适应卡中的某些功能处于预览状态或设计为在 Bot Framework 之外使用。网络聊天不支持这些功能。

4.16.0 显着变化

从 4.16.0 开始，不再支持 Internet Explorer。在 Internet Explorer 11 正式退役一年多后，我们决定停止支持 Internet Explorer。这将帮助我们为网络聊天带来新功能。 4.15.9 是最后一个以有限方式支持 Internet Explorer 的版本。

4.12.1补丁：新样式属性adaptiveCardsParserMaxVersion

Web Chat 4.12.1 补丁包含一个新的样式属性，允许开发人员选择最大自适应卡架构版本。有关代码更改，请参阅 PR #3778。

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

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

• 默认情况下，网络聊天将根据自适应卡版本（截至此补丁，架构 1.3）应用可用的最大架构。
• 无效版本将恢复为 Web Chat 的默认版本。

网络聊天 4.12.0 中的文字焦点更改为视觉焦点

PR #3703 中的 Web Chat 添加了新的辅助功能更新。默认情况下，此更改为转录本（粗体黑色边框）和aria-activedescendent聚焦活动（黑色虚线边框）创建视觉焦点。在适用的情况下， transcriptVisualKeyboardIndicator...值也将应用于轮播（ CarouselFilmStrip.js ）子项。这样做是为了匹配自适应卡当前的默认焦点样式，该卡可能是轮播的子项。

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

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

上面的代码显示了您将在网络聊天中看到的默认值。

API 重构为 Web Chat 4.11.0 中的新包

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 中的语音更改

网络聊天中有关语音和输入提示的行为预期发生了重大变化。详细信息请参阅4.5.0之前的输入提示行为部分。

从 Web Chat v3 迁移到 v4

查看迁移文档以了解如何从 Web Chat v3 进行迁移。

---

如何使用

首先，使用 Azure 机器人服务创建一个机器人。创建机器人后，您将需要在 Azure 门户中获取机器人的 Web 聊天密钥。然后使用该密钥生成令牌并将其传递到您的网络聊天。

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

Web 聊天在 Direct Line 和 Direct Line 语音通道之上提供 UI。有两种方法可以通过客户端的 HTTP 调用连接到您的机器人：发送机器人密钥或通过密钥生成令牌。

我们强烈建议使用令牌 API，而不是向应用程序提供您的密钥。要了解更多原因，请参阅有关令牌 API 和客户端安全性的身份验证文档。

如需进一步阅读，请参阅以下链接：

• 将 Web 聊天与 Azure Bot 服务身份验证结合使用

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

与 JavaScript 集成

Web Chat 旨在使用 JavaScript 或 React 与您现有的网站集成。与 JavaScript 集成将为您提供适度的样式和可定制性选项。

您可以使用完整的、典型的 Web 聊天包（称为全功能包），其中包含最常用的功能。

以下是将网络聊天控件添加到您的网站的方法：

">

 >
< 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 聊天道具的更多信息，请参阅 Web 聊天 API 参考文档。

不建议将userID分配为静态值，因为这会导致所有用户共享状态。请参阅API userID entry以获取更多信息。

有关本地化的更多信息可以在本地化文档中找到。

请参阅完整网络聊天包的工作示例。

与反应集成

为了实现完全的可定制性，您可以使用 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 构建中作为一项可选功能启用。

这是为了了解网络聊天的工作原理。这不是 API 浏览器，也不认可使用 Redux 存储以编程方式访问 UI。应改用 hooks API。

要使用 Redux DevTools，请使用createStoreWithDevTools函数来创建支持 Redux DevTools 的存储。

; };">

  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 ;
  };

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

• Redux 存储通过redux-saga使用副作用。时间旅行可能会破坏用户界面。
• 许多 UI 状态存储在 React 上下文和状态中。它们不会暴露在 Redux 存储中。
• 一些时间敏感的 UI 基于实时时钟，不受时间旅行的影响。
• 调度操作不受官方支持。请改用 hooks API。
• 操作和减速器可以跨版本移入和移出 Redux 存储。 Hooks API 是用于访问 UI 的官方 API。

自定义网络聊天 UI

网络聊天被设计为可定制，无需分叉源代码。下表概述了以不同方式导入网络聊天时可以实现的自定义类型。此列表并不详尽。

	CDN 捆绑	反应
改变颜色	✔	✔
改变尺寸	✔	✔
更新/替换 CSS 样式	✔	✔
聆听事件	✔	✔
与托管网页交互	✔	✔
自定义渲染活动		✔
自定义渲染附件		✔
添加新的 UI 组件		✔
重构整个UI		✔

请参阅有关自定义 Web 聊天的更多信息，了解有关自定义的更多信息。

Web 聊天客户端支持的活动类型

Bot Framework 有多种活动类型，但并非所有活动类型都在 Web Chat 中受支持。查看活动类型文档以了解更多信息。

样品清单

查看 Web 聊天示例的完整列表，了解有关自定义 Web 聊天的更多想法。

进一步阅读

API参考

查看用于实施 Web 聊天的 API 文档。

浏览器兼容性

网络聊天支持最新 2 个版本的现代浏览器，例如 Chrome、Microsoft Edge 和 FireFox。如果您需要 Internet Explorer 11 中的 Web 聊天，请参阅 ES5 捆绑演示。

但请注意：

• 网络聊天不支持早于版本 11 的 Internet Explorer
• Internet Explorer 不支持非 ES5 示例中所示的自定义。由于 IE11 是非现代浏览器，它不支持 ES6，并且许多使用箭头函数和现代 Promise 的示例需要手动转换为 ES5。如果您需要对应用程序进行大量自定义，我们强烈建议您为 Google Chrome 或 Microsoft Edge 等现代浏览器开发应用程序。
• Web Chat 没有计划支持 IE11 (ES5) 的示例。
  • 对于希望手动重写我们的其他示例以在 IE11 中工作的客户，我们建议考虑使用 polyfill 和转译器（如babel将代码从 ES6+ 转换为 ES5。

无障碍

查看辅助功能文档。

本土化

查看用于在 Web Chat 中实施的本地化文档。

通知

查看在 Web Chat 中实施的通知文档。

遥测

查看用于在网络聊天中实施的遥测文档。

技术支持指南

在提交新问题之前，请查看技术支持指南，以获取有关 Web Chat 存储库中的故障排除的指导和帮助，以获取更多信息。

演讲

网络聊天支持多种语音引擎，可实现与机器人的自然聊天体验。本节概述了支持的不同引擎：

• 直线语音
• 认知服务 语音服务
• 浏览器提供的引擎或其他引擎

与 Direct Line Speech 集成

Direct Line Speech 是在网络聊天中添加语音功能的首选方式。有关详细信息，请参阅 Direct Line Speech 文档。

与认知服务语音服务集成

您可以使用认知服务语音服务向 Web 聊天添加语音功能。有关详细信息，请参阅认知服务语音服务文档。

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

您还可以使用任何支持 W3C Web Speech API 标准的语音引擎。某些浏览器支持语音识别 API 和语音合成 API。您可以混合搭配不同的引擎（包括认知服务语音服务）以提供最佳的用户体验。

---

如何使用 Web Chat 的最新功能进行测试

Web Chat 的最新信息可在 Web Chat 每日发布页面上找到。

每日任务将在太平洋标准时间凌晨 3:00 之后发布，届时主分支已提交更改。

贡献

请参阅我们的贡献页面，了解有关如何构建项目的详细信息以及我们的拉取请求存储库指南。

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

报告安全问题

查看安全文档以了解有关报告安全问题的更多信息。