Avancerad läsare JavaScript SDK-referens (v1.4)

Artikel
03/05/2024

Avancerad läsare SDK innehåller ett JavaScript-bibliotek som gör att du kan integrera Avancerad läsare i ditt program.

Du kan använda npm, yarneller ett HTML-element <script> för att inkludera biblioteket för den senaste stabila versionen i webbappen:

<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

SDK:et exponerar följande funktioner:

ImmersiveReader.launchAsync(token, underdomän, innehåll, alternativ)
ImmersiveReader.close()
ImmersiveReader.renderButtons(options)

Funktion: `launchAsync`

ImmersiveReader.launchAsync(token, subdomain, content, options)startar Avancerad läsare i ett HTML-element iframe i webbappen. Storleken på ditt innehåll är begränsad till högst 50 MB.

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

Parameter	Typ	Beskrivning
token	sträng	Microsoft Entra-autentiseringstoken. Mer information finns i Skapa en Avancerad läsare resurs.
Underdomän	sträng	Den anpassade underdomänen för din Avancerad läsare resurs i Azure.
innehåll	Innehåll	Ett objekt som innehåller det innehåll som ska visas i Avancerad läsare.
alternativ	Alternativ	Alternativ för att konfigurera vissa beteenden i Avancerad läsare. Valfritt.

Returer

Returnerar en Promise<LaunchResponse>, som matchar när Avancerad läsare läses in. Matchar Promise ett LaunchResponse-objekt .

Undantag

Om Avancerad läsare inte kan läsas in avvisas den returnerade Promise med ett felobjekt.

Funktion: `close`

ImmersiveReader.close()stänger Avancerad läsare.

Ett exempel på användningsfall för den här funktionen är om avslutsknappen är dold genom att ange hideExitButton: true alternativ. Sedan kan en annan knapp (till exempel en mobil rubriks bakåtpil) anropa den här close funktionen när den klickas.

close(): void;

Funktion: `renderButtons`

Funktionen ImmersiveReader.renderButtons(options) är inte nödvändig om du använder vägledningen Så här anpassar du Avancerad läsare-knappen.

Den här funktionen formatmallar och uppdaterar dokumentets Avancerad läsare knappelement. Om options.elements anges återges knapparna i varje element som anges i options.elements. Att använda parametern options.elements är användbart när du har flera avsnitt i dokumentet där du kan starta Avancerad läsare och vill ha ett förenklat sätt att återge flera knappar med samma format, eller vill återge knapparna med ett enkelt och konsekvent designmönster. Om du vill använda den här funktionen med parametern renderButtons-alternativ anropar ImmersiveReader.renderButtons(options: RenderButtonsOptions); du sidinläsningen enligt beskrivningen i följande kodfragment. Annars återges knapparna i dokumentets element som har klassen immersive-reader-button som visas i Så här anpassar du knappen Avancerad läsare.

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

Fler återgivningsalternativ finns i startknappens valfria attribut. Om du vill använda de här alternativen lägger du till något av alternativattributen till var och en HTMLDivElement i sidans HTML-kod.

renderButtons(options?: RenderButtonsOptions): void;

Parameter	Typ	Beskrivning
alternativ	renderButtons-alternativ	Alternativ för att konfigurera vissa beteenden för funktionen renderButtons. Valfritt.

renderButtons-alternativ

Alternativ för att återge knapparna för Avancerad läsare.

{
    elements: HTMLDivElement[];
}

Parameter	Typ	Beskrivning
Element	HTMLDivElement[]	Element som ska återge Avancerad läsare knapparna i.

Type: HTMLDivElement[]
Required: false

Knappen Starta

SDK:t tillhandahåller standardformatering för knappen Avancerad läsare starta. Använd klassattributet immersive-reader-button för att aktivera den här formateringen. Mer information finns i Anpassa knappen Avancerad läsare.

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

Använd följande valfria attribut för att konfigurera knappens utseende och känsla.

