справочник по пакету SDK для JavaScript Иммерсивное средство чтения (версия 1.4)
SDK иммерсивного средства чтения содержит библиотеку JavaScript, которая позволяет интегрировать иммерсивное средство чтения в ваше приложение.
Вы можете использовать npmyarnэлемент HTML <script> или библиотеку последней стабильной сборки в веб-приложении:
<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(options)
Функция: launchAsync
ImmersiveReader.launchAsync(token, subdomain, content, options)запускает Иммерсивное средство чтения в элементе HTML iframe в веб-приложении. Размер вашего контента ограничен максимум 50 МБ.
launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;
| Параметр | Тип | Описание |
|---|---|---|
| token | строка | Маркер проверки подлинности Microsoft Entra. Дополнительные сведения см. в статье "Создание ресурса Иммерсивное средство чтения". |
| subdomain | строка | Настраиваемый поддомен ресурса Иммерсивное средство чтения в Azure. |
| content | Содержимое | Объект, содержащий содержимое, отображаемое в Иммерсивное средство чтения. |
| options | Параметры | Параметры для настройки определенного поведения иммерсивного средства чтения. Необязательно. |
Возвраты
Возвращает Promise<LaunchResponse>, которое разрешается при загрузке иммерсивного средства чтения. Разрешение Promise объекта LaunchResponse .
Исключения
Если Иммерсивное средство чтения не удается загрузить, возвращенный Promise объект отклоняется объектом Error.
Функция: close
ImmersiveReader.close()закрывает Иммерсивное средство чтения.
Примером использования этой функции является скрытие кнопки выхода путем настройки hideExitButton: true в параметрах. Затем другая кнопка (например, стрелка обратного заголовка мобильного устройства) может вызывать эту close функцию при щелчке.
close(): void;
Функция: renderButtons
Функция 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;
| Параметр | Тип | Описание |
|---|---|---|
| options | настройки renderButtons | Параметры для настройки определенного поведения функции renderButtons. Необязательно. |
настройки renderButtons
Параметры для отрисовки кнопок иммерсивного средства чтения.
{
elements: HTMLDivElement[];
}
| Параметр | Тип | Описание |
|---|---|---|
| элементы | HTMLDivElement[] | Элементы для отрисовки кнопок иммерсивного средства чтения. |
Type: HTMLDivElement[]
Required: false
Кнопка "Запустить"
Пакет SDK предоставляет стили по умолчанию для кнопки запуска Иммерсивное средство чтения. Используйте атрибут класса immersive-reader-button, чтобы включить этот стиль. Дополнительные сведения см. в разделе "Настройка кнопки Иммерсивное средство чтения".
<div class='immersive-reader-button'></div>
Используйте следующие необязательные атрибуты, чтобы настроить внешний вид и ощущение кнопки.
| Атрибут | Description |
|---|---|
| стиль кнопки данных | Устанавливает стиль кнопки. Возможные значения: icon, text или iconAndText. По умолчанию — icon. |
| языковой стандарт данных | Устанавливает языковой стандарт. Например, en-US или fr-FR. По умолчанию используется английский язык en. |
| размер объекта data-icon-px | Устанавливает размер значка в пикселях. Значение по умолчанию — 20 пикселей. |
LaunchResponse
Содержит ответ от вызова ImmersiveReader.launchAsync. Ссылка на HTML-элементiframe, содержащий Иммерсивное средство чтения, можно получить через container.firstChild.
{
container: HTMLDivElement;
sessionId: string;
charactersProcessed: number;
}
| Параметр | Тип | Описание |
|---|---|---|
| контейнер | HTMLDivElement | HTML-элемент, содержащий элемент iframe иммерсивного средства чтения. |
| sessionId | Строка | Глобальный уникальный идентификатор для этого сеанса, используемый для отладки. |
| charactersProcessed | number | Общее количество обработанных символов |
Ошибка
Содержит информацию об ошибке.
{
code: string;
message: string;
}
| Параметр | Тип | Описание |
|---|---|---|
| кодом | Строка | Один из набора кодов ошибок. |
| message | Строка | Читаемое представление ошибки. |
| Код ошибки | Description |
|---|---|
| BadArgument | Указанный аргумент недопустим. См message . параметр ошибки. |
| Время ожидания | Не удалось загрузить иммерсивное средство чтения в течение указанного времени ожидания. |
| TokenExpired | Срок действия предоставленного токена истек. |
| Регулируемый | Превышен лимит скорости звонков. |
Типы
Содержимое
Содержит контент, который будет отображаться в иммерсивном средстве чтения.
{
title?: string;
chunks: Chunk[];
}
| Параметр | Тип | Описание |
|---|---|---|
| название | Строка | Текст заголовка, отображаемый в верхней части иммерсивного средства чтения (необязательно) |
| Куски | 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 | Строка | Строка, содержащая содержимое, отправленное в иммерсивное средство чтения. |
| lang | Строка | Язык текста, значение находится в формате тега BCP 47 языка IETF, например 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 | Description |
|---|---|
| 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-индекс созданного HTML-элемента iframe (по умолчанию — 1000). |
| useWebview | Логический | Используйте тег веб-представления вместо HTML-элемента iframe для совместимости с приложениями Chrome (по умолчанию — false). |
| onExit | Function | Выполняется при выходе из иммерсивного средства чтения. |
| customDomain | Строка | Зарезервировано для внутреннего использования. Пользовательский домен, в котором размещено веб-приложение иммерсивного средства чтения (по умолчанию — 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 | Параметры для настройки размера текста, шрифта, темы и т. п. |
| предпочтения | Строка | Строка, возвращенная из onPreferencesChanged, представляющая предпочтения пользователя в иммерсивном средстве чтения. Дополнительные сведения см. в статье о хранении параметров пользователя. |
| onPreferencesChanged | Function | Выполняется при изменении предпочтений пользователя. Дополнительные сведения см. в статье о хранении параметров пользователя. |
| 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
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 | Строка | Голос, либо женщина, либо мужчина. Не все языки поддерживают оба рода. |
| скорость | Число | Скорость воспроизведения. Должно быть от 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;
};
| Параметр | Тип | Описание |
|---|---|---|
| язык | Строка | Задает язык перевода, значение находится в формате тега BCP 47 языка IETF, например 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 | Строка | Задает выбранный шрифт (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
- Google Chrome
- Mozilla Firefox
- Apple Safari;