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

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;

renderButtons options

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

{
    elements: HTMLDivElement[];
}

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.

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

Erro

Contém informações sobre um erro.

{
    code: string;
    message: string;
}

Tipos

Conteúdo

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

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

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

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

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

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

TranslationOptions

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 }

DisplayOptions

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

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.

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