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 compléments Office.
Pour plus d’informations, consultez « Utiliser l’API de boîte de dialogue dans vos compléments Office ».
Méthodes
| add |
Ajoute un gestionnaire d’événements à l’objet à l’aide du type d’événement spécifié. |
| add |
Ajoute un gestionnaire d’événements à l’objet à l’aide du type d’événement spécifié. |
| close |
Ferme le conteneur d’IU où le code JavaScript est exécuté. |
| display |
Affiche une boîte de dialogue pour afficher ou collecter des informations auprès de l’utilisateur ou faciliter la navigation web. |
| display |
Affiche une boîte de dialogue pour afficher ou collecter des informations auprès de l’utilisateur ou faciliter la navigation web. |
| message |
Remet un message de la part de la boîte de dialogue à sa page parent/d’ouverture. |
| open |
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.
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 des applications Office et des exigences d’API, si vous utilisez le manifeste XML. Si vous utilisez le manifeste Teams (préversion), voir Manifeste Teams pour compléments Office (préversion) .
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.
Considérations relatives à la conception :
Les considérations de conception suivantes s’appliquent aux boîtes de dialogue.
Un volet Office complément Office ne peut ouvrir qu’une seule boîte de dialogue à tout moment. Plusieurs boîtes de dialogue peuvent être ouvertes en même temps à partir des commandes de complément (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 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/progression/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.
erreurs displayDialogAsync
| Numéro de code | Signification |
|---|---|
| 12004 | Le domaine de l’URL passée à 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 retourner les informations suivantes.
| Propriété | Utilisation |
|---|---|
AsyncResult.value | Accéder à l’objet Dialog |
AsyncResult.status | Déterminer la réussite ou l’échec de l’opération |
AsyncResult.error | Accéder à un objet Error qui fournit des informations d’erreur en cas d’échec de l’opération |
AsyncResult.asyncContext | Accéder à 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 des applications Office et des exigences d’API, si vous utilisez le manifeste XML. Si vous utilisez le manifeste Teams (préversion), voir Manifeste Teams pour compléments Office (préversion) .
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.
Considérations relatives à la conception :
Les considérations de conception suivantes s’appliquent aux boîtes de dialogue.
Un volet Office complément Office ne peut ouvrir qu’une seule boîte de dialogue à tout moment. Plusieurs boîtes de dialogue peuvent être ouvertes en même temps à partir des commandes de complément (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 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/progression/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.
erreurs displayDialogAsync
| Numéro de code | Signification |
|---|---|
| 12004 | Le domaine de l’URL passée à 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 retourner les informations suivantes.
| Propriété | Utilisation |
|---|---|
AsyncResult.value | Accéder à l’objet Dialog |
AsyncResult.status | Déterminer la réussite ou l’échec de l’opération |
AsyncResult.error | Accéder à un objet Error qui fournit des informations d’erreur en cas d’échec de l’opération |
AsyncResult.asyncContext | Accéder à 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
Ensembles de conditions requises :
Si le
messageOptionsparamè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));
}
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 échéant.
Retours
void
Remarques
Ensemble de conditions requises : OpenBrowserWindowAPI 1.1
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour