справочник по пакету 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>;

Возвраты

Возвращает 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;

настройки renderButtons

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

{
    elements: HTMLDivElement[];
}

Type: HTMLDivElement[]
Required: false

Кнопка "Запустить"

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

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

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

LaunchResponse

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

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

Ошибка

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

{
    code: string;
    message: string;
}

Типы

Содержимое

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

{
    title?: string;
    chunks: 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

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

Параметры

Содержит свойства, которые настраивают определенное поведение иммерсивного средства чтения.

{
    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

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

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

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;
};

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

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.

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

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

Поддержка HTML

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

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

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

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

• Microsoft Edge
• Google Chrome
• Mozilla Firefox
• Apple Safari;

Следующий шаг