Attribut	beskrivning
dataknappsformat	Anger knappens formatmall. Kan vara `icon`, `text`eller `iconAndText`. Standardvärdet är `icon`.
data-språk	Anger nationella inställningar. Exempel: `en-US` eller `fr-FR`. Standardvärdet är engelska `en`.
data-icon-px-size	Anger storleken på ikonen i bildpunkter. Standardvärdet är 20 px.

LaunchResponse

Innehåller svaret från anropet till ImmersiveReader.launchAsync. En referens till HTML-elementet iframe som innehåller Avancerad läsare kan nås via container.firstChild.

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

Parameter	Typ	Beskrivning
container	HTMLDivElement	HTML-element som innehåller elementet Avancerad läsare`iframe`.
sessionId	String	Globalt unik identifierare för den här sessionen, som används för felsökning.
charactersProcessed	Nummer	Totalt antal bearbetade tecken

Fel

Innehåller information om ett fel.

{
    code: string;
    message: string;
}

Parameter	Typ	Beskrivning
kod	String	En av en uppsättning felkoder.
meddelande	String	Mänsklig läsbar representation av felet.

Felkod	beskrivning
BadArgument	Argumentet är ogiltigt. Se `message` parametern för felet.
Timeout	Det gick inte att läsa in Avancerad läsare inom den angivna tidsgränsen.
TokenExpired	Den angivna token har upphört att gälla.
Begränsad	Gränsen för samtalsfrekvens har överskridits.

Typer

Innehåll

Innehåller det innehåll som ska visas i Avancerad läsare.

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

Parameter	Typ	Beskrivning
rubrik	String	Rubriktext som visas överst i Avancerad läsare (valfritt)
Bitar	Segment[]	Matris med segment

`title`

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

`chunks`

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

Segment

Ett enda datasegment som skickas till innehållet i Avancerad läsare.

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

Parameter	Typ	Beskrivning
innehåll	String	Strängen som innehåller innehållet som skickas till Avancerad läsare.
Lang	String	Språket för texten, värdet är i IETF BCP 47-språk taggformat, till exempel en, es-ES. Språket identifieras automatiskt om det inte anges. Mer information finns i språk som stöds.
Mimetype	sträng	Oformaterad text, MathML- och HTML- och Microsoft Word DOCX-format stöds. Mer information finns i MIME-typer som stöds.

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

MIME-typer som stöds

MIME-typ	beskrivning
text/plain	Oformaterad text.
text/html	HTML-innehåll.
application/mathml+xml	Matematiskt markeringsspråk (MathML).
application/vnd.openxmlformats-officedocument.wordprocessingml.document	Microsoft Word .docx formatera dokument.

Alternativ

Innehåller egenskaper som konfigurerar vissa beteenden för Avancerad läsare.

