Referência do SDK JavaScript do Leitor Imersivo (v1.4)
O SDK do Leitor Imersivo contém uma biblioteca JavaScript que permite integrar o Leitor Imersivo 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 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 | Description |
|---|---|---|
| token | string | O token de autenticação do Microsoft Entra. Para saber mais, consulte Como criar um recurso de leitor imersivo. |
| subdomínio | string | O subdomínio personalizado do seu recurso Leitor Imersivo no Azure. |
| content | Conteúdo | Um objeto que contém o conteúdo a ser mostrado no Leitor Imersivo. |
| options | Opções | Opções para configurar determinados comportamentos do Leitor Imersivo. Opcional. |
Devoluções
Retorna um Promise<LaunchResponse>, que é resolvido quando o Leitor Imersivo é carregado. O Promise resolve para um objeto LaunchResponse .
Exceções
Se o Immersive Reader falhar ao carregar, o retorno Promise será rejeitado com um objeto Error .
Função: close
ImmersiveReader.close() fecha o Leitor Imersivo.
Um exemplo de caso de uso para esta função é se o botão de saída estiver oculto definindo 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 é necessária se você usar a orientação do botão Como personalizar o Leitor Imersivo.
Esta função estiliza e atualiza os elementos do botão Leitor Imersivo do documento. Se options.elements for fornecido, os botões serão renderizados dentro de cada elemento fornecido em options.elements. O uso do options.elements parâmetro é útil quando você tem várias seções no documento para iniciar o Leitor Imersivo e deseja uma maneira simplificada 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); o carregamento da página, conforme demonstrado no trecho de código a seguir. Caso contrário, os botões sã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 um no HTML da página.
renderButtons(options?: RenderButtonsOptions): void;
| Parâmetro | Tipo | Description |
|---|---|---|
| options | opções renderButtons | Opções para configurar determinados comportamentos da função renderButtons. Opcional. |
opções renderButtons
Opções para renderizar os botões do Leitor Imersivo.
{
elements: HTMLDivElement[];
}
| Parâmetro | Tipo | Description |
|---|---|---|
| elementos | HTMLDivElement[] | Elementos para renderizar os botões do Leitor Imersivo. |
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 immersive-reader-button atributo class 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 | Description |
|---|---|
| estilo de botão de dados | Define o estilo do botão. Pode ser icon, text, ou iconAndText. O padrão é icon. |
| localidade de dados | 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 | Description |
|---|---|---|
| contentor | HTMLDivElement | HTML que contém o elemento Immersive Reader iframe . |
| sessionId | String | Identificador global exclusivo para esta sessão, usado para depuração. |
| caracteresProcessados | Número | Número total de caracteres processados |
Erro
Contém informações sobre um erro.
{
code: string;
message: string;
}
| Parâmetro | Tipo | Description |
|---|---|---|
| code | String | Um de um conjunto de códigos de erro. |
| mensagem | String | Representação legível por humanos do erro. |
| Código de erro | Description |
|---|---|
| BadArgument | O argumento fornecido é inválido. Consulte message o parâmetro do erro. |
| Limite de tempo excedido | O leitor imersivo falhou ao carregar dentro do tempo limite especificado. |
| TokenExpired | O token fornecido expirou. |
| Limitado | O limite da taxa de chamadas foi excedido. |
Tipos
Conteúdo
Contém o conteúdo a ser mostrado no Leitor Imersivo.
{
title?: string;
chunks: Chunk[];
}
| Parâmetro | Tipo | Description |
|---|---|---|
| cargo | String | Texto do título mostrado na parte superior do Leitor Imersivo (opcional) |
| pedaços | Chunk[] | 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 é passado para o conteúdo do Leitor Imersivo.
{
content: string;
lang?: string;
mimeType?: string;
}
| Parâmetro | Tipo | Description |
|---|---|---|
| content | String | A cadeia de caracteres que contém o conteúdo enviado para o Leitor Imersivo. |
| lang | String | Idioma do texto, o valor está no formato de tag IETF BCP 47-language , por exemplo, en, es-ES. O idioma é detetado automaticamente se não for especificado. Para obter mais informações, veja Idiomas suportados. |
| mimeType | string | Texto simples, MathML, HTML ou formatos DOCX do Microsoft Word são suportados. Para obter mais informações, consulte Tipos 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 MIME suportados
| Tipo MIME | Description |
|---|---|
| text/plain | Texto simples. |
| text/html | Conteúdo HTML. |
| aplicativo/mathml+xml | Linguagem de Marcação Matemática (MathML). |
| aplicativo/vnd.openxmlformats-officedocument.wordprocessingml.document | Documento em formato de .docx do Microsoft Word. |
Opções
Contém propriedades que configuram determinados comportamentos do Leitor Imersivo.
{
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 | Description |
|---|---|---|
| uiLang | String | Idioma da interface do usuário, o valor está no formato de marca de 47 idiomas BCP IETF, por exemplo, en, es-ES. O padrão é o idioma do navegador, se não for especificado. |
| tempo limite | Número | Duração (em milissegundos) antes de iniciarAsync falha com um erro de tempo limite (o padrão é 15.000 ms). Este tempo limite só se aplica ao lançamento inicial da página Leitor, quando a página Leitor é aberta com êxito e o girador é iniciado. O ajuste do tempo limite não deve ser necessário. |
| uiZIndex | Número | Z-index do elemento HTML iframe que é criado (o padrão é 1000). |
| useWebview | Boolean | Utilize uma etiqueta Webview em vez de um elemento HTML iframe para compatibilidade com as aplicações Chrome (o predefinido é false). |
| onSair | Function | Executa quando o Leitor Imersivo é encerrado. |
| customDomain | String | Reservado para uso interno. Domínio personalizado onde o webapp Immersive Reader está hospedado (o padrão é null). |
| permitirTela cheia | Boolean | A capacidade de alternar em tela cheia (o padrão é true). |
| parent | 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 do Leitor Imersivo (o padrão é false). Esse valor só deve ser verdadeiro se houver um mecanismo alternativo fornecido para sair do Leitor Imersivo (por exemplo, a seta para trás de uma barra de ferramentas móvel). |
| Política de cookies | Política de Cookies | Configuração para o uso de cookies do Leitor Imersivo (o padrão é CookiePolicy.Disable). É da responsabilidade da aplicação anfitriã obter qualquer consentimento necessário do utilizador de acordo com a Política de Conformidade de Cookies da UE. Para obter mais informações, consulte Opções da Política de cookies. |
| desativarFirstRun | Boolean | Desative a primeira experiência de execução. |
| readAloudOptions | ReadAloudOptions | Opções para configurar a leitura em voz alta. |
| traduçãoOpções | Opções de tradução | Opções para configurar a tradução. |
| displayOpções | Opções de exibição | Opções para configurar o tamanho do texto, fonte, tema e assim por diante. |
| preferências | String | String retornada de onPreferencesChanged representando as preferências do usuário no Immersive Reader. Para obter mais informações, consulte Como armazenar as preferências do usuário. |
| onPreferênciasAlterado | Function | É executado quando as preferências do usuário foram alteradas. Para obter mais informações, consulte Como armazenar as preferências do usuário. |
| desativarTradução | Boolean | Desative a experiência de tradução de palavras e documentos. |
| disableGrammar | Boolean | Desative a experiência gramatical. Esta opção também desativa Sílabas, Partes da Fala e Dicionário de Imagens, que depende de Partes da Fala. |
| disableLanguageDetection | Boolean | Desative a Deteção de Idioma para garantir que o Leitor Imersivo use apenas o idioma explicitamente especificado no Chunk/[]. Essa opção deve ser usada com moderação, principalmente em situações em que a deteção de idioma não está funcionando. Por exemplo, é mais provável que este problema aconteça com passagens curtas de menos de 100 caracteres. Você deve ter certeza sobre o idioma que está enviando, pois a conversão de texto em fala não terá a voz correta. As sílabas, as partes da fala e o 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
Atenção
Não tente alterar programaticamente os valores da cadeia de -preferences 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 ou manipular a -preferences cadeia de caracteres. Ao usar a -preferences opção string, use apenas o valor exato que foi retornado da -onPreferencesChanged opção 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 | Description |
|---|---|---|
| voice | String | Voz, feminina ou masculina. Nem todos os idiomas suportam ambos os sexos. |
| velocidade | Número | Velocidade de reprodução. Deve ter entre 0,5 e 2,5, inclusive. |
| Reprodução automática | Boolean | Inicie automaticamente a leitura em voz alta quando o leitor imersivo carregar. |
Nota
Devido a limitações do navegador, a reprodução automática não é suportada 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
Opções de tradução
type TranslationOptions = {
language: string;
autoEnableDocumentTranslation?: boolean;
autoEnableWordTranslation?: boolean;
};
| Parâmetro | Tipo | Description |
|---|---|---|
| idioma | String | Define o idioma de tradução, o valor está no formato de tag IETF BCP de 47 idiomas , por exemplo, fr-FR, es-MX, zh-Hans-CN. Necessário para ativar automaticamente a tradução de palavras ou documentos. |
| autoEnableDocumentTranslation | Boolean | Traduza automaticamente todo o documento. |
| autoEnableWordTranslation | Boolean | Habilite automaticamente a tradução de palavras. |
language
Type: String
Required: true
Default value: null
Values available: For more information, see the Supported languages section
ThemeOption
enum ThemeOption { Light, Dark }
Opções de exibição
type DisplayOptions = {
textSize?: number;
increaseSpacing?: boolean;
fontFamily?: string;
themeOption?: ThemeOption
};
| Parâmetro | Tipo | Description |
|---|---|---|
| textSize | Número | Define o tamanho do texto escolhido. |
| aumentarEspaçamento | Boolean | Define se o espaçamento entre textos está ativado ou desativado. |
| fontFamília | 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. O Immersive Reader armazena as suas definições, ou preferências do utilizador, em cookies. Esta opção cookiePolicy desativa o uso de cookies por padrão para seguir as leis de conformidade de cookies da UE. 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 reativar os cookies no Leitor Imersivo, você deve definir explicitamente a opção cookiePolicy como CookiePolicy.Enable ao iniciar o Leitor Imersivo.
A tabela a seguir descreve quais configurações o Immersive Reader armazena em seu cookie quando a opção cookiePolicy está ativada.
| Definição | Tipo | Description |
|---|---|---|
| textSize | Número | Define o tamanho do texto escolhido. |
| fontFamília | String | Define a fonte escolhida (Calibri, ComicSans ou Sitka). |
| textEspaçamento entre textos | Número | Define se o espaçamento entre textos está ativado ou desativado. |
| formataçãoAtivado | Boolean | Define se a formatação HTML está ativada ou desativada. |
| tema | String | Define o tema escolhido (Claro, Escuro). |
| syllabificationEnabled | Boolean | Define se a silabificação foi ativada ou desativada. |
| nounHighlightingEnabled | Boolean | Define se o realce de substantivo está ativado ou desativado. |
| substantivoDestaqueCor | String | Define a cor de realce substantivo escolhida. |
| verbHighlightingEnabled | Boolean | Define se o realce de verbos é ativado ou desativado. |
| verbHighlightingColor | String | Define a cor de realce verbal escolhida. |
| adjetivoDestaqueAtivado | Boolean | Define se o realce de adjetivo está ativado ou desativado. |
| adjetivoDestaqueCor | String | Define a cor de realce adjetivo escolhida. |
| adverbHighlightingEnabled | Boolean | Define se o realce de advérbio está ativado ou desativado. |
| advérbioHighlightingColor | String | Define a cor de realce de advérbio escolhida. |
| pictureDictionaryEnabled | Boolean | Define se o Dicionário de Imagens está ativado ou desativado. |
| posLabelsEnabled | Boolean | Define se o rótulo de texto sobrescrito de cada Parte da Fala realçada está ativado ou desativado. |
Idiomas suportados
O recurso de tradução do Immersive Reader suporta muitos idiomas. Para obter mais informações, consulte Suporte a idiomas.
Suporte HTML
Quando a formatação está ativada, o conteúdo a seguir é processado como HTML no Leitor Imersivo.
| HTML | Conteúdo suportado |
|---|---|
| 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. Imagens e tabelas não são suportadas no momento.
Suporte do browser
Use as versões mais recentes dos seguintes navegadores para obter a melhor experiência com o Immersive Reader.
- Microsoft Edge
- Google Chrome
- Mozilla Firefox
- Apple Safari