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>;
| 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 | Número | Í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 HTMLiframe. 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 | Número | 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