Insluitende lezer JavaScript SDK-verwijzing (v1.4)
De Insluitende lezer SDK bevat een JavaScript-bibliotheek waarmee u de Insluitende lezer in uw toepassing kunt integreren.
U kunt , yarnof een HTML-element <script> gebruiken npmom de bibliotheek van de nieuwste stabiele build in uw webtoepassing op te nemen:
<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
De SDK maakt deze functies beschikbaar:
- ImmersiveReader.launchAsync(token, subdomein, inhoud, opties)
- ImmersiveReader.close()
- ImmersiveReader.renderButtons(opties)
Functie: launchAsync
ImmersiveReader.launchAsync(token, subdomain, content, options)start de Insluitende lezer in een HTML-element iframe in uw webtoepassing. De grootte van uw inhoud is beperkt tot maximaal 50 MB.
launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;
| Parameter | Type | Description |
|---|---|---|
| token | tekenreeks | Het Microsoft Entra-verificatietoken. Zie Een Insluitende lezer-resource maken voor meer informatie. |
| Subdomein | tekenreeks | Het aangepaste subdomein van uw Insluitende lezer-resource in Azure. |
| content | Inhoud | Een object dat de inhoud bevat die moet worden weergegeven in de Insluitende lezer. |
| Opties | Opties | Opties voor het configureren van bepaald gedrag van de Insluitende lezer. Optioneel. |
Retouren
Retourneert een Promise<LaunchResponse>, die wordt omgezet wanneer de Insluitende lezer wordt geladen. De Promise oplossing wordt omgezet in een LaunchResponse-object .
Uitzonderingen
Als de Insluitende lezer niet kan worden geladen, wordt het geretourneerde Promise object geweigerd met een foutobject.
Functie: close
ImmersiveReader.close()sluit de Insluitende lezer.
Een voorbeeld van een use case voor deze functie is als de afsluitknop verborgen is door opties in te stellenhideExitButton: true. Vervolgens kan een andere knop (bijvoorbeeld de pijl-terug van een mobiele koptekst) deze close functie aanroepen wanneer erop wordt geklikt.
close(): void;
Functie: renderButtons
De ImmersiveReader.renderButtons(options) functie is niet nodig als u de richtlijnen voor het aanpassen van de Insluitende lezer-knop gebruikt.
Met deze functiestijlen worden de Insluitende lezer knopelementen van het document bijgewerkt. Als options.elements dit is opgegeven, worden de knoppen weergegeven binnen elk element dat is opgegeven in options.elements. Het gebruik van de options.elements parameter is handig wanneer u meerdere secties in uw document hebt waarop u de Insluitende lezer kunt starten en een vereenvoudigde manier wilt gebruiken om meerdere knoppen met dezelfde stijl weer te geven of de knoppen met een eenvoudig en consistent ontwerppatroon wilt weergeven. Als u deze functie wilt gebruiken met de parameter renderButtons-opties , roept ImmersiveReader.renderButtons(options: RenderButtonsOptions); u het laden van pagina's aan, zoals wordt gedemonstreerd in het volgende codefragment. Anders worden de knoppen weergegeven in de elementen van het document die de klasse immersive-reader-button bevatten, zoals wordt weergegeven in Het aanpassen van de knop Insluitende lezer.
// 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});
Bekijk de optionele kenmerken van de startknop voor meer renderingopties. Als u deze opties wilt gebruiken, voegt u een van de optiekenmerken toe aan elk HTMLDivElement kenmerk in de HTML-code van uw pagina.
renderButtons(options?: RenderButtonsOptions): void;
| Parameter | Type | Description |
|---|---|---|
| Opties | renderButtons-opties | Opties voor het configureren van bepaald gedrag van de functie renderButtons. Optioneel. |
renderButtons-opties
Opties voor het weergeven van de Insluitende lezer knoppen.
{
elements: HTMLDivElement[];
}
| Parameter | Type | Description |
|---|---|---|
| Elementen | HTMLDivElement[] | Elementen om de Insluitende lezer knoppen weer te geven. |
Type: HTMLDivElement[]
Required: false
Knop Starten
De SDK biedt standaardstijl voor de Insluitende lezer startknop. Gebruik het immersive-reader-button klassekenmerk om deze stijl in te schakelen. Zie De knop Insluitende lezer aanpassen voor meer informatie.
<div class='immersive-reader-button'></div>
Gebruik de volgende optionele kenmerken om het uiterlijk van de knop te configureren.
| Kenmerk | Beschrijving |
|---|---|
| gegevensknopstijl | Hiermee stelt u de stijl van de knop in. De waarde kan icon, textof iconAndText zijn. Standaard ingesteld op icon. |
| landinstellingen voor gegevens | Hiermee stelt u de landinstelling in. Bijvoorbeeld en-US of fr-FR. Standaard ingesteld op Engels en. |
| data-icon-px-size | Hiermee stelt u de grootte van het pictogram in pixels in. De standaardwaarde is 20 px. |
LaunchResponse
Bevat het antwoord van de aanroep naar ImmersiveReader.launchAsync. Een verwijzing naar het HTML-element iframe dat de Insluitende lezer bevat, kan worden geopend via container.firstChild.
{
container: HTMLDivElement;
sessionId: string;
charactersProcessed: number;
}
| Parameter | Type | Description |
|---|---|---|
| container | HTMLDivElement | HTML-element dat het Insluitende lezer iframe element bevat. |
| sessionId | String | Globally Unique Identifier voor deze sessie, gebruikt voor foutopsporing. |
| tekensProcessed | Nummer | Totaal aantal verwerkte tekens |
Error
Bevat informatie over een fout.
{
code: string;
message: string;
}
| Parameter | Type | Description |
|---|---|---|
| code | String | Een van een set foutcodes. |
| bericht | String | Leesbare weergave van de fout. |
| Foutcode | Beschrijving |
|---|---|
| BadArgument | Het opgegeven argument is ongeldig. Zie message de parameter van de fout. |
| Timeout | De Insluitende lezer kan niet worden geladen binnen de opgegeven time-out. |
| TokenExpired | Het opgegeven token is verlopen. |
| Beperkt | De oproepfrequentielimiet is overschreden. |
Typen
Inhoud
Bevat de inhoud die moet worden weergegeven in de Insluitende lezer.
{
title?: string;
chunks: Chunk[];
}
| Parameter | Type | Description |
|---|---|---|
| titel | String | Titeltekst boven aan de Insluitende lezer (optioneel) |
| Brokken | Segment[] | Matrix van segmenten |
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null
Segment
Eén deel van de gegevens, dat wordt doorgegeven aan de inhoud van de Insluitende lezer.
{
content: string;
lang?: string;
mimeType?: string;
}
| Parameter | Type | Omschrijving |
|---|---|---|
| content | String | De tekenreeks die de inhoud bevat die naar de Insluitende lezer is verzonden. |
| lang | String | De taal van de tekst is de waarde in de tagindeling IETF BCP 47 , bijvoorbeeld en es-ES. Taal wordt automatisch gedetecteerd als deze niet is opgegeven. Zie voor meer informatie Ondersteunde talen. |
| Mimetype | tekenreeks | Tekst zonder opmaak, MathML, HTML en Microsoft Word DOCX-indelingen worden ondersteund. Zie Ondersteunde MIME-typen voor meer informatie. |
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"
Ondersteunde MIME-typen
| MIME-type | Beschrijving |
|---|---|
| text/plain | Tekst zonder opmaak. |
| text/html | HTML-inhoud. |
| application/mathml+xml | Wiskundige opmaaktaal (MathML). |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | Microsoft Word .docx document opmaken. |
Opties
Bevat eigenschappen waarmee bepaald gedrag van de Insluitende lezer wordt geconfigureerd.
{
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;
}
| Parameter | Type | Description |
|---|---|---|
| uiLangLang | String | De taal van de gebruikersinterface heeft de waarde de tagindeling IETF BCP 47 , bijvoorbeeld en es-ES. Standaardinstelling voor browsertaal als deze niet is opgegeven. |
| timeout | Aantal | Duur (in milliseconden) voordat launchAsync mislukt met een time-outfout (standaard is 15.000 ms). Deze time-out is alleen van toepassing op de eerste start van de pagina Lezer, wanneer de pagina Lezer wordt geopend en de spinner wordt gestart. Aanpassing van de time-out hoeft niet nodig te zijn. |
| uiZIndex | Aantal | Z-index van het HTML-element iframe dat wordt gemaakt (standaard is 1000). |
| useWebview | Booleaanse waarde | Gebruik een webweergavetag in plaats van een HTML-element iframe voor compatibiliteit met Chrome-apps (standaard is onwaar). |
| onExit | Functie | Wordt uitgevoerd wanneer de Insluitende lezer wordt afgesloten. |
| customDomain | String | Gereserveerd voor intern gebruik. Aangepast domein waarin de Insluitende lezer web-app wordt gehost (standaard is null). |
| allowFullscreen | Booleaanse waarde | De mogelijkheid om volledig scherm in te schakelen (standaard is waar). |
| bovenliggende | Knooppunt | Knooppunt waarin het HTML-element iframe of Webview de container wordt geplaatst. Als het element niet bestaat, wordt iframe in bodygeplaatst. |
| hideExitButton | Booleaanse waarde | Hiermee verbergt u de pijl voor het afsluiten van de Insluitende lezer (standaard is onwaar). Deze waarde mag alleen waar zijn als er een alternatief mechanisme is om de Insluitende lezer af te sluiten (bijvoorbeeld de pijl-terug van een mobiele werkbalk). |
| cookiePolicy | CookiePolicy | Instelling voor het cookiegebruik van de Insluitende lezer (standaard is CookiePolicy.Disable). Het is de verantwoordelijkheid van de hosttoepassing om de benodigde gebruikerstoestemming te verkrijgen volgens het EU-nalevingsbeleid voor cookies. Zie Opties voor cookiebeleid voor meer informatie. |
| disableFirstRun | Booleaanse waarde | Schakel de eerste uitvoeringservaring uit. |
| readAloudOptions | ReadAloudOptions | Opties voor het configureren van Hardop voorlezen. |
| translationOptions | TranslationOptions | Opties voor het configureren van vertaling. |
| displayOptions | DisplayOptions | Opties voor het configureren van de tekengrootte, het lettertype, het thema, enzovoort. |
| Voorkeuren | String | Tekenreeks die wordt geretourneerd door onPreferencesChanged die de voorkeuren van de gebruiker in de Insluitende lezer vertegenwoordigt. Zie Gebruikersvoorkeuren opslaan voor meer informatie. |
| onPreferencesChanged | Functie | Wordt uitgevoerd wanneer de voorkeuren van de gebruiker zijn gewijzigd. Zie Gebruikersvoorkeuren opslaan voor meer informatie. |
| disableTranslation | Booleaanse waarde | Schakel de vertaalervaring voor woorden en documenten uit. |
| disableGrammar | Booleaanse waarde | Schakel de grammatica-ervaring uit. Met deze optie worden ook lettergrepen, spraakonderdelen en afbeeldingswoordenlijst uitgeschakeld, afhankelijk van spraakonderdelen. |
| disableLanguageDetection | Booleaanse waarde | Schakel Taaldetectie uit om ervoor te zorgen dat de Insluitende lezer alleen de taal gebruikt die expliciet is opgegeven in het inhoudssegment/[]. Deze optie moet spaarzaam worden gebruikt, voornamelijk in situaties waarin taaldetectie niet werkt. Dit probleem treedt bijvoorbeeld vaker op met korte passages van minder dan 100 tekens. U moet zeker zijn van de taal die u verzendt, omdat tekst-naar-spraak niet de juiste stem heeft. Lettergrepen, spraakonderdelen en afbeeldingswoordenlijst werken niet correct als de taal niet juist is. |
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
Let op
Probeer niet programmatisch de waarden van de -preferences tekenreeks te wijzigen die naar en van de Insluitende lezer toepassing wordt verzonden, omdat dit onverwacht gedrag kan veroorzaken, wat resulteert in een verminderde gebruikerservaring. Hosttoepassingen mogen nooit een aangepaste waarde toewijzen aan of bewerken van de -preferences tekenreeks. Wanneer u de -preferences tekenreeksoptie gebruikt, gebruikt u alleen de exacte waarde die is geretourneerd vanuit de -onPreferencesChanged callback-optie.
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;
};
| Parameter | Type | Description |
|---|---|---|
| voice | String | Stem, vrouwelijk of mannelijk. Niet alle talen ondersteunen beide geslachten. |
| snelheid | Aantal | Afspeelsnelheid. Moet tussen 0,5 en 2,5 liggen, inclusief. |
| Automatisch afspelen | Booleaanse waarde | Automatisch hardop voorlezen starten wanneer de Insluitende lezer wordt geladen. |
Notitie
Vanwege browserbeperkingen wordt automatisch afspelen niet ondersteund in 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;
};
| Parameter | Type | Description |
|---|---|---|
| taal | String | Hiermee stelt u de vertaaltaal in, de waarde heeft de tagindeling IETF BCP 47 , bijvoorbeeld fr-FR, es-MX, zh-Hans-CN. Vereist om word- of documentomzetting automatisch in te schakelen. |
| autoEnableDocumentTranslation | Booleaanse waarde | Automatisch het hele document vertalen. |
| autoEnableWordTranslation | Booleaanse waarde | Automatisch woordomzetting inschakelen. |
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
};
| Parameter | Type | Description |
|---|---|---|
| textSize | Aantal | Hiermee stelt u de gekozen tekengrootte in. |
| increaseSpacing | Booleaanse waarde | Hiermee stelt u in of de tekstafstand is in- of uitgeschakeld. |
| fontFamily | String | Hiermee stelt u het gekozen lettertype in (Calibri, ComicSans of Sitka). |
| themeOption | ThemeOption | Hiermee stelt u het gekozen thema van de lezer in (Licht, Donker). |
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"
Opties voor CookiePolicy
enum CookiePolicy { Disable, Enable }
De volgende instellingen zijn alleen bedoeld voor informatieve doeleinden. De Insluitende lezer slaat de instellingen of gebruikersvoorkeuren op in cookies. Met deze cookiePolicy-optiewordt het gebruik van cookies standaard uitgeschakeld om de EU-wetgeving inzake cookienaleving te volgen. Als u cookies opnieuw wilt inschakelen en de standaardfunctionaliteit voor Insluitende lezer gebruikersvoorkeuren wilt herstellen, heeft uw website of toepassing de juiste toestemming van de gebruiker nodig om cookies in te schakelen. Als u cookies vervolgens opnieuw wilt inschakelen in de Insluitende lezer, moet u de cookiePolicy-optieexpliciet instellen op CookiePolicy.Enable bij het starten van de Insluitende lezer.
In de volgende tabel wordt beschreven welke instellingen de Insluitende lezer in de cookie opslaat wanneer de optie cookiePolicy is ingeschakeld.
| Instelling | Type | Description |
|---|---|---|
| textSize | Aantal | Hiermee stelt u de gekozen tekengrootte in. |
| fontFamily | String | Hiermee stelt u het gekozen lettertype in (Calibri, ComicSans of Sitka). |
| textSpacing | Aantal | Hiermee stelt u in of de tekstafstand is in- of uitgeschakeld. |
| formatEnabled | Booleaanse waarde | Hiermee stelt u in of HTML-opmaak is ingeschakeld of uitgeschakeld. |
| thema | String | Hiermee stelt u het gekozen thema in (Licht, Donker). |
| syllabificationEnabled | Booleaanse waarde | Hiermee stelt u in of lettergrepen in- of uitschakelen. |
| zelfstandig naamwoordHighlightingEnabled | Booleaanse waarde | Hiermee stelt u in of zelfstandig naamwoordmarkering is in- of uitgeschakeld. |
| zelfstandig naamwoordHighlightingColor | String | Hiermee stelt u de gekozen kleur voor het markeren van een zelfstandig naamwoord in. |
| verbHighlightingEnabled | Booleaanse waarde | Hiermee stelt u in of het markeren van werkwoorden is in- of uitgeschakeld. |
| verbHighlightingColor | String | Hiermee stelt u de gekozen kleur voor werkwoordmarkeringen in. |
| bijvoeglijk naamwoordHighlightingEnabled | Booleaanse waarde | Hiermee stelt u in of bijvoeglijk naamwoordmarkering is ingeschakeld of uitgeschakeld. |
| bijvoeglijk naamwoordHighlightingColor | String | Hiermee stelt u de gekozen kleur voor bijvoeglijk naamwoordmarkering in. |
| adverbHighlightingEnabled | Booleaanse waarde | Hiermee stelt u in of adverb-markering is ingeschakeld of uitgeschakeld. |
| adverbHighlightingColor | String | Hiermee stelt u de gekozen kleur voor adverb-markering in. |
| pictureDictionaryEnabled | Booleaanse waarde | Hiermee stelt u in of afbeeldingswoordenlijst is ingeschakeld of uitgeschakeld. |
| posLabelsEnabled | Booleaanse waarde | Hiermee stelt u in of het superscripttekstlabel van elk gemarkeerd deel van spraak is in- of uitgeschakeld. |
Ondersteunde talen
De vertaalfunctie van Insluitende lezer ondersteunt veel talen. Zie Taalondersteuning voor meer informatie.
HTML-ondersteuning
Wanneer opmaak is ingeschakeld, wordt de volgende inhoud weergegeven als HTML in de Insluitende lezer.
| HTML | Ondersteunde inhoud |
|---|---|
| Tekenstijlen | Vet, cursief, onderstrepen, code, doorhalen, superscript, subscript |
| Niet-geordende lijsten | Schijf, cirkel, vierkant |
| Geordende lijsten | Decimaal, boven-alfa, onderste alfa, hoofdletter-Romeins, lager-Romeins |
Niet-ondersteunde tags worden vergelijkbaar weergegeven. Afbeeldingen en tabellen worden momenteel niet ondersteund.
Browserondersteuning
Gebruik de meest recente versies van de volgende browsers voor de beste ervaring met de Insluitende lezer.
- Microsoft Edge
- Google Chrome
- Mozilla Firefox
- Apple Safari