referência Leitura Avançada JavaScript SDK (v1.2)

O Leitura Avançada SDK contém uma biblioteca JavaScript que lhe permite integrar o Leitura Avançada na sua aplicação.

Pode utilizar npm, yarnou elemento, um HTML<script> elemento para incluir a biblioteca da mais recente construção estável na sua aplicação web:

<script type='text/javascript' src='https://ircdname.azureedge.net/immersivereadersdk/immersive-reader-sdk.1.2.0.js'></script>
npm install @microsoft/immersive-reader-sdk
yarn add @microsoft/immersive-reader-sdk

Funções

O SDK expõe as funções:


lançarAsync

Lança o Leitura Avançada dentro de um HTMLiframe elemento na sua aplicação web. O tamanho do seu conteúdo está limitado a um máximo de 50 MB.

launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;

lançar Parâmetros Async

Nome Tipo Description
token cadeia (de carateres) O Azure AD símbolo de autenticação. Para mais informações, consulte Como Criar um recurso Leitura Avançada.
subdomain string O subdomínio personalizado do seu Leitura Avançada recurso em Azure. Para mais informações, consulte Como Criar um recurso Leitura Avançada.
content Conteúdo Um objeto que contenha o conteúdo a ser mostrado no Leitura Avançada.
options Opções Opções para configurar certos comportamentos da Leitura Avançada. Opcional.

Devoluções

Devolve um Promise<LaunchResponse>, que resolve quando o Leitura Avançada é carregado. A Promise determinação de um LaunchResponse objeto.

Exceções

A devolvição Promise será rejeitada com um Error objeto se o Leitura Avançada não carregar. Para mais informações, consulte os códigos de erro.


fechar

Fecha a Leitura Avançada.

Um exemplo de caso de utilização para esta função é se o botão de saída estiver escondido definindo hideExitButton: trueas opções. Em seguida, um botão diferente (por exemplo, a seta traseira de um cabeçalho móvel) pode chamar esta close função quando é clicada.

close(): void;

Botão de lançamento Leitura Avançada

O SDK fornece um estilo predefinido para o botão para o lançamento do Leitura Avançada. Utilize o immersive-reader-button atributo de classe para ativar este estilo. Para obter mais informações, consulte como personalizar o botão Leitura Avançada.

<div class='immersive-reader-button'></div>

Atributos opcionais

Utilize os seguintes atributos para configurar o aspeto e a sensação do botão.

Atributo Descrição
data-button-style Define o estilo do botão. Pode ser icon, textou iconAndText. . Incumprimentos a icon.
data-locale Define o local. Por exemplo, en-US ou fr-FR. Incumprimentos em inglês en.
data-icon-px-size Define o tamanho do ícone em pixels. Predefinições a 20px.

renderMatons

A renderButtons função não é necessária se estiver a utilizar a orientação do botão "Como Personalizar a Leitura Avançada".

Esta função tem estilos e atualiza os elementos de botão Leitura Avançada do documento. Se options.elements for fornecido, os botões serão renderizados dentro de cada elemento fornecido em options.elements. A utilização do options.elements parâmetro é útil quando tem várias secções no documento para lançar o Leitura Avançada, e quer uma forma simplificada de tornar vários botões com o mesmo estilo, ou pretender tornar os botões com um padrão de design simples e consistente. Para utilizar esta função com o parâmetro de opções renderbuttons , ligue para ImmersiveReader.renderButtons(options: RenderButtonsOptions); a carga da página como demonstrado no corte de código abaixo. Caso contrário, os botões serão renderizados dentro dos elementos do documento que têm a classe immersive-reader-button como mostrado no botão 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 acima para obter mais opções de renderização. Para utilizar estas opções, adicione qualquer um dos atributos de opção a cada um HTMLDivElement na sua página HTML.

renderButtons(options?: RenderButtonsOptions): void;

renderMatons Parâmetros

Nome Tipo Description
options renderAs opções de Botões Opções para configurar certos comportamentos da função renderbuttons. Opcional.

renderAs opções de Botões

