Справочник по SDK JavaScript для иммерсивного средства чтения (v1.2)

SDK иммерсивного средства чтения содержит библиотеку JavaScript, которая позволяет интегрировать иммерсивное средство чтения в ваше приложение.

Вы можете использовать элемент npm, yarn или HTML<script> для включения библиотеки последней стабильной сборки в веб-приложение:

<script type='text/javascript' src='https://ircdname.azureedge.net/immersivereadersdk/immersive-reader-sdk.1.2.0.js'></script>
npm install @microsoft/immersive-reader-sdk
yarn add @microsoft/immersive-reader-sdk

Функции

SDK предоставляет следующие функции:


launchAsync

Запускает иммерсивное средство чтения в элементе HTMLiframe в вашем веб-приложении. Размер вашего контента ограничен максимум 50 МБ.

launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;

Параметры launchAsync

Имя Тип Описание
token строка Маркер проверки подлинности Azure Active Directory. Для получения дополнительной информации см. Как создать ресурс для иммерсивного средства чтения.
subdomain строка Пользовательский поддомен вашего ресурса иммерсивного средства чтения в Azure. Для получения дополнительной информации см. Как создать ресурс для иммерсивного средства чтения.
content Содержимое Объект, содержащий контент, который будет отображаться в иммерсивном средстве чтения.
options Параметры Параметры для настройки определенного поведения иммерсивного средства чтения. Необязательный элемент.

Возвращаемое значение

Возвращает Promise<LaunchResponse>, которое разрешается при загрузке иммерсивного средства чтения. Promise разрешается в объект LaunchResponse.

Исключения

Возвращенный Promise будет отклонен с объектом Error, если иммерсивное средство чтения не загрузится. Для получения дополнительной информации см. коды ошибок.


close

Закрывает иммерсивное средство чтения.

Примером использования этой функции является скрытие кнопки выхода путем настройки hideExitButton: true в параметрах. Затем другая кнопка (например, стрелка назад мобильного заголовка) может вызывать эту функцию close при нажатии.

close(): void;

Кнопка запуска иммерсивного средства чтения

SDK предоставляет стиль по умолчанию для кнопки запуска иммерсивного средства чтения. Используйте атрибут класса immersive-reader-button, чтобы включить этот стиль. Для получения дополнительной информации см. Как настроить кнопку иммерсивного модуля чтения.

<div class='immersive-reader-button'></div>

Необязательные атрибуты

Используйте следующие атрибуты, чтобы настроить внешний вид кнопки.

attribute Описание
data-button-style Устанавливает стиль кнопки. Возможные значения: icon, text или iconAndText. По умолчанию — icon.
data-locale Устанавливает языковой стандарт. Например, en-US или fr-FR. По умолчанию используется английский язык en.
data-icon-px-size Устанавливает размер значка в пикселях. По умолчанию 20 пикселей.

renderButtons

В функции renderButtons нет необходимости, если вы используете руководство по кнопке Как настроить иммерсивное средство чтения.

Эта функция стилизует и обновляет элементы кнопки иммерсивного средства чтения документа. Если 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

Имя Тип Описание
options настройки renderButtons Параметры для настройки определенного поведения функции renderButtons. Необязательный элемент.

Настройки renderButtons

Параметры для отрисовки кнопок иммерсивного средства чтения.

{
    elements: HTMLDivElement[];
}

Параметры настроек renderButtons

Параметр Тип Описание
элементы HTMLDivElement[] Элементы для отрисовки кнопок иммерсивного средства чтения.
elements
Type: HTMLDivElement[]
Required: false

LaunchResponse

Содержит ответ от вызова ImmersiveReader.launchAsync. Ссылку на элемент HTMLiframe, который содержит иммерсивное средство чтения, можно получить через container.firstChild.

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

Параметры LaunchResponse

Параметр Тип Описание
контейнер HTMLDivElement HTML-элемент, содержащий элемент iframe иммерсивного средства чтения.
sessionID Строка Глобальный уникальный идентификатор для этого сеанса, используемый для отладки.
charactersProcessed number Общее количество обработанных символов

