Plastischer Reader JavaScript SDK-Referenz (v1.4)

  • Artikel

Das Plastischer Reader-SDK enthält eine JavaScript-Bibliothek, die es Ihnen ermöglicht, den Plastischen Reader in Ihre Anwendung zu integrieren.

Sie können die Bibliothek des neuesten stabilen Builds in Ihre Webanwendung verwenden, yarnoder ein HTML-Element <script> verwendennpm:

<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

Funktionen

Das SDK macht diese Funktionen verfügbar:

Funktion: launchAsync

ImmersiveReader.launchAsync(token, subdomain, content, options)Startet die Plastischer Reader in einem HTML-Element iframe in Ihrer Webanwendung. Die Größe Ihres Inhalts ist auf höchstens 50 MB beschränkt.

launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;
Parameter Typ Beschreibung
token Zeichenfolge Dabei handelt es sich um das Microsoft Entra-Authentifizierungstoken. Weitere Informationen finden Sie unter Erstellen einer Plastischer Reader Ressource.
Unterdomäne Zeichenfolge Die benutzerdefinierte Unterdo Standard Ihrer Plastischer Reader Ressource in Azure.
content Inhalt Ein Objekt, das den inhalt enthält, der im Plastischer Reader angezeigt werden soll.
Optionen Optionen Optionen zum Konfigurieren bestimmter Verhaltensweisen des Plastischen Readers. Optional.

Rückgabe

Gibt ein Promise<LaunchResponse> zurück, das beim Laden des Plastischen Readers aufgelöst wird. Die Promise Auflösung wird in ein LaunchResponse-Objekt aufgelöst.

Ausnahmen

Wenn die Plastischer Reader nicht geladen werden kann, wird die zurückgegebene Promise Datei mit einem Error-Objekt abgelehnt.

Funktion: close

ImmersiveReader.close()schließt die Plastischer Reader.

Ein Beispiel eines Anwendungsfalls für diese Funktion ist, wenn die Schaltfläche „Beenden“ durch die Einstellung hideExitButton: true in Optionen ausgeblendet wird. Anschließend kann eine andere Schaltfläche (z. B. der Rückpfeil einer mobilen Kopfzeile) diese close Funktion aufrufen, wenn darauf geklickt wird.

close(): void;

Funktion: renderButtons

Die ImmersiveReader.renderButtons(options) Funktion ist nicht erforderlich, wenn Sie die Anleitung zum Anpassen der Plastischer Reader Schaltfläche verwenden.

Diese Funktion formatiert und aktualisiert die Schaltflächenelemente für „Plastischer Reader“ des Dokuments. Wenn options.elements angegeben, werden die Schaltflächen innerhalb der einzelnen elemente gerendert, die in options.elements. Die Verwendung des Parameters options.elements ist hilfreich, wenn Sie mehrere Abschnitte in Ihrem Dokument besitzen, auf denen der plastische Reader gestartet werden soll, und Sie eine vereinfachte Möglichkeit zum Rendern mehrerer Schaltflächen mit demselben Format wünschen oder die Schaltflächen mit einem einfachen und konsistenten Entwurfsmuster darstellen möchten. Um diese Funktion mit dem parameter "renderButtons options " zu verwenden, rufen Sie ImmersiveReader.renderButtons(options: RenderButtonsOptions); das Laden der Seite auf, wie im folgenden Codeausschnitt gezeigt. Andernfalls werden die Schaltflächen innerhalb der Elemente des Dokuments gerendert, die die Klasse immersive-reader-button aufweisen, wie in how to customize the Plastischer Reader button.

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

Unter den optionalen Attributen der Startschaltfläche finden Sie weitere Renderingoptionen. Fügen Sie jedem HTMLDivElement in Ihrem HTML-Code der Seite eines der Optionsattribute hinzu, um diese Optionen zu verwenden.

renderButtons(options?: RenderButtonsOptions): void;
Parameter Typ Beschreibung
Optionen renderButtons options Optionen zum Konfigurieren bestimmter Verhaltensweisen der Funktion „renderButtons“. Optional.

renderButtons options

Optionen für das Rendering der Schaltflächen des Plastischen Readers.

{
    elements: HTMLDivElement[];
}
Parameter Typ Beschreibung
Elemente HTMLDivElement[] Elemente, in denen die Schaltflächen des plastischen Readers gerendert werden. 
Type: HTMLDivElement[]
Required: false

Schaltfläche "Start"

Das SDK bietet standardmäßige Formatierungen für die Plastischer Reader Startschaltfläche. Verwenden Sie das Klassenattribut immersive-reader-button zum Aktivieren dieses Stils. Weitere Informationen finden Sie unter Anpassen der Schaltfläche Plastischer Reader.

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

