你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Web 聊天概述

项目
01/18/2024

适用于： SDK v4

本文包含 Bot Framework Web Chat 组件的详细信息。 Bot Framework Web Chat 组件是一个基于 Web 的高度可自定义客户端，用于 Bot Framework V4 SDK。 Bot Framework SDK v4 使开发人员能够创建对话模型并生成复杂的机器人应用程序。

如果想要从 Web Chat v3 迁移到 v4，请跳转到迁移部分。

Web 聊天入门

注意

要获取 Web Chat (v3) 的之前版本，请访问 Web Chat v3 分支。

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

以下示例演示如何向网站添加Web 聊天控件。

<!DOCTYPE html>
<html>
   <body>
      <div id="webchat" role="main"></div>
      <script src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"></script>
      <script>

         // Set style options.
         const styleOptions = {
            botAvatarInitials: 'BF',
            userAvatarInitials: 'WC'
         };

         window.WebChat.renderWebChat(
            {
               directLine: window.WebChat.createDirectLine({
                  token: 'YOUR_DIRECT_LINE_TOKEN'
               }),
               userID: 'YOUR_USER_ID',
               username: 'Web Chat User',
               locale: 'en-US',
               styleOptions
            },
            document.getElementById('webchat')
         );
      </script>
   </body>
</html>

userID、username、locale、botAvatarInitials 和 userAvatarInitials 是要传递到 renderWebChat 方法的全部可选参数。有关样式的详细信息，请参阅 “为什么 styleOptions？”。若要详细了解Web 聊天属性，请参阅Web 聊天 API 参考部分。

此外，如果机器人是区域机器人（这意味着机器人资源位于“全局”以外的区域），则必须通过在方法中的其他domainwindow.WebChat.createDirectLine()字段中设置它来指定区域直接线 URL。将域指定为任一域 europe.webchat.botframework.com， unitedstates.webchat.botframework.com 或 india.webchat.botframework.com指定适合所选区域的任何域。阅读 “接听欧洲电话：在欧盟存储和处理欧盟数据，了解有关数据驻留的信息。

与 JavaScript 进行集成

Web Chat 用于集成使用 JavaScript 或 React 的现有网站。与 JavaScript 集成可提供一些样式和可自定义性，有关详细信息，请参阅将Web 聊天集成到网站中。

可以使用包含最常用的功能的完整典型 botframework-webchat 包。

<!DOCTYPE html>
<html>
   <body>
      <div id="webchat" role="main"></div>
      <script src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"></script>
      <script>
         window.WebChat.renderWebChat(
            {
               directLine: window.WebChat.createDirectLine({
                  token: 'YOUR_DIRECT_LINE_TOKEN'
               }),
               userID: 'YOUR_USER_ID'
            },
            document.getElementById('webchat')
         );
      </script>
   </body>
</html>

请参阅完整的 Web Chat 捆绑包的有效示例。

与 React 集成

要获得完全可自定义性，可使用 React 重新组织 Web Chat 组件。

若要从 npm 安装生产版本，请运行 npm install botframework-webchat。

import { DirectLine } from 'botframework-directlinejs';
import React from 'react';
import ReactWebChat from 'botframework-webchat';

export default class extends React.Component {
  constructor(props) {
    super(props);

    this.directLine = new DirectLine({ token: 'YOUR_DIRECT_LINE_TOKEN' });
  }

  render() {
    return (
      <ReactWebChat directLine={ this.directLine } userID='YOUR_USER_ID' />
      element
    );
  }
}

此外，还可运行 npm install botframework-webchat@master 以安装与 Web Chat 的 GitHub master 分支同步的开发版本。

请参阅通过 React 呈现的 Web Chat 的有效示例。

提示

如果你不熟悉 React 和 jsx，可以在 Reacts 入门页上找到培训。

自定义 Web Chat UI

Web Chat 是可自定义的，无需创建源代码分支。下表概述了在以不同方式导入Web 聊天时可以实现的自定义类型。此列表并不详尽。

