Partager via

Office.UI interface

  • Référence
Paquet:
office

Fournit des objets et des méthodes pour créer et manipuler des composants d’interface utilisateur, tels que des boîtes de dialogue, dans vos compléments Office.

Pour obtenir des conseils sur la configuration des boîtes de dialogue, voir Utiliser l’API de dialogue dans vos compléments Office.

Remarques

Exemples

// Get an Office.UI object and use it to open a dialog with a specified size. 
const uiContext = Office.context.ui;
uiContext.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 });

Méthodes

addHandlerAsync(eventType, handler, options, callback)

Ajoute un gestionnaire d’événements à l’objet à l’aide du type d’événement spécifié.
addHandlerAsync(eventType, handler, callback)

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

Ferme le conteneur d’IU où le code JavaScript est exécuté.
displayDialogAsync(startAddress, options, callback)

Affiche une boîte de dialogue pour afficher ou collecter des informations auprès de l’utilisateur ou faciliter la navigation web.
displayDialogAsync(startAddress, callback)

Affiche une boîte de dialogue pour afficher ou collecter des informations auprès de l’utilisateur ou faciliter la navigation web.
messageParent(message, messageOptions)

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

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

Détails de la méthode

addHandlerAsync(eventType, handler, options, callback)

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

eventType
Office.EventType

Spécifie le type d’événement à ajouter. Il doit être Office.EventType.DialogParentMessageReceived.

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

Fonction de gestionnaire d’événements à ajouter, dont le seul paramètre est de type Office.DialogParentMessageReceivedEventArgs.

options
Office.AsyncContextOptions

Fournit une option permettant de conserver les données de contexte de tout type, inchangées, pour une utilisation dans un rappel.

callback

(result: Office.AsyncResult<void>) => void

Facultatif. Fonction appelée lorsque l’inscription du gestionnaire est retournée, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

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.

addHandlerAsync(eventType, handler, callback)

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

eventType
Office.EventType

Spécifie le type d’événement à ajouter. Il doit être Office.EventType.DialogParentMessageReceived.

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

Fonction de gestionnaire d’événements à ajouter, dont le seul paramètre est de type Office.DialogParentMessageReceivedEventArgs.

callback

(result: Office.AsyncResult<void>) => void

Facultatif. Fonction appelée lorsque l’inscription du gestionnaire est retournée, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

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

closeContainer()

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

closeContainer(): void;

Retours

void

Remarques

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

Ensembles de conditions requises :

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 ne sera pas é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();

displayDialogAsync(startAddress, options, callback)

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

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

Paramètres

startAddress

string

Accepte l’URL HTTPS complète initiale qui s’ouvre dans la boîte de dialogue. Les URL relatives ne doivent pas être utilisées.

options
Office.DialogOptions

Facultatif. Accepte un objet Office.DialogOptions pour définir l’affichage de la boîte de dialogue.

callback

(result: Office.AsyncResult<Office.Dialog>) => void

Facultatif. Accepte une fonction de rappel pour gérer la tentative de création de boîte de dialogue. En cas de réussite, AsyncResult.value est un objet Dialog.

Retours

void

Remarques

Applications : Excel, Outlook, PowerPoint, Word

Ensembles de conditions requises :

Cette méthode est disponible dans l’ensemble de conditions requises DialogApi pour les compléments Excel, PowerPoint ou Word, et dans l’ensemble de conditions requises boîte aux lettres 1.4 pour Outlook. Pour plus d’informations sur la façon de spécifier un ensemble de conditions requises dans votre manifeste, voir Spécifier les applications Office et les exigences d’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ée 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 trouver 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 boîte de dialogue Office, voir Meilleures pratiques et règles pour l’API de boîte de dialogue Office.

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

  • Dans Outlook sur le web et 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 gérer les fonctionnalités entre les redirections de page.

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

Propriété Utilisation
AsyncResult.value Accéder à l’objet Dialog.
AsyncResult.status Déterminer si l’opération a réussi ou échoué.
AsyncResult.error Accéder à un objet Error fournissant des informations sur l’erreur en cas d’échec de l’opération.
AsyncResult.asyncContext Accédez à votre objet ou valeur défini par l’utilisateur, si vous en avez passé un en tant que paramètre asyncContext.

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

displayDialogAsync(startAddress, callback)

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

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

Paramètres

startAddress

string

Accepte l’URL HTTPS complète initiale qui s’ouvre dans la boîte de dialogue. Les URL relatives ne doivent pas être utilisées.

callback

(result: Office.AsyncResult<Office.Dialog>) => void

Facultatif. Accepte une fonction de rappel pour gérer la tentative de création de boîte de dialogue. En cas de réussite, AsyncResult.value est un objet Dialog.

Retours

void

Remarques

Applications : Excel, Outlook, PowerPoint, Word

Ensembles de conditions requises :

Cette méthode est disponible dans l’ensemble de conditions requises DialogApi pour les compléments Excel, PowerPoint ou Word, et dans l’ensemble de conditions requises boîte aux lettres 1.4 pour Outlook. Pour plus d’informations sur la façon de spécifier un ensemble de conditions requises dans votre manifeste, voir Spécifier les applications Office et les exigences d’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ée 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 trouver 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 boîte de dialogue Office, voir Meilleures pratiques et règles pour l’API de boîte de dialogue Office.

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

  • Dans Outlook sur le web et 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 gérer les fonctionnalités entre les redirections de page.

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

Propriété Utilisation
AsyncResult.value Accéder à l’objet Dialog.
AsyncResult.status Déterminer si l’opération a réussi ou échoué.
AsyncResult.error Accéder à un objet Error fournissant des informations sur l’erreur en cas d’échec de l’opération.
AsyncResult.asyncContext Accédez à votre objet ou valeur défini par l’utilisateur, si vous en avez passé un en tant que paramètre asyncContext.

messageParent(message, messageOptions)

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

message

string

Accepte un message provenant de la boîte de dialogue et destiné au complément. Tout ce qui peut être sérialisé dans une chaîne, y compris JSON et XML, peut être envoyé.

messageOptions
Office.DialogMessageOptions

Facultatif. Fournit des options permettant d’envoyer le message.

Retours

void

Remarques

Applications : Excel, Outlook, PowerPoint, Word

Ensembles de conditions requises :

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

openBrowserWindow(url)

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

openBrowserWindow(url: string): void;

Paramètres

url

string

URL complète à ouvrir, y compris le protocole (http ou https) et le numéro de port, le cas échéant. Les autres protocoles tels que mailto ne sont pas pris en charge.

Retours

void

Remarques

Ensemble de conditions requises : 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();