{
    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	Typ	Beskrivning
uiLang	String	Språket i användargränssnittet är värdet i IETF BCP 47-språks taggformat, till exempel en, es-ES. Standardvärdet är webbläsarspråk om det inte anges.
timeout	Antal	Varaktighet (i millisekunder) innan launchAsync misslyckas med ett timeoutfel (standardvärdet är 15 000 ms). Den här tidsgränsen gäller endast för den första starten av sidan Läsare, när sidan Läsare öppnas och spinnaren startar. Det bör inte vara nödvändigt att justera tidsgränsen.
uiZIndex	Antal	Z-index för HTML-elementet `iframe` som skapas (standardvärdet är 1 000).
useWebview	Booleskt	Använd en webbvytagg i stället för ett HTML-element `iframe` för kompatibilitet med Chrome Apps (standardvärdet är falskt).
onExit	Funktion	Körs när Avancerad läsare avslutas.
customDomain	String	Reserverad för internt bruk. Anpassad domän där den Avancerad läsare webbappen finns (standardvärdet är null).
Allowfullscreen	Booleskt	Möjligheten att växla fullskärmsläge (standardvärdet är sant).
överordnad	Nod	Nod där HTML-elementet `iframe` eller `Webview` containern placeras. Om elementet inte finns placeras iframe i `body`.
hideExitButton	Booleskt	Döljer Avancerad läsare avslutsknappspil (standardvärdet är falskt). Det här värdet bör bara vara sant om det finns en alternativ mekanism för att avsluta Avancerad läsare (till exempel en mobil verktygsfälts bakåtpil).
cookiePolicy	CookiePolicy	Inställning för Avancerad läsare cookieanvändning (standard är CookiePolicy.Disable). Det är värdprogrammets ansvar att erhålla alla nödvändiga användarmedgivanden enligt EU:s policy för cookieefterlevnad. Mer information finns i Alternativ för cookieprincip.
disableFirstRun	Booleskt	Inaktivera den första körningen.
readAloudOptions	ReadAloudOptions	Alternativ för att konfigurera Läs upp.
translationOptions	TranslationOptions	Alternativ för att konfigurera översättning.
displayOptions	DisplayOptions	Alternativ för att konfigurera textstorlek, teckensnitt, tema och så vidare.
Inställningar	String	Sträng som returneras från onPreferencesChanged som representerar användarens inställningar i Avancerad läsare. Mer information finns i Så här lagrar du användarinställningar.
onPreferencesChanged	Funktion	Körs när användarens inställningar har ändrats. Mer information finns i Så här lagrar du användarinställningar.
disableTranslation	Booleskt	Inaktivera ord- och dokumentöversättningsupplevelsen.
disableGrammar	Booleskt	Inaktivera grammatikupplevelsen. Det här alternativet inaktiverar också stavelser, delar av tal och bildordlista, som är beroende av delar av tal.
disableLanguageDetection	Booleskt	Inaktivera Språkidentifiering för att säkerställa att Avancerad läsare endast använder det språk som uttryckligen anges i innehållssegmentet /[]. Det här alternativet bör användas sparsamt, främst i situationer där språkidentifiering inte fungerar. Det här problemet är till exempel mer sannolikt med korta passager på färre än 100 tecken. Du bör vara säker på språket du skickar eftersom text till tal inte har rätt röst. Stavelser, delar av tal och bildordlista fungerar inte korrekt om språket inte är korrekt.

`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

Varning

Försök inte att programmatiskt ändra värdena för strängen -preferences som skickas till och från Avancerad läsare-programmet eftersom detta kan orsaka oväntat beteende som resulterar i en försämrad användarupplevelse. Värdprogram bör aldrig tilldela ett anpassat värde till eller ändra strängen -preferences . När du använder strängalternativet -preferences använder du bara det exakta värde som returnerades från återanropsalternativet -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;
};

Parameter	Typ	Beskrivning
voice	String	Röst, antingen kvinna eller man. Alla språk stöder inte båda könen.
hastighet	Antal	Uppspelningshastighet. Måste vara mellan 0,5 och 2,5, inklusive.
Autoplay	Booleskt	Starta Läs upp automatiskt när Avancerad läsare läses in.

Kommentar

På grund av webbläsarbegränsningar stöds inte autoplay i 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	Typ	Beskrivning
språk	String	Anger översättningsspråket, värdet är i IETF BCP 47-språks taggformat, till exempel fr-FR, es-MX, zh-Hans-CN. Krävs för att automatiskt aktivera ord- eller dokumentöversättning.
autoEnableDocumentTranslation	Booleskt	Översätt hela dokumentet automatiskt.
autoEnableWordTranslation	Booleskt	Aktivera automatiskt ordöversättning.

`language`

Type: String
Required: true
Default value: null 
Values available: For more information, see the Supported languages section

TemaAlternativ

enum ThemeOption { Light, Dark }

DisplayOptions

type DisplayOptions = {
    textSize?: number;
    increaseSpacing?: boolean;
    fontFamily?: string;
    themeOption?: ThemeOption
};

Parameter	Typ	Beskrivning
textStorlek	Antal	Anger den valda textstorleken.
increaseSpacing	Booleskt	Anger om textavståndet ska aktiveras eller inaktiveras.
fontFamily	String	Anger det valda teckensnittet (Calibri, ComicSans eller Sitka).
themeOption	TemaAlternativ	Anger det valda temat för läsaren (Ljus, Mörk).

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

enum CookiePolicy { Disable, Enable }

Följande inställningar är endast i informationssyfte. Avancerad läsare lagrar sina inställningar, eller användarinställningar, i cookies. Det här cookiePolicy-alternativetinaktiverar användningen av cookies som standard för att följa EU:s lagar om cookieefterlevnad. Om du vill återaktivera cookies och återställa standardfunktionerna för Avancerad läsare användarinställningar behöver din webbplats eller ditt program rätt medgivande från användaren för att aktivera cookies. För att återaktivera cookies i Avancerad läsare måste du uttryckligen ange cookiePolicy-alternativet till CookiePolicy.Enable när du startar Avancerad läsare.

I följande tabell beskrivs vilka inställningar Avancerad läsare lagrar i sin cookie när alternativet cookiePolicy är aktiverat.

Inställning	Typ	Beskrivning
textStorlek	Antal	Anger den valda textstorleken.
fontFamily	String	Anger det valda teckensnittet (Calibri, ComicSans eller Sitka).
textAvstånd	Antal	Anger om textavståndet ska aktiveras eller inaktiveras.
formateringEnabled	Booleskt	Anger om HTML-formatering ska aktiveras eller inaktiveras.
tema	String	Anger det valda temat (ljust, mörkt).
syllabificationEnabled	Booleskt	Anger om syllabification ska aktiveras eller inaktiveras.
nounHighlightingEnabled	Booleskt	Anger om substantivmarkering ska aktiveras eller inaktiveras.
nounHighlightingColor	String	Anger den valda substantivmarkeringsfärgen.
verbHighlightingEnabled	Booleskt	Anger om verbmarkering ska aktiveras eller inaktiveras.
verbHighlightingColor	String	Anger den valda verbmarkeringsfärgen.
adjectiveHighlightingEnabled	Booleskt	Anger om adjektivmarkering ska aktiveras eller inaktiveras.
adjectiveHighlightingColor	String	Anger den valda adjektivmarkeringsfärgen.
adverbHighlightingEnabled	Booleskt	Anger om adverb-markering ska aktiveras eller inaktiveras.
adverbHighlightingColor	String	Anger den valda adverb-markeringsfärgen.
pictureDictionaryEnabled	Booleskt	Anger om bildordlistan ska aktiveras eller inaktiveras.
posLabelsEnabled	Booleskt	Anger om den upphöjda textetiketten för varje markerad del av tal ska aktiveras eller inaktiveras.

Språk som stöds

Översättningsfunktionen i Avancerad läsare stöder många språk. Mer information finns i Språkstöd.

HTML-stöd

När formatering är aktiverat återges följande innehåll som HTML i Avancerad läsare.

HTML	Innehåll som stöds
Teckenstilar	Fet, kursiv, understrykning, kod, genomstruken, upphöjd, nedsänkt
Osorterade listor	Skiva, cirkel, kvadrat
Ordnade listor	Decimal, övre alfa, lägre alfa, övre romersk, nedre romare

Taggar som inte stöds återges jämförelsevis. Bilder och tabeller stöds för närvarande inte.

Webbläsarstöd

Använd de senaste versionerna av följande webbläsare för att få bästa möjliga upplevelse av Avancerad läsare.

Microsoft Edge
Google Chrome
Mozilla Firefox
Apple Safari

Gå vidare

Utforska Avancerad läsare SDK

Avancerad läsare JavaScript SDK-referens (v1.4)

Functions

Funktion: launchAsync

Returer

Undantag

Funktion: close

Funktion: renderButtons

renderButtons-alternativ

Knappen Starta

LaunchResponse

Fel

Typer

Innehåll

title

chunks

Segment

content

lang

mimeType