Plastischer Reader JavaScript SDK-Referenz (v1.4)
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:
- ImmersiveReader.launchAsync(token, subdomain, content, options)
- ImmersiveReader.close()
- ImmersiveReader.renderButtons(options)
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 Unterdomäne Ihrer Plastischer Reader Ressource in Azure. |
| Inhalt | 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 | Anzahl | 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-Zeichenfolge, die an die und von der Immersive Reader-Anwendung gesendet werden, programmgesteuert zu ändern, da dies zu unerwartetem Verhalten führen kann, das die Benutzerfreundlichkeit beeinträchtigt. 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 | Anzahl | 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 |
|---|---|
| Font-Stile | 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