Modern olvasó JavaScript SDK-referencia (v1.4)
A Modern olvasó SDK tartalmaz egy JavaScript-kódtárat, amellyel integrálhatja a Modern olvasó az alkalmazásba.
A npmwebalkalmazás legújabb stabil buildjének kódtárát használhatja , yarnvagy HTML-elemet <script> is használhat:
<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
Az SDK a következő függvényeket teszi elérhetővé:
- ImmersiveReader.launchAsync(token, altartomány, tartalom, beállítások)
- ImmersiveReader.close()
- ImmersiveReader.renderButtons(beállítások)
Funkció: launchAsync
ImmersiveReader.launchAsync(token, subdomain, content, options)elindítja a Modern olvasó egy HTML-elemen iframe belül a webalkalmazásban. A tartalom mérete legfeljebb 50 MB lehet.
launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;
| Paraméter | Típus | Leírás |
|---|---|---|
| jogkivonat | húr | A Microsoft Entra hitelesítési jogkivonata. További információ: Hogyan hozhat létre Modern olvasó erőforrást. |
| Aldomain | húr | A Modern olvasó erőforrás egyéni altartománya az Azure-ban. |
| content | Tartalom | A Modern olvasó megjelenítendő tartalmat tartalmazó objektum. |
| Lehetőségek | Beállítások | A Modern olvasó bizonyos viselkedésének konfigurálásának lehetőségei. Opcionális. |
Válaszok
Promise<LaunchResponse>A Modern olvasó betöltésekor feloldó értéket ad vissza. A Promise feloldás egy LaunchResponse objektumra lesz feloldva.
Kivételek
Ha a Modern olvasó nem töltődik be, a visszaadott Promise értéket hibaobjektummal utasítja el a rendszer.
Funkció: close
ImmersiveReader.close()bezárja a Modern olvasó.
Erre a függvényre például akkor van példa, ha a kilépés gomb rejtett a beállítások beállításával.hideExitButton: true Ezután egy másik gomb (például egy mobilfejléc hátranyilása) meghívhatja ezt a close függvényt, amikor rákattint.
close(): void;
Funkció: renderButtons
A ImmersiveReader.renderButtons(options) Modern olvasó gomb útmutatójának testreszabásához nincs szükség a függvényre.
Ez a függvénystílusok és a dokumentum Modern olvasó gombelemeinek frissítése. Ha options.elements meg van adva, akkor a gombok a megadott elemeken options.elementsbelül jelennek meg. options.elements A paraméter használata akkor hasznos, ha több szakaszt tartalmaz a dokumentumban, amelyeken elindítja a Modern olvasó, és egyszerűbb módot szeretne arra, hogy több gombot jelenítsen meg ugyanazzal a stílussal, vagy egyszerű és konzisztens tervezési mintával szeretné megjeleníteni a gombokat. Ha ezt a függvényt a renderButtons beállításparaméterrel szeretné használni, hívja meg ImmersiveReader.renderButtons(options: RenderButtonsOptions); az oldalbetöltést az alábbi kódrészletben bemutatott módon. Ellenkező esetben a gombok a dokumentum azon elemein belül jelennek meg, amelyek az osztályt immersive-reader-button a Modern olvasó gomb testreszabása című témakörben látható módon jelenítik meg.
// 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});
További megjelenítési lehetőségekért tekintse meg az indítási gomb választható attribútumait. A beállítások használatához adja hozzá a beállítási attribútumok HTMLDivElement bármelyikét a lap HTML-fájljában.
renderButtons(options?: RenderButtonsOptions): void;
| Paraméter | Típus | Leírás |
|---|---|---|
| Lehetőségek | renderButtons-beállítások | A renderButtons függvény bizonyos viselkedéseinek konfigurálásának beállításai. Opcionális. |
renderButtons-beállítások
A Modern olvasó gombok megjelenítésének beállításai.
{
elements: HTMLDivElement[];
}
| Paraméter | Típus | Leírás |
|---|---|---|
| Elemek | HTMLDivElement[] | Elemek a Modern olvasó gombok megjelenítéséhez. |
Type: HTMLDivElement[]
Required: false
Indítás gomb
Az SDK alapértelmezett stílust biztosít a Modern olvasó indítási gombhoz. A stílus engedélyezéséhez használja az immersive-reader-button osztályattribútumot. További információ: A Modern olvasó gomb testreszabása.
<div class='immersive-reader-button'></div>
Az alábbi választható attribútumokkal konfigurálhatja a gomb megjelenését és megjelenését.
| Attribútum | Leírás |
|---|---|
| data-button-style | Beállítja a gomb stílusát. iconLehet , textvagy iconAndText. Alapértelmezett érték: icon. |
| adat-területi beállítás | Beállítja a területi beállításokat. Például, en-US vagy fr-FR. Alapértelmezés szerint angol en. |
| data-icon-px-size | Az ikon méretét képpontban állítja be. Alapértelmezés szerint 20 px. |
LaunchResponse
A hívás ImmersiveReader.launchAsyncválaszát tartalmazza. A Modern olvasó tartalmazó HTML-elemre iframe mutató hivatkozás a következővel container.firstChildérhető el:
{
container: HTMLDivElement;
sessionId: string;
charactersProcessed: number;
}
| Paraméter | Típus | Leírás |
|---|---|---|
| tároló | HTMLDivElement | A Modern olvasó iframe elemet tartalmazó HTML-elem. |
| Munkamenet | Sztring | A munkamenet globálisan egyedi azonosítója, amely hibakeresésre szolgál. |
| charactersProcessed | szám | Feldolgozott karakterek teljes száma |
Hiba
Hibainformációkat tartalmaz.
{
code: string;
message: string;
}
| Paraméter | Típus | Leírás |
|---|---|---|
| code | Sztring | Hibakódok egyike. |
| üzenet | Sztring | A hiba emberi olvasásra alkalmas ábrázolása. |
| Hibakód | Leírás |
|---|---|
| BadArgument | A megadott argumentum érvénytelen. Tekintse meg message a hiba paraméterét. |
| Időkorlát | A Modern olvasó nem sikerült betölteni a megadott időtúllépésen belül. |
| TokenExpired | A megadott jogkivonat lejárt. |
| Szabályozva | Túllépte a hívássebesség korlátját. |
Típusok
Tartalom
A Modern olvasó megjelenítendő tartalmat tartalmazza.
{
title?: string;
chunks: Chunk[];
}
| Paraméter | Típus | Leírás |
|---|---|---|
| Cím | Sztring | Címszöveg a Modern olvasó tetején (nem kötelező) |
| Darabokat | Adattömb[] | Tömbök tömbje |
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null
Adattömb
Egyetlen adattömb, amely a Modern olvasó tartalmába kerül.
{
content: string;
lang?: string;
mimeType?: string;
}
| Paraméter | Típus | Leírás |
|---|---|---|
| content | Sztring | A Modern olvasó küldött tartalmat tartalmazó sztring. |
| Lang | Sztring | A szöveg nyelve, az érték IETF BCP 47 nyelvű címkeformátumban van, például en, es-ES. A rendszer automatikusan észleli a nyelvet, ha nincs megadva. További információk: Támogatott nyelvek. |
| mimeType | húr | Egyszerű szöveges, MathML- és HTML- és Microsoft Word DOCX-formátumok támogatottak. További információ: Támogatott MIME-típusok. |
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"
Támogatott MIME-típusok
| MIME-típus | Leírás |
|---|---|
| text/plain | Egyszerű szöveg. |
| szöveg/html | HTML-tartalom. |
| application/mathml+xml | Matematikai korrektúranyelv (MathML). |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | Microsoft Word .docx dokumentum formázása. |
Beállítások
Olyan tulajdonságokat tartalmaz, amelyek a Modern olvasó bizonyos viselkedését konfigurálják.
{
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;
}
| Paraméter | Típus | Leírás |
|---|---|---|
| uiLang | Sztring | A felhasználói felület nyelve, az érték IETF BCP 47 nyelvű címkeformátumban van, például en, es-ES. Alapértelmezés szerint a böngésző nyelve, ha nincs megadva. |
| timeout | Szám | A launchAsync elindítása előtti időtartam (ezredmásodpercben) időtúllépési hibával meghiúsul (az alapértelmezett érték 15 000 ms). Ez az időtúllépés csak az Olvasó lap kezdeti indítására vonatkozik, amikor az Olvasó lap sikeresen megnyílik, és elindul a tárcsa. Nem szükséges módosítani az időtúllépést. |
| uiZIndex | Szám | A létrehozott HTML-elem iframe Z-indexe (alapértelmezés szerint 1000). |
| useWebview | Logikai | Html-elem helyett iframe webnézetcímkét használjon a Chrome Apps-kompatibilitás érdekében (az alapértelmezett érték hamis). |
| onExit | Függvény | Akkor hajtja végre, amikor a Modern olvasó kilép. |
| customDomain | Sztring | Belső használatra van fenntartva. Egyéni tartomány, ahol a Modern olvasó webalkalmazás üzemel (alapértelmezés szerint null). |
| allowFullscreen | Logikai | A teljes képernyős váltás lehetősége (az alapértelmezett érték igaz). |
| Szülő | Csomópont | Csomópont, amelyben a HTML-elem iframe vagy Webview -tároló el van helyezve. Ha az elem nem létezik, az iframe be lesz helyezve.body |
| hideExitButton | Logikai | Elrejti a Modern olvasó kilépési gombját (az alapértelmezett érték hamis). Ez az érték csak akkor lehet igaz, ha van alternatív mechanizmus a Modern olvasó (például egy mobilpult visszanyilat) való kilépéséhez. |
| cookiePolicy | CookiePolicy | A Modern olvasó cookie-használatának beállítása (alapértelmezés szerint a CookiePolicy.Disable). A gazdaalkalmazás felelőssége, hogy beszerezze a szükséges felhasználói hozzájárulást az EU cookie-megfelelőségi szabályzatát követve. További információ: Cookie Policy options. |
| disableFirstRun | Logikai | Tiltsa le az első futtatási felületet. |
| readAloudOptions | ReadAloudOptions | Az olvasási felolvasás konfigurálásához megadott beállítások. |
| translationOptions | TranslationOptions | A fordítás konfigurálható beállításai. |
| displayOptions | DisplayOptions | A szöveg méretének, betűtípusának, témájának stb. konfigurálására vonatkozó beállítások. |
| Beállítások | Sztring | Az onPreferencesChanged függvényből visszaadott sztring a felhasználó beállításainak felel meg a Modern olvasó. További információ: Felhasználói beállítások tárolása. |
| onPreferencesChanged | Függvény | Akkor hajtja végre, amikor a felhasználó beállításai megváltoztak. További információ: Felhasználói beállítások tárolása. |
| disableTranslation | Logikai | Tiltsa le a szó- és dokumentumfordítási felületet. |
| disableGrammar | Logikai | Tiltsa le a nyelvtani felületet. Ez a beállítás letiltja a szótagokat, a beszédrészeket és a képszótárat is, amely a beszédrészek függvénye. |
| disableLanguageDetection | Logikai | Tiltsa le a nyelvészlelést annak biztosításához, hogy a Modern olvasó csak a tartalomtömbön/[] explicit módon megadott nyelvet használja. Ezt a lehetőséget takarékosan kell használni, elsősorban olyan helyzetekben, amikor a nyelvészlelés nem működik. Ez a probléma például nagyobb valószínűséggel fordul elő 100 karakternél rövidebb rövid szakaszok esetén. Biztosnak kell lennie a küldendő nyelvben, mivel a szövegfelolvasás nem lesz a megfelelő hang. A szótagok, a beszédrészek és a képszótár nem működnek megfelelően, ha a nyelv nem megfelelő. |
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
Figyelemfelhívás
Ne kísérelje meg programozott módon módosítani a Modern olvasó alkalmazásba és onnan küldött sztring értékeit-preferences, mert ez váratlan viselkedést okozhat, ami csökkentett felhasználói élményt eredményezhet. A gazdagépalkalmazások soha nem rendelnek egyéni értéket a sztringhez, és nem módosíthatják azt -preferences . A sztringbeállítás -preferences használatakor csak a visszahívási beállításból -onPreferencesChanged visszaadott pontos értéket használja.
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;
};
| Paraméter | Típus | Leírás |
|---|---|---|
| voice | Sztring | Hang, akár nő, akár férfi. Nem minden nyelv támogatja mindkét nemet. |
| sebesség | Szám | Lejátszási sebesség. A 0,5 és 2,5 közötti értéknek kell lennie, beleértve a 0,5-öt is. |
| Robotpilota | Logikai | A Modern olvasó betöltésekor automatikusan elindítja az Olvasás felolvasását. |
Feljegyzés
A böngésző korlátozásai miatt az automatikus lejátszás nem támogatott a Safariban.
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;
};
| Paraméter | Típus | Leírás |
|---|---|---|
| language | Sztring | Beállítja a fordítási nyelvet, az érték IETF BCP 47 nyelvű címkeformátumban van, például fr-FR, es-MX, zh-Hans-CN. A szó- vagy dokumentumfordítás automatikus engedélyezéséhez szükséges. |
| autoEnableDocumentTranslation | Logikai | A teljes dokumentum automatikus lefordítása. |
| autoEnableWordTranslation | Logikai | A szófordítás automatikus engedélyezése. |
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
};
| Paraméter | Típus | Leírás |
|---|---|---|
| textSize | Szám | Beállítja a kiválasztott szövegméretet. |
| increaseSpacing | Logikai | Beállítja, hogy a szövegköz be- vagy ki van-e kapcsolva. |
| fontFamily | Sztring | Beállítja a választott betűtípust (Calibri, ComicSans vagy Sitka). |
| themeOption | ThemeOption | Beállítja az olvasó választott témáját (Világos, Sötét). |
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"
CookiePolicy-beállítások
enum CookiePolicy { Disable, Enable }
Az alábbi beállítások csak tájékoztató jellegűek. A Modern olvasó a beállításokat vagy a felhasználói beállításokat cookie-kban tárolja. Ez a cookiePolicy beállítás alapértelmezés szerint letiltja a cookie-k használatát az EU cookie-megfelelőségi törvényeinek betartása érdekében. Ha újra engedélyezni szeretné a cookie-kat, és vissza szeretné állítani Modern olvasó felhasználói beállítások alapértelmezett funkcióit, a webhelyének vagy alkalmazásának megfelelő hozzájárulásra van szüksége a felhasználótól a cookie-k engedélyezéséhez. Ezután a cookie-k Modern olvasó való újbóli engedélyezéséhez a cookiePolicy beállítást kifejezetten CookiePolicy.Enable értékre kell állítania a Modern olvasó indításakor.
Az alábbi táblázat azt ismerteti, hogy milyen beállításokat tárol a Modern olvasó a cookiePolicy beállítás engedélyezésekor.
| Beállítás | Típus | Leírás |
|---|---|---|
| textSize | Szám | Beállítja a kiválasztott szövegméretet. |
| fontFamily | Sztring | Beállítja a választott betűtípust (Calibri, ComicSans vagy Sitka). |
| textSpacing | Szám | Beállítja, hogy a szövegköz be- vagy ki van-e kapcsolva. |
| formattingEnabled | Logikai | Beállítja, hogy a HTML-formázás be- vagy ki van-e kapcsolva. |
| Téma | Sztring | Beállítja a kiválasztott témát (Világos, Sötét). |
| syllabificationEnabled | Logikai | Beállítja, hogy a szillabification be- vagy ki van-e kapcsolva. |
| nounHighlightingEnabled | Logikai | Beállítja, hogy a főnévkiemelés be- vagy ki van-e kapcsolva. |
| nounHighlightingColor | Sztring | Beállítja a kiválasztott főnévkiemelő színt. |
| verbHighlightingEnabled | Logikai | Beállítja, hogy az igék kiemelése be- vagy ki van-e kapcsolva. |
| verbHighlightingColor | Sztring | Beállítja a választott igekiemelő színt. |
| melléknévHighlightingEnabled | Logikai | Beállítja, hogy a melléknévkiemelés be- vagy ki van-e kapcsolva. |
| melléknévHighlightingColor | Sztring | Beállítja a választott mellékneves-kiemelő színt. |
| adverbHighlightingEnabled | Logikai | Beállítja, hogy az adverb-highlighting be- vagy ki van-e kapcsolva. |
| adverbHighlightingColor | Sztring | Beállítja a kiválasztott adverb-highlighting színt. |
| pictureDictionaryEnabled | Logikai | Beállítja, hogy a Képszótár be- vagy ki van-e kapcsolva. |
| posLabelsEnabled | Logikai | Beállítja, hogy a beszéd egyes kiemelt részeinek felső indexű szövegfelirata be- vagy kikapcsolva legyen-e. |
Támogatott nyelvek
A Modern olvasó fordítási funkciója számos nyelvet támogat. További információ: Nyelvi támogatás.
HTML-támogatás
Ha a formázás engedélyezve van, a következő tartalom html formátumban jelenik meg a Modern olvasó.
| HTML | Támogatott tartalom |
|---|---|
| Betűstílusok | Félkövér, dőlt, aláhúzott, kód, áthúzott, felső index, alsó index |
| Számozatlan listák | Lemez, kör, négyzet |
| Számozott listák | Decimális, felső alfa, alsó-alfa, felső-római, alsó-római |
A nem támogatott címkék összehasonlítható módon jelennek meg. A képek és táblák jelenleg nem támogatottak.
Böngészőtámogatás
A Modern olvasó legjobb élményéhez használja az alábbi böngészők legújabb verzióit.
- Microsoft Edge
- Google Chrome
- Mozilla Firefox
- Apple Safari