Office.UI interface

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

Visiter «Utiliser l’API de boîte de dialogue dans vos Office de boîte de dialogue» pour plus d’informations.

Méthodes

addHandlerAsync(eventType, handler, options, callback)

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

addHandlerAsync(eventType, handler, callback)

Ajoute un handler 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 de l’utilisateur ou pour faciliter la navigation Web.

displayDialogAsync(startAddress, callback)

Affiche une boîte de dialogue pour afficher ou collecter des informations de l’utilisateur ou pour 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 handler 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 s’y trouver Office.EventType.DialogParentMessageReceived.

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

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

options
Office.AsyncContextOptions

Fournit une option pour conserver les données de contexte de n’importe quel type, inchangées, à utiliser dans un rappel.

callback

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

Facultatif. Fonction qui est invoquée lors du retour de l’inscription du handler, dont le seul paramètre est de type Office. AsyncResult.

Retours

void

Remarques

Ensemble de conditions requises : DialogAPI 1.2

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

addHandlerAsync(eventType, handler, callback)

Ajoute un handler 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 s’y trouver Office.EventType.DialogParentMessageReceived.

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

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

callback

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

Facultatif. Fonction qui est invoquée lors du retour de l’inscription du handler, dont le seul paramètre est de type Office. AsyncResult.

Retours

void

Remarques

Ensemble de conditions requises : DialogAPI 1.2

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

closeContainer()

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

closeContainer(): void;

Retours

void

Remarques

Hôtes: Excel, Outlook (ensemble minimal de conditions requises : Mailbox 1.5), PowerPoint, Word

Ensembles de conditions requises:

Le comportement de cette méthode est spécifié par les critères 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 Des tâches : le volet Des tâches se ferme. Toute boîte de dialogue ouverte par displayDialogAsync se ferme également. Si le volet Des tâches prend en charge l’épinglage et a été épinglé par l’utilisateur, il n’est pas épinglé.

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

displayDialogAsync(startAddress, options, callback)

Affiche une boîte de dialogue pour afficher ou collecter des informations de l’utilisateur ou pour 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 une Office. Objet DialogOptions pour définir l’affichage de la boîte de dialogue.

callback

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

Facultatif. Accepte une méthode de rappel pour gérer la tentative de création de boîte de dialogue. Si elle réussit, asyncResult.value est un objet Dialog.

Retours

void

Remarques

Hôtes: Excel, Outlook, PowerPoint, Word

Ensembles de conditions requises:

Cette méthode est disponible dans l’ensemble de conditions requises DialogApi pour les Excel, PowerPoint ou word, et dans l’ensemble de conditions requises Mailbox 1.4 pour Outlook. Pour plus d’informations sur la spécification d’un ensemble de conditions requises dans votre manifeste, voir Spécifier les Office et les conditions requises de l’API.

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

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

Considérations de conception:

Les considérations relatives à la conception ci-dessous s’appliquent aux boîtes de dialogue :

  • Un Office du volet Des tâches du module de Office ne peut avoir qu’une seule boîte de dialogue ouverte à tout moment. Plusieurs boîtes de dialogue peuvent être ouvertes en même temps à partir des commandes de module (boutons de ruban personnalisés ou éléments de menu).

  • Toutes les boîtes de dialogue peuvent être déplacées et redimensionnées par l’utilisateur.

  • Toutes les boîtes de dialogue s’affichent au centre de l’écran à l’ouverture.

  • Les boîtes de dialogue s’affichent au-dessus de l’application hôte et dans l’ordre dans lequel elles ont été créées.

Utilisez une boîte de dialogue pour :

  • Afficher les pages d’authentification permettant de collecter les informations d’identification de l’utilisateur.

  • Afficher un écran d’erreur/de progression/d’entrée à partir d’une commande ShowTaskpane ou ExecuteAction.

  • Augmenter provisoirement la surface dont un utilisateur dispose pour effectuer une tâche.

N’utilisez pas de boîte de dialogue pour interagir avec un document. Il est préférable d’utiliser un volet des tâches.

DisplayDialogAsync Errors:

