Referência do SDK JavaScript do Immersive Reader (v1.4)
O SDK do leitor de imersão contém uma biblioteca JavaScript que permite integrar a Leitura Avançada ao seu aplicativo.
Você pode usar npm, yarnou um elemento HTML <script> para incluir a biblioteca da compilação estável mais recente em seu aplicativo 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
Funções
O SDK expõe estas funções:
- ImmersiveReader.launchAsync(token, subdomínio, conteúdo, opções)
- ImmersiveReader.close()
- ImmersiveReader.renderButtons(opções)
Função: launchAsync
ImmersiveReader.launchAsync(token, subdomain, content, options) inicia o Immersive Reader dentro de um elemento HTML iframe em seu aplicativo Web. O tamanho do seu conteúdo é limitado a um máximo de 50 MB.
launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;
| Parâmetro | Tipo | Descrição |
|---|---|---|
| token | string | O token de autenticação do Microsoft Entra. Para saber mais, consulte Como criar um recurso de leitor imersivo. |
| subdomain | string | O subdomínio personalizado do recurso Leitor Imersivo no Azure. |
| content | Sumário | Um objeto que contém o conteúdo a ser mostrado no Immersive Reader. |
| opções | Opções | Opções para configurar determinados comportamentos da Leitura Avançada. Opcional. |
Retornos
Retorna um Promise<LaunchResponse>, que resolve quando a Leitura Avançada é carregada. O Promise resolve para um objeto LaunchResponse .
Exceções
Se o leitor imersivo falhar ao carregar, o retornado Promise será rejeitado com um objeto Error .
Função: close
ImmersiveReader.close() fecha o Leitor Imersivo.
Um exemplo de caso de uso para essa função é se o botão sair estiver oculto pela configuração hideExitButton: true em opções. Em seguida, um botão diferente (por exemplo, a seta para trás de um cabeçalho móvel) pode chamar essa close função quando ele é clicado.
close(): void;
Função: renderButtons
A ImmersiveReader.renderButtons(options) função não é necessária se você usar a orientação do botão Como personalizar o Leitor Imersivo.
Essa função define o estilo e atualiza os elementos do botão de Leitura Avançada do documento. Se options.elements for fornecido, os botões serão renderizados dentro de cada elemento fornecido no options.elements. O uso do parâmetro options.elements é útil quando você tem várias seções em seu documento para iniciar a Leitura Avançada e deseja ter um modo simplificado de renderizar vários botões com o mesmo estilo ou deseja renderizar os botões com um padrão de design simples e consistente. Para usar essa função com o parâmetro de opções renderButtons, chame ImmersiveReader.renderButtons(options: RenderButtonsOptions); o carregamento da página conforme demonstrado no trecho de código a seguir. Caso contrário, os botões serão renderizados dentro dos elementos do documento que têm a classe immersive-reader-button , conforme mostrado em Como personalizar o botão Leitor imersivo.
// 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 os atributos opcionais do botão de inicialização para obter mais opções de renderização. Para usar essas opções, adicione qualquer um dos atributos de opção a cada HTMLDivElement em seu HTML de página.
renderButtons(options?: RenderButtonsOptions): void;
| Parâmetro | Tipo | Descrição |
|---|---|---|
| opções | renderButtons options | Opções para configurar determinados comportamentos da função renderButtons. Opcional. |
renderButtons options
Opções para renderizar os botões de Leitura Avançada.
{
elements: HTMLDivElement[];
}
| Parâmetro | Tipo | Descrição |
|---|---|---|
| elementos | HTMLDivElement[] | Elementos em que renderizar os botões Leitura Avançada. |
Type: HTMLDivElement[]
Required: false
Botão Iniciar
O SDK fornece estilo padrão para o botão de inicialização do Immersive Reader. Use o atributo de classe immersive-reader-button para habilitar esse estilo. Para obter mais informações, consulte Como personalizar o botão Leitor imersivo.
<div class='immersive-reader-button'></div>
Use os seguintes atributos opcionais para configurar a aparência do botão.
| Atributo | Descrição |
|---|---|
| estilo de botão de dados | Define o estilo de um botão. Pode ser icon, text ou iconAndText. Assume o padrão de icon. |
| data-locale | Define a localidade. Por exemplo, en-US ou fr-FR. O padrão é inglês en. |
| data-icon-px-size | Define o tamanho do ícone em pixels. O padrão é 20 px. |
LaunchResponse
Contém a resposta da chamada para ImmersiveReader.launchAsync. Uma referência ao elemento HTML iframe que contém o Immersive Reader pode ser acessada via container.firstChild.
{
container: HTMLDivElement;
sessionId: string;
charactersProcessed: number;
}
| Parâmetro | Tipo | Descrição |
|---|---|---|
| contêiner | HTMLDivElement | O elemento HTML que contém o elemento iframe de Leitura Avançada. |
| sessionID | String | Identificador global exclusivo para esta sessão, usado para depuração. |
| charactersProcessed | número | Número total de caracteres processados |
Erro
Contém informações sobre um erro.
{
code: string;
message: string;
}
| Parâmetro | Tipo | Descrição |
|---|---|---|
| code | String | Um entre um conjunto de códigos de erro. |
| message | String | Representação legível ao olho humano do erro. |
| Código do erro | Descrição |
|---|---|
| BadArgument | O argumento fornecido é inválido. Consulte message o parâmetro do erro. |
| Tempo limite | A Leitura Avançada falhou ao ser carregada no tempo limite especificado. |
| TokenExpired | O token fornecido está expirado. |
| Acelerado | O limite de taxa de chamada foi excedido. |
Tipos
Conteúdo
Contém o conteúdo a ser mostrado na Leitura Avançada.
{
title?: string;
chunks: Chunk[];
}
| Parâmetro | Tipo | Descrição |
|---|---|---|
| cargo | String | Texto do título mostrado na parte superior da Leitura Avançada (opcional) |
| chunks | Chunk[] | Matriz de partes |
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null
Chunk
Um único bloco de dados, que é passado para o conteúdo do Leitor Imersivo.
{
content: string;
lang?: string;
mimeType?: string;
}
| Parâmetro | Tipo | Descrição |
|---|---|---|
| conteúdo | String | A cadeia de caracteres com o conteúdo enviado à Leitura Avançada. |
| lang | String | Idioma do texto, o valor está no formato de tag IETF BCP 47-language , por exemplo, en, es-ES. O idioma é detectado automaticamente se não for especificado. Para obter mais informações, consulte Idiomas com suporte. |
| Tipo MIME | string | Há suporte para formatos de texto sem formatação, MathML e HTML e Microsoft Word DOCX. Para obter mais informações, consulte os tipos MIME com suporte. |
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 com suporte
| tipo MIME | Descrição |
|---|---|
| texto/sem formatação | Texto sem formatação. |
| texto/html | Conteúdo HTML. |
| application/mathml+xml | Linguagem de Marcação Matemática (MathML). |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | Documento no formato .docx do Microsoft Word. |
Opções
Contém propriedades que configuram determinados comportamentos de Leitura Avançada.
{
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 | Descrição |
|---|---|---|
| uiLang | String | Idioma da interface do usuário, o valor está no formato de marca IETF BCP 47-language , por exemplo, en, es-ES. O padrão será o idioma do navegador, se não for especificado. |
| tempo limite | Número | Duração (em milissegundos) antes de launchAsync falhar com um erro de tempo limite (o padrão é 15,000 ms). Esse tempo limite só se aplica à inicialização inicial da página do leitor, quando a página do leitor é aberta com sucesso e o controle giratório é iniciado. O ajuste do tempo limite não deve ser necessário. |
| uiZIndex | Número | Z-index do elemento HTML iframe criado (o padrão é 1000). |
| useWebview | Booliano | Use uma tag webview em vez de um elemento HTML iframe , para compatibilidade com os Aplicativos Chrome (o padrão é false). |
| onExit | Função | É executado quando a Leitura Avançada é encerrada. |
| customDomain | String | Reservado para uso interno. Domínio personalizado no qual o webapp Leitura Avançada está hospedado (o padrão é null). |
| allowFullscreen | Boolean | A capacidade de alternar a tela inteira (o padrão é true). |
| pai | Nó | Nó no qual o elemento HTML iframe ou Webview contêiner é colocado. Se o elemento não existir, o iframe será colocado em body. |
| hideExitButton | Boolean | Oculta a seta do botão de saída da Leitura Avançada (o padrão é false). Esse valor só deve ser verdadeiro se houver um mecanismo alternativo fornecido para sair do Immersive Reader (por exemplo, a seta para trás de uma barra de ferramentas móvel). |
| cookiePolicy | CookiePolicy | Configuração para o uso do cookie da Leitura Avançada (o padrão é CookiePolicy.Disable). É responsabilidade do aplicativo host obter qualquer consentimento do usuário necessário seguindo a política de conformidade do cookie da Europa. Para obter mais informações, consulte Opções de política de cookies. |
| disableFirstRun | Boolean | Desabilite a primeira experiência de execução. |
| readAloudOptions | ReadAloudOptions | Opções para configurar a leitura em voz alta. |
| translationOptions | TranslationOptions | Opções para configurar a tradução. |
| displayOptions | DisplayOptions | Opções para configurar o tamanho do texto, a fonte, tema e assim por diante. |
| preferências | String | Cadeia de caracteres retornada por onPreferencesChanged que representa as preferências do usuário na Leitura Avançada. Para obter mais informações, consulte Como armazenar preferências do usuário. |
| onPreferencesChanged | Função | É executado quando as preferências do usuário são alteradas. Para obter mais informações, consulte Como armazenar preferências do usuário. |
| disableTranslation | Boolean | Desabilite a experiência de tradução de palavras e documentos. |
| disableGrammar | Boolean | Desabilite a experiência de Gramática. Essa opção também desabilita Sílabas, Partes da Fala e Dicionário de Imagens, que depende de Partes da Fala. |
| disableLanguageDetection | Boolean | Desabilite Detecção de Idioma para garantir que o Leitura Avançada use apenas o idioma especificado explicitamente no Chunk[]/de Conteúdo. Essa opção deve ser usada com moderação, principalmente em situações em que a detecção de idioma não está funcionando. Por exemplo, é mais provável que esse problema aconteça com passagens curtas de menos de 100 caracteres. Você deve ter certeza sobre o idioma que está enviando, pois o texto em fala não terá a voz correta. Sílabas, Partes da Fala e Dicionário de Imagens não funcionam corretamente se o idioma não estiver correto. |
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
Cuidado
Não tente alterar programaticamente os -preferences valores da cadeia de caracteres enviada de e para o aplicativo Immersive Reader porque isso pode causar um comportamento inesperado, resultando em uma experiência de usuário degradada. Os aplicativos host nunca devem atribuir um valor personalizado nem manipular a cadeia de caracteres -preferences. Ao usar a opção de cadeia de caracteres -preferences, use apenas o valor exato que foi retornado da opção -onPreferencesChanged de retorno de chamada.
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 | Descrição |
|---|---|---|
| voice | String | Voz, Feminina ou Masculina. Nem todos os idiomas dão suporte para ambas os gêneros. |
| velocidade | Número | Velocidade de reprodução. Deve estar entre 0,5 e 2,5, inclusive. |
| autoPlay | Boolean | Iniciar automaticamente Leitura em Voz Alta quando a Leitura Avançada for carregada. |
Observação
Devido a limitações do navegador, a reprodução automática não tem suporte no 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 | Descrição |
|---|---|---|
| Linguagem | String | Define o idioma de tradução, o valor está no formato de tag IETF BCP 47-language , por exemplo, fr-FR, es-MX, zh-Hans-CN. Necessário para habilitar automaticamente a tradução de palavras ou documentos. |
| autoEnableDocumentTranslation | Boolean | Traduza automaticamente o documento inteiro. |
| autoEnableWordTranslation | Boolean | Habilitar automaticamente a tradução de palavra. |
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 | Descrição |
|---|---|---|
| textSize | Número | Define o tamanho do texto escolhido. |
| increaseSpacing | Boolean | Define se o espaçamento de texto será ativado ou desativado. |
| fontFamily | String | Define a fonte escolhida (Calibri, ComicSans ou Sitka). |
| ThemeOption | ThemeOption | Define o tema escolhido do leitor (Claro, Escuro). |
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"
Opções de CookiePolicy
enum CookiePolicy { Disable, Enable }
As configurações a seguir são apenas para fins informativos. A Leitura Avançada armazena suas configurações, ou preferências do usuário, em cookies. Essa opção cookiePolicydesabilita o uso de cookies por padrão para seguir às leis de conformidade de cookie da Europa. Se você quiser reativar os cookies e restaurar a funcionalidade padrão para as preferências do usuário do Immersive Reader, seu site ou aplicativo precisa do consentimento adequado do usuário para ativar os cookies. Em seguida, para reabilitar os cookies em Leitura Avançada, defina explicitamente a opção cookiePolicy como CookiePolicy.Enable ao iniciar a Leitura Avançada.
A tabela a seguir descreve quais configurações o Immersive Reader armazena em seu cookie quando a opção cookiePolicy está ativada.
| Configuração | Type | Descrição |
|---|---|---|
| textSize | Número | Define o tamanho do texto escolhido. |
| fontFamily | String | Define a fonte escolhida (Calibri, ComicSans ou Sitka). |
| textSpacing | Número | Define se o espaçamento de texto será ativado ou desativado. |
| formattingEnabled | Boolean | Define se a formatação HTML é ativada ou desativada. |
| theme | String | Define o tema escolhido (Claro, Escuro). |
| syllabificationEnabled | Boolean | Define se a silabação está ativada ou desativada. |
| nounHighlightingEnabled | Boolean | Define se o realce de substantivo é ativado ou desativado. |
| nounHighlightingColor | String | Define a cor de realce de substantivo escolhida. |
| verbHighlightingEnabled | Boolean | Define se o realce de verbo é ativado ou desativado. |
| verbHighlightingColor | String | Define a cor de realce de verbo escolhida. |
| adjectiveHighlightingEnabled | Boolean | Define se o realce de adjetivo é ativado ou desativado. |
| adjectiveHighlightingColor | String | Define a cor de realce de adjetivo escolhida. |
| adverbHighlightingEnabled | Boolean | Define se o realce de advérbio é ativado ou desativado. |
| adverbHighlightingColor | String | Define a cor de realce de advérbio escolhida. |
| pictureDictionaryEnabled | Boolean | Define se o dicionário de imagem é ativado ou desativado. |
| posLabelsEnabled | Boolean | Define se o rótulo de texto sobrescrito de cada parte realçada da fala é ativado ou desativado. |
Idiomas com suporte
O recurso de tradução de Leitura Avançada dá suporte a vários idiomas. Para mais informações, consulte Suporte do idioma.
Suporte para HTML
Quando a formatação está habilitada, o conteúdo a seguir é renderizado como HTML no Immersive Reader.
| HTML | Conteúdo com suporte |
|---|---|
| Estilos de fonte | Negrito, itálico, sublinhado, código, tachado, sobrescrito, subscrito |
| Listas não ordenadas | Disco, círculo, quadrado |
| Listas ordenadas | Decimal, alfa superior, alfa inferior, romano superior, romano inferior |
As tags sem suporte são renderizadas de forma comparável. Não há suporte para imagens e tabelas no momento.
Suporte ao navegador
Use as versões mais recentes dos navegadores a seguir para obter a melhor experiência com a Leitura Avançada.
- Microsoft Edge
- Google Chrome
- Mozilla Firefox
- Apple Safari