Ошибка

Содержит информацию об ошибке.

{
    code: string;
    message: string;
}

Параметры ошибок

Параметр Тип Описание
code Строка Один из набора кодов ошибок. Подробнее этот вопрос раскрыт в Коды ошибок.
message Строка Читаемое представление ошибки.

Коды ошибок

Код Описание
BadArgument Указанный аргумент недействителен, см. параметр messageОшибки.
Время ожидания Не удалось загрузить иммерсивное средство чтения в течение указанного времени ожидания.
TokenExpired Срок действия предоставленного токена истек.
Ожидает повтора Превышен лимит скорости звонков.

Типы

Content

Содержит контент, который будет отображаться в иммерсивном средстве чтения.

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

Параметры содержимого

Имя Тип Описание
title Строка Текст заголовка, отображаемый в верхней части иммерсивного средства чтения (необязательно)
блоки 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 строка Поддерживаются форматы обычного текста, 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 Строка Язык пользовательского интерфейса, значение находится в формате языкового тега IETF BCP 47, например, en, es-ES. По умолчанию используется язык браузера, если он не указан.
timeout Число Продолжительность (в миллисекундах) до того, как launchAsync завершится ошибкой с ошибкой тайм-аута (по умолчанию 15 000 мс). Этот тайм-аут применяется только к первоначальному запуску страницы Reader, когда страница Reader успешно открывается и запускается счетчик. Регулировка тайм-аута не требуется.
uiZIndex Число Z-индекс элемента HTMLiframe, который будет создан (по умолчанию 1000).
useWebview Логическое Используйте тег webview вместо элемента HTMLiframe для совместимости с приложениями Chrome (по умолчанию — false).
onExit Функция Выполняется при выходе из иммерсивного средства чтения.
customDomain Строка Зарезервировано для внутреннего использования. Пользовательский домен, в котором размещено веб-приложение иммерсивного средства чтения (по умолчанию — null).
allowFullscreen Логическое Возможность переключения в полноэкранный режим (по умолчанию true).
родитель Узел Узел, в котором размещается элемент HTMLiframe или контейнер Webview. Если элемент не существует, iframe помещается в body.
hideExitButton Логическое Скрывает стрелку кнопки выхода иммерсивного средства чтения (по умолчанию — false). Это значение должно быть верно только в том случае, если существует альтернативный механизм для выхода из иммерсивного средства чтения (например, стрелка назад на мобильной панели инструментов).
cookiePolicy CookiePolicy Параметр для использования файлов cookie иммерсивного средства чтения (по умолчанию CookiePolicy.Disable). Хост-приложение несет ответственность за получение любого необходимого согласия пользователя согласно Политике соответствия ЕС в отношении файлов cookie. Дополнительные сведения см. в разделе Параметры политики файлов cookie.
disableFirstRun Логическое Отключите первый запуск.
readAloudOptions ReadAloudOptions Параметры для настройки чтения вслух.
translationOptions TranslationOptions Параметры для настройки перевода.
displayOptions DisplayOptions Параметры для настройки размера текста, шрифта, темы и т. п.
предпочтения Строка Строка, возвращенная из onPreferencesChanged, представляющая предпочтения пользователя в иммерсивном средстве чтения. Для получения дополнительной информации см. Параметры настроек и Как сохранить настройки пользователя.
onPreferencesChanged Функция Выполняется при изменении предпочтений пользователя. Для получения дополнительной информации см. Как сохранить настройки пользователя.
disableTranslation Логическое Отключение функции перевода слов и документов.
disableGrammar Логическое Отключение грамматической функции. Этот параметр также отключает слоги, части речи и словарь с иллюстрациями, которые зависят от частей речи.
disableLanguageDetection Логическое Отключение распознавания языка, чтобы в Иммерсивном средстве чтения использовался только язык, явно указанный в блоке Содержимое/[]. Этот параметр следует использовать умеренно, в основном, в ситуациях, когда определение языка не работает, например, такая проблема, скорее всего, будет возникать с короткими фрагментами менее 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

Внимание!