Numéro de code Signification
12004 Le domaine de l’URL transmise à displayDialogAsync n’est pas approuvé. Le domaine doit soit être identique à la page hôte (y compris le protocole et le numéro de port), soit être inscrit dans la section `AppDomains` du manifeste du complément.
12005 L’URL transmise à displayDialogAsync utilise le protocole HTTP. C’est le protocole HTTPS qui est requis. (Dans certaines versions d’Office, le message d’erreur renvoyé avec le code 12005 est identique à celui renvoyé avec le code 12004.)
12007 Une boîte de dialogue est déjà ouverte à partir du volet Office. Une seule boîte de dialogue à la fois peut être ouverte dans un complément de volet Office.
12009 L’utilisateur a choisi d’ignorer la boîte de dialogue. Cette erreur peut se produire dans les versions en ligne d’Office, quand les utilisateurs peuvent choisir d’autoriser ou non un complément à afficher une boîte de dialogue.

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

Propriété À utiliser pour
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éder à votre valeur ou object défini par l’utilisateur, si vous en avez passé un en tant que paramètre asyncContext.

displayDialogAsync(startAddress, callback)

Affiche une boîte de dialogue pour afficher ou collecter des informations de l’utilisateur ou pour 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 méthode de rappel pour gérer la tentative de création de boîte de dialogue. Si elle réussit, asyncResult.value est un objet Dialog.

Retours

void

Remarques

Hôtes: Excel, Outlook, PowerPoint, Word

Ensembles de conditions requises:

Cette méthode est disponible dans l’ensemble de conditions requises DialogApi pour les Excel, PowerPoint ou word, et dans l’ensemble de conditions requises Mailbox 1.4 pour Outlook. Pour plus d’informations sur la spécification d’un ensemble de conditions requises dans votre manifeste, voir Spécifier les Office et les conditions requises de l’API.

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

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

Considérations de conception:

Les considérations relatives à la conception ci-dessous s’appliquent aux boîtes de dialogue :

  • Un Office du volet Des tâches du module de Office ne peut avoir qu’une seule boîte de dialogue ouverte à tout moment. Plusieurs boîtes de dialogue peuvent être ouvertes en même temps à partir des commandes de module (boutons de ruban personnalisés ou éléments de menu).

  • Toutes les boîtes de dialogue peuvent être déplacées et redimensionnées par l’utilisateur.

  • Toutes les boîtes de dialogue s’affichent au centre de l’écran à l’ouverture.

  • Les boîtes de dialogue s’affichent au-dessus de l’application hôte et dans l’ordre dans lequel elles ont été créées.

Utilisez une boîte de dialogue pour :

  • Afficher les pages d’authentification permettant de collecter les informations d’identification de l’utilisateur.

  • Afficher un écran d’erreur/de progression/d’entrée à partir d’une commande ShowTaskpane ou ExecuteAction.

  • Augmenter provisoirement la surface dont un utilisateur dispose pour effectuer une tâche.

N’utilisez pas de boîte de dialogue pour interagir avec un document. Il est préférable d’utiliser un volet des tâches.

DisplayDialogAsync Errors:

Numéro de code Signification
12004 Le domaine de l’URL transmise à displayDialogAsync n’est pas approuvé. Le domaine doit soit être identique à la page hôte (y compris le protocole et le numéro de port), soit être inscrit dans la section `AppDomains` du manifeste du complément.
12005 L’URL transmise à displayDialogAsync utilise le protocole HTTP. C’est le protocole HTTPS qui est requis. (Dans certaines versions d’Office, le message d’erreur renvoyé avec le code 12005 est identique à celui renvoyé avec le code 12004.)
12007 Une boîte de dialogue est déjà ouverte à partir du volet Office. Une seule boîte de dialogue à la fois peut être ouverte dans un complément de volet Office.
12009 L’utilisateur a choisi d’ignorer la boîte de dialogue. Cette erreur peut se produire dans les versions en ligne d’Office, quand les utilisateurs peuvent choisir d’autoriser ou non un complément à afficher une boîte de dialogue.

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

Propriété À utiliser pour
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éder à votre valeur ou object 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é en chaîne, y compris JSON et XML, peut être envoyé.

messageOptions
Office.DialogMessageOptions

Facultatif. Fournit des options pour l’envoi du message.

Retours

void

Remarques

Ensembles de conditions requises:

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 (par exemple, https) et le numéro de port, le cas besoin.

Retours

void

Remarques

Ensemble de conditions requises : OpenBrowserWindowAPI 1.1