referenční informace k sadě JavaScript SDK Asistivní čtečka (v1.4)

Článek
03/01/2024

Sada Asistivní čtečka SDK obsahuje javascriptovou knihovnu, která umožňuje integrovat Asistivní čtečka do aplikace.

K zahrnutí knihovny nejnovějšího stabilního buildu do webové aplikace můžete použít npmelement HTML yarnnebo <script> .

<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

Functions

Sada SDK zveřejňuje tyto funkce:

ImmersiveReader.launchAsync(token, subdoména, obsah, možnosti)
Asistivní čtečka.close()
ImmersiveReader.renderButtons(options)

Funkce: `launchAsync`

ImmersiveReader.launchAsync(token, subdomain, content, options)spustí Asistivní čtečka uvnitř elementu HTML iframe ve webové aplikaci. Velikost obsahu je omezená na maximálně 50 MB.

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

Parametr	Typ	Popis
token	string	Ověřovací token Microsoft Entra. Další informace najdete v tématu Vytvoření prostředku Asistivní čtečka.
Subdoménu	string	Vlastní subdoména vašeho prostředku Asistivní čtečka v Azure.
content	Obsah	Objekt, který obsahuje obsah, který se má zobrazit v Asistivní čtečka.
options	Možnosti	Možnosti konfigurace určitých chování Asistivní čtečka Nepovinné.

Návraty

Vrátí hodnotu Promise<LaunchResponse>, která se vyřeší při načtení Asistivní čtečka. Přeloží Promise se na objekt LaunchResponse .

Výjimky

Pokud se Asistivní čtečka nepodaří načíst, vrácený Promise objekt se odmítne s objektem Error.

Funkce: `close`

ImmersiveReader.close()zavře Asistivní čtečka.

Příkladem použití této funkce je, pokud je tlačítko ukončení skryté nastavením hideExitButton: true v možnostech. Potom může po kliknutí na tuto close funkci volat jiné tlačítko (například šipka zpět mobilního záhlaví).

close(): void;

Funkce: `renderButtons`

Funkce ImmersiveReader.renderButtons(options) není nutná, pokud použijete postup přizpůsobení pokynů k tlačítku Asistivní čtečka.

Tato funkce styly a aktualizuje prvky tlačítka Asistivní čtečka dokumentu. Pokud options.elements je k dispozici, jsou tlačítka vykreslena v rámci každého prvku zadaného v options.elements. Použití parametru options.elements je užitečné, pokud máte v dokumentu více oddílů, na kterých chcete spustit Asistivní čtečka, a chcete zjednodušený způsob vykreslení více tlačítek se stejným stylem nebo chcete tlačítka vykreslit jednoduchým a konzistentním vzorem návrhu. Pokud chcete tuto funkci použít s parametrem možnosti renderButtons, zavolejte ImmersiveReader.renderButtons(options: RenderButtonsOptions); načtení stránky, jak je znázorněno v následujícím fragmentu kódu. V opačném případě se tlačítka vykreslují v elementech dokumentu, které mají tříduimmersive-reader-button, jak je znázorněno v postupu přizpůsobení tlačítka Asistivní čtečka.

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

Další možnosti vykreslování najdete na volitelném tlačítku pro spuštění. Pokud chcete tyto možnosti použít, přidejte do každého HTMLDivElement z html stránky některý z atributů možností.

renderButtons(options?: RenderButtonsOptions): void;

Parametr	Typ	Popis
options	možnosti renderButtons	Možnosti konfigurace určitého chování funkce renderButtons Nepovinné.

možnosti renderButtons

Možnosti pro vykreslení tlačítek Asistivní čtečka

{
    elements: HTMLDivElement[];
}

Parametr	Typ	Popis
elementy	HTMLDivElement[]	Prvky pro vykreslení tlačítek Asistivní čtečka v.

Type: HTMLDivElement[]
Required: false

Tlačítko Spustit

Sada SDK poskytuje výchozí styl tlačítka pro spuštění Asistivní čtečka. immersive-reader-button K povolení tohoto stylu použijte atribut třídy. Další informace naleznete v tématu Jak přizpůsobit tlačítko Asistivní čtečka.

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

Ke konfiguraci vzhledu a chování tlačítka použijte následující volitelné atributy.

