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

Article
09/01/2024

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

Parámetro	Tipo	Descripción
token	string	El token de autenticación de Microsoft Entra. Para más información, consulte Creación de un recurso de Lector inmersivo.
subdomain	string	Subdominio personalizado del recurso de Lector inmersivo en Azure.
content	Contenido	Objeto que contiene el contenido que se va a mostrar en el Lector inmersivo.
options	Opciones	Opciones para configurar ciertos comportamientos del Lector inmersivo. Opcional.

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;

Parámetro	Tipo	Descripción
options	Opciones de renderButtons	Opciones para configurar ciertos comportamientos de la función renderButtons. Opcional.

Opciones de renderButtons

Opciones para representar los botones del lector inmersivo.

{
    elements: HTMLDivElement[];
}

Parámetro	Tipo	Descripción
Elementos	HTMLDivElement[]	Elementos para representar los botones del Lector inmersivo.

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.

Atributo	Descripción
estilo de botón de datos	Establece el estilo del botón. Puede ser `icon`, `text` o `iconAndText`. Su valor predeterminado es `icon`.
configuración regional de datos	Establece la configuración regional. Por ejemplo, `en-US` o `fr-FR`. El valor predeterminado es el idioma inglés `en`.
data-icon-px-size	Establece el tamaño del icono en píxeles. El valor predeterminado es de 20 px.

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

Parámetro	Tipo	Descripción
contenedor	HTMLDivElement	Elemento HTML que contiene el elemento `iframe` del Lector inmersivo.
sessionID	String	Identificador único global de esta sesión, que se usa para la depuración.
charactersProcessed	number	Número total de caracteres procesados.

Error

Contiene información sobre un error.

{
    code: string;
    message: string;
}

Parámetro	Tipo	Descripción
código	String	Uno de un conjunto de códigos de error.
message	String	Representación legible del error.

Código de error	Descripción
BadArgument	El argumento proporcionado no es válido. Consulte `message` el parámetro del error.
Tiempo de espera	El Lector inmersivo no se pudo cargar en el tiempo de espera especificado.
TokenExpired	El token suministrado en caché ha expirado.
Limitado	Se ha superado el límite de frecuencia de llamadas.

Tipos

Contenido

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

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

Parámetro	Tipo	Descripción
nombre	String	Texto del título que se muestra en la parte superior del Lector inmersivo (opcional)
fragmentos	Chunk[]	Matriz de fragmentos

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

Parámetro	Tipo	Descripción
contenido	String	Cadena con el contenido enviado al Lector inmersivo.
lang	String	Idioma del texto, el valor está en formato de etiqueta IETF BCP 47-language , por ejemplo, en, es-ES. El idioma se detecta automáticamente si no se especifica. Para obtener más información, consulte Idiomas admitidos.
mimeType	string	Se admiten los formatos de texto sin formato, MathML, HTML y Microsoft Word DOCX. Para obtener más información, consulte Tipos MIME admitidos.

`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

Tipo de MIME	Descripción
text/plain	Texto sin formato.
text/html	Contenido HTML.
application/mathml+xml	Lenguaje de marcado matemático (MathML).
application/vnd.openxmlformats-officedocument.wordprocessingml.document	Documento de Microsoft Word con formato .docx.

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

Parámetro	Tipo	Descripción
uiLang	String	Idioma de la interfaz de usuario, el valor está en formato de etiqueta IETF BCP 47-language , por ejemplo, en, es-ES. Si no se especifica, el valor predeterminado es el idioma del explorador.
timeout	Number	Duración (en milisegundos) antes de que launchAsync produzca un error de tiempo de espera (el valor predeterminado es de 15 000 ms). Este tiempo de espera solo se aplica al lanzamiento inicial de la página Lector, cuando se abre la página Lector y se inicia el indicador giratorio. El ajuste del tiempo de espera no debe ser necesario.
uiZIndex	Number	Índice Z del elemento HTML `iframe` que se crea (el valor predeterminado es 1000).
useWebview	Booleano	Use una etiqueta webview en lugar de un elemento HTML `iframe` para la compatibilidad con Chrome Apps (el valor predeterminado es false).
onExit	Función	Se ejecuta cuando se cierra el Lector inmersivo.
customDomain	String	Reservado para uso interno. Dominio personalizado en el que se hospeda la aplicación web del Lector inmersivo (el valor predeterminado es null).
allowFullscreen	Boolean	La capacidad de alternar a la pantalla completa (el valor predeterminado es true).
primario	Nodo	Nodo en el que se coloca el elemento o `Webview` contenedor HTML`iframe`. Si el elemento no existe, el iframe se coloca en `body`.
hideExitButton	Boolean	Ocultar la flecha del botón de salida del Lector inmersivo (el valor predeterminado es false). Este valor solo debe ser true si hay un mecanismo alternativo proporcionado para salir del Lector inmersivo (por ejemplo, una flecha atrás de una barra de herramientas móvil).
cookiePolicy	CookiePolicy	Configuración para el uso de cookies del Lector inmersivo (el valor predeterminado es CookiePolicy.Disable). Es responsabilidad de la aplicación host obtener cualquier consentimiento necesario del usuario según la directiva de cumplimiento de cookies de la UE. Para obtener más información, consulte Opciones de directiva de cookies.
disableFirstRun	Boolean	Deshabilita la experiencia de primera ejecución.
readAloudOptions	ReadAloudOptions	Opciones para configurar la lectura en voz alta.
translationOptions	TranslationOptions	Opciones para configurar la traducción.
displayOptions	DisplayOptions	Opciones para configurar el tamaño del texto, la fuente, el tema, etc.
preferences	String	Cadena devuelta por onPreferencesChanged que representa las preferencias del usuario en el Lector inmersivo. Para obtener más información, consulte How to store user preferences (Cómo almacenar preferencias de usuario).
onPreferencesChanged	Función	Se ejecuta cuando las preferencias del usuario han cambiado. Para obtener más información, consulte How to store user preferences (Cómo almacenar preferencias de usuario).
disableTranslation	Boolean	Deshabilita la experiencia de traducción de palabras y documentos.
disableGrammar	Boolean	Deshabilita la experiencia de Gramática. Esta opción también deshabilita las sílabas, partes de voz y diccionario de imágenes, que depende de partes de voz.
disableLanguageDetection	Boolean	Deshabilita Detección de idioma para asegurarse de que Lector inmersivo solo use el idioma que se especifique explícitamente en Contenido/Fragmento[]. Esta opción se debe usar con moderación, principalmente en situaciones en las que la detección de idioma no funciona. Por ejemplo, es más probable que este problema ocurra con pasajes cortos de menos de 100 caracteres. Debe estar seguro del idioma que está enviando, ya que la funcionalidad de texto a voz no tendrá la voz correcta. Las sílabas, las partes de voz y el diccionario de imágenes no funcionan correctamente si el idioma no es correcto.

`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

