你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
如何存储用户首选项
本文演示如何通过 -preferences 和 -onPreferencesChanged 沉浸式阅读器 SDK 选项存储用户的 UI 设置或用户首选项。
如果将 CookiePolicy SDK 选项设置为“已启用”，沉浸式阅读器应用程序将会通过使用 Cookie 存储用户首选项，例如文本大小、主题颜色和字体。 这些 Cookie 是特定浏览器和设备本地的。 每当用户在同一浏览器和设备上启动沉浸式阅读器时，它都会按照用户在该设备上最后一次会话的用户首选项打开。 但如果用户在其他浏览器或设备上打开沉浸式阅读器应用，该设置最初将会使用沉浸式阅读器的默认设置进行配置，用户则需要为其使用的每台设备再次设置其首选项。。 -preferences 和 -onPreferencesChanged 沉浸式阅读器 SDK 选项为应用程序提供了一种在各种浏览器和设备上漫游用户首选项的方法，这样无论用户在何处使用应用程序都能获得一致的体验。
首先，通过在启动沉浸式阅读器应用程序时提供 -onPreferencesChanged 回调 SDK 选项，每当用户在沉浸式阅读器会话期间更改其首选项时，沉浸式阅读器都会将 -preferences 字符串发送回主机应用程序。 然后，主机应用程序负责在其自己的系统中存储用户首选项。 接着，当同一用户再次启动沉浸式阅读器时，主机应用程序可以从存储中检索该用户的首选项，并在启动沉浸式阅读器应用程序时将其作为 -preferences 字符串 SDK 选项提供，以便还原用户的首选项。
在无需使用 Cookie 或使用 Cookie 不可行的情况下，此功能可用作存储用户首选项的替代方法。
注意
不要尝试以编程方式更改发送到或来自沉浸式读取器应用程序的 -preferences 字符串值，因为这可能会导致意外行为，致使用户体验降级。 主机应用程序不应将自定义值分配给 -preferences 字符串或操作该字符串。 使用 -preferences 字符串选项时，请仅使用从 -onPreferencesChanged 回调选项返回的确切值。
启用存储用户首选项
沉浸式阅读器 SDK launchAsyncoptions 参数包含 -onPreferencesChanged 回调。 每当用户更改其首选项时，都将调用此函数。 value 参数包含一个字符串，该字符串表示用户的当前首选项。 然后，由主机应用程序为该用户存储此字符串。
const options = {
onPreferencesChanged: (value: string) => {
// Store user preferences here
}
};
ImmersiveReader.launchAsync(YOUR_TOKEN, YOUR_SUBDOMAIN, YOUR_DATA, options);
首选项 JSON 结构示例
下面是 value 参数解析后的样子以及每个字段的类型的示例：
{
"displayOptionsState": {
"textSize": "number",
"fontFamily": "string",
"textSpacing": "number",
"formattingEnabled": "boolean",
"theme": "string",
"themeSetByUser": "boolean",
"syllabificationEnabled": "boolean",
"nounHighlightingEnabled": "boolean",
"nounHighlightingColor": "string",
"verbHighlightingEnabled": "boolean",
"verbHighlightingColor": "string",
"adjectiveHighlightingEnabled": "boolean",
"adjectiveHighlightingColor": "string",
"adverbHighlightingEnabled": "boolean",
"adverbHighlightingColor": "string",
"pictureDictionaryEnabled": "boolean",
"posLabelsEnabled": "boolean"
},
"readAloudState": {
"readAloudSpeed": "number",
"voice": "string"
},
"translationState": {
"shouldTranslateWords": "boolean",
"translationLanguage": "string" // encoded JSON
}
}
下面是 translationLanguage 解码后的 JSON 示例。
{
"text": "string",
"key": "string",
"data": {
"tlc": "string",
"slc": "string"
}
}
加载用户首选项
使用 -preferences 选项将用户的首选项传递给沉浸式阅读器应用。 一个存储和加载用户首选项的普通示例如下所示：
const storedUserPreferences = localStorage.getItem("USER_PREFERENCES");
let userPreferences = storedUserPreferences === null ? null : storedUserPreferences;
const options = {
preferences: userPreferences,
onPreferencesChanged: (value: string) => {
userPreferences = value;
localStorage.setItem("USER_PREFERENCES", userPreferences);
}
};