Referência do SDK do JavaScript da Leitura Avançada (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, yarn, ou 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 a Leitura Avançada em 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 Leitura Avançada. |
| subdomain | string | O subdomínio personalizado do recurso de Leitura Avançada no Azure. |
| content | Sumário | Um objeto que contém o conteúdo a ser mostrado na Leitura Avançada. |
| 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 é resolvido para um objeto LaunchResponse .
Exceções
Se a Leitura Avançada não for carregada, o retornado Promise será rejeitado com um objeto Error .
Função: close
ImmersiveReader.close() fecha a Leitura Avançada.
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 é clicado.
close(): void;
Função: renderButtons
A ImmersiveReader.renderButtons(options) função não será necessária se você usar a orientação do botão Como personalizar a Leitura Avançada.
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 em 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 renderButtons options , chame ImmersiveReader.renderButtons(options: RenderButtonsOptions); no carregamento da página, conforme demonstrado no snippet 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 Leitura Avançada.
// 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 de inicialização
O SDK fornece estilo padrão para o botão de inicialização da Leitura Avançada. Use o atributo de classe immersive-reader-button para habilitar esse estilo. Para obter mais informações, consulte Como personalizar o botão Leitura Avançada.
<div class='immersive-reader-button'></div>
Use os atributos opcionais a seguir 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. |
| localidade de dados | Define a localidade. Por exemplo, en-US ou fr-FR. O padrão é inglês en. |
| tamanho px do ícone de dados | 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 a Leitura Avançada 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. Veja message o parâmetro do erro. |
| Timeout | 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
Uma única parte de dados, que é passada para o conteúdo da Leitura Avançada.
{
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 de 47 idiomas , 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 de 47 idiomas IETF BCP, 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 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ó deverá ser verdadeiro se houver um mecanismo alternativo fornecido para sair da Leitura Avançada (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 da 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 as 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 as 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 desativa Sílabas, Classes gramaticais e Dicionário de imagens, que depende de Classes gramaticais. |
| 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 ocorra com passagens curtas com 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, Classes gramaticais 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 valores da cadeia de caracteres -preferences enviada de e para o aplicativo da Leitura Avançada, pois 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 marca IETF BCP de 47 idiomas , 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 pelo 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 da Leitura Avançada, seu site ou aplicativo precisará do consentimento adequado do usuário para habilitar 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 a Leitura Avançada armazena em seu cookie quando a opção cookiePolicy está habilitada.
| 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 na Leitura Avançada.
| 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 não suportadas são renderizadas comparativamente. 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