dokumentacja zestawu SDK języka JavaScript Czytnik immersyjny (wersja 1.4)

Zestaw SDK Czytnik immersyjny zawiera bibliotekę języka JavaScript, która umożliwia integrację Czytnik immersyjny z aplikacją.

Możesz użyć npmelementu , yarnlub HTML <script> , aby uwzględnić bibliotekę najnowszej stabilnej kompilacji w aplikacji internetowej:

<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

Funkcje

Zestaw SDK uwidacznia następujące funkcje:

• ImmersiveReader.launchAsync(token, poddomena, zawartość, opcje)
• ImmersiveReader.close()
• ImmersiveReader.renderButtons(opcje)

Funkcja: launchAsync

ImmersiveReader.launchAsync(token, subdomain, content, options)uruchamia Czytnik immersyjny w elemecie HTML iframe w aplikacji internetowej. Rozmiar zawartości jest ograniczony do maksymalnie 50 MB.

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

Zwraca

Zwraca wartość Promise<LaunchResponse>, która jest rozpoznawana podczas ładowania Czytnik immersyjny. Rozpoznawany Promise jest obiekt LaunchResponse .

Wyjątki

Jeśli nie można załadować Czytnik immersyjny, zwrócony Promise obiekt zostanie odrzucony z obiektem Error.

Funkcja: close

ImmersiveReader.close()zamyka Czytnik immersyjny.

Przykładowy przypadek użycia tej funkcji to, czy przycisk wyjścia jest ukryty, ustawiając w hideExitButton: trueopcjach. Następnie inny przycisk (na przykład strzałka wstecz nagłówka mobilnego) może wywołać tę close funkcję po kliknięciu.

close(): void;

Funkcja: renderButtons

Funkcja ImmersiveReader.renderButtons(options) nie jest konieczna, jeśli używasz wskazówek dotyczących dostosowywania Czytnik immersyjny przycisków.

Ta funkcja style i aktualizuje elementy przycisku Czytnik immersyjny dokumentu. Jeśli options.elements zostanie podana wartość , przyciski są renderowane w ramach każdego elementu podanego w pliku options.elements. Użycie parametru options.elements jest przydatne, gdy w dokumencie znajduje się wiele sekcji, na których ma zostać uruchomiony Czytnik immersyjny, i chcesz uprościć renderowanie wielu przycisków z tym samym stylem lub chcesz renderować przyciski z prostym i spójnym wzorcem projektowania. Aby użyć tej funkcji z parametrem opcji renderButtons, wywołaj metodę ImmersiveReader.renderButtons(options: RenderButtonsOptions); ładowania strony, jak pokazano w poniższym fragmencie kodu. W przeciwnym razie przyciski są renderowane w elementach dokumentu, które mają klasęimmersive-reader-button, jak pokazano w temacie Jak dostosować przycisk Czytnik immersyjny.

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

Zobacz opcjonalne atrybuty przycisku uruchamiania, aby uzyskać więcej opcji renderowania. Aby użyć tych opcji, dodaj dowolne atrybuty opcji do każdego HTMLDivElement z nich w kodzie HTML strony.

renderButtons(options?: RenderButtonsOptions): void;

opcje renderButtons

Opcje renderowania przycisków Czytnik immersyjny.

{
    elements: HTMLDivElement[];
}

Type: HTMLDivElement[]
Required: false

Przycisk Uruchom

Zestaw SDK zapewnia domyślny styl dla przycisku uruchamiania Czytnik immersyjny. Użyj atrybutu immersive-reader-button klasy, aby włączyć ten styl. Aby uzyskać więcej informacji, zobacz Jak dostosować przycisk Czytnik immersyjny.

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

Użyj następujących opcjonalnych atrybutów, aby skonfigurować wygląd i działanie przycisku.

LaunchResponse

Zawiera odpowiedź z wywołania na ImmersiveReader.launchAsync. Odwołanie do elementu HTML iframe zawierającego Czytnik immersyjny można uzyskać dostęp za pośrednictwem metody container.firstChild.

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

Błąd

Zawiera informacje o błędzie.

{
    code: string;
    message: string;
}

Typy

Zawartość

Zawiera zawartość, która ma być wyświetlana w Czytnik immersyjny.

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

title

Type: String
Required: false
Default value: "Immersive Reader" 

chunks

Type: Chunk[]
Required: true
Default value: null 

Fragment

Pojedynczy fragment danych, który jest przekazywany do zawartości Czytnik immersyjny.

{
    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"

Obsługiwane typy MIME

Opcje

Zawiera właściwości, które konfigurują pewne zachowania Czytnik immersyjny.

{
    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

TematOpcje

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"

Opcje cookiePolicy

enum CookiePolicy { Disable, Enable }

Następujące ustawienia są przeznaczone tylko do celów informacyjnych. Czytnik immersyjny przechowuje ustawienia lub preferencje użytkownika w plikach cookie. Ta opcja cookiePolicy domyślnie wyłącza korzystanie z plików cookie zgodnie z przepisami ue dotyczącymi zgodności plików cookie. Jeśli chcesz ponownie włączyć pliki cookie i przywrócić domyślne funkcje Czytnik immersyjny preferencji użytkownika, witryna internetowa lub aplikacja wymaga odpowiedniej zgody od użytkownika w celu włączenia plików cookie. Następnie, aby ponownie włączyć pliki cookie w Czytnik immersyjny, należy jawnie ustawić opcję cookiePolicy na CookiePolicy.Enable podczas uruchamiania Czytnik immersyjny.

W poniższej tabeli opisano ustawienia, które Czytnik immersyjny przechowuje w pliku cookie po włączeniu opcji cookiePolicy.

Obsługiwane języki

Funkcja tłumaczenia Czytnik immersyjny obsługuje wiele języków. Aby uzyskać więcej informacji, zobacz Obsługa języka.

Obsługa kodu HTML

Po włączeniu formatowania następująca zawartość jest renderowana jako HTML w Czytnik immersyjny.

Nieobsługiwane tagi są renderowane w sposób porównywalny. Obrazy i tabele nie są obecnie obsługiwane.

Obsługa przeglądarek

Użyj najnowszych wersji poniższych przeglądarek, aby uzyskać najlepsze środowisko pracy z Czytnik immersyjny.

• Microsoft Edge
• Google Chrome
• Mozilla Firefox
• Apple Safari

Następny krok