沉浸式閱讀程式 JavaScript SDK 參考 （v1.4）
沉浸式閱讀程式 SDK 包含 JavaScript 連結庫，可讓您將 沉浸式閱讀程式 整合到應用程式中。
您可以使用 npm、 yarn或 HTML <script> 元素，在 Web 應用程式中包含最新穩定組建的連結庫：
<script type='text/javascript' src='https://ircdname.azureedge.net/immersivereadersdk/immersive-reader-sdk.1.4.0.js'></script>
npm install @microsoft/immersive-reader-sdk
yarn add @microsoft/immersive-reader-sdk
函式
SDK 會公開這些函式：
功能： launchAsync
ImmersiveReader.launchAsync(token, subdomain, content, options)會在 Web 應用程式中的 HTML iframe 元素內啟動 沉浸式閱讀程式。 內容的大小限制為最多 50 MB。
launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;
| 參數 | 類型 | 描述 |
|---|---|---|
| token | 字串 | Microsoft Entra 驗證令牌。 若要深入瞭解，請參閱如何建立 沉浸式閱讀程式 資源。 |
| subdomain | 字串 | Azure 中 沉浸式閱讀程式 資源的自定義子域。 |
| content | 內容 | 物件，其中包含要顯示在 沉浸式閱讀程式 中的內容。 |
| 電子商務選項中 | 選項 | 設定 沉浸式閱讀程式 特定行為的選項。 選擇性。 |
傳回
傳Promise<LaunchResponse>回 ，它會在載入 沉浸式閱讀程式 時解析。 會 Promise 解析為 LaunchResponse 物件。
例外狀況
如果 沉浸式閱讀程式 無法載入，則傳回的 Promise 會以 Error 物件拒絕。
功能： close
ImmersiveReader.close()會關閉 沉浸式閱讀程式。
此函式的範例使用案例是，如果結束按鈕是藉由在選項中設定hideExitButton: true來隱藏。 然後，不同的按鈕（例如，行動標頭的返回箭號）可以在按兩下時呼叫此 close 函式。
close(): void;
功能： renderButtons
如果您使用 How to customize the 沉浸式閱讀程式 button guidance，則不需要函ImmersiveReader.renderButtons(options)式。
此函式會樣式並更新檔的 沉浸式閱讀程式 按鈕元素。 如果 options.elements 提供 ，則會在 中 options.elements提供的每個元素內轉譯按鈕。 options.elements當您檔中有多個區段可啟動 沉浸式閱讀程式，並想要簡化的方式來轉譯具有相同樣式的多個按鈕，或想要使用簡單且一致的設計模式來轉譯按鈕時，使用 參數會很有用。 若要搭配 renderButtons 選項 參數使用此函式，請在頁面載入上呼叫 ImmersiveReader.renderButtons(options: RenderButtonsOptions); ，如下列代碼段所示。 否則，按鈕會在具有 類別immersive-reader-button的檔元素內轉譯，如如何自定義 沉浸式閱讀程式 按鈕所示。
// This snippet assumes there are two empty div elements in
// the page HTML, button1 and button2.
const btn1: HTMLDivElement = document.getElementById('button1');
const btn2: HTMLDivElement = document.getElementById('button2');
const btns: HTMLDivElement[] = [btn1, btn2];
ImmersiveReader.renderButtons({elements: btns});
如需更多轉譯選項，請參閱啟動按鈕選擇性屬性。 若要使用這些選項，請將任何選項屬性新增至 HTMLDivElement 頁面 HTML 中的每個選項屬性。
renderButtons(options?: RenderButtonsOptions): void;
| 參數 | 類型 | 描述 |
|---|---|---|
| 電子商務選項中 | renderButtons 選項 | 設定 renderButtons 函式特定行為的選項。 選擇性。 |
renderButtons 選項
用於轉譯 沉浸式閱讀程式 按鈕的選項。
{
elements: HTMLDivElement[];
}
| 參數 | 類型 | 描述 |
|---|---|---|
| 項目 | HTMLDivElement[] | 要呈現中 沉浸式閱讀程式 按鈕的專案。 |
Type: HTMLDivElement[]
Required: false
啟動按鈕
SDK 會提供 沉浸式閱讀程式 啟動按鈕的預設樣式。 使用 immersive-reader-button 類別屬性來啟用此樣式。 如需詳細資訊，請參閱如何自定義 沉浸式閱讀程式 按鈕。
<div class='immersive-reader-button'></div>
使用下列選擇性屬性來設定按鈕的外觀和風格。
| 屬性 | 描述 |
|---|---|
| data-button-style | 設定按鈕的樣式。 可以是 icon、text 或 iconAndText。 預設為 icon。 |
| data-locale | 設定地區設定。 例如，en-US 或 fr-FR。 預設為英文 en。 |
| data-icon-px-size | 以像素為單位設定圖示的大小。 預設值為 20 px。 |
LaunchResponse
包含呼叫 ImmersiveReader.launchAsync的回應。 您可以透過 container.firstChild存取包含 沉浸式閱讀程式 的 HTML iframe 元素參考。
{
container: HTMLDivElement;
sessionId: string;
charactersProcessed: number;
}
| 參數 | 類型 | 描述 |
|---|---|---|
| 容器 | HTMLDivElement | 包含 沉浸式閱讀程式 iframe 專案的 HTML 專案。 |
| sessionId | String | 此工作階段的全域唯一標識碼，用於偵錯。 |
| charactersProcessed | 數值 | 已處理的字元總數 |
錯誤
包含錯誤的相關信息。
{
code: string;
message: string;
}
| 參數 | 類型 | 描述 |
|---|---|---|
| code | String | 其中一組錯誤碼。 |
| message | String | 人類可讀取的錯誤表示法。 |
| 錯誤碼 | 描述 |
|---|---|
| BadArgument | 提供的自變數無效。 請參閱 message 錯誤的參數。 |
| Timeout | 沉浸式閱讀程式 無法在指定的逾時內載入。 |
| TokenExpired | 提供的令牌已過期。 |
| 調整執行速度 | 已超過通話速率限制。 |
類型
Content
包含要顯示在 沉浸式閱讀程式 中的內容。
{
title?: string;
chunks: Chunk[];
}
| 參數 | 類型 | 描述 |
|---|---|---|
| 標題 | String | 沉浸式閱讀程式 頂端顯示的標題文字 （選擇性） |
| 塊 | Chunk[] | 區塊陣列 |
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null
區塊
單一數據區塊，會傳遞至 沉浸式閱讀程式 的內容。
{
content: string;
lang?: string;
mimeType?: string;
}
| 參數 | 類型 | 描述 |
|---|---|---|
| content | String | 字串，包含傳送至 沉浸式閱讀程式 的內容。 |
| lang | String | 文字的語言，值是以 IETF BCP 47語言 標記格式，例如 en、es-ES。 如果未指定，系統會自動偵測語言。 如需詳細資訊，請參閱支援的語言。 |
| mimeType | 字串 | 支援純文本、MathML、HTML 和 Microsoft Word DOCX 格式。 如需詳細資訊，請參閱 支援的MIME類型。 |
content
Type: String
Required: true
Default value: null
lang
Type: String
Required: false
Default value: Automatically detected
mimeType
Type: String
Required: false
Default value: "text/plain"
支援的MIME類型
| MIME 類型 | 描述 |
|---|---|
| text/plain | 純文本。 |
| text/html | HTML 內容。 |
| application/mathml+xml | 數學標記語言 （MathML）。 |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | Microsoft Word .docx格式檔。 |
選項。
包含屬性，這些屬性會設定 沉浸式閱讀程式 的特定行為。
{
uiLang?: string;
timeout?: number;
uiZIndex?: number;
useWebview?: boolean;
onExit?: () => any;
customDomain?: string;
allowFullscreen?: boolean;
parent?: Node;
hideExitButton?: boolean;
cookiePolicy?: CookiePolicy;
disableFirstRun?: boolean;
readAloudOptions?: ReadAloudOptions;
translationOptions?: TranslationOptions;
displayOptions?: DisplayOptions;
preferences?: string;
onPreferencesChanged?: (value: string) => any;
disableGrammar?: boolean;
disableTranslation?: boolean;
disableLanguageDetection?: boolean;
}
| 參數 | 類型 | 描述 |
|---|---|---|
| uiLang | String | UI 的語言，此值是以 IETF BCP 47 語言 標記格式，例如 en、es-ES。 如果未指定，預設為瀏覽器語言。 |
| timeout | 數字 | launchAsync 失敗前的持續時間（以毫秒為單位），並出現逾時錯誤（預設值為15,000毫秒）。 此逾時僅適用於讀取器頁面的初始啟動，當讀取器頁面成功開啟且啟動微調程式時。 不應該調整逾時。 |
| uiZIndex | 數字 | 所建立 HTML iframe 專案的 Z 索引（預設值為 1000）。 |
| useWebview | 布林值 | 使用 Webview 標籤而非 HTML iframe 元素，以與 Chrome Apps 相容（預設值為 false）。 |
| onExit | 函式 | 當 沉浸式閱讀程式 結束時執行。 |
| customDomain | String | 保留為內部使用。 裝載 沉浸式閱讀程式 webapp 的自定義網域（預設值為 null）。 |
| allowFullscreen | 布林值 | 切換全螢幕的能力（預設值為 true）。 |
| parent | 節點 | 放置 HTML iframe 專案或 Webview 容器的節點。 如果專案不存在，iframe 會放在 中 body。 |
| hideExitButton | 布林值 | 隱藏 沉浸式閱讀程式 的結束按鈕箭號（預設值為 false）。 只有當提供替代機制結束 沉浸式閱讀程式 時，這個值才應為 true（例如，行動工具列的返回箭號）。 |
| cookiePolicy | CookiePolicy | 設定 沉浸式閱讀程式 的 Cookie 使用量（預設值為 CookiePolicy.Disable）。 在歐盟 Cookie 合規性政策之後，主機應用程式必須負責取得任何必要的使用者同意。 如需詳細資訊，請參閱 Cookie 原則選項。 |
| disableFirstRun | 布林值 | 停用第一次執行體驗。 |
| readAloudOptions | ReadAloudOptions | 設定大聲讀取的選項。 |
| translationOptions | TranslationOptions | 設定翻譯的選項。 |
| displayOptions | DisplayOptions | 設定文字大小、字型、主題等的選項。 |
| 偏好 | String | 從 onPreferencesChanged 傳回的字串，代表使用者 沉浸式閱讀程式 中的喜好設定。 如需詳細資訊，請參閱 如何儲存使用者喜好設定。 |
| onPreferencesChanged | 函式 | 當使用者的喜好設定變更時執行。 如需詳細資訊，請參閱 如何儲存使用者喜好設定。 |
| disableTranslation | 布林值 | 停用文字和文件翻譯體驗。 |
| disableGrammar | 布林值 | 停用文法體驗。 此選項也會停用音節、語音部分和圖片字典，這相依於語音部分。 |
| disableLanguageDetection | 布林值 | 停用語言偵測，以確保 沉浸式閱讀程式 只會使用在 Content/Chunk[] 上明確指定的語言。 此選項應該謹慎使用，主要是在語言偵測無法運作的情況下。 例如，此問題更有可能發生於少於 100 個字元的簡短段落。 您應該確定要傳送的語言，因為文字到語音轉換不會有正確的語音。 如果語言不正確，語音和圖片字典的音節、部分語音和圖片字典無法正確運作。 |
uiLang
Type: String
Required: false
Default value: User's browser language
timeout
Type: Number
Required: false
Default value: 15000
uiZIndex
Type: Number
Required: false
Default value: 1000
onExit
Type: Function
Required: false
Default value: null
preferences
Type: String
Required: false
Default value: null
警告
請勿嘗試以程式設計方式變更傳送至沈浸式閱讀程式應用程式和從沈浸式閱讀程式應用程式傳送的 -preferences 字串值，因為這可能會導致非預期的行為，進而使得使用者體驗降級。 主應用程式絕對不應為 -preferences 字串指派自訂值或操作該字串。 使用 -preferences 字串選項時，只使用從 -onPreferencesChanged 回呼選項傳回的確切值。
onPreferencesChanged
Type: Function
Required: false
Default value: null
customDomain
Type: String
Required: false
Default value: null
ReadAloudOptions
type ReadAloudOptions = {
voice?: string;
speed?: number;
autoplay?: boolean;
};
| 參數 | 類型 | 描述 |
|---|---|---|
| voice | String | 語音，無論是 女性 還是 男性。 並非所有語言都支援兩種性別。 |
| 速度 | 數字 | 播放速度。 必須介於 0.5 和 2.5 之間，包含。 |
| autoPlay | 布林值 | 當 沉浸式閱讀程式 載入時，自動開始大聲讀取。 |
注意
由於瀏覽器限制，Safari 不支援自動播放。
voice
Type: String
Required: false
Default value: "Female" or "Male" (determined by language)
Values available: "Female", "Male"
speed
Type: Number
Required: false
Default value: 1
Values available: 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2, 2.25, 2.5
TranslationOptions
type TranslationOptions = {
language: string;
autoEnableDocumentTranslation?: boolean;
autoEnableWordTranslation?: boolean;
};
| 參數 | 類型 | 描述 |
|---|---|---|
| 語言 | String | 設定翻譯語言，此值是以 IETF BCP 47 語言 標記格式，例如 fr-FR、es-MX、zh-Hans-CN。 自動啟用文字或文件翻譯的必要專案。 |
| autoEnableDocumentTranslation | 布林值 | 自動翻譯整份檔。 |
| autoEnableWordTranslation | 布林值 | 自動啟用文字翻譯。 |
language
Type: String
Required: true
Default value: null
Values available: For more information, see the Supported languages section
ThemeOption
enum ThemeOption { Light, Dark }
DisplayOptions
type DisplayOptions = {
textSize?: number;
increaseSpacing?: boolean;
fontFamily?: string;
themeOption?: ThemeOption
};
| 參數 | 類型 | 描述 |
|---|---|---|
| textSize | 數字 | 設定所選的文字大小。 |
| increaseSpacing | 布林值 | 設定是否開啟或關閉文字間距。 |
| fontFamily | String | 設定所選字型 （Calibri、 ComicSans 或 Sitka）。 |
| themeOption | ThemeOption | 設定讀者選擇的主題（淺色、深色）。 |
textSize
Type: Number
Required: false
Default value: 20, 36 or 42 (Determined by screen size)
Values available: 14, 20, 28, 36, 42, 48, 56, 64, 72, 84, 96
fontFamily
Type: String
Required: false
Default value: "Calibri"
Values available: "Calibri", "Sitka", "ComicSans"
CookiePolicy 選項
enum CookiePolicy { Disable, Enable }
下列設定僅供參考之用。 沉浸式閱讀程式 會將其設定或用戶喜好設定儲存在 Cookie 中。 此 cookiePolicy 選項 預設會停用 使用 Cookie，以遵循歐盟 Cookie 合規性法。 如果您想要重新啟用 Cookie 並還原 沉浸式閱讀程式 使用者喜好設定的預設功能，您的網站或應用程式需要使用者的適當同意，才能啟用 Cookie。 然後，若要在 沉浸式閱讀程式 中重新啟用 Cookie，您必須在啟動 沉浸式閱讀程式 時，將 cookiePolicy 選項明確設定為 CookiePolicy.Enable。
下表描述啟用 cookiePolicy 選項時，沉浸式閱讀程式 儲存在其 Cookie 中的設定。
| 設定 | 類型 | 描述 |
|---|---|---|
| textSize | 數字 | 設定所選的文字大小。 |
| fontFamily | String | 設定所選字型 （Calibri、 ComicSans 或 Sitka）。 |
| textSpacing | 數字 | 設定是否開啟或關閉文字間距。 |
| formattingEnabled | 布林值 | 設定是否開啟或關閉 HTML 格式設定。 |
| 佈景主題 | String | 設定所選的主題（淺色、深色）。 |
| syllabificationEnabled | 布林值 | 設定是否開啟或關閉教學大綱。 |
| nounHighlightingEnabled | 布林值 | 設定是否開啟或關閉名詞醒目提示。 |
| nounHighlightingColor | String | 設定所選的名詞醒目提示色彩。 |
| verbHighlightingEnabled | 布林值 | 設定動詞醒目提示是否開啟或關閉。 |
| verbHighlightingColor | String | 設定所選動詞醒目提示色彩。 |
| adjectiveHighlightingEnabled | 布林值 | 設定是否開啟或關閉形容詞醒目提示。 |
| adjectiveHighlightingColor | String | 設定所選的形容詞醒目提示色彩。 |
| adverbHighlightingEnabled | 布林值 | 設定是否開啟或關閉反白顯示。 |
| adverbHighlightingColor | String | 設定所選的反白顯示色彩。 |
| pictureDictionaryEnabled | 布林值 | 設定是否開啟或關閉圖片字典。 |
| posLabelsEnabled | 布林值 | 設定是否開啟或關閉每個醒目提示的語音部分的上標文字標籤。 |
支援的語言
沉浸式閱讀程式的翻譯功能支援多種語言。 如需詳細資訊，請參閱語言支援。
HTML 支援
啟用格式設定時，下列內容會在 沉浸式閱讀程式 中轉譯為 HTML。
| HTML | 支援的內容 |
|---|---|
| 字型樣式 | 粗體、斜體、底線、代碼、刪除線、上標、下標 |
| 未排序的清單 | 光碟、圓圈、方形 |
| 已排序的清單 | Decimal、upper-Alpha、lower-Alpha、upper-Roman、lower-Roman、lower-Roman |
不受支援的標籤可比較轉譯。 目前不支援映像和數據表。
瀏覽器支援
使用下列瀏覽器的最新版本，以獲得最佳 沉浸式閱讀程式 體驗。
- Microsoft Edge
- Google Chrome
- Mozilla Firefox
- Apple Safari