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

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;

opções renderButtons

Opções para renderizar os botões do Leitor Imersivo.

{
    elements: HTMLDivElement[];
}

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.

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;
}

Erro

Contém informações sobre um erro.

{
    code: string;
    message: string;
}

Tipos

Conteúdo

Contém o conteúdo a ser mostrado no Leitor Imersivo.

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

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;
}

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

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;
}

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

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;
};

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;
};

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
};

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.

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.

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

Próximo passo