Web 聊天概述

项目
11/11/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 参考部分。

与 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 时，有三条可能的迁移路径。将你的初始方案与下面列出的方案进行比较。

若要升级嵌入在 <iframe> 中的 Web 聊天控件，请参阅 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，并且许多使用箭头函数和新式 Promise 的示例需要手动转换为 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 密钥）可在安全技术中心中找到。

通过