Verwenden Sie die folgenden optionalen Attribute, um das Aussehen und Verhalten der Schaltfläche zu konfigurieren.

attribute BESCHREIBUNG
Data-Button-Style Legt den Stil der Schaltfläche fest. Kann icon, text oder iconAndText sein. Der Standardwert lautet icon.
Datengebietsschema Legt das Gebietsschema fest. Zum Beispiel: en-US oder fr-FR. Der Standardwert ist „Englisch“ en.
data-icon-px-size Legt die Größe des Symbols in Pixel fest. Standardwert ist 20 px.

LaunchResponse

Enthält die Antwort aus dem Aufruf von ImmersiveReader.launchAsync. Auf einen Verweis auf das HTML-Elementiframe, das die Plastischer Reader enthält, kann über container.firstChilddiese zugegriffen werden.

{
    container: HTMLDivElement;
    sessionId: string;
    charactersProcessed: number;
}
Parameter Typ BESCHREIBUNG
Container HTMLDivElement HTML-Element, das das iframe-Element des plastischen Readers enthält.
sessionID String Global eindeutiger Bezeichner für diese Sitzung, der zum Debuggen verwendet wird.
charactersProcessed number Gesamtzahl verarbeiteter Zeichen

Fehler

Enthält Informationen zu einem Fehler.

{
    code: string;
    message: string;
}
Parameter Typ BESCHREIBUNG
code String Einer aus einer Reihe von Fehlercodes.
message String Lesbare Darstellung des Fehlers.
Fehlercode Beschreibung
BadArgument Das angegebene Argument ist ungültig. Siehe message Parameter des Fehlers.
Timeout Der Plastische Reader konnte innerhalb des angegebenen Zeitlimits nicht geladen werden.
TokenExpired Das angegebene Token ist abgelaufen.
Gedrosselt Das Limit für die Aufrufrate wurde überschritten.

Typen

Inhalt

Enthält den Inhalt, der im Plastischen Reader angezeigt werden soll.

{
    title?: string;
    chunks: Chunk[];
}
Parameter Typ BESCHREIBUNG
Titel String Titeltext, der oben auf dem plastischen Reader angezeigt wird (optional).
Blöcke Chunk[] Array von Blöcken
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null

Block

Ein einzelner Datenabschnitt, der an den Inhalt der Plastischer Reader übergeben wird.

{
    content: string;
    lang?: string;
    mimeType?: string;
}
Parameter Typ Beschreibung
Inhalt String Die Zeichenfolge, die den an den plastischen Reader gesendeten Inhalt enthält.
lang String Die Sprache des Texts, der Wert befindet sich im IETF BCP 47-Sprachtagformat , z. B. en, es-ES. Die Sprache wird automatisch erkannt, wenn sie nicht angegeben ist. Weitere Informationen finden Sie unter unterstützte Sprachen.
mimeType Zeichenfolge Nur-Text-, MathML-, HTML- und Microsoft Word DOCX-Formate werden unterstützt. Weitere Informationen finden Sie unter Unterstützte MIME-Typen.
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"

Unterstützte MIME-Typen

MIME-Typ BESCHREIBUNG
text/plain Nur-Text.
text/html HTML-Inhalt.
application/mathml+xml Mathematical Markup Language (MathML).
application/vnd.openxmlformats-officedocument.wordprocessingml.document Dokument im DOCX-Format von Microsoft Word.

Tastatur

Enthält Eigenschaften, die bestimmte Verhaltensweisen des Plastischen Readers konfigurieren.

