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

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;

Options renderButtons

Options de rendu des boutons du Lecteur immersif.

{
    elements: HTMLDivElement[];
}

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.

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

Error

Contient des informations sur une erreur.

{
    code: string;
    message: string;
}

Types

Contenu

Contient le contenu à afficher dans le lecteur immersif.

{
    title?: string;
    chunks: Chunk[];
}

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

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

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

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

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

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

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

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.

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.

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