沉浸式閱讀程式 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 string Microsoft Entra 驗證令牌。 若要深入瞭解，請參閱如何建立 沉浸式閱讀程式 資源。
子域 string 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 字串，包含傳送至 沉浸式閱讀程式 的內容。
朗 String 文字的語言，值是以 IETF BCP 47語言 標記格式，例如 en、es-ES。 如果未指定，系統會自動偵測語言。 如需詳細資訊，請參閱支援的語言。
mimeType string 支援純文本、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

後續步驟

探索 沉浸式閱讀程式 SDK