{
    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 Beschreibung
uiLang String Die Sprache der Benutzeroberfläche weist den Wert im IETF BCP 47-Sprachtagformat auf, z. B. en, es-ES. Standardmäßig wird die Browsersprache verwendet, falls nicht angegeben.
timeout Nr. Dauer (in Millisekunden), bevor bei launchAsync ein Timeoutfehler auftritt (Standard ist 15.000 ms). Dieser Timeout gilt nur für den anfänglichen Start der Seite „Reader“, wenn die Seite „Reader“ erfolgreich geöffnet und das Drehfeld gestartet wird. Die Anpassung des Timeouts sollte nicht erforderlich sein.
uiZIndex Zahl Z-Index des erstellten HTML-Elements iframe (Standardwert ist 1000).
useWebview Boolean Verwenden Sie ein Webview-Tag anstelle eines HTML-Elements iframe , um kompatibilität mit Chrome-Apps zu gewährleisten (Standardwert ist "false").
onExit Funktion Wird ausgeführt, wenn der plastische Reader beendet wird.
customDomain String Für die interne Verwendung reserviert. Benutzerdefinierte Domäne, in der die Web-App des plastischen Readers gehostet wird (der Standardwert ist „NULL“).
allowFullscreen Boolean Die Möglichkeit zum Vollbildschirm zu wechseln (der Standardwert ist „true“).
parent Node Knoten, in dem das HTML-Element oder Webview der Container iframe platziert wird. Wenn das Element nicht vorhanden ist, wird iframe in body platziert.
hideExitButton Boolean Blendet den Pfeil der Schaltfläche „Beenden“ des plastischen Readers aus (der Standardwert ist „false“). Dieser Wert sollte nur true sein, wenn ein alternativer Mechanismus zum Beenden der Plastischer Reader bereitgestellt wird (z. B. der Zurückpfeil einer mobilen Symbolleiste).
cookiePolicy CookiePolicy Einstellung für die Verwendung von Cookies für den plastischen Reader (der Standardwert ist CookiePolicy.Disable). Es liegt in der Verantwortung der Hostanwendung, die erforderliche Zustimmung des Benutzers in Übereinstimmung mit der Cookiekonformitätsrichtlinie der EU einzuholen. Weitere Informationen finden Sie unter Cookie-Richtlinienoptionen.
disableFirstRun Boolean Deaktiviert die zuerst ausgeführte Umgebung.
readAloudOptions ReadAloudOptions Optionen zum Konfigurieren des lauten Vorlesens.
translationOptions TranslationOptions Optionen zum Konfigurieren der Übersetzung.
displayOptions DisplayOptions Optionen zum Konfigurieren von Textgröße, Schriftart, Design usw.
Voreinstellungen String Von onPreferencesChanged zurückgegebene Zeichenfolge, die die Voreinstellungen des Benutzers im plastischen Reader darstellt. Weitere Informationen finden Sie unter Speichern von Benutzereinstellungen.
onPreferencesChanged Funktion Wird ausgeführt, wenn sich die Voreinstellungen des Benutzers geändert haben. Weitere Informationen finden Sie unter Speichern von Benutzereinstellungen.
disableTranslation Boolean Deaktiviert die Übersetzungserfahrung für Wörter und Dokumente.
disableGrammar Boolean Deaktiviert die Grammatikerfahrung. Mit dieser Option werden auch Silben, Teile von Sprache und Bildwörterbuch deaktiviert, die von Sprachteilen abhängig sind.
disableLanguageDetection Boolean Deaktiviert die Sprachenerkennung, um sicherzustellen, dass der plastische Reader nur die Sprache verwendet, die explizit im Content/Chunk[] angegeben ist. Diese Option sollte sparsam verwendet werden, in erster Linie in Situationen, in denen die Spracherkennung nicht funktioniert. Beispielsweise ist dieses Problem wahrscheinlicher mit kurzen Passagen von weniger als 100 Zeichen. Sie sollten sich bei der Sprache sicher sein, die Sie senden, da die Sprachsynthese sonst nicht die richtige Stimme hat. Silben, Wortarten und Bildwörterbuch funktionieren nicht ordnungsgemäß, wenn die Sprache nicht korrekt ist.
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

Achtung

Versuchen Sie nicht, die Werte der -preferences an und von der Plastischer Reader Anwendung gesendeten Zeichenfolge programmgesteuert zu ändern, da dies zu unerwartetem Verhalten führen kann, was zu einer beeinträchtigten Benutzererfahrung führt. Hostanwendungen sollten der Zeichenfolge -preferences niemals einen benutzerdefinierten Wert zuweisen oder sie manipulieren. Wenn Sie die Zeichenfolgenoption -preferences verwenden, verwenden Sie nur genau den Wert, der von der Rückrufoption -onPreferencesChanged zurückgegeben wurde.

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 Beschreibung
voice String Stimme, entweder weiblich oder männlich. Nicht alle Sprachen unterstützen beide Geschlechter.
Geschwindigkeit Zahl Wiedergabegeschwindigkeit. Muss zwischen 0,5 und 2,5 (einschließlich) liegen.
autoPlay Boolean Starten Sie automatisch das laute Vorlesen, wenn der plastische Reader geladen wird.

Hinweis

Aufgrund von Browsereinschränkungen wird die automatische Wiedergabe in Safari nicht unterstützt.

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 BESCHREIBUNG
language String Legt die Übersetzungssprache fest, der Wert befindet sich im IETF BCP 47-Sprachtagformat , z. B. fr-FR, es-MX, zh-Hans-CN. Erforderlich zur automatischen Aktivierung der Wort- oder Dokumentübersetzung.
autoEnableDocumentTranslation Boolean Übersetzen Sie automatisch das gesamte Dokument.
autoEnableWordTranslation Boolean Aktivieren Sie automatisch die Übersetzung von Wörtern.
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 Typ Beschreibung
textSize Nr. Legt die gewählte Textgröße fest.
increaseSpacing Boolean Legt fest, ob der Textabstand aktiviert oder deaktiviert wird.
fontFamily String Legt die ausgewählte Schriftart fest (Calibri, ComicSans oder Sitka).
themeOption ThemeOption Legt das ausgewählte Design des Readers fest (Hell, Dunkel).
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-Optionen

enum CookiePolicy { Disable, Enable }

Die folgenden Einstellungen dienen nur informationszwecken. Der plastische Reader speichert seine Einstellungen bzw. Benutzervoreinstellungen in Cookies. Diese cookiePolicy-Option deaktiviert standardmäßig die Verwendung von Cookies, um den Gesetzen der Cookiekonformitätsrichtlinie der EU zu entsprechen. Wenn Sie Cookies erneut aktivieren und die Standardfunktionalität für Plastischer Reader Benutzereinstellungen wiederherstellen möchten, benötigt Ihre Website oder Anwendung eine ordnungsgemäße Zustimmung des Benutzers, um Cookies zu aktivieren. Um Cookies im plastischen Reader wieder zu aktivieren, müssen Sie dann beim Start des plastischen Readers die Option cookiePolicy explizit auf CookiePolicy.Enable festlegen.

In der folgenden Tabelle wird beschrieben, welche Einstellungen der Plastischer Reader in seinem Cookie speichert, wenn die CookiePolicy-Option aktiviert ist.

Einstellung type Beschreibung
textSize Nr. Legt die gewählte Textgröße fest.
fontFamily String Legt die ausgewählte Schriftart fest (Calibri, ComicSans oder Sitka).
textSpacing Nr. Legt fest, ob der Textabstand aktiviert oder deaktiviert wird.
formattingEnabled Boolean Legt fest, ob die HTML-Formatierung aktiviert oder deaktiviert wird.
Design String Legt das ausgewählte Design fest (Hell, Dunkel).
syllabificationEnabled Boolean Legt fest, ob die Silbentrennung aktiviert oder deaktiviert wird.
nounHighlightingEnabled Boolean Legt fest, ob die Hervorhebung von Nomen aktiviert oder deaktiviert ist.
nounHighlightingColor String Legt die gewählte Farbe für die Hervorhebung der Nomen fest.
verbHighlightingEnabled Boolean Legt fest, ob die Hervorhebung von Verben aktiviert oder deaktiviert ist.
verbHighlightingColor String Legt die gewählte Farbe für die Hervorhebung der Verben fest.
adjectiveHighlightingEnabled Boolean Legt fest, ob die Hervorhebung von Adjektiven aktiviert oder deaktiviert ist.
adjectiveHighlightingColor String Legt die gewählte Farbe für die Hervorhebung der Adjektive fest.
adverbHighlightingEnabled Boolean Legt fest, ob die Hervorhebung von Adverbien aktiviert oder deaktiviert wird.
adverbHighlightingColor String Legt die gewählte Farbe für die Hervorhebung der Adverbien fest.
pictureDictionaryEnabled Boolean Legt fest, ob das Bildwörterbuch aktiviert oder deaktiviert wird.
posLabelsEnabled Boolean Legt fest, ob die hochgestellte Beschriftung jedes hervorgehobenen Satzteils aktiviert oder deaktiviert wird.

Unterstützte Sprachen

Das Übersetzungsfeature des plastischen Readers unterstützt viele Sprachen. Weitere Informationen finden Sie unter Sprachunterstützung.

HTML-Unterstützung

Wenn die Formatierung aktiviert ist, wird der folgende Inhalt im Plastischer Reader als HTML gerendert.

HTML Unterstützte Inhalte
Schriftschnitten Fett, kursiv, unterstrichen, Code, durchgestrichen, hochgestellt, tiefgestellt
Unsortierte Listen Scheibe, Kreis, Quadrat
Sortierte Listen Dezimalzahl, Upper-Alpha, Lower-Alpha, upper-Roman, lower-Roman

Nicht unterstützte Tags werden vergleichbar gerendert. Bilder und Tabellen werden derzeit nicht unterstützt.

Browserunterstützung

Verwenden Sie die neuesten Versionen der folgenden Browser, um mit dem Plastischen Reader optimale Ergebnisse zu erzielen.

  • Microsoft Edge
  • Google Chrome
  • Mozilla Firefox
  • Apple Safari

Nächster Schritt

Erkunden des Plastischer Reader SDK