BotFramework WebChat
[4.18.0] - 2024-07-10
此存储库包含 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 开发人员使用~ （波形符范围）来选择次要版本，其中包含新功能和/或修复。使用^ （插入符号范围）选择主要版本，其中可能包含重大更改。
在此版本中，我们专注于性能改进，包括内存和加载时间优化。
机器人现在可以直播他们的回答。在 Bot Framework SDK 支持此功能之前，机器人作者可以按照 LIVESTREAMING.md 中的详细信息构建直播响应。
Web Chat 现在导出为 ES 模块（命名导出）以及 CommonJS（命名和未命名导出）。
最终用户现在可以在将文件上传到机器人之前添加消息并确认。要选择退出新体验，请在样式选项中传递sendAttachmentOn: 'send' 。
我们很高兴添加主题包支持。开发人员现在可以将所有自定义打包到一个包中并将其发布到 NPM。
我们很高兴地宣布 Fluent UI 主题包正在开发中，目前处于实验阶段。该主题包专为希望为客户带来原生 Copilot 用户体验的 Web 开发人员而设计。
我们将继续添加新功能，并以同等水平同时支持白标体验和 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 >
) ;
} Web Chat 现在将在 Markdown 中呈现 HTML。我们已经将我们的清理程序和辅助功能修复程序移植到 HTML 级别。 Markdown 和 HTML-in-Markdown 都将受到相同的处理，并满足我们的安全性和可访问性要求。
您可以通过将styleOptions.markdownRenderHTML设置为false来关闭此选项。
Web Chat 现在支持自适应卡架构最高可达 1.6。自适应卡中的某些功能处于预览状态或设计为在 Bot Framework 之外使用。网络聊天不支持这些功能。
从 4.16.0 开始，不再支持 Internet Explorer。在 Internet Explorer 11 正式退役一年多后，我们决定停止支持 Internet Explorer。这将帮助我们为网络聊天带来新功能。 4.15.9 是最后一个以有限方式支持 Internet Explorer 的版本。
adaptiveCardsParserMaxVersionWeb Chat 4.12.1 补丁包含一个新的样式属性，允许开发人员选择最大自适应卡架构版本。有关代码更改，请参阅 PR #3778。
要指定不同的最大版本，您可以调整样式选项，如下所示：
window . WebChat . renderWebChat (
{
directLine ,
store ,
styleOptions : {
adaptiveCardsParserMaxVersion : '1.2'
}
} ,
document . getElementById ( 'webchat' )
) ;PR #3703 中的 Web Chat 添加了新的辅助功能更新。默认情况下，此更改为转录本（粗体黑色边框）和aria-activedescendent聚焦活动（黑色虚线边框）创建视觉焦点。在适用的情况下， transcriptVisualKeyboardIndicator...值也将应用于轮播（ CarouselFilmStrip.js ）子项。这样做是为了匹配自适应卡的当前默认焦点样式，该卡可能是轮播的子项。
要修改这些样式，您可以通过styleOptions更改以下属性：
transcriptActivityVisualKeyboardIndicatorColor: DEFAULT_SUBTLE,
transcriptActivityVisualKeyboardIndicatorStyle: 'dashed',
transcriptActivityVisualKeyboardIndicatorWidth: 1,
transcriptVisualKeyboardIndicatorColor: 'Black',
transcriptVisualKeyboardIndicatorStyle: 'solid',
transcriptVisualKeyboardIndicatorWidth: 2,
上面的代码显示了您将在网络聊天中看到的默认值。
Web Chat API 已重构为单独的包。要了解更多信息，请查看 API 重构摘要。
从 Web Chat 4.7.0 开始，支持 Direct Line Speech，这是在 Web Chat 中提供集成语音功能的首选方式。我们正在努力缩小 Direct Line Speech 和 Web Speech API（包括认知服务和浏览器提供的语音功能）之间的功能差距。
从 Web Chat 4.6.0 开始，Web Chat 需要 React 16.8.6 或更高版本。
尽管我们建议您尽早升级主机应用程序，但我们知道主机应用程序可能需要一些时间才能更新其 React 依赖项，特别是对于大型应用程序。
如果您的应用程序尚未准备好使用 React 16.8.6，您可以按照混合 React 示例在您的应用程序中使用双主机 React。
网络聊天中有关语音和输入提示的行为预期发生了重大变化。详细信息请参阅4.5.0之前的输入提示行为部分。
查看迁移文档以了解如何从 Web Chat v3 进行迁移。
首先，使用 Azure 机器人服务创建一个机器人。创建机器人后，您将需要在 Azure 门户中获取机器人的 Web 聊天密钥。然后使用该密钥生成令牌并将其传递到您的网络聊天。
Web 聊天在 Direct Line 和 Direct Line 语音通道之上提供 UI。有两种方法可以通过客户端的 HTTP 调用连接到您的机器人：发送机器人密钥或通过密钥生成令牌。
我们强烈建议使用令牌 API，而不是向应用程序提供您的密钥。要了解更多原因，请参阅有关令牌 API 和客户端安全性的身份验证文档。
如需进一步阅读，请参阅以下链接：
将 Web 聊天与 Azure Bot 服务身份验证结合使用
增强的 Direct Line 身份验证功能
Web Chat 旨在使用 JavaScript 或 React 与您现有的网站集成。与 JavaScript 集成将为您提供适度的样式和可定制性选项。
您可以使用完整的、典型的 Web 聊天包（称为全功能包），其中包含最常用的功能。
以下是将网络聊天控件添加到您的网站的方法：
<!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 聊天道具的更多信息，请参阅 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 的 GitHubmain分支同步的开发版本。
请参阅通过 React 呈现的 Web Chat 的工作示例。
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 <ReactWebChat directLine={directLine} store={store} userID="YOUR_USER_ID" />;
};使用 Redux DevTools 时存在一些限制：
redux-saga使用副作用。时间旅行可能会破坏用户界面。网络聊天被设计为可定制，无需分叉源代码。下表概述了当您以不同方式导入 Web Chat 时可以实现的自定义类型。此列表并不详尽。
| CDN 捆绑 | 反应 | |
|---|---|---|
| 改变颜色 | ✔ | ✔ |
| 改变尺寸 | ✔ | ✔ |
| 更新/替换 CSS 样式 | ✔ | ✔ |
| 聆听事件 | ✔ | ✔ |
| 与托管网页交互 | ✔ | ✔ |
| 自定义渲染活动 | ✔ | |
| 自定义渲染附件 | ✔ | |
| 添加新的 UI 组件 | ✔ | |
| 重构整个UI | ✔ |
请参阅有关自定义 Web 聊天的更多信息，了解有关自定义的更多信息。
Bot Framework 有多种活动类型，但并非所有活动类型都在 Web Chat 中受支持。查看活动类型文档以了解更多信息。
查看 Web 聊天示例的完整列表，了解有关自定义 Web 聊天的更多想法。
查看用于实施 Web 聊天的 API 文档。
网络聊天支持最新 2 个版本的现代浏览器，例如 Chrome、Microsoft Edge 和 FireFox。如果您需要 Internet Explorer 11 中的 Web 聊天，请参阅 ES5 捆绑演示。
但请注意：
babel将代码从 ES6+ 转换为 ES5。 查看辅助功能文档。
查看用于在 Web Chat 中实施的本地化文档。
查看在 Web Chat 中实施的通知文档。
查看用于在网络聊天中实施的遥测文档。
在提交新问题之前，请查看技术支持指南，获取有关 Web Chat 存储库中的故障排除的指导和帮助，以获取更多信息。
网络聊天支持多种语音引擎，可实现与机器人的自然聊天体验。本节概述了支持的不同引擎：
Direct Line Speech 是在网络聊天中添加语音功能的首选方式。有关详细信息，请参阅 Direct Line Speech 文档。
您可以使用认知服务语音服务向 Web 聊天添加语音功能。有关详细信息，请参阅认知服务语音服务文档。
您还可以使用任何支持 W3C Web Speech API 标准的语音引擎。某些浏览器支持语音识别 API 和语音合成 API。您可以混合搭配不同的引擎（包括认知服务语音服务）以提供最佳的用户体验。
Web Chat 的最新信息可在 Web Chat 每日发布页面上找到。
每日任务将在太平洋标准时间凌晨 3:00 之后发布，届时主分支已提交更改。
请参阅我们的贡献页面，了解有关如何构建项目的详细信息以及我们的拉取请求存储库指南。
有关 Microsoft 行为准则的详细信息，请参阅我们的行为准则页面。
查看安全文档以了解有关报告安全问题的更多信息。
