naslaginformatie over Insluitende lezer JavaScript SDK (v1.2)
De Insluitende lezer SDK bevat een JavaScript-bibliotheek waarmee u de Insluitende lezer in uw toepassing kunt integreren.
U kunt een HTML<script> element , yarnof gebruiken npmom de bibliotheek van de meest recente stabiele build in uw webtoepassing op te nemen:
<script type='text/javascript' src='https://ircdname.azureedge.net/immersivereadersdk/immersive-reader-sdk.1.2.0.js'></script>
npm install @microsoft/immersive-reader-sdk
yarn add @microsoft/immersive-reader-sdk
Functions
De SDK maakt de functies beschikbaar:
launchAsync
Hiermee start u de Insluitende lezer binnen een HTMLiframe element 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>;
launchAsync-parameters
| Naam | Type | Description |
|---|---|---|
token |
tekenreeks | Het Azure AD verificatietoken. Zie How-To Create an Insluitende lezer Resource (Een Insluitende lezer resource maken) voor meer informatie. |
subdomain |
tekenreeks | Het aangepaste subdomein van uw Insluitende lezer resource in Azure. Zie How-To Create an Insluitende lezer Resource (Een Insluitende lezer resource maken) voor meer informatie. |
content |
Inhoud | Een object met de inhoud die moet worden weergegeven in de Insluitende lezer. |
options |
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 wordt omgezet in een LaunchResponse -object.
Uitzonderingen
De geretourneerde Promise wordt geweigerd met een Error object als de Insluitende lezer niet kan worden geladen. Zie de foutcodes voor meer informatie.
sluiten
Hiermee sluit u de Insluitende lezer.
Een voorbeeld van een gebruiksvoorbeeld voor deze functie is als de knop Afsluiten is verborgen door in te stellen hideExitButton: true in opties. Vervolgens kan een andere knop (bijvoorbeeld de pijl terug van een mobiele header) deze close functie aanroepen wanneer erop wordt geklikt.
close(): void;
Insluitende lezer startknop
De SDK biedt de standaardstijl voor de knop voor het starten van de Insluitende lezer. Gebruik het immersive-reader-button kenmerk class om deze stijl in te schakelen. Zie De knop Insluitende lezer aanpassen voor meer informatie.
<div class='immersive-reader-button'></div>
Optionele kenmerken
Gebruik de volgende kenmerken om het uiterlijk van de knop te configureren.
| Kenmerk | Beschrijving |
|---|---|
data-button-style |
Hiermee stelt u de stijl van de knop in. De waarde kan icon, textof iconAndText zijn. De standaardwaarde is icon. |
data-locale |
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 20px. |
renderButtons
De renderButtons functie is niet nodig als u de instructies voor het aanpassen van de Insluitende lezer-knop gebruikt.
Met deze functie worden de Insluitende lezer knopelementen van het document aangepast. Als options.elements wordt opgegeven, worden de knoppen weergegeven binnen elk element dat is opgegeven in options.elements. Het gebruik van de options.elements parameter is handig als u meerdere secties in uw document hebt waarop u de Insluitende lezer wilt starten en een vereenvoudigde manier wilt om meerdere knoppen met dezelfde stijl weer te geven of de knoppen wilt weergeven met een eenvoudig en consistent ontwerppatroon. Als u deze functie wilt gebruiken met de parameter renderButtons options , roept u ImmersiveReader.renderButtons(options: RenderButtonsOptions); aan bij het laden van de pagina, zoals wordt weergegeven in het onderstaande codefragment. Anders worden de knoppen weergegeven in de elementen van het document die de klasse immersive-reader-button hebben, zoals wordt weergegeven in De knop Insluitende lezer aanpassen.
// 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});
Zie de bovenstaande optionele kenmerken voor meer weergaveopties. Als u deze opties wilt gebruiken, voegt u een van de optiekenmerken toe aan elk van de HTMLDivElement opties in de HTML-code van uw pagina.
renderButtons(options?: RenderButtonsOptions): void;
parameters renderButtons
| Naam | Type | Description |
|---|---|---|
options |
opties voor renderButtons | Opties voor het configureren van bepaald gedrag van de functie renderButtons. Optioneel. |
renderButtons Options
Opties voor het weergeven van de Insluitende lezer knoppen.
{
elements: HTMLDivElement[];
}
parameters voor renderButtons-opties
| Instelling | Type | Description |
|---|---|---|
| Elementen | HTMLDivElement[] | Elementen om de Insluitende lezer knoppen in weer te geven. |
elements
Type: HTMLDivElement[]
Required: false
LaunchResponse
Bevat het antwoord van de aanroep naar ImmersiveReader.launchAsync. Een verwijzing naar het HTMLiframe element dat de Insluitende lezer bevat, is toegankelijk via container.firstChild.
{
container: HTMLDivElement;
sessionId: string;
charactersProcessed: number;
}
LaunchResponse-parameters
| Instelling | Type | Description |
|---|---|---|
| container | HTMLDivElement | HTML-element dat het element Insluitende lezer iframe bevat. |
| Sessionid | Tekenreeks | Globally Unique Identifier voor deze sessie, gebruikt voor foutopsporing. |
| charactersProcessed | getal | Totaal aantal verwerkte tekens |
Fout
Bevat informatie over een fout.
{
code: string;
message: string;
}
Foutparameters
| Instelling | Type | Description |
|---|---|---|
| code | Tekenreeks | Een van een set foutcodes. Zie Foutcodes voor meer informatie. |
| message | Tekenreeks | Door mensen leesbare weergave van de fout. |
Foutcodes
| Code | Description |
|---|---|
| BadArgument | Het opgegeven argument is ongeldig. Zie message de parameter van de fout. |
| Time-out | De Insluitende lezer kan niet worden geladen binnen de opgegeven time-out. |
| TokenExpired | Het opgegeven token is verlopen. |
| Smoorklep | De limiet voor aanroepfrequentie is overschreden. |
Typen
Content
Bevat de inhoud die moet worden weergegeven in de Insluitende lezer.
{
title?: string;
chunks: Chunk[];
}
Inhoudsparameters
| Naam | Type | Description |
|---|---|---|
| title | Tekenreeks | Titeltekst die boven aan de Insluitende lezer wordt weergegeven (optioneel) |
| Brokken | Segment[] | Matrix van segmenten |
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null
Chunk
Eén stuk gegevens, dat wordt doorgegeven aan de inhoud van de Insluitende lezer.
{
content: string;
lang?: string;
mimeType?: string;
}
Segmentparameters
| Naam | Type | Description |
|---|---|---|
| inhoud | Tekenreeks | De tekenreeks die de inhoud bevat die naar de Insluitende lezer is verzonden. |
| lang | Tekenreeks | Taal van de tekst is de waarde in de IETF BCP 47-taaltagindeling, bijvoorbeeld en, es-ES. Taal wordt automatisch gedetecteerd als deze niet is opgegeven. Zie Ondersteunde talen voor meer informatie. |
| Mimetype | tekenreeks | Tekst zonder opmaak, MathML en HTML & 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 | Description |
|---|---|
| tekst/tekst zonder opmaak | Tekst zonder opmaak. |
| text/html | HTML-inhoud. Meer informatie |
| application/mathml+xml | MathML (Mathematical Markup Language). Meer informatie. |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | Microsoft Word .docx documentindeling. |
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;
}
Parameters voor opties
| Naam | Type | Description |
|---|---|---|
| uiLang | Tekenreeks | Taal van de gebruikersinterface, de waarde is in de IETF BCP 47-taaltagindeling, bijvoorbeeld en, es-ES. De standaardinstelling is de browsertaal als deze niet is opgegeven. |
| timeout | Aantal | Duur (in milliseconden) voordat launchAsync mislukt met een time-outfout (standaard 15.000 ms). Deze time-out is alleen van toepassing op de eerste keer dat de pagina Lezer wordt gestart, wanneer de pagina Lezer wordt geopend en de kringvelder wordt gestart. Aanpassing van de time-out zou niet nodig moeten zijn. |
| uiZIndex | Aantal | Z-index van het HTMLiframe element dat wordt gemaakt (standaard is 1000). |
| useWebview | Booleaans | Gebruik een webweergavetag in plaats van een HTMLiframe element voor compatibiliteit met Chrome-apps (standaard is onwaar). |
| onExit | Functie | Wordt uitgevoerd wanneer de Insluitende lezer wordt afgesloten. |
| customDomain | Tekenreeks | Gereserveerd voor intern gebruik. Aangepast domein waarin de Insluitende lezer web-app wordt gehost (standaard is null). |
| allowFullscreen | Booleaans | De mogelijkheid om volledig scherm in te schakelen (standaard is waar). |
| Bovenliggende | Knooppunt | Knooppunt waarin het element of Webview de HTMLiframe container wordt geplaatst. Als het element niet bestaat, wordt iframe in bodygeplaatst. |
| hideExitButton | Booleaans | Hiermee verbergt u de pijl van de afsluitknop 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 (standaardinstelling is CookiePolicy.Disable). Het is de verantwoordelijkheid van de hosttoepassing om alle benodigde gebruikerstoestemming te verkrijgen volgens het EU-cookienalevingsbeleid. Zie Opties voor het cookiebeleid voor meer informatie. |
| disableFirstRun | Booleaans | Schakel de ervaring van de eerste uitvoering 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 tekstgrootte, lettertype, thema, enzovoort. |
| Voorkeuren | Tekenreeks | Tekenreeks geretourneerd door onPreferencesChanged die de voorkeuren van de gebruiker in de Insluitende lezer vertegenwoordigt. Zie Instellingenparameters en Gebruikersvoorkeuren opslaan voor meer informatie. |
| onPreferencesChanged | Functie | Wordt uitgevoerd wanneer de voorkeuren van de gebruiker zijn gewijzigd. Zie Gebruikersvoorkeuren opslaan voor meer informatie. |
| disableTranslation | Booleaans | Schakel de vertaalervaring voor woorden en documenten uit. |
| disableGrammar | Booleaans | Schakel de grammatica-ervaring uit. Met deze optie worden ook lettergrepen, spraakonderdelen en afbeeldingswoordenlijst uitgeschakeld, die afhankelijk zijn van spraakonderdelen. |
| disableLanguageDetection | Booleaans | 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, met name in situaties waarin taaldetectie niet werkt. Dit probleem treedt bijvoorbeeld vaker op bij 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 goed 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
Waarschuwing
BELANGRIJK 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 dat resulteert in een verslechterde gebruikerservaring voor uw klanten. Hosttoepassingen mogen nooit een aangepaste waarde toewijzen aan of de -preferences tekenreeks bewerken. Wanneer u de -preferences tekenreeksoptie gebruikt, gebruikt u alleen de exacte waarde die is geretourneerd door de -onPreferencesChanged callback-optie.
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;
};
ReadAloudOptions-parameters
| Naam | Type | Description |
|---|---|---|
| stem | Tekenreeks | Stem, ofwel "Vrouwelijk" of "Mannelijk". Niet alle talen ondersteunen beide geslachten. |
| snelheid | Aantal | De afspeelsnelheid moet tussen 0,5 en 2,5 liggen. |
| Automatisch afspelen | Booleaans | Automatisch hardop voorlezen starten wanneer de Insluitende lezer wordt geladen. |
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
Notitie
Vanwege browserbeperkingen wordt automatisch afspelen niet ondersteund in Safari.
TranslationOptions
type TranslationOptions = {
language: string;
autoEnableDocumentTranslation?: boolean;
autoEnableWordTranslation?: boolean;
};
TranslationOptions-parameters
| Naam | Type | Description |
|---|---|---|
| language | Tekenreeks | Hiermee stelt u de vertaaltaal in. De waarde heeft de tagindeling IETF BCP 47, bijvoorbeeld fr-FR, es-MX, zh-Hans-CN. Vereist om automatisch word- of documentvertaling in te schakelen. |
| autoEnableDocumentTranslation | Booleaans | Het hele document automatisch vertalen. |
| autoEnableWordTranslation | Booleaans | Automatisch woordvertaling 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
};
DisplayOptions Parameters
| Naam | Type | Description |
|---|---|---|
| textSize | Aantal | Hiermee stelt u de gekozen tekstgrootte in. |
| increaseSpacing | Booleaans | Hiermee stelt u in of de tekstafstand wordt in- of uitgeschakeld. |
| fontFamily | Tekenreeks | 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"
CookieBeleidsopties
enum CookiePolicy { Disable, Enable }
De onderstaande instellingen zijn alleen bedoeld ter informatie. De Insluitende lezer slaat de instellingen, of gebruikersvoorkeuren, op in cookies. Met deze cookiePolicy-optie wordt het gebruik van cookies standaard uitgeschakeld om de EU-wetgeving voor 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 optie cookiePolicy expliciet instellen op CookiePolicy.Enable bij het starten van de Insluitende lezer. In de onderstaande tabel wordt beschreven welke instellingen de Insluitende lezer opslaat in de cookie wanneer de optie cookiePolicy is ingeschakeld.
Parameters voor instellingen
| Instelling | Type | Description |
|---|---|---|
| textSize | Aantal | Hiermee stelt u de gekozen tekstgrootte in. |
| fontFamily | Tekenreeks | Hiermee stelt u het gekozen lettertype in ('Calibri', 'ComicSans' of 'Sitka'). |
| textSpacing | Aantal | Hiermee stelt u in of de tekstafstand wordt in- of uitgeschakeld. |
| formatEnabled | Booleaans | Hiermee stelt u in of HTML-opmaak wordt in- of uitgeschakeld. |
| Thema | Tekenreeks | Hiermee stelt u het gekozen thema in (bijvoorbeeld "Licht", "Donker"...). |
| syllabificationEnabled | Booleaans | Hiermee stelt u in of syllabificatie is in- of uitgeschakeld. |
| nounHighlightingEnabled | Booleaans | Hiermee stelt u in of markering van zelfstandig naamwoorden is in- of uitgeschakeld. |
| nounHighlightingColor | Tekenreeks | Hiermee stelt u de gekozen kleur voor het markeren van een zelfstandig naamwoord in. |
| verbHighlightingEnabled | Booleaans | Hiermee stelt u in of het markeren van werkwoorden wordt in- of uitgeschakeld. |
| verbHighlightingColor | Tekenreeks | Hiermee stelt u de gekozen kleur voor het markeren van werkwoorden in. |
| adjectiveHighlightingEnabled | Booleaans | Hiermee stelt u in of markering van bijvoeglijke naamwoorden wordt in- of uitgeschakeld. |
| adjectiveHighlightingColor | Tekenreeks | Hiermee stelt u de gekozen kleur voor het markeren van bijvoeglijke naamwoorden in. |
| adverbHighlightingEnabled | Booleaans | Hiermee stelt u in of bijwoordmarkering is in- of uitgeschakeld. |
| adverbHighlightingColor | Tekenreeks | Hiermee stelt u de gekozen kleur voor bijwoordmarkeringen in. |
| pictureDictionaryEnabled | Booleaans | Hiermee stelt u in of Afbeeldingswoordenlijst is in- of uitgeschakeld. |
| posLabelsEnabled | Booleaans | Hiermee stelt u in of het superscriptlabel 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, Hoofdletter alfa, Onder alfa, Hoog-Romeins, Lower-Roman |
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
- Internet Explorer 11
- Google Chrome
- Mozilla Firefox
- Apple Safari