自定义	CDN 捆绑包	React
更改颜色	✔	✔
更改大小	✔	✔
更新/替换 CSS 样式	✔	✔
侦听事件	✔	✔
与托管网页进行交互	✔	✔
自定义呈现活动		✔
自定义呈现附件		✔
添加新 UI 组件		✔
重新组织整个 UI		✔

请参阅自定义 Web Chat，以获取有关自定义的详细信息。

注意

有关内容分发网络 (CDN) 的信息，请参阅内容分发网络 (CDN)

从 Web Chat v3 迁移到 v4

从 v3 迁移到 v4 时，有三条可能的迁移路径。将开始方案与下面列出的方案进行比较。

若要升级嵌入在Web 聊天<iframe>控件中，请参阅嵌入包Web 聊天存储库中的文档。
若要升级几乎没有自定义项的Web 聊天控件，请查看描述该过程的 Web 聊天 00.migration/a.v3-to-v4 示例。
若要升级高度自定义Web 聊天的分叉版本，请参阅Web 聊天迁移指南。

Web Chat API 参考

你可能会将几个属性传递到 Web Chat React 组件 (<ReactWebChat>) 或 renderWebChat() 方法。有关可用属性的简短说明，请参阅Web 聊天 API 参考。此外，请随时检查源代码 packages/component/src/Composer.js。

浏览器兼容性

Web Chat 支持新式浏览器（如 Chrome、Microsoft Edge 和 FireFox）的最近 2 个版本。如果需要在 Internet Explorer 11 中Web 聊天，请参阅 ES5 捆绑包和演示。

Web 聊天不支持低于版本 11 的 Internet Explorer
Internet Explorer 不支持自定义，如非 ES5 示例所示。由于 IE11 是非新式浏览器，因此它不支持 ES6，并且许多使用箭头函数和新式承诺的示例需要手动转换为 ES5。如果你需要对应用进行大量自定义，我们强烈建议为新式浏览器（如 Google Chrome 或 Edge）开发应用。
Web Chat 不打算支持 IE11 (ES5) 的示例。
对于想要手动重写其他示例以便在 IE11 中工作的客户，建议使用填充代码和 transpiler（如 babel）查看从 ES6+ 到 ES5 的代码转换。

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

此时只能通过 MyGet 包装测试未发布的功能。

如果要测试尚未发布的功能或 bug 修复，则需要将Web 聊天包指向Web 聊天的每日源，而不是官方 npmjs 源。

目前，可以通过订阅我们的 MyGet 源来访问 Web Chat 的日报。为此，需要更新项目中的注册表。此更改是可逆的，我们的指导包括如何还原到订阅正式版本。

在 `myget.org` 上订阅最新位

为此，可以添加包，然后更改项目注册表。

添加项目依赖项而非 Web Chat。
在项目的根目录中，创建 .npmrc 文件
将以下行添加到你的文件：registry=https://botbuilder.myget.org/F/botframework-webchat/npm/
将 Web Chat 添加到项目依赖项 npm i botframework-webchat --save
package-lock.json在你的注册表中，指向的注册表现在是 MyGet。 Web Chat 项目已启用上游源代理，这会将非 MyGet 包重定向到 npmjs.com。

重新订阅正式发布 `npmjs.com`

重新订阅要求重置注册表。

删除 .npmrc file
删除根 package-lock.json
删除 node_modules 目录
使用 npm i 重新安装包
package-lock.json在你的注册表中，注册表将再次指向https://npmjs.com/。

贡献

请参阅参与页，详细了解如何生成项目，以及用于拉取请求的存储库指南。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答；若有其他任何问题或意见，请联系 opencode@microsoft.com。

报告安全问题

应通过电子邮件以非公开方式向 Microsoft 安全响应中心 (MSRC) secure@microsoft.com 报告安全问题和 bug。你应该会在 24 小时内收到答复。如果出于某种原因，请通过电子邮件跟进，确保收到原始邮件。详细信息（包括 MSRC PGP 密钥）可在安全技术中心中找到。