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 行為準則的詳細信息，請參閱我們的行為準則頁面。
查看安全文件以了解有關報告安全問題的更多資訊。
