你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

沉浸式阅读器 JavaScript SDK 参考（v1.4）

项目
09/01/2024

沉浸式阅读器 SDK 包含 JavaScript 库，它使你能够将沉浸式阅读器集成在应用程序中。

可以使用 npmHTML yarn<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 公开以下函数：

ImmersiveReader.launchAsync（token， subdomain， content， options）
ImmersiveReader.close（）
ImmersiveReader.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	string	Microsoft Entra 身份验证令牌。若要了解详细信息，请参阅如何创建沉浸式阅读器资源。
subdomain	string	Azure 中沉浸式阅读器资源的自定义子域。
content	内容	包含要显示在沉浸式阅读器中的内容的对象。
选项	选项	用于配置沉浸式阅读器的某些行为的选项。可选。

返回 Promise<LaunchResponse>，它可以解析加载沉浸式阅读器的时间。解析 Promise 为 LaunchResponse 对象。

异常

如果沉浸式阅读器无法加载，则返回Promise的会被拒绝并显示 Error 对象。

功能： `close`

ImmersiveReader.close()关闭沉浸式阅读器。

此函数的一个示例用例是通过设置“选项”中的 hideExitButton: true 来确定退出按钮是否处于隐藏状态。然后，其他按钮（例如移动标头的后退箭头）可以在单击时调用此 close 函数。

close(): void;

功能： `renderButtons`

ImmersiveReader.renderButtons(options)如果使用 How to customize the 沉浸式阅读器 button guidance，则不需要该函数。

此函数设置并更新文档的沉浸式阅读器按钮元素。如果 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});

有关更多呈现选项，请参阅启动按钮可选属性。若要使用这些选项，请将任何选项属性添加到页面 HTML 中的每个 HTMLDivElement 属性。

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 像素。

LaunchResponse

包含对 ImmersiveReader.launchAsync 的调用的响应。可以通过访问container.firstChild包含沉浸式阅读器的 HTML iframe 元素的引用。

{
    container: HTMLDivElement;
    sessionId: string;
    charactersProcessed: number;
}

参数	类型	说明
container	HTMLDivElement	包含沉浸式阅读器 `iframe` 元素的 HTML 元素。
sessionID	字符串	此会话的全局唯一标识符，用于调试。
charactersProcessed	数字	处理的字符总数

错误

包含有关错误的信息。

{
    code: string;
    message: string;
}

参数	类型	说明
code	字符串	一组错误代码的其中一个。
message	字符串	错误的用户可读表示形式。

错误代码	说明
BadArgument	提供的参数无效。请参阅 `message` 错误的参数。
超时	沉浸式阅读器无法在指定的超时内加载。
TokenExpired	提供的令牌已过期。
已中止	超出了调用速率限制。

类型

内容

包含要在沉浸式阅读器中显示的内容。

{
    title?: string;
    chunks: Chunk[];
}

参数	类型	说明
职务	字符串	沉浸式阅读器顶部显示的标题文本（可选）
区块	[]	区块数组

`title`

Type: String
Required: false
Default value: "Immersive Reader"

`chunks`

Type: Chunk[]
Required: true
Default value: null

Chunk

传入沉浸式阅读器内容的单个数据块。

{
    content: string;
    lang?: string;
    mimeType?: string;
}

参数	类型	描述
内容	字符串	包含发送到沉浸式阅读器的内容的字符串。
lang	字符串	文本的语言，该值采用 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 类型 (MIME type)	说明
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	字符串	UI 的语言，该值采用 IETF BCP 47 语言标记格式，例如 en、es-ES。如果未指定，则默认为浏览器语言。
timeout	Number	launchAsync 失败并出现超时错误的持续时间（以毫秒为单位，默认值为 15,000 ms）。此超时仅适用于阅读器页面的初始启动，此时阅读器页面成功打开且微调器启动。不应调整超时。
uiZIndex	Number	创建的 HTML `iframe` 元素的 Z 索引（默认值为 1000）。
useWebview	布尔	使用 Webview 标记而不是 HTML `iframe` 元素，以便与 Chrome 应用兼容（默认值为 false）。
onExit	函数	沉浸式阅读器退出时执行。
customDomain	字符串	保留以供内部使用。托管沉浸式阅读器 Web 应用的自定义域（默认值为 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	用于配置文本大小、字体、主题等的选项。
preferences	字符串	从 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	字符串	语音，女性或男性。并非所有语言都支持这两种性别。
速度	Number	播放速度。必须介于 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;
};

参数	类型	说明
语言	字符串	设置翻译语言，该值采用 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	Number	设置所选的文本大小。
increaseSpacing	布尔	设置开启还是关闭文本间距。
fontFamily	字符串	设置所选字体（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	Number	设置所选的文本大小。
fontFamily	字符串	设置所选字体（Calibri、 ComicSans 或 Sitka）。
textSpacing	Number	设置开启还是关闭文本间距。
formattingEnabled	布尔	设置开启还是关闭 HTML 格式设置。
Theme — 主题	字符串	设置所选主题（浅色、深色）。
syllabificationEnabled	布尔	设置开启还是关闭音节划分。
nounHighlightingEnabled	布尔	设置开启还是关闭名词突出显示。
nounHighlightingColor	字符串	设置所选的名词突出显示颜色。
verbHighlightingEnabled	布尔	设置开启还是关闭谓词突出显示。
verbHighlightingColor	字符串	设置所选的谓词突出显示颜色。
adjectiveHighlightingEnabled	布尔	设置开启还是关闭形容词突出显示。
adjectiveHighlightingColor	字符串	设置所选的形容词突出显示颜色。
adverbHighlightingEnabled	布尔	设置开启还是关闭副词突出显示。
adverbHighlightingColor	字符串	设置所选的副词突出显示颜色。
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

错误

类型

内容

title

chunks

Chunk

content

lang

mimeType

支持的 MIME 类型

选项

uiLang

timeout

uiZIndex

onExit

preferences

onPreferencesChanged

customDomain