Office.UI interface

Ajoute un gestionnaire d’événements à l’objet à l’aide du type d’événement spécifié.

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, options: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

Retours

Remarques

Ensemble de conditions requises : DialogApi 1.2

Vous pouvez ajouter plusieurs gestionnaires d’événements pour le type d’événement spécifié tant que le nom de chaque fonction de gestionnaire d’événements est unique.

Ajoute un gestionnaire d’événements à l’objet à l’aide du type d’événement spécifié.

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

Retours

Remarques

Ensemble de conditions requises : DialogApi 1.2

Vous pouvez ajouter plusieurs gestionnaires d’événements pour le type d’événement spécifié tant que le nom de chaque fonction de gestionnaire d’événements est unique.

Exemples

// The following example shows how to add an event handler for the DialogParentMessageReceived event.
Office.onReady(() => {
    Office.context.ui.addHandlerAsync(
        Office.EventType.DialogParentMessageReceived,
        onMessageFromParent,
        onRegisterMessageComplete
    );
});

function onMessageFromParent(arg) {
    const messageFromParent = JSON.parse(arg.message);
    document.querySelector('h1').textContent = messageFromParent.name;
}

function onRegisterMessageComplete(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
    }
}

Ferme le conteneur d’IU où le code JavaScript est exécuté.

closeContainer(): void;

Retours

Remarques

Applications : Excel, Outlook (configuration minimale requise : Boîte aux lettres 1.5), PowerPoint, Word

Ensembles de conditions requises :

• DialogApi

• Mailbox 1.5

Le comportement de cette méthode est spécifié par les éléments suivants :

• Appelé à partir d’un bouton de commande sans interface utilisateur : Aucun effet. Les boîtes de dialogue ouvertes par displayDialogAsync restent ouvertes.

• Appelé à partir d’un volet Office : le volet Office se ferme. Toute boîte de dialogue ouverte par displayDialogAsync se ferme également. Si le volet Office prend en charge l’épinglage et a été épinglé par l’utilisateur, il sera désépinglé.

• Appelé à partir d’une extension de module : aucun effet.

Exemples

// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();

Affiche une boîte de dialogue pour afficher ou collecter des informations auprès de l’utilisateur, ou pour faciliter la navigation sur le Web.

displayDialogAsync(startAddress: string, options?: DialogOptions, callback?: (result: AsyncResult<Dialog>) => void): void;

Paramètres

Retours

Remarques

Applications : Excel, Outlook, PowerPoint, Word

Ensembles de conditions requises :

• DialogApi

• Mailbox 1.4

Cette méthode est disponible dans la configuration requise DialogAPI définie pour les compléments Excel, PowerPoint ou Word, et dans la configuration requise boîte aux lettres définie 1.4 pour Outlook. Pour plus d’informations sur la spécification d’un ensemble de conditions requises dans votre manifeste, consultez Spécifier les applications Office et les exigences API, si vous utilisez le manifeste de complément uniquement. Si vous utilisez le manifeste unifié pour Microsoft 365, consultez Compléments Office avec le manifeste d’application unifié pour Microsoft 365.

Important:

• La page initiale doit se trouver sur le même domaine que la page parente (paramètre startAddress). Après le chargement de la page initiale, vous pouvez également accéder à d’autres domaines.

• Tout appel Office.context.ui.messageParent de page doit également se faire sur le même domaine que la page parente.

• Pour en savoir plus sur les règles, les limitations et les meilleures pratiques pour l’API de dialogue Office, consultez Meilleures pratiques et règles pour l’API de dialogue Office.

• Pour plus d’informations sur les erreurs et leur gestion, consultez Gérer les erreurs et les événements dans la boîte de dialogue Office.

• Dans Outlook sur le web et la nouvelle version d’Outlook sur Windows, ne définissez pas la propriété window.name lors de la configuration d’une boîte de dialogue dans votre complément. La window.name propriété est utilisée par ces clients Outlook pour maintenir les fonctionnalités entre les redirections de page.

• Dans la fonction de rappel transmise à la méthode displayDialogAsync, vous pouvez utiliser les propriétés de l’objet AsyncResult pour renvoyer les informations suivantes.

Exemples

// The following example shows how to open a dialog with a specified size. It also shows
// how to register a function to handle the message when Office.UI.messageParent() is called
// in the dialog. The implementation of the processMessage() function is omitted.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult) => {
        const dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

// The following example does the same thing in TypeScript.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult: Office.AsyncResult) => {
        const dialog: Office.Dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg: string) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

Affiche une boîte de dialogue pour afficher ou collecter des informations auprès de l’utilisateur, ou pour faciliter la navigation sur le Web.

displayDialogAsync(startAddress: string, callback?: (result: AsyncResult<Dialog>) => void): void;

Paramètres

Retours

Remarques

Applications : Excel, Outlook, PowerPoint, Word

Ensembles de conditions requises :

• DialogApi

• Mailbox 1.4

Cette méthode est disponible dans la configuration requise DialogAPI définie pour les compléments Excel, PowerPoint ou Word, et dans la configuration requise boîte aux lettres définie 1.4 pour Outlook. Pour plus d’informations sur la spécification d’un ensemble de conditions requises dans votre manifeste, consultez Spécifier les applications Office et les exigences API, si vous utilisez le manifeste de complément uniquement. Si vous utilisez le manifeste unifié pour Microsoft 365, consultez Compléments Office avec le manifeste d’application unifié pour Microsoft 365.

Important:

• La page initiale doit se trouver sur le même domaine que la page parente (paramètre startAddress). Après le chargement de la page initiale, vous pouvez également accéder à d’autres domaines.

• Tout appel Office.context.ui.messageParent de page doit également se faire sur le même domaine que la page parente.

• Pour en savoir plus sur les règles, les limitations et les meilleures pratiques pour l’API de dialogue Office, consultez Meilleures pratiques et règles pour l’API de dialogue Office.

• Pour plus d’informations sur les erreurs et leur gestion, consultez Gérer les erreurs et les événements dans la boîte de dialogue Office.

• Dans Outlook sur le web et la nouvelle version d’Outlook sur Windows, ne définissez pas la propriété window.name lors de la configuration d’une boîte de dialogue dans votre complément. La window.name propriété est utilisée par ces clients Outlook pour maintenir les fonctionnalités entre les redirections de page.

• Dans la fonction de rappel transmise à la méthode displayDialogAsync, vous pouvez utiliser les propriétés de l’objet AsyncResult pour renvoyer les informations suivantes.

Remet un message de la part de la boîte de dialogue à sa page parent/d’ouverture.

messageParent(message: string, messageOptions?: DialogMessageOptions): void;

Paramètres

Retours

Remarques

Applications : Excel, Outlook, PowerPoint, Word

Ensembles de conditions requises :

• DialogApi

• Mailbox 1.4

• Si le messageOptions paramètre est utilisé, DialogOrigin 1.1 est également requis.

Exemples

// The following example shows how to send a JSON string to the parent. The profile object
// is returned from some website when a user signs into it.
function userProfileSignedIn(profile) {
    const profileMessage = {
        "name": profile.name,
        "email": profile.email,
    };
    Office.context.ui.messageParent(JSON.stringify(profileMessage));
}

Ouvre une fenêtre de navigateur et charge l’URL spécifiée.

openBrowserWindow(url: string): void;

Paramètres

Retours

Remarques

Configuration requise définie : OpenBrowserWindowApi 1.1

Exemples

// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();