Atribut	Popis
data-button-style	Nastaví styl tlačítka. Může být `icon`, `text`nebo `iconAndText`. Výchozí hodnota `icon`je .
národní prostředí dat	Nastaví národní prostředí. Například `en-US` nebo `fr-FR`. Výchozí hodnota je angličtina `en`.
data-icon-px-size	Nastaví velikost ikony v pixelech. Výchozí hodnota je 20 px.

LaunchResponse

Obsahuje odpověď z volání na ImmersiveReader.launchAsync. Odkaz na element HTMLiframe, který obsahuje Asistivní čtečka lze získat přístup prostřednictvím container.firstChild.

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

Parametr	Typ	Popis
kontejner	HTMLDivElement	ELEMENT HTML, který obsahuje Asistivní čtečka `iframe` element.
sessionId	String	Globálně jedinečný identifikátor této relace, který se používá k ladění.
charactersProcessed	Číslo	Celkový počet zpracovaných znaků

Chyba

Obsahuje informace o chybě.

{
    code: string;
    message: string;
}

Parametr	Typ	Popis
code	String	Jedna ze sady kódů chyb.
zpráva	String	Čitelné znázornění chyby člověkem

Kód chyby	Popis
BadArgument	Zadaný argument je neplatný. Viz `message` parametr chyby.
Timeout	Asistivní čtečka se nepodařilo načíst v zadaném časovém limitu.
TokenExpired	Platnost zadaného tokenu vypršela.
Omezeno	Byl překročen limit četnosti volání.

Typy

Content

Obsahuje obsah, který se má zobrazit v Asistivní čtečka.

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

Parametr	Typ	Popis
nadpis	String	Text nadpisu zobrazený v horní části Asistivní čtečka (volitelné)
Kousky	Blok dat[]	Pole bloků dat

`title`

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

`chunks`

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

Blok dat

Jeden blok dat, který se předává do obsahu Asistivní čtečka.

{
    content: string;
    lang?: string;
    mimeType?: string;
}

Parametr	Typ	Popis
content	String	Řetězec, který obsahuje obsah odeslaný do Asistivní čtečka.
Lang	String	Jazyk textu, hodnota je ve formátu značky IETF BCP 47 jazyka , například en, es-ES. Pokud není zadaný jazyk, rozpozná se automaticky. Další informace najdete v části Podporované jazyky.
Mimetype	string	Podporují se formáty prostého textu, MathML, HTML a Microsoft Word DOCX. Další informace naleznete v tématu Podporované 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"

Podporované typy MIME

Typ MIME	Popis
text/plain	Prostý text.
text/html	Obsah HTML.
application/mathml+xml	Math Markup Language (MathML)
application/vnd.openxmlformats-officedocument.wordprocessingml.document	Dokument formátu aplikace Microsoft Word .docx

Možnosti

Obsahuje vlastnosti, které konfigurují určité chování Asistivní čtečka.

