Lecteur immersif référence du Kit de développement logiciel (SDK) JavaScript (v1.4)
Le kit SDK du Lecteur immersif contient une bibliothèque JavaScript qui vous permet d’intégrer le Lecteur immersif à votre application.
Vous pouvez utiliser npm, ou yarnun élément HTML <script> pour inclure la bibliothèque de la dernière build stable dans votre application web :
<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
Le Kit de développement logiciel (SDK) expose ces fonctions :
- ImmersiveReader.launchAsync(token, subdomain, content, options)
- ImmersiveReader.close()
- ImmersiveReader.renderButtons(options)
Fonction: launchAsync
ImmersiveReader.launchAsync(token, subdomain, content, options)lance le Lecteur immersif au sein d’un élément HTML iframe dans votre application web. La taille de votre contenu est limitée à un maximum de 50 Mo.
launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;
| Paramètre | Type | Description |
|---|---|---|
| token | string | Jeton d’authentification Microsoft Entra. Pour plus d’informations, consultez Comment créer une ressource Lecteur immersif. |
| subdomain | string | Sous-domaine personnalisé de votre ressource Lecteur immersif dans Azure. |
| content | Contenu | Objet qui contient le contenu à afficher dans la Lecteur immersif. |
| options | Options | Options de configuration de certains comportements du lecteur immersif. facultatif. |
Retours
Retourne un Promise<LaunchResponse> qui se résout quand le Lecteur immersif est chargé. Est Promise résolu en objet LaunchResponse .
Exceptions
Si le Lecteur immersif ne parvient pas à se charger, le retour Promise est rejeté avec un objet Error.
Fonction: close
ImmersiveReader.close()ferme le Lecteur immersif.
Par exemple, cette fonction est utile si hideExitButton: true est défini dans options pour masquer le bouton Quitter. Ensuite, un autre bouton (par exemple, la flèche arrière d’un en-tête mobile) peut appeler cette close fonction quand elle est cliquée.
close(): void;
Fonction: renderButtons
La ImmersiveReader.renderButtons(options) fonction n’est pas nécessaire si vous utilisez la procédure de personnalisation du bouton Lecteur immersif.
Cette fonction définit un style et met à jour les boutons du Lecteur immersif du document. Si options.elements elle est fournie, les boutons sont rendus dans chaque élément fourni dans options.elements. L’utilisation du paramètre options.elements est utile lorsque vous avez plusieurs sections dans votre document où lancer le Lecteur immersif, et que vous souhaitez bénéficier d’une méthode simplifiée pour afficher plusieurs boutons avec le même style, ou que vous souhaitez afficher les boutons selon un modèle de conception simple et cohérent. Pour utiliser cette fonction avec le paramètre d’options renderButtons, appelez ImmersiveReader.renderButtons(options: RenderButtonsOptions); le chargement de page comme illustré dans l’extrait de code suivant. Dans le cas contraire, les boutons sont affichés dans les éléments du document qui ont la classeimmersive-reader-button, comme indiqué dans Comment personnaliser le bouton Lecteur immersif.
// 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});
Consultez les attributs facultatifs du bouton de lancement pour plus d’options de rendu. Pour utiliser ces options, ajoutez l’un des attributs optionnels à chaque HTMLDivElement dans le code HTML de votre page.
renderButtons(options?: RenderButtonsOptions): void;
| Paramètre | Type | Description |
|---|---|---|
| options | Options renderButtons | Options de configuration de certains comportements de la fonction renderButtons. facultatif. |
Options renderButtons
Options de rendu des boutons du Lecteur immersif.
{
elements: HTMLDivElement[];
}
| Paramètre | Type | Description |
|---|---|---|
| elements | HTMLDivElement[] | Éléments dans lesquels afficher les boutons du Lecteur immersif. |
Type: HTMLDivElement[]
Required: false
Bouton Lancer
Le Kit de développement logiciel (SDK) fournit un style par défaut pour le bouton de lancement Lecteur immersif. Utilisez l'attribut de classe immersive-reader-button pour activer ce style. Pour plus d’informations, consultez Comment personnaliser le bouton Lecteur immersif.
<div class='immersive-reader-button'></div>
Utilisez les attributs facultatifs suivants pour configurer l’apparence du bouton.
| Attribut | Description |
|---|---|
| data-button-style | Définit le style du bouton. Peut être icon, text ou iconAndText. La valeur par défaut est icon. |
| data-locale | Définit les paramètres régionaux. Par exemple, en-US ou fr-FR. La valeur par défaut est l’anglais (en). |
| data-icon-px-size | Définit la taille de l’icône en pixels. La valeur par défaut est 20 px. |
LaunchResponse
Contient la réponse de l’appel à ImmersiveReader.launchAsync. Une référence à l’élément HTML iframe qui contient le Lecteur immersif est accessible via container.firstChild.
{
container: HTMLDivElement;
sessionId: string;
charactersProcessed: number;
}
| Paramètre | Type | Description |
|---|---|---|
| conteneur | HTMLDivElement | Élément HTML qui contient l’élément iframe du Lecteur immersif. |
| sessionID | Chaîne | Identificateur global unique de cette session, utilisé pour le débogage. |
| charactersProcessed | nombre | Nombre total de caractères traités |
Error
Contient des informations sur une erreur.
{
code: string;
message: string;
}
| Paramètre | Type | Description |
|---|---|---|
| code | String | Un code d’erreur dans un ensemble. |
| message | Chaîne | Représentation contrôlable de visu de l’erreur. |
| Code d'erreur | Description |
|---|---|
| BadArgument | L’argument fourni n’est pas valide. Consultez message le paramètre de l’erreur. |
| Délai d'expiration | Le lecteur immersif n'a pas été chargé dans le délai spécifié. |
| TokenExpired | Le jeton fourni a expiré. |
| Throttled | Le taux d’appels maximal a été dépassé. |
Types
Contenu
Contient le contenu à afficher dans le lecteur immersif.
{
title?: string;
chunks: Chunk[];
}
| Paramètre | Type | Description |
|---|---|---|
| titre | String | Texte de titre affiché en haut du Lecteur immersif (facultatif) |
| segments | Chunk[] | Tableau de segments |
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null
Bloc
Un seul segment de données, qui est passé dans le contenu du Lecteur immersif.
{
content: string;
lang?: string;
mimeType?: string;
}
| Paramètre | Type | Description |
|---|---|---|
| contenu | Chaîne | Chaîne qui contient le contenu envoyé au Lecteur immersif. |
| lang | Chaîne | Langue du texte, la valeur est au format de balise IETF BCP 47-language , par exemple, en, es-ES. La langue est détectée automatiquement si elle n’est pas spécifiée. Pour plus d’informations, consultez Langues prises en charge. |
| mimeType | string | Les formats de texte brut, MathML, HTML et Microsoft Word DOCX sont pris en charge. Pour plus d’informations, consultez Types MIME pris en charge. |
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"
Types MIME pris en charge
| Type de l’MIME | Description |
|---|---|
| texte/brut | Texte brut. |
| texte/html | Contenu HTML. |
| application/mathml+xml | Langage de balisage mathématique (MathML). |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | Document au format .docx Microsoft Word. |
Options
Contient les propriétés qui configurent certains comportements du lecteur immersif.
{
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;
}
| Paramètre | Type | Description |
|---|---|---|
| uiLang | Chaîne | Langue de l’interface utilisateur, la valeur est au format de balise IETF BCP 47-language , par exemple, en, es-ES. Si elle n’est pas spécifiée, la langue du navigateur est définie par défaut. |
| délai d'expiration | Numéro | Durée (en millisecondes) avant l’échec de launchAsync avec une erreur de délai d’attente (15 000 ms par défaut). Ce délai d’attente s’applique uniquement au lancement initial de la page du Lecteur, lorsque la page du Lecteur s’ouvre et que le compteur démarre. L’ajustement du délai d’expiration ne doit pas être nécessaire. |
| uiZIndex | Nombre | Index Z de l’élément HTML iframe créé (la valeur par défaut est 1 000). |
| useWebview | Boolean | Utilisez une balise webview au lieu d’un élément HTML iframe pour la compatibilité avec Chrome Apps (la valeur par défaut est false). |
| onExit | Fonction | S’exécute à la fermeture du Lecteur immersif. |
| customDomain | Chaîne | Réservé à un usage interne. Domaine personnalisé dans lequel l’application web Lecteur immersif est hébergée (la valeur par défaut est null). |
| allowFullscreen | Boolean | Possibilité de basculer en plein écran (la valeur par défaut est true). |
| parent | Nœud | Nœud dans lequel l’élément HTML iframe ou Webview le conteneur est placé. Si l’élément n’existe pas, l’iframe est placé dans body. |
| hideExitButton | Boolean | Masque la flèche du bouton de sortie du Lecteur immersif (la valeur par défaut est false). Cette valeur ne doit être vraie que s’il existe un autre mécanisme fourni pour quitter le Lecteur immersif (par exemple, flèche arrière d’une barre d’outils mobile). |
| cookiePolicy | CookiePolicy | Paramètre d’utilisation des cookies du Lecteur immersif (la valeur par défaut est CookiePolicy.Disable). Il incombe à l’application hôte d’obtenir les éventuels consentements nécessaires de l’utilisateur conformément à la stratégie de conformité des cookies de l’Union européenne. Pour plus d’informations, consultez les options de stratégie de cookie. |
| disableFirstRun | Boolean | Désactiver l’expérience de première exécution. |
| readAloudOptions | ReadAloudOptions | Options de configuration de la lecture à voix haute. |
| translationOptions | TranslationOptions | Options de configuration de la traduction. |
| displayOptions | DisplayOptions | Options de configuration de la taille du texte, de la police, du thème, etc. |
| preferences | Chaîne | Chaîne retournée par onPreferencesChanged représentant les préférences de l’utilisateur dans le Lecteur immersif. Pour plus d’informations, consultez Comment stocker les préférences utilisateur. |
| onPreferencesChanged | Fonction | S’exécute lorsque les préférences de l’utilisateur ont changé. Pour plus d’informations, consultez Comment stocker les préférences utilisateur. |
| disableTranslation | Boolean | Désactiver l’expérience de traduction des mots et documents. |
| disableGrammar | Boolean | Désactiver l’expérience Grammaire. Cette option désactive également les syllabes, les parties du discours et le dictionnaire d’images, qui dépendent des parties de la parole. |
| disableLanguageDetection | Boolean | Désactiver la détection de la langue pour faire en sorte que le Lecteur immersif n’utilise que la langue explicitement spécifiée sur le segment Contenu/Chunk[]. Cette option doit être utilisée avec parcimonie, principalement dans les situations où la détection de langue ne fonctionne pas. Par exemple, ce problème est plus susceptible de se produire avec des passages courts de moins de 100 caractères. Vous devez être certain de la langue que vous envoyez, car la synthèse vocale n’aura pas la bonne voix. Syllabes, parties de discours et dictionnaire d’images ne fonctionnent pas correctement si la langue n’est pas correcte. |
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
Attention
N’essayez pas de modifier par programmation les valeurs de la chaîne -preferences envoyée à destination et en provenance de l’application Immersive Reader, car cela peut provoquer un comportement inattendu entraînant une dégradation de l’expérience utilisateur. Les applications hôtes ne doivent jamais attribuer une valeur personnalisée ou manipuler la chaîne -preferences. Quand vous utilisez l’option de chaîne -preferences, utilisez uniquement la valeur exacte qui a été retournée à partir de l’option de rappel de -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;
};
| Paramètre | Type | Description |
|---|---|---|
| voice | Chaîne | Voix, femelle ou mâle. Toutes les langues ne permettent pas de choisir entre les deux genres. |
| speed | Nombre | Vitesse de lecture. Doit être compris entre 0,5 et 2,5 inclus. |
| autoPlay | Boolean | Démarrer automatiquement la lecture à voix haute au chargement du Lecteur immersif. |
Notes
En raison des limitations du navigateur, la lecture automatique n’est pas prise en charge dans 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;
};
| Paramètre | Type | Description |
|---|---|---|
| langage | Chaîne | Définit la langue de traduction, la valeur est au format de balise IETF BCP 47-language , par exemple, fr-FR, es-MX, zh-Hans-CN. Requis pour activer automatiquement la traduction des mots ou du document. |
| autoEnableDocumentTranslation | Boolean | Traduire automatiquement le document complet. |
| autoEnableWordTranslation | Boolean | Activer automatiquement la traduction des mots. |
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
};
| Paramètre | Type | Description |
|---|---|---|
| textSize | Numéro | Définit la taille du texte choisi. |
| increaseSpacing | Boolean | Définit si l’espacement du texte est activé ou désactivé. |
| fontFamily | Chaîne | Définit la police choisie (Calibri, ComicSans ou Sitka). |
| themeOption | ThemeOption | Définit le thème choisi du lecteur (Clair, Foncé). |
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"
Options CookiePolicy
enum CookiePolicy { Disable, Enable }
Les paramètres suivants sont uniquement à des fins d’information. Le Lecteur immersif stocke ses paramètres ou les préférences de l’utilisateur dans des cookies. Cette option cookiePolicydésactive l’utilisation des cookies par défaut conformément aux réglementations de conformité des cookies de l’Union européenne. Si vous souhaitez réactiver les cookies et restaurer les fonctionnalités par défaut pour Lecteur immersif préférences utilisateur, votre site web ou votre application a besoin du consentement approprié de l’utilisateur pour activer les cookies. Ensuite, pour réactiver les cookies dans le Lecteur immersif, vous devez définir explicitement l’option cookiePolicy sur CookiePolicy.Enable au lancement du Lecteur immersif.
Le tableau suivant décrit les paramètres que la Lecteur immersif stocke dans son cookie lorsque l’option cookiePolicy est activée.
| Setting | Type | Description |
|---|---|---|
| textSize | Numéro | Définit la taille du texte choisi. |
| fontFamily | Chaîne | Définit la police choisie (Calibri, ComicSans ou Sitka). |
| textSpacing | Numéro | Définit si l’espacement du texte est activé ou désactivé. |
| formattingEnabled | Boolean | Définit si la mise en forme HTML est activée ou désactivée. |
| thème | Chaîne | Définit le thème choisi (Clair, Foncé). |
| syllabificationEnabled | Boolean | Définit si la décomposition des mots en syllabes est activée ou désactivée. |
| nounHighlightingEnabled | Boolean | Définit si la mise en surbrillance des substantifs est activée ou désactivée. |
| nounHighlightingColor | Chaîne | Définit la couleur de mise en surbrillance des substantifs. |
| verbHighlightingEnabled | Boolean | Définit si la mise en surbrillance des verbes est activée ou désactivée. |
| verbHighlightingColor | Chaîne | Définit la couleur de mise en surbrillance des verbes. |
| adjectiveHighlightingEnabled | Boolean | Définit si la mise en surbrillance des adjectifs est activée ou désactivée. |
| adjectiveHighlightingColor | Chaîne | Définit la couleur de mise en surbrillance des adjectifs. |
| adverbHighlightingEnabled | Boolean | Définit si la mise en surbrillance des adverbes est activée ou désactivée. |
| adverbHighlightingColor | Chaîne | Définit la couleur de mise en surbrillance des adverbes. |
| pictureDictionaryEnabled | Boolean | Définit si le dictionnaire d’images est activé ou désactivé. |
| posLabelsEnabled | Boolean | Définit si les étiquettes de texte en exposants des éléments morphosyntaxiques sont activées ou désactivées. |
Langues prises en charge
La fonctionnalité de traduction du Lecteur immersif prend en charge de nombreuses langues. Pour plus d’informations, consultez Prise en charge linguistique.
Prise en charge du langage HTML
Lorsque la mise en forme est activée, le contenu suivant est affiché en tant que code HTML dans la Lecteur immersif.
| HTML | Contenu pris en charge |
|---|---|
| Styles de police | Gras, italique, soulignement, code, grève, exposant, indice |
| Listes non triées | Disque, cercle, carré |
| Listes triées | Decimal, upper-Alpha, lower-Alpha, upper-Roman, lower-Roman |
Les balises non prises en charge sont rendues de façon comparable. Les images et les tables ne sont pas prises en charge pour l’instant.
Prise en charge des navigateurs
Pour une meilleure expérience avec le lecteur immersif, utilisez les versions les plus récentes des navigateurs suivants.
- Microsoft Edge
- Google Chrome
- Mozilla Firefox
- Apple Safari