Precaución

No intente cambiar mediante programación los valores de la cadena -preferences enviada a la aplicación de Immersive Reader o desde ella, ya que puede provocar un comportamiento inesperado y dar lugar a una experiencia de usuario degradada. Recuerde que las aplicaciones host nunca deben asignar un valor personalizado a la cadena -preferences ni manipularla. Al utilizar la opción de cadena -preferences, use solo el valor exacto que se devolvió en la opción de devolución de llamada -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;
};

Parámetro	Tipo	Descripción
voice	Cadena	Voz, femenina o masculina. No todos los idiomas admiten ambos géneros.
velocidad	Number	Velocidad de reproducción. Debe estar comprendido entre 0,5 y 2,5, ambos incluidos.
autoPlay	Boolean	Se inicia automáticamente la lectura en voz alta cuando se carga el Lector inmersivo.

Nota

Debido a las limitaciones del explorador, la reproducción automática no se admite en 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;
};

Parámetro	Tipo	Descripción
language	String	Establece el idioma de traducción, el valor está en formato de etiqueta IETF BCP 47-language , por ejemplo, fr-FR, es-MX, zh-Hans-CN. Necesario para habilitar automáticamente la traducción de documentos o palabras.
autoEnableDocumentTranslation	Boolean	Traducción automática de todo el documento.
autoEnableWordTranslation	Boolean	Habilitación automática de la traducción de palabras.

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

Parámetro	Tipo	Descripción
textSize	Number	Establece el tamaño de texto elegido.
increaseSpacing	Boolean	Establece si el espaciado de texto está activado o desactivado.
fontFamily	Cadena	Establece la fuente elegida (Calibri, ComicSans o Sitka).
themeOption	ThemeOption	Establece el tema elegido del lector (Claro, Oscuro).

`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.

Configuración	Tipo	Descripción
textSize	Number	Establece el tamaño de texto elegido.
fontFamily	Cadena	Establece la fuente elegida (Calibri, ComicSans o Sitka).
textSpacing	Number	Establece si el espaciado de texto está activado o desactivado.
formattingEnabled	Boolean	Establece si el formato HTML de texto está activado o desactivado.
tema	Cadena	Establece el tema elegido (Claro, Oscuro).
syllabificationEnabled	Boolean	Establece si la silabación está activada o desactivada.
nounHighlightingEnabled	Boolean	Establece si el resaltado de sustantivos está activado o desactivado.
nounHighlightingColor	String	Establece el color elegido para el resaltado de sustantivos.
verbHighlightingEnabled	Boolean	Establece si el resaltado de verbos está activado o desactivado.
verbHighlightingColor	String	Establece el color elegido para el resaltado de verbos.
adjectiveHighlightingEnabled	Boolean	Establece si el resaltado de adjetivos está activado o desactivado.
adjectiveHighlightingColor	String	Establece el color elegido para el resaltado de adjetivos.
adverbHighlightingEnabled	Boolean	Establece si el resaltado de adverbios está activado o desactivado.
adverbHighlightingColor	String	Establece el color elegido para el resaltado de adverbios.
pictureDictionaryEnabled	Boolean	Establece si el Diccionario de imágenes está activado o desactivado.
posLabelsEnabled	Boolean	Establece si la etiqueta de texto de superíndice de cada parte de voz resaltada está activada o desactivada.

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.

HTML	Contenido admitido
Estilos de fuente	Negrita, cursiva, subrayado, código, tachado, superíndice, subíndice
Listas sin ordenar	Disco, círculo, cuadrado
Listas ordenadas	Decimal, upper-Alpha, lower-Alpha, upper-Roman, lower-Roman

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

Exploración del SDK de Immersive Reader

Comparteix a través de

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

Funciones

Función: launchAsync

Devuelve

Excepciones

Función: close

Función: renderButtons

Opciones de renderButtons

Botón Iniciar

LaunchResponse

Error

Tipos

Contenido

title

chunks

Fragmento

content

lang

mimeType

Tipos MIME compatibles

Opciones

uiLang

timeout

uiZIndex

onExit

preferences

onPreferencesChanged

customDomain