{
    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	Typ	Popis
uiLang	String	Jazyk uživatelského rozhraní, hodnota je ve formátu značky IETF BCP 47 , například en, es-ES. Pokud není zadaný, nastaví se výchozí hodnota jazyka prohlížeče.
timeout	Počet	Doba trvání (v milisekundách) před selháním launchAsync s chybou časového limitu (výchozí hodnota je 15 000 ms). Tento časový limit platí jenom pro počáteční spuštění stránky Čtenář, když se stránka Čtenář úspěšně otevře a spustí se číselník. Úprava časového limitu by neměla být nutná.
uiZIndex	Počet	Index Z elementu HTML `iframe` , který je vytvořen (výchozí hodnota je 1000).
useWebview	Logická hodnota	Místo elementu HTML `iframe` použijte značku webview kvůli kompatibilitě s aplikacemi pro Chrome (výchozí hodnota je false).
onExit	Function	Spustí se při ukončení Asistivní čtečka.
customDomain	String	Vyhrazeno pro interní použití. Vlastní doména, ve které je webová aplikace Asistivní čtečka hostovaná (výchozí hodnota je null).
allowFullscreen	Logická hodnota	Možnost přepnout celou obrazovku (výchozí hodnota je true).
parent	Uzel	Uzel, ve kterém je umístěn element HTML `iframe` nebo `Webview` kontejner. Pokud prvek neexistuje, je prvek iframe umístěn do `body`.
hideExitButton	Logická hodnota	Skryje šipku tlačítka pro ukončení Asistivní čtečka (výchozí hodnota je false). Tato hodnota by měla být pravdivá pouze v případě, že existuje alternativní mechanismus pro ukončení Asistivní čtečka (například šipka zpět mobilního panelu nástrojů).
cookiePolicy	CookiePolicy	Nastavení pro použití souborů cookie Asistivní čtečka (výchozí hodnota je CookiePolicy.Disable). Hostitelská aplikace zodpovídá za získání veškerého nezbytného souhlasu uživatele v souladu se zásadami dodržování předpisů EU pro soubory cookie. Další informace najdete v tématu Možnosti zásad souborů cookie.
disableFirstRun	Logická hodnota	Zakažte první spuštění.
readAloudOptions	ReadAloudOptions	Možnosti konfigurace funkce Číst nahlas
translationOptions	TranslationOptions	Možnosti konfigurace překladu
displayOptions	DisplayOptions	Možnosti konfigurace velikosti textu, písma, motivu atd.
Předvolby	String	Řetězec vrácený z onPreferencesChanged představující předvolby uživatele v Asistivní čtečka. Další informace naleznete v tématu Ukládání uživatelských předvoleb.
onPreferencesChanged	Function	Spustí se, když se změní předvolby uživatele. Další informace naleznete v tématu Ukládání uživatelských předvoleb.
disableTranslation	Logická hodnota	Zakažte prostředí překladu slov a dokumentů.
disableGrammar	Logická hodnota	Zakažte prostředí Gramatika. Tato možnost také zakáže slabiky, slovní druhy a slovník obrázků, které závisí na slovních částech.
disableLanguageDetection	Logická hodnota	Zakažte rozpoznávání jazyka, abyste zajistili, že Asistivní čtečka používá pouze jazyk, který je explicitně specifikován v bloku obsahu /[]. Tato možnost by se měla používat střídmě, především v situacích, kdy rozpoznávání jazyka nefunguje. K tomuto problému může dojít například u krátkých pasáží s méně než 100 znaky. Měli byste mít jistotu o jazyce, který posíláte, protože text na řeč nebude mít správný hlas. Slabiky, slovní druhy a slovník obrázků nefungují správně, pokud jazyk není správný.

`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

Upozornění

Nepokoušejte se programově změnit hodnoty -preferences řetězce odesílaného do a z aplikace Asistivní čtečka, protože to může způsobit neočekávané chování, které vede ke zhoršení uživatelského prostředí. Hostitelské aplikace by nikdy neměly přiřazovat vlastní hodnotu řetězci ani s ním -preferences manipulovat. Při použití -preferences možnosti řetězce použijte pouze přesnou hodnotu vrácenou z možnosti zpětného -onPreferencesChanged volání.

`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	Typ	Popis
voice	String	Hlas, žena nebo muž. Ne všechny jazyky podporují obě pohlaví.
rychlost	Počet	Rychlost přehrávání. Musí být v rozmezí od 0,5 do 2,5 včetně.
Automatické přehrávání	Logická hodnota	Automaticky spustit čtení nahlas při načtení Asistivní čtečka.

Poznámka:

Vzhledem k omezením prohlížeče se automatické přehrávání v Safari nepodporuje.

`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	Typ	Popis
jazyk	String	Nastaví jazyk překladu, hodnota je ve formátu značky IETF BCP 47, například fr-FR, es-MX, zh-Hans-CN. Vyžaduje se k automatickému povolení překladu textu nebo dokumentu.
autoEnableDocumentTranslation	Logická hodnota	Automaticky přeložit celý dokument.
autoEnableWordTranslation	Logická hodnota	Automatické povolení překladu slov

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

Parametr	Typ	Popis
TextSize	Počet	Nastaví zvolenou velikost textu.
increaseSpacing	Logická hodnota	Nastaví, jestli je zapnuté nebo vypnuté řádkování textu.
Fontfamily	String	Nastaví zvolené písmo (Calibri, ComicSans nebo Sitka).
themeOption	ThemeOption	Nastaví vybraný motiv čtenáře (světlý, tmavý).

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

Možnosti cookiePolicy

enum CookiePolicy { Disable, Enable }

Následující nastavení jsou určena pouze pro informační účely. Asistivní čtečka ukládá do souborů cookie svoje nastavení nebo uživatelské předvolby. Tato možnost cookiePolicy zakáže používání souborů cookie ve výchozím nastavení podle zákonů EU o dodržování předpisů cookie. Pokud chcete soubory cookie znovu povolit a obnovit výchozí funkce pro Asistivní čtečka uživatelské předvolby, musí váš web nebo aplikace udělit uživateli správný souhlas s povolením souborů cookie. Pokud chcete soubory cookie v Asistivní čtečka znovu povolit, musíte při spuštění Asistivní čtečka explicitně nastavit možnost cookiePolicy na CookiePolicy.Enable.

Následující tabulka popisuje, jaká nastavení Asistivní čtečka ukládá do souboru cookie, když je povolená možnost cookiePolicy.

Nastavení	Typ	Popis
TextSize	Počet	Nastaví zvolenou velikost textu.
Fontfamily	String	Nastaví zvolené písmo (Calibri, ComicSans nebo Sitka).
mezery mezi texty	Počet	Nastaví, jestli je zapnuté nebo vypnuté řádkování textu.
formattingEnabled	Logická hodnota	Nastaví, jestli je formátování HTML zapnuté nebo vypnuté.
motiv	String	Nastaví vybraný motiv (světlý, tmavý).
syllabificationEnabled	Logická hodnota	Nastaví, jestli je slabičení zapnuté nebo vypnuté.
nounHighlightingEnabled	Logická hodnota	Nastaví, jestli je zvýraznění podstatného jména zapnuté nebo vypnuté.
nounHighlightingColor	String	Nastaví zvolenou barvu zvýraznění podstatného jména.
verbHighlightingEnabled	Logická hodnota	Nastaví, jestli je zapnuté nebo vypnuté zvýrazňování sloves.
verbHighlightingColor	String	Nastaví zvolenou barvu zvýrazňování sloves.
adjectiveHighlightingEnabled	Logická hodnota	Nastaví, jestli je zapnuté nebo vypnuté zvýrazňování přídavných jmen.
adjectiveHighlightingColor	String	Nastaví zvolenou barvu zvýraznění přídavných jmen.
adverbHighlightingEnabled	Logická hodnota	Nastaví, jestli je zapnuté nebo vypnuté zvýrazňování přísloví.
adverbHighlightingColor	String	Nastaví zvolenou barvu zvýraznění přísloví.
pictureDictionaryEnabled	Logická hodnota	Nastaví, jestli je slovník obrázků zapnutý nebo vypnutý.
posLabelsEnabled	Logická hodnota	Nastaví, jestli je zapnutý nebo vypnutý popisek textu horního indexu každé zvýrazněné části řeči.

Podporované jazyky

Funkce překladu Asistivní čtečka podporuje mnoho jazyků. Další informace najdete v tématu Podpora jazyků.

Podpora HTML

Pokud je formátování povolené, následující obsah se v Asistivní čtečka vykreslí jako HTML.

HTML	Podporovaný obsah
Styly písma	Tučné, kurzíva, podtržení, kód, přeškrtnutí, horní index, dolní index
Neuspořádané seznamy	Disk, kruh, čtverec
Uspořádané seznamy	Decimal, upper-Alpha, lower-Alpha, upper-Roman, lower-Roman

Nepodporované značky se vykreslují srovnatelně. Obrázky a tabulky se v současné době nepodporují.

Podpora prohlížečů

Nejlepší možnosti s Asistivní čtečka vám použijí nejnovější verze následujících prohlížečů.

Microsoft Edge
Google Chrome
Mozilla Firefox
Apple Safari

Další krok

Prozkoumání sady Asistivní čtečka SDK

referenční informace k sadě JavaScript SDK Asistivní čtečka (v1.4)

Functions

Funkce: launchAsync

Návraty

Výjimky

Funkce: close

Funkce: renderButtons

možnosti renderButtons

Tlačítko Spustit

LaunchResponse

Chyba

Typy

Content

title

chunks

Blok dat

content

lang

mimeType