ВАЖНО! Не пытайтесь программно изменить значения строки -preferences, отправляемой в приложение иммерсивного средства чтения и из него, так как это может вызвать неожиданное поведение, которое приведет к ухудшению взаимодействия с пользователем для ваших клиентов. Ведущие приложения никогда не должны назначать настраиваемое значение или манипулировать строкой -preferences. При использовании строкового параметра -preferences используйте только то точное значение, которое было возвращено параметром обратного вызова -onPreferencesChanged.

Type: String
Required: false
Default value: null
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;
};

Параметры ReadAloudOptions

Имя Тип Описание
voice Строка Голос, либо "Женский", либо "Мужской". Не все языки поддерживают оба рода.
Скорость Число Скорость воспроизведения должна быть от 0,5 до 2,5 включительно.
autoPlay Логическое Автоматически запускать чтение вслух при загрузке иммерсивного средства чтения.
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

Примечание

Из-за ограничений браузера автовоспроизведение не поддерживается в Safari.


TranslationOptions

type TranslationOptions = {
    language: string;
    autoEnableDocumentTranslation?: boolean;
    autoEnableWordTranslation?: boolean;
};

Параметры TranslationOptions

Имя Тип Описание
Язык Строка Устанавливает язык перевода, значение находится в формате языкового тега 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
};

Параметры DisplayOptions

Имя Тип Описание
textSize Число Устанавливает выбранный размер текста.
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 при запуске иммерсивного средства чтения. В таблице ниже описано, какие настройки иммерсивного средства чтения сохраняет в своих файлах cookie, когда включена опция cookiePolicy.

Параметры настроек

Параметр Тип Описание
textSize Число Устанавливает выбранный размер текста.
fontFamily Строка Устанавливает выбранный шрифт ("Calibri", "ComicSans" или "Sitka").
textSpacing Число Устанавливает, включен или выключен интервал текста.
formattingEnabled Логическое Устанавливает, включено или выключено форматирование HTML.
тема Строка Устанавливает выбранную тему (например, "Светлый", "Темный"...).
syllabificationEnabled Логическое Устанавливает, включено или выключено слоговое изменение.
nounHighlightingEnabled Логическое Устанавливает, будет ли выделение существительных включено или выключено.
nounHighlightingColor Строка Устанавливает выбранный цвет выделения существительного.
verbHighlightingEnabled Логическое Устанавливает, включено или выключено выделение глаголов.
verbHighlightingColor Строка Устанавливает выбранный цвет выделения глагола.
adjectiveHighlightingEnabled Логическое Устанавливает, включено или выключено выделение прилагательного.
adjectiveHighlightingColor Строка Устанавливает выбранный цвет выделения прилагательного.
adverbHighlightingEnabled Логическое Устанавливает, включено или выключено выделение наречий.
adverbHighlightingColor Строка Устанавливает выбранный цвет выделения наречия.
pictureDictionaryEnabled Логическое Устанавливает, включен или выключен словарь изображений.
posLabelsEnabled Логическое Устанавливает, включается или отключается надстрочная текстовая метка каждой выделенной части речи.

Поддерживаемые языки

Функция перевода иммерсивного средства чтения поддерживает множество языков. Дополнительные сведения см. в разделе Поддержка языков.


Поддержка HTML

Когда форматирование включено, следующее содержимое будет отображаться как HTML в иммерсивном средстве чтения.

HTML Поддерживаемое содержимое
Стили шрифтов Жирный, Курсив, Подчеркнутый, Код, Зачеркнутый, Надстрочный, Подстрочный
Неупорядоченные списки Диск, Круг, Квадрат
Упорядоченные списки Десятичный, верхний алфавит, нижний алфавит, верхний римский алфавит, нижний римский алфавит

Неподдерживаемые теги будут отображаться аналогично. Изображения и таблицы в настоящее время не поддерживаются.


Поддержка браузеров

Используйте самые последние версии следующих браузеров для наилучшего взаимодействия с иммерсивным средством чтения.

  • Microsoft Edge
  • Internet Explorer 11;
  • Google Chrome
  • Mozilla Firefox
  • Apple Safari;

Дальнейшие действия