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>;
| Parametr | Type | Opis |
|---|---|---|
| token | string | Token uwierzytelniania entra firmy Microsoft. Aby dowiedzieć się więcej, zobacz Jak utworzyć zasób Czytnik immersyjny. |
| Poddomeny | string | Niestandardowa poddomena zasobu Czytnik immersyjny na platformie Azure. |
| content | Zawartość | Obiekt zawierający zawartość do wyświetlenia w Czytnik immersyjny. |
| options | Opcje | Opcje konfigurowania niektórych zachowań Czytnik immersyjny. Opcjonalny. |
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;
| Parametr | Type | Opis |
|---|---|---|
| options | opcje renderButtons | Opcje konfigurowania niektórych zachowań funkcji renderButtons. Opcjonalny. |
opcje renderButtons
Opcje renderowania przycisków Czytnik immersyjny.
{
elements: HTMLDivElement[];
}
| Parametr | Type | Opis |
|---|---|---|
| elementy | HTMLDivElement[] | Elementy do renderowania przycisków Czytnik immersyjny. |
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.
| Atrybut | opis |
|---|---|
| styl przycisku danych | Ustawia styl przycisku. Może to być icon, textlub iconAndText. Wartość domyślna to icon. |
| ustawienia regionalne danych | Ustawia ustawienia regionalne. Na przykład: en-US lub fr-FR. Domyślnie jest to angielski en. |
| data-icon-px-size | Ustawia rozmiar ikony w pikselach. Wartość domyślna to 20 pikseli. |
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;
}
| Parametr | Type | Opis |
|---|---|---|
| kontener | HTMLDivElement | Element HTML zawierający element Czytnik immersyjnyiframe. |
| sessionId | String | Globalnie unikatowy identyfikator dla tej sesji używany do debugowania. |
| znakiProcessed | Liczba | Łączna liczba przetworzonych znaków |
Błąd
Zawiera informacje o błędzie.
{
code: string;
message: string;
}
| Parametr | Type | Opis |
|---|---|---|
| code | String | Jeden z zestawów kodów błędów. |
| wiadomość | String | Czytelna dla człowieka reprezentacja błędu. |
| Kod błędu | opis |
|---|---|
| BadArgument | Podany argument jest nieprawidłowy. Zobacz message parametr błędu. |
| Timeout | Nie można załadować Czytnik immersyjny w określonym przedziale czasu. |
| TokenExpired | Podany token wygasł. |
| Ograniczono | Przekroczono limit liczby wywołań. |
Typy
Zawartość
Zawiera zawartość, która ma być wyświetlana w Czytnik immersyjny.
{
title?: string;
chunks: Chunk[];
}
| Parametr | Type | Opis |
|---|---|---|
| title | String | Tekst tytułu wyświetlany w górnej części Czytnik immersyjny (opcjonalnie) |
| Kawałki | Fragment[] | Tablica fragmentów |
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;
}
| Parametr | Type | Opis |
|---|---|---|
| content | String | Ciąg zawierający zawartość wysłaną do Czytnik immersyjny. |
| Lang | String | Język tekstu, wartość jest w formacie tagu IETF BCP 47-language , na przykład en, es-ES. Język jest wykrywany automatycznie, jeśli nie zostanie określony. Aby uzyskać więcej informacji, zobacz listę Obsługiwane języki. |
| Mimetype | string | Obsługiwane są formaty Zwykłego tekstu, MathML, HTML i Microsoft Word DOCX. Aby uzyskać więcej informacji, zobacz Obsługiwane typy MIME. |
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
| Typ MIME | opis |
|---|---|
| text/plain | Zwykły tekst. |
| text/html | Zawartość HTML. |
| application/mathml+xml | Matematyczny język znaczników (MathML). |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | Dokument w formacie .docx programu Microsoft Word. |
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;
}
| Parametr | Type | Opis |
|---|---|---|
| uiLang | String | Język interfejsu użytkownika, wartość jest w formacie tagu IETF BCP 47-language , na przykład en, es-ES. Wartość domyślna dla języka przeglądarki, jeśli nie zostanie określona. |
| timeout | Liczba | Czas trwania (w milisekundach) przed niepowodzeniem funkcji launchAsync z powodu błędu przekroczenia limitu czasu (wartość domyślna to 15 000 ms). Ten limit czasu dotyczy tylko początkowego uruchomienia strony Czytelnik, po pomyślnym otwarciu strony Czytelnik i uruchomieniu pokrętła. Dostosowanie limitu czasu nie powinno być konieczne. |
| uiZIndex | Liczba | Indeks Z utworzonego elementu HTML iframe (wartość domyślna to 1000). |
| useWebview | Wartość logiczna | Użyj tagu webview zamiast elementu HTML iframe , aby uzyskać zgodność z aplikacjami dla programu Chrome (wartość domyślna to false). |
| onExit | Function | Wykonuje po zakończeniu Czytnik immersyjny. |
| customDomain | String | Zarezerwowane do użytku wewnętrznego. Domena niestandardowa, w której jest hostowana aplikacja internetowa Czytnik immersyjny (wartość domyślna to null). |
| allowFullscreen | Wartość logiczna | Możliwość przełączania pełnoekranowego (wartość domyślna to true). |
| parent | Węzeł | Węzeł, w którym znajduje się element HTML iframe lub Webview kontener. Jeśli element nie istnieje, element iframe zostanie umieszczony w elemecie body. |
| hideExitButton | Wartość logiczna | Ukrywa strzałkę przycisku zakończenia Czytnik immersyjny (wartość domyślna to false). Ta wartość powinna być prawdziwa tylko wtedy, gdy istnieje alternatywny mechanizm umożliwiający wyjście z Czytnik immersyjny (na przykład strzałka wstecz paska narzędzi mobilnych). |
| cookiePolicy | CookiePolicy | Ustawienie użycia plików cookie Czytnik immersyjny (wartość domyślna to CookiePolicy.Disable). Jest to odpowiedzialność aplikacji hosta za uzyskanie wszelkich niezbędnych zgody użytkownika zgodnie z zasadami zgodności plików cookie UE. Aby uzyskać więcej informacji, zobacz Opcje zasad plików cookie. |
| disableFirstRun | Wartość logiczna | Wyłącz pierwsze środowisko uruchamiania. |
| readAloudOptions | ReadAloudOptions | Opcje konfigurowania odczytu na głos. |
| translationOptions | TranslationOptions | Opcje konfigurowania tłumaczenia. |
| displayOptions | DisplayOptions | Opcje konfigurowania rozmiaru tekstu, czcionki, motywu itd. |
| Preferencje | String | Ciąg zwrócony z elementu onPreferencesChanged reprezentujący preferencje użytkownika w Czytnik immersyjny. Aby uzyskać więcej informacji, zobacz Jak przechowywać preferencje użytkownika. |
| onPreferencesChanged | Function | Wykonuje, gdy preferencje użytkownika uległy zmianie. Aby uzyskać więcej informacji, zobacz Jak przechowywać preferencje użytkownika. |
| disableTranslation | Wartość logiczna | Wyłącz środowisko tłumaczenia wyrazów i dokumentów. |
| disableGrammar | Wartość logiczna | Wyłącz środowisko gramatyki. Ta opcja powoduje również wyłączenie syllables, części mowy i słownika obrazów, które zależą od części mowy. |
| disableLanguageDetection | Wartość logiczna | Wyłącz wykrywanie języka, aby upewnić się, że Czytnik immersyjny używa tylko języka, który jest jawnie określony w fragmentu zawartości/[]. Ta opcja powinna być używana oszczędnie, przede wszystkim w sytuacjach, w których wykrywanie języka nie działa. Na przykład ten problem jest bardziej prawdopodobny w przypadku krótkich fragmentów o mniej niż 100 znaków. Należy mieć pewność, że język, który wysyłasz, ponieważ zamiana tekstu na mowę nie będzie miała poprawnego głosu. Syllables, Part of Speech i Picture Dictionary nie działają poprawnie, jeśli język nie jest poprawny. |
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
Uwaga
Nie próbuj programowo zmieniać wartości ciągu wysyłanego -preferences do i z aplikacji Czytnik immersyjny, ponieważ może to spowodować nieoczekiwane zachowanie, co spowoduje obniżenie wydajności środowiska użytkownika. Aplikacje hosta nigdy nie powinny przypisywać wartości niestandardowej do ciągu ani manipulować nim -preferences . W przypadku korzystania z opcji ciągu użyj tylko dokładnej -preferences wartości zwróconej z opcji wywołania zwrotnego -onPreferencesChanged .
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;
};
| Parametr | Type | Opis |
|---|---|---|
| voice | String | Głos, kobieta lub mężczyzna. Nie wszystkie języki obsługują obie płcie. |
| szybkość | Liczba | Szybkość odtwarzania. Musi należeć do przedziału od 0,5 do 2,5 włącznie. |
| Autoodtwarzanie | Wartość logiczna | Automatycznie uruchom odczyt na głos po załadowaniu Czytnik immersyjny. |
Uwaga
Ze względu na ograniczenia przeglądarki autoodtwarzanie nie jest obsługiwane w przeglądarce 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
TranslationOptions
type TranslationOptions = {
language: string;
autoEnableDocumentTranslation?: boolean;
autoEnableWordTranslation?: boolean;
};
| Parametr | Type | Opis |
|---|---|---|
| język | String | Ustawia język tłumaczenia, wartość jest w formacie tagu IETF BCP 47-language , na przykład fr-FR, es-MX, zh-Hans-CN. Wymagane do automatycznego włączania tłumaczenia wyrazów lub dokumentów. |
| autoEnableDocumentTranslation | Wartość logiczna | Automatycznie przetłumacz cały dokument. |
| autoEnableWordTranslation | Wartość logiczna | Automatycznie włącz tłumaczenie wyrazów. |
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
};
| Parametr | Type | Opis |
|---|---|---|
| Textsize | Liczba | Ustawia wybrany rozmiar tekstu. |
| increaseSpacing | Wartość logiczna | Określa, czy odstęp między tekstami jest włączony, czy wyłączony. |
| Fontfamily | String | Ustawia wybraną czcionkę (Calibri, ComicSans lub Sitka). |
| themeOption | TematOpcje | Ustawia wybrany motyw czytnika (jasny, ciemny). |
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.
| Ustawienie | Type | Opis |
|---|---|---|
| Textsize | Liczba | Ustawia wybrany rozmiar tekstu. |
| Fontfamily | String | Ustawia wybraną czcionkę (Calibri, ComicSans lub Sitka). |
| textSpacing | Liczba | Określa, czy odstęp między tekstami jest włączony, czy wyłączony. |
| formatowanieEnabled | Wartość logiczna | Określa, czy formatowanie HTML jest włączone, czy wyłączone. |
| motyw | String | Ustawia wybrany motyw (jasny, ciemny). |
| syllabificationEnabled | Wartość logiczna | Określa, czy sylabizacja jest włączona, czy wyłączona. |
| NounHighlightingEnabled | Wartość logiczna | Określa, czy wyróżnianie owników jest włączone, czy wyłączone. |
| nounHighlightingColor | String | Ustawia wybrany kolor wyróżniania ciołów. |
| verbHighlightingEnabled | Wartość logiczna | Określa, czy wyróżnianie czasowników jest włączone, czy wyłączone. |
| verbHighlightingColor | String | Ustawia wybrany kolor wyróżniania czasowników. |
| przymiotnik wyróżnianieEnabled | Wartość logiczna | Określa, czy wyróżnianie przymiotnikowe jest włączone, czy wyłączone. |
| Przymiotnik WyróżnianieColor | String | Ustawia wybrany kolor wyróżniania przymiotnikowego. |
| adverbHighlightingEnabled | Wartość logiczna | Określa, czy wyróżnianie przeciwników jest włączone, czy wyłączone. |
| adverbHighlightingColor | String | Ustawia wybrany kolor wyróżniania przeciwnika. |
| pictureDictionaryEnabled | Wartość logiczna | Określa, czy słownik obrazów jest włączony, czy wyłączony. |
| posLabelsEnabled | Wartość logiczna | Określa, czy etykieta tekstowa indeksu górnego każdego wyróżnionego składnika Mowa jest włączona lub wyłączona. |
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.
| HTML | Treści wspierane |
|---|---|
| Style czcionek | Pogrubienie, kursywa, podkreślenie, kod, przekreślenie, indeks górny, indeks dolny |
| Listy nieuporządkowane | Tarcza, okrąg, kwadrat |
| Listy uporządkowane | Liczba dziesiętna, górna alfa, dolna-alfa, rzymsko-górna, dolna-rzymska |
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