Dela via

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

  • Artikel

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

Funktioner

SDK:et exponerar följande funktioner:

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, texteller 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äsareiframe.
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 Klartext.
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.
spela upp automatiskt 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-alternativet inaktiverar 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