Opções para renderizar os botões Leitura Avançada.

{
    elements: HTMLDivElement[];
}

renderButtons Parâmetros de opções

Definições Tipo Description
elementos HTMLDivElement[] Elementos para tornar os botões Leitura Avançada dentro.
elements
Type: HTMLDivElement[]
Required: false

LaunchResponse

Contém a resposta da chamada para ImmersiveReader.launchAsync. Uma referência ao HTMLiframe elemento que contém o Leitura Avançada pode ser acedida através de container.firstChild.

{
    container: HTMLDivElement;
    sessionId: string;
    charactersProcessed: number;
}

Lançar Parâmetros de Resposta

Definições Tipo Description
contentor HTMLDivElement Elemento HTML que contém o elemento Leitura Avançadaiframe.
sessionId String Identificador globalmente único para esta sessão, usado para depurar.
caracteres Processado número Número total de caracteres processados

Erro

Contém informações sobre um erro.

{
    code: string;
    message: string;
}

Parâmetros de erro

Definições Tipo Descrição
code String Um de um conjunto de códigos de erro. Para obter mais informações, consulte os códigos De erro.
message String Representação legível pelo homem do erro.

Códigos de erro

Código Descrição
BadArgument O argumento fornecido é inválido, consulte message o parâmetro do Erro.
Tempo Limite O Leitura Avançada não foi carregado dentro do intervalo especificado.
TokenExpired O token fornecido expirou.
Acelerador O limite da taxa de chamada foi ultrapassado.

Tipos

Conteúdo

Contém o conteúdo a ser mostrado no Leitura Avançada.

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

Parâmetros de conteúdo

Nome Tipo Description
título String Texto do título mostrado no topo do Leitura Avançada (opcional)
pedaços Pedaço[] Matriz de pedaços
title
Type: String
Required: false
Default value: "Immersive Reader" 
chunks
Type: Chunk[]
Required: true
Default value: null 

Segmento

Um único pedaço de dados, que será passado para o conteúdo do Leitura Avançada.

{
    content: string;
    lang?: string;
    mimeType?: string;
}

Parâmetros de pedaços

Nome Tipo Description
conteúdo String A cadeia que contém o conteúdo enviado para a Leitura Avançada.
lang String Linguagem do texto, o valor está no formato de tag de 47 línguas do IETF BCP, por exemplo, en, es-ES. A linguagem será detetada automaticamente se não for especificada. Para mais informações, consulte idiomas apoiados.
mímicaType string Texto simples, MathML, HTML & Microsoft os formatos Word DOCX são suportados. Para mais informações, consulte os tipos de MIME suportados.
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 de MIME suportados

Tipo de MIME Description
texto/planície Texto simples.
text/html Conteúdo HTML. Saiba mais
aplicação/mathml+xml Linguagem de marcação matemática (MathML). Saiba mais.
aplicação/vnd.openxmlformats-officedocument.wordprocessingml.document documento de formato Microsoft Word .docx.

Opções

Contém propriedades que configuram certos comportamentos da 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âmetros de opções

