Lector inmersivo referencia del SDK de JavaScript (v1.4)

El SDK del Lector inmersivo contiene una biblioteca de JavaScript que permite integrar dicho lector en la aplicación.

Puede usar npm, yarno un elemento HTML <script> para incluir la biblioteca de la compilación estable más reciente en la aplicación 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

Funciones

El SDK expone estas funciones:

• ImmersiveReader.launchAsync(token, subdominio, contenido, opciones)
• ImmersiveReader.close()
• ImmersiveReader.renderButtons(options)

Función: launchAsync

ImmersiveReader.launchAsync(token, subdomain, content, options)inicia el Lector inmersivo dentro de un elemento HTML iframe en la aplicación web. El tamaño del contenido está limitado a un máximo de 50 MB.

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

Devuelve

Devuelve Promise<LaunchResponse>, que se resuelve cuando el lector inmersivo se carga. se Promise resuelve en un objeto LaunchResponse .

Excepciones

Si el Lector inmersivo no se puede cargar, el devuelto Promise se rechaza con un objeto Error.

Función: close

ImmersiveReader.close()cierra el Lector inmersivo.

Un caso de uso de ejemplo de esta función se produce si el botón para salir se oculta al establecer hideExitButton: true en options. A continuación, un botón diferente (por ejemplo, la flecha atrás de un encabezado móvil) puede llamar a esta close función cuando se hace clic en ella.

close(): void;

Función: renderButtons

La ImmersiveReader.renderButtons(options) función no es necesaria si usa la guía del botón Cómo personalizar la Lector inmersivo.

Esta función crea los estilos y actualiza los elementos del botón de lector inmersivo del documento. Si options.elements se proporciona, los botones se representan dentro de cada elemento proporcionado en options.elements. El uso del parámetro options.elements resulta útil cuando en varias secciones del documento se inicia el Lector inmersivo y se quiere una manera simplificada de presentar varios botones con el mismo estilo o se quiere representar los botones con un modelo de diseño sencillo y coherente. Para usar esta función con el parámetro de opciones renderButtons, llame a ImmersiveReader.renderButtons(options: RenderButtonsOptions); en la carga de página como se muestra en el siguiente fragmento de código. De lo contrario, los botones se representan dentro de los elementos del documento que tienen la clase immersive-reader-button tal y como se muestra en Cómo personalizar el botón Lector inmersivo.

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

Consulte los atributos opcionales del botón de inicio para obtener más opciones de representación. Para usar estas opciones, agregue cualquiera de los atributos de opción a cada HTMLDivElement en el código HTML de la página.

renderButtons(options?: RenderButtonsOptions): void;

Opciones de renderButtons

Opciones para representar los botones del lector inmersivo.

{
    elements: HTMLDivElement[];
}

Type: HTMLDivElement[]
Required: false

Botón Iniciar

El SDK proporciona estilos predeterminados para el botón de inicio de Lector inmersivo. Use el atributo de clase immersive-reader-button para habilitar este estilo. Para obtener más información, consulte Personalización del botón Lector inmersivo.

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

Use los siguientes atributos opcionales para configurar la apariencia del botón.

LaunchResponse

Contiene la respuesta de la llamada a ImmersiveReader.launchAsync. Se puede acceder a una referencia al elemento HTML iframe que contiene el Lector inmersivo a través container.firstChildde .

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

Error

Contiene información sobre un error.

{
    code: string;
    message: string;
}

Tipos

Contenido

Contiene el contenido que se mostrará en el Lector inmersivo.

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

title

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

chunks

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

Fragmento

Un único fragmento de datos, que se pasa al contenido del Lector inmersivo.

{
    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"

Tipos MIME compatibles

Opciones

Contiene propiedades que configuran ciertos comportamientos del Lector inmersivo.

{
    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"

Opciones de CookiePolicy

enum CookiePolicy { Disable, Enable }

La siguiente configuración solo tiene fines informativos. El Lector inmersivo almacena su configuración, o preferencias de usuario, en cookies. La opción cookiePolicydeshabilita el uso de cookies de manera predeterminada para ajustarse a las leyes de cumplimiento de cookies de la UE. Si desea volver a habilitar cookies y restaurar la funcionalidad predeterminada para Lector inmersivo preferencias de usuario, su sitio web o aplicación necesita el consentimiento adecuado del usuario para habilitar las cookies. Después, para volver a habilitar las cookies en el Lector inmersivo, debe establecer explícitamente la opción cookiePolicy en CookiePolicy.Enable al iniciar el Lector inmersivo.

En la tabla siguiente se describe la configuración que el Lector inmersivo almacena en su cookie cuando la opción cookiePolicy está habilitada.

Idiomas compatibles

La característica de traducción del Lector inmersivo admite muchos idiomas. Para obtener más información, consulte Compatibilidad de idioma.

Compatibilidad con HTML

Cuando se habilita el formato, el siguiente contenido se representa como HTML en el Lector inmersivo.

Las etiquetas no admitidas se representan de forma comparable. Las imágenes y las tablas actualmente no se admiten.

Compatibilidad con exploradores

Use las versiones más recientes de los siguientes exploradores para disfrutar de la mejor experiencia con el Lector inmersivo.

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

Paso siguiente