沉浸式閱讀程式 JavaScript SDK 參考（v1.4）

發行項
09/01/2024

沉浸式閱讀程式 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 會公開這些函式：

沈浸式Reader.launchAsync（token，子域，內容，選項）
沈浸式Reader.close（）
沈浸式Reader.renderButtons（選項）

功能： `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

後續步驟

探索沉浸式閱讀程式 SDK

共用方式為

沉浸式閱讀程式 JavaScript SDK 參考 （v1.4）

函式

功能： launchAsync

傳回

例外狀況

功能： close

功能： renderButtons

renderButtons 選項

啟動按鈕

LaunchResponse

錯誤

類型

Content

title

chunks

區塊

content

lang

mimeType

支援的MIME類型

選項。

uiLang

timeout

uiZIndex

onExit

preferences

onPreferencesChanged

customDomain