Referencia del SDK de JavaScript de Lector inmersivo (v 1.1)

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

Functions

El SDK expone las funciones:

• ImmersiveReader.launchAsync(token, subdomain, content, options)

• ImmersiveReader.close()

• ImmersiveReader.renderButtons(options)

launchAsync

Inicia el Lector inmersivo dentro de un iframe en la aplicación web. Tenga en cuenta que 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>;

Parámetros de launchAsync

Devuelve

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

Excepciones

El valor devuelto de Promise se rechazará con un objeto Error si el Lector inmersivo no se puede cargar. Para más información, consulte los códigos de error.

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. Después, un botón distinto (por ejemplo, la flecha atrás de un encabezado para dispositivos móviles) puede llamar a esta función close cuando se hace clic en ella.

close(): void;

Botón de inicio del Lector inmersivo

El SDK proporciona el estilo predeterminado para el botón para iniciar el Lector inmersivo. Use el atributo de clase immersive-reader-button para habilitar este estilo. Consulte Procedimiento: Personalización del botón del Lector inmersivo para más detalles.

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

Atributos opcionales

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

renderButtons

La función renderButtons no es necesaria si usa la guía Procedimiento: Personalización del botón del Lector inmersivo.

Esta función crea los estilos y actualiza los elementos del botón de lector inmersivo del documento. Si se proporciona options.elements, los botones se representarán 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 renderButtons options, llame a ImmersiveReader.renderButtons(options: RenderButtonsOptions); en la carga de la página, como se muestra en el fragmento de código siguiente. De lo contrario, los botones se representarán dentro de los elementos del documento que tengan la clase immersive-reader-button, tal como se muestra en Procedimiento: Personalización del botón del 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 el apartado Atributos opcionales anterior, para 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;

Parámetros de renderButtons

Opciones de renderButtons

Opciones para representar los botones del lector inmersivo.

{
    elements: HTMLDivElement[];
}

Parámetros de opciones de renderButtons

elements

Type: HTMLDivElement[]
Required: false

LaunchResponse

Contiene la respuesta de la llamada a ImmersiveReader.launchAsync. Tenga en cuenta que se puede acceder a una referencia al elemento iframe que contiene el Lector inmersivo a través de container.firstChild.

{
    container: HTMLDivElement;
    sessionId: string;
}

Parámetros de LaunchResponse

Error

Contiene información sobre un error.

{
    code: string;
    message: string;
}

Parámetros de error

Códigos de error

Tipos

Contenido

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

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

Parámetros de contenido

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 pasará al contenido del lector inmersivo.

{
    content: string;
    lang?: string;
    mimeType?: string;
}

Parámetros de fragmentos

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;
    allowFullscreen?: boolean;
    hideExitButton?: boolean;
    cookiePolicy?: CookiePolicy;
    disableFirstRun?: boolean;
    readAloudOptions?: ReadAloudOptions;
    translationOptions?: TranslationOptions;
    displayOptions?: DisplayOptions;
    preferences?: string;
    onPreferencesChanged?: (value: string) => any;
    customDomain?: string;
}

Parámetros de opciones

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

Parámetros de ReadAloudOptions

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

Parámetros de TranslationOptions

language

Type: String
Required: true
Default value: null 
Values available: See the Supported Languages section

DisplayOptions

type DisplayOptions = {
    textSize?: number;
    increaseSpacing?: boolean;
    fontFamily?: string;
};

Parámetros de DisplayOptions

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 configuración que se muestra a continuación solo es informativa. El Lector inmersivo almacena su configuración, o preferencias de usuario, en cookies. La opción cookiePolicy deshabilita el uso de cookies de manera predeterminada para cumplir con las leyes de cumplimiento de cookies de Europa. Si desea volver a habilitar las cookies y restaurar la funcionalidad predeterminada para las preferencias de usuario del Lector inmersivo, deberá asegurarse de que el sitio web o la aplicación obtienen 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 qué configuración almacena el Lector inmersivo en su cookie cuando está habilitada la opción cookiePolicy.

Parámetros de configuración

Idiomas compatibles

La característica de traducción del Lector inmersivo admite muchos idiomas. Vea Compatibilidad de idiomas para obtener más información.

Compatibilidad con HTML

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

Las etiquetas no admitidas se representarán de la misma forma. 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
• Internet Explorer 11
• Google Chrome
• Mozilla Firefox
• Apple Safari

Pasos siguientes

• Explorar el SDK del Lector inmersivo en GitHub
• Inicio rápido: Creación de una aplicación web que inicia el Lector inmersivo (C#)