Nome Tipo Description
uiLang String Idioma da UI, o valor está no formato de tag de 47 línguas do IETF BCP, por exemplo, en, es-ES. Predefinições no idioma do navegador se não for especificado.
tempo limite Número Duração (em milissegundos) antes do lançamentoAsync falha com um erro de tempo limite (o padrão é de 15.000 ms). Este intervalo aplica-se apenas ao lançamento inicial da página Reader, quando a página Reader abre com sucesso e o girador começa. O ajuste do tempo limite não deve ser necessário.
uiZIndex Número Z-index do HTMLiframe elemento que será criado (o padrão é 1000).
useWebview Booleano Utilize uma etiqueta webview em vez de um HTMLiframe elemento, para compatibilidade com apps do Chrome (o padrão é falso).
onExit Função Executa quando o Leitura Avançada sai.
CustomDomain String Reservado para uso interno. Domínio personalizado onde o webapp Leitura Avançada está hospedado (o padrão é nulo).
permitir o ecrã Del Booleano A capacidade de alternar o ecrã completo (o padrão é verdadeiro).
pai Nó no qual o HTMLiframe elemento ou Webview o recipiente é colocado. Se o elemento não existir, o iframe é colocado em body.
hideExitButton Booleano Esconde a seta do botão de saída do Leitura Avançada (o padrão é falso). Este valor só deve ser verdadeiro se existir um mecanismo alternativo para sair do Leitura Avançada (por exemplo, a seta traseira de uma barra de ferramentas móvel).
cookiePolicy Política de Cookies Definição para o uso de cookies do Leitura Avançada (padrão é CookiePolicy.Disable). É da responsabilidade da aplicação do anfitrião obter o consentimento necessário do utilizador seguindo a Política de Conformidade com os Cookies da UE. Para mais informações, consulte as Opções de Política de Cookies.
desativarFirstRun Booleano Desative a primeira experiência de execução.
readAloudOptions ReadAloudOptions Opções para configurar Leia em voz alta.
traduções Opções Opções de Tradução Opções para configurar a tradução.
displayOptions DisplayOptions Opções para configurar o tamanho do texto, fonte, tema, e assim por diante.
preferências String String retornado de onPreferencesChanged representando as preferências do utilizador no Leitura Avançada. Para obter mais informações, consulte parâmetros de definições e como armazenar as preferências do utilizador.
onPreferencesOdado Função Executa quando as preferências do utilizador mudaram. Para mais informações, consulte como armazenar as preferências do utilizador.
desativação Booleano Desative a experiência de tradução de palavras e documentos.
desativarGrammar Booleano Desative a experiência gramática. Esta opção também irá desativar sílabas, partes do dicionário de discurso e imagem, que depende de partes do discurso.
desativação de Deteção de Lição de Lição Booleano Desativar a Deteção de Idiomas para garantir que o Leitura Avançada apenas utiliza o idioma explicitamente especificado no Pedaço de Conteúdo/[]. Esta opção deve ser usada com moderação, principalmente em situações em que a deteção de linguagem não está a funcionar, por exemplo, esta questão é mais provável de acontecer com passagens curtas de menos de 100 caracteres. Devias ter a certeza sobre a linguagem que estás a enviar, já que o texto-a-voz não terá a voz correta. Sílabas, Partes do Dicionário de Discurso e Imagem não funcionarão corretamente se a língua não estiver correta.
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

Atenção

IMPORTANTE Não tente alterar programáticamente os valores da -preferences cadeia enviada para e a partir da aplicação Leitura Avançada, pois isso pode causar um comportamento inesperado resultando numa experiência de utilizador degradada para os seus clientes. As aplicações de anfitrião nunca devem atribuir um valor personalizado ou manipular a -preferences cadeia. Ao utilizar a opção -preferences de cadeia, utilize apenas o valor exato que foi devolvido da opção -onPreferencesChanged de retorno.

Type: String
Required: false
Default value: null
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âmetros de ReadAloudOptions

Nome Tipo Description
voz String Voz, "Fêmea" ou "Macho". Nem todas as línguas apoiam ambos os sexos.
velocidade Número Velocidade de reprodução, deve ser entre 0,5 e 2,5, inclusive.
autoPlay Booleano Comece automaticamente a ler em voz alta quando o Leitura Avançada carregar.
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

Nota

Devido às limitações do navegador, a reprodução automática não é suportada no Safari.


Opções de Tradução

type TranslationOptions = {
    language: string;
    autoEnableDocumentTranslation?: boolean;
    autoEnableWordTranslation?: boolean;
};

Parâmetros de Opções de Tradução

Nome Tipo Description
language String Define a língua de tradução, o valor está no formato de tag de 47 línguas do IETF BCP, por exemplo, fr-FR, es-MX, zh-Hans-CN. É necessário ativar automaticamente a tradução de palavras ou documentos.
autoEnableDocumentTranslation Booleano Traduza automaticamente todo o documento.
autoEnableWordTranslation Booleano Ativar automaticamente a tradução de palavras.
language
Type: String
Required: true
Default value: null 
Values available: For more information, see the Supported Languages section

