Partager via


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 :

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 Number 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 Number 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

Étape suivante