Compartilhar via


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:

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

Próxima etapa