Opção Temática

enum ThemeOption { Light, Dark }

DisplayOptions

type DisplayOptions = {
    textSize?: number;
    increaseSpacing?: boolean;
    fontFamily?: string;
    themeOption?: ThemeOption
};

Parâmetros displayOptions

Nome Tipo Description
textSize Número Define o tamanho do texto escolhido.
aumento Dopaco Booleano Define se o espaçamento do texto é alternado dentro ou fora.
fonteFamily String Define a fonte escolhida ("Calibri", "ComicSans" ou "Sitka").
temaOption Opção Temática Define o tema escolhido do leitor ("Luz", "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 Política de Cookies

enum CookiePolicy { Disable, Enable }

As definições listadas abaixo são apenas para fins informativos. O Leitura Avançada armazena as suas definições, ou preferências do utilizador, em cookies. Esta opção cookiePolicydesativa o uso de cookies por padrão para seguir as leis de Conformidade de Cookies da UE. Se pretender ativar os cookies e restaurar a funcionalidade padrão para Leitura Avançada preferências do utilizador, o seu website ou aplicação necessitará do consentimento adequado do utilizador para ativar os cookies. Em seguida, para ree capacitar os cookies no Leitura Avançada, tem de definir explicitamente a opção cookiePolicy para CookiePolicy.Enable ao lançar o Leitura Avançada. A tabela abaixo descreve quais as configurações que o Leitura Avançada armazena no seu cookie quando a opção cookiePolicy está ativada.

Parâmetros de definição

Definições Tipo Description
textSize Número Define o tamanho do texto escolhido.
fonteFamily String Define a fonte escolhida ("Calibri", "ComicSans" ou "Sitka").
textSpacing Número Define se o espaçamento do texto é alternado dentro ou fora.
formattingEnabled Booleano Define se a formatação HTML é alternada ou desligada.
tema String Define o tema escolhido (por exemplo, "Luz", "Escuro"...).
syllabificationEnabled Booleano Define se a syllabificação alternada ou desligada.
substantivo Booleano Define se o substantivo é alternado dentro ou fora.
substantivo String Define a cor de realçar o substantivo escolhido.
verboHighlightingEnabled Booleano Define se o realce de verbo é alternado dentro ou fora.
verbHighlightingColor String Define a cor de realce de verbo escolhido.
adjetivoHighlightingEnabled Booleano Define se o realce adjetivo é alternado dentro ou fora.
adjectivoHighlightingColor String Define a cor de realce adjetivo escolhido.
adverbHighlightingEnabled Booleano Define se o advérte é alternado dentro ou fora.
adverbHighlightingColor String Define a cor de realce do advérte escolhido.
pictureDictionaryEnabled Booleano Define se o Dicionário de Imagem é alternado dentro ou fora.
posLabelsEnabled Booleano Define se o rótulo de texto sobrescrito de cada Parte do Discurso realçado é alternado dentro ou fora.

Idiomas Suportados

A característica de tradução de Leitura Avançada suporta muitas línguas. Para mais informações, consulte suporte linguístico.


Suporte HTML

Quando a formatação estiver ativada, o seguinte conteúdo será tornado HTML no Leitura Avançada.

HTML Conteúdo suportado
Estilos de fonte Negrito, Itálico, Sublinhado, Código, Strikethrough, Superscript, Subscript
Listas não ordenadas Disco, Círculo, Quadrado
Listas ordenadas Decimal, Superior Alfa, Alfa Inferior, Superior-Romano, Lower-Roman

As etiquetas não suportadas serão comparadas. Imagens e tabelas não são suportadas atualmente.


Browser support (Suporte do browser)

Utilize as versões mais recentes dos seguintes navegadores para obter a melhor experiência com o Leitura Avançada.

  • Microsoft Edge
  • Internet Explorer 11
  • Google Chrome
  • Mozilla Firefox
  • Apple Safari

Passos seguintes