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 行為準則的詳細信息，請參閱我們的行為準則頁面。

報告安全問題

查看安全文件以了解有關報告安全問題的更多資訊。