Partager via

Utiliser l’API de boîte de dialogue Office dans les compléments Office

  • Article

Utilisez l’API de boîte de dialogue Office pour ouvrir des boîtes de dialogue dans votre complément Office. Cet article fournit des conseils concernant l’utilisation de l’API de dialogue dans votre complément Office. Envisagez d’ouvrir une boîte de dialogue à partir d’un volet Office, d’un complément de contenu ou d’une commande de complément pour effectuer les opérations suivantes :

  • Connectez un utilisateur avec une ressource telle que Google, Facebook ou Identité Microsoft. Pour plus d’informations, consultez s’authentifier avec l’API de boîte de dialogue Office.
  • fournir davantage d’espace à l’écran, ou même un plein écran, pour certaines tâches exécutées dans votre complément ;
  • héberger une vidéo qui serait trop petite si elle était limitée à un volet Office.

Conseil

Comme des éléments d’interface utilisateur qui se chevauchent peuvent gêner des utilisateurs, évitez d’ouvrir une boîte de dialogue à partir d’un volet Office à moins que votre scénario l’exige. Lorsque vous envisagez d’utiliser la surface d’exposition d’un volet Office, tenez compte du fait que les volets Office peuvent être affichés sous forme d’onglets. Pour obtenir un exemple de volet Office à onglets, consultez l’exemple De complément Excel JavaScript SalesTracker .

L’image suivante montre un exemple de boîte de dialogue.

Boîte de dialogue de connexion avec Plateforme d'identités Microsoft dans Word.

La boîte de dialogue s’ouvre toujours au centre de l’écran. L’utilisateur peut la déplacer et la redimensionner. La fenêtre n’est pas modifiée : un utilisateur peut continuer à interagir avec le document dans l’application Office et avec la page dans le volet Office, le cas échéant.

Remarque

Si vous développez un complément qui s’exécute dans Office sur le Web ou outlook sur Windows et qu’il nécessite l’accès aux fonctionnalités d’appareil d’un utilisateur, consultez l’API d’autorisation d’appareil pour savoir comment demander des autorisations à l’utilisateur. Les fonctionnalités de l’appareil incluent la caméra, la géolocalisation et le microphone d’un utilisateur.

Ouvrir une boîte de dialogue à partir d’une page hôte

Les API JavaScript Office incluent un objet Dialog et deux fonctions dans l’espace de noms Office.context.ui.

Pour ouvrir une boîte de dialogue, généralement une page dans un volet des tâches, votre code appelle la méthode displayDialogAsync et lui transmet l’URL de la ressource que vous voulez ouvrir. La page sur laquelle cette méthode est appelée est connue sous le nom de « page hôte ». Par exemple, si vous appelez cette méthode dans le script sur index.html d'un volet de tâches, la page index.html correspond à la page hôte de la boîte de dialogue ouverte par la méthode.

La ressource ouverte dans la boîte de dialogue correspond généralement à une page, mais ce peut être une méthode du contrôleur dans une application MVC, un itinéraire, une méthode de service web ou toute autre ressource. Dans cet article, les termes « page » ou « site web » font référence à la ressource dans la boîte de dialogue. Le code suivant est un exemple simple.

Office.context.ui.displayDialogAsync('https://www.contoso.com/myDialog.html');
  • L’URL utilise le protocole HTTPS. Ceci est obligatoire pour toutes les pages chargées dans une boîte de dialogue, pas seulement la première page chargée.
  • Le domaine de la boîte de dialogue est le même que celui de la page hôte, qui peut être la page d’un volet Office ou le fichier de fonctions d’une commande de complément. Il est nécessaire que la page, la méthode de contrôleur ou toute autre ressource transmise à la displayDialogAsync méthode se trouve dans le même domaine que la page hôte.

Importante

La page hôte et les ressources s'ouvrant dans la boîte de dialogue doivent avoir le même domaine complet. Si vous tentez de passer displayDialogAsync un sous-domaine du domaine du complément, cela ne fonctionnera pas. Le domaine complet et tous les sous-domaines doivent être exactement les mêmes.

Une fois que la première page (ou toute autre ressource) est chargée, un utilisateur peut utiliser des liens ou une autre interface utilisateur pour accéder à n’importe quel site web (ou n’importe quelle autre ressource) qui utilise le protocole HTTPS. Vous pouvez également concevoir la première page de façon à ce que l’utilisateur soit immédiatement redirigé vers un autre site.

Par défaut, la boîte de dialogue occupera 80 % de la hauteur et de la largeur de l’écran de l’appareil, mais vous pouvez définir des pourcentages différents en transmettant un objet de configuration à la méthode, comme indiqué dans l’exemple suivant.

Office.context.ui.displayDialogAsync('https://www.contoso.com/myDialog.html', { height: 30, width: 20 });

Pour obtenir un exemple de complément qui effectue cette opération, voir Créer des compléments Office pour Excel. Pour plus d’exemples qui utilisent displayDialogAsync, consultez Exemples de code.

Définissez les deux valeurs sur 100 % pour bénéficier d’une réelle d’expérience de plein écran. La valeur maximale effective est de 99,5 %, et la fenêtre est toujours déplaçable et redimensionnable.

Vous ne pouvez ouvrir qu’une seule boîte de dialogue à partir d’une fenêtre hôte. Toute tentative d’ouverture d’une autre boîte de dialogue génère une erreur. Par exemple, si un utilisateur ouvre une boîte de dialogue à partir d’un volet Office, il ne peut pas ouvrir une deuxième boîte de dialogue à partir d’une autre page dans le volet Office. Toutefois, quand une boîte de dialogue est ouverte à partir d’une commande de complément, la commande ouvre un nouveau fichier HTML (mais invisible) chaque fois qu’elle est sélectionnée. Cela crée une nouvelle fenêtre hôte (invisible), afin que chaque fenêtre de ce type puisse lancer sa propre boîte de dialogue. Pour plus d’informations, reportez-vous à Erreurs provenant de displayDialogAsync.

Tirer parti d’une option de performances dans Office sur le web

La propriété displayInIframe est une propriété supplémentaire dans l’objet de configuration que vous pouvez transmettre à displayDialogAsync. Lorsque cette propriété est définie sur true et que le complément est en cours d’exécution dans un document ouvert dans Office sur le web, la boîte de dialogue s’ouvre sous la forme d’un iframe flottant et non d’une fenêtre indépendante ; elle s’ouvre ainsi plus rapidement. Voici un exemple.

Office.context.ui.displayDialogAsync('https://www.contoso.com/myDialog.html', { height: 30, width: 20, displayInIframe: true });

La valeur par défaut est false, ce qui revient à omettre entièrement la propriété. Si le complément n’est pas en cours d’exécution dans Office sur le Web, le displayInIframe est ignoré.

Remarque

Vous ne devez pas utiliser displayInIframe: true si la boîte de dialogue redirige à tout moment vers une page qui ne peut pas être ouverte dans un iframe. Par exemple, les pages de connexion de nombreux services web populaires, tels que google et compte Microsoft, ne peuvent pas être ouvertes dans un iframe.

Envoi d’informations à la page hôte à partir de la boîte de dialogue

Le code dans la boîte de dialogue utilise la fonction messageParent pour envoyer un message de chaîne à la page hôte. La chaîne peut être un mot, une phrase, un objet blob XML, un JSON stringifié ou tout autre élément qui peut être sérialisé en chaîne ou converti en chaîne. Pour utiliser la messageParent méthode , la boîte de dialogue doit d’abord initialiser l’API JavaScript Office.

Remarque

Pour plus de clarté, dans cette section, nous appelons le message cible la page hôte, mais strictement, les messages sont envoyés au runtime dans le volet Office (ou au runtime qui héberge un fichier de fonction). La distinction n’est significative que dans le cas de la messagerie inter-domaines. Pour plus d’informations, consultez Messagerie inter-domaines au runtime hôte.

L’exemple suivant montre comment initialiser Office JS et envoyer un message à la page hôte.

Office.onReady(() => {
   // Add any initialization code for your dialog here.
});

// Called when dialog signs in the user.
function userSignedIn() {
    Office.context.ui.messageParent(true.toString());
}

L’exemple suivant montre comment retourner une chaîne JSON contenant des informations de profil.

function userProfileSignedIn(profile) {
    const profileMessage = {
        "name": profile.name,
        "email": profile.email,
    };
    Office.context.ui.messageParent(JSON.stringify(profileMessage));
}

La messageParent fonction est l’une des deux SEULES API JS Office qui peuvent être appelées dans la boîte de dialogue. L’autre API JS qui peut être appelée dans la boîte de dialogue est Office.context.requirements.isSetSupported. Pour plus d’informations à ce sujet, voir Spécifier les applications Office et les exigences d’API. Toutefois, dans la boîte de dialogue, cette API n’est pas prise en charge dans les Outlook 2016 perpétuels sous licence en volume (autrement dit, la version MSI).

La page hôte doit être configurée de façon à recevoir le message. Pour ce faire, ajoutez un paramètre de rappel à l’appel d’origine de displayDialogAsync. Le rappel attribue un gestionnaire à l’événement DialogMessageReceived. Voici un exemple.

let dialog; // Declare dialog as global for use in later functions.
Office.context.ui.displayDialogAsync('https://www.contoso.com/myDialog.html', { height: 30, width: 20 },
    (asyncResult) => {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
);

Office transmet un objet AsyncResult au rappel. Il représente le résultat de la tentative d’ouverture de la boîte de dialogue. Il ne représente pas le résultat de tous les événements dans la boîte de dialogue. Pour plus d’informations sur cette distinction, consultez la Gestion des erreurs et des événements.

  • La propriété value de asyncResult est définie sur un objet Dialog, qui existe dans la page hôte, pas dans le contexte d’exécution de la boîte de dialogue.
  • processMessage est la fonction qui gère l’événement. Vous pouvez lui donner le nom que vous souhaitez.
  • La variable dialog est déclarée avec une portée plus large que le rappel, car elle est également référencée dans processMessage.

Voici un exemple simple de gestionnaire pour l’événement DialogMessageReceived.

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    showUserName(messageFromDialog.name);
}

Office transmet l’objet arg au gestionnaire. Sa message propriété est la chaîne envoyée par l’appel de dans messageParent la boîte de dialogue. Dans cet exemple, il s’agit d’une représentation stringifiée du profil d’un utilisateur à partir d’un service, tel que un compte Microsoft ou Google, de sorte qu’elle est désérialisée en objet avec JSON.parse. L’implémentation showUserName n’est pas affichée. Elle peut afficher un message de bienvenue personnalisé dans le volet Office.

Lorsque l’intervention de l’utilisateur sur la boîte de dialogue est terminée, votre gestionnaire de messages doit fermer la boîte de dialogue, comme indiqué dans cet exemple.

function processMessage(arg) {
    dialog.close();
    // Add code to process the message here.
}

L’objet dialog doit être le même que celui renvoyé par l’appel de displayDialogAsync. Vous devez déclarer l’objet dialog en tant que variable globale. Vous pouvez également limiter l’objet dialog à l’appel displayDialogAsync avec une fonction de rappel anonyme, comme illustré dans l’exemple suivant. Dans l’exemple, processMessage n’a pas besoin de fermer le dialogue, car la close méthode est appelée dans la fonction de rappel anonyme.

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

Si le complément a besoin d’ouvrir une autre page du volet Office après avoir reçu le message, vous pouvez utiliser la méthode window.location.replace (ou window.location.href) en tant que dernière ligne du gestionnaire. Voici un exemple.

function processMessage(arg) {
    // Add code to process the message here.
    window.location.replace("/newPage.html");
    // Alternatively, use the following:
    // window.location.href = "/newPage.html";
}

Pour voir un exemple de complément qui effectue ce type d’action, consultez l’article relatif à l’exemple Insérer des graphiques Excel à l’aide de Microsoft Graph dans un complément PowerPoint.

Messagerie conditionnelle

Étant donné que vous pouvez envoyer plusieurs appels messageParent à partir de la boîte de dialogue, mais que vous n’avez qu’un seul gestionnaire dans la page hôte pour l’événement DialogMessageReceived, le gestionnaire doit utiliser la logique conditionnelle pour distinguer les différents messages. Par exemple, si la boîte de dialogue invite un utilisateur à se connecter à un fournisseur d’identité tel qu’un compte Microsoft ou Google, elle envoie le profil de l’utilisateur sous forme de message. Si l’authentification échoue, la boîte de dialogue envoie des informations d’erreur à la page hôte, comme dans l’exemple suivant.

if (loginSuccess) {
    const userProfile = getProfile();
    const messageObject = { messageType: "signinSuccess", profile: userProfile };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
} else {
    const errorDetails = getError();
    const messageObject = { messageType: "signinFailure", error: errorDetails };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
}

À propos de l’exemple précédent, notez :

  • La variable loginSuccess serait initialisée en lisant la réponse HTTP à partir du fournisseur d’identité.
  • L’implémentation des getProfile fonctions et getError n’est pas affichée. Chacune obtient des données à partir d’un paramètre de requête ou du corps de la réponse HTTP.
  • Des objets anonymes de différents types sont envoyés selon que la connexion a réussi ou non. Tous deux ont une propriété messageType, mais un a une propriété profile et l’autre une propriété error.

Le code du gestionnaire dans la page hôte utilise la valeur de la propriété messageType pour créer une branche comme le montre l’exemple suivant. Notez que la fonction showUserName est identique à celle de l’exemple précédent et que la fonction showNotification affiche l’erreur dans l’interface utilisateur de la page hôte.

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    if (messageFromDialog.messageType === "signinSuccess") {
        dialog.close();
        showUserName(messageFromDialog.profile.name);
        window.location.replace("/newPage.html");
    } else {
        dialog.close();
        showNotification("Unable to authenticate user: " + messageFromDialog.error);
    }
}

L’implémentation showNotification n’est pas affichée. Il peut afficher status dans une barre de notification du volet Office.

Messagerie inter-domaines vers le runtime hôte

Une fois la boîte de dialogue ouverte, la boîte de dialogue ou le runtime parent peut s’éloigner du domaine du complément. Si l’une de ces choses se produit, un appel de messageParent échoue, sauf si votre code spécifie le domaine du runtime parent. Pour ce faire, ajoutez un paramètre DialogMessageOptions à l’appel de messageParent. Cet objet a une targetOrigin propriété qui spécifie le domaine auquel le message doit être envoyé. Si le paramètre n’est pas utilisé, Office suppose que la cible est le même domaine que celui que la boîte de dialogue héberge actuellement.

Remarque

L’utilisation messageParent de pour envoyer un message inter-domaines nécessite l’ensemble de conditions requises Dialog Origin 1.1. Le DialogMessageOptions paramètre est ignoré sur les versions antérieures d’Office qui ne prennent pas en charge l’ensemble de conditions requises, de sorte que le comportement de la méthode n’est pas affecté si vous la transmettez.

Voici un exemple d’utilisation messageParent de pour envoyer un message inter-domaines.

Office.context.ui.messageParent("Some message", { targetOrigin: "https://resource.contoso.com" });

Si le message n’inclut pas de données sensibles, vous pouvez définir sur targetOrigin « * », ce qui permet d’être envoyé à n’importe quel domaine. Voici un exemple.

Office.context.ui.messageParent("Some message", { targetOrigin: "*" });

Conseil

  • Le DialogMessageOptions paramètre a été ajouté à la messageParent méthode en tant que paramètre obligatoire à la mi-2021. Les compléments plus anciens qui envoient un message inter-domaines avec la méthode ne fonctionnent plus tant qu’ils n’ont pas été mis à jour pour utiliser le nouveau paramètre. Tant que le complément n’est pas mis à jour, dans Office sur Windows uniquement, les utilisateurs et les administrateurs système peuvent permettre à ces compléments de continuer à fonctionner en spécifiant les domaines approuvés avec un paramètre de Registre : HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\AllowedDialogCommunicationDomains. Pour ce faire, créez un fichier avec une .reg extension, enregistrez-le sur l’ordinateur Windows, puis double-cliquez dessus pour l’exécuter. Voici un exemple du contenu d’un tel fichier.

    Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\AllowedDialogCommunicationDomains]
"My trusted domain"="https://www.contoso.com"
"Another trusted domain"="https://fabrikam.com"

  • Dans Office sur le Web et outlook sur Windows, si le domaine de votre boîte de dialogue est différent de celui de votre complément et qu’il applique l’en-tête de réponse Cross-Origin-Opener-Policy : same-origin, votre complément sera bloqué pour accéder aux messages à partir de la boîte de dialogue et l’erreur 12006 s’affichera pour vos utilisateurs. Pour éviter cela, vous devez définir l’en-tête Cross-Origin-Opener-Policy: unsafe-none sur ou configurer votre complément et votre boîte de dialogue pour qu’il se trouve dans le même domaine.

Transmission d’informations à la boîte de dialogue

Votre complément peut envoyer des messages de la page hôte à une boîte de dialogue à l’aide de Dialog.messageChild.

Utiliser messageChild() à partir de la page hôte

Lorsque vous appelez l’API de boîte de dialogue Office pour ouvrir une boîte de dialogue, un objet Dialog est retourné. Il doit être affecté à une variable dont l’étendue est globale afin que vous puissiez la référencer à partir d’autres fonctions. Voici un exemple.

let dialog; // Declare as global variable.
Office.context.ui.displayDialogAsync('https://www.contoso.com/myDialog.html',
    (asyncResult) => {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
);

function processMessage(arg) {
    dialog.close();

    // Add code to process the message here.

}

Cet Dialog objet a une méthode messageChild qui envoie toute chaîne, y compris les données stringifiées, à la boîte de dialogue. Cela déclenche un DialogParentMessageReceived événement dans la boîte de dialogue. Votre code doit gérer cet événement, comme indiqué dans la section suivante.

Imaginez un scénario dans lequel l’interface utilisateur de la boîte de dialogue est liée à la feuille de calcul Excel actuellement active et à la position de cette feuille de calcul par rapport aux autres feuilles de calcul. Dans l’exemple suivant, worksheetPropertiesChanged envoie les propriétés de la feuille de calcul active à la boîte de dialogue. Les données sont stringifiées afin qu’elles puissent être passées à messageChild.

await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getActiveWorksheet();
    worksheet.load();
    await context.sync();
    worksheetPropertiesChanged(worksheet);
});

...

function worksheetPropertiesChanged(currentWorksheet) {
    const messageToDialog = JSON.stringify(currentWorksheet);
    dialog.messageChild(messageToDialog);
}

Gérer DialogParentMessageReceived dans la boîte de dialogue

Dans le code JavaScript de la boîte de dialogue, inscrivez un gestionnaire pour l’événement DialogParentMessageReceived avec la méthode UI.addHandlerAsync . Cette opération est généralement effectuée dans la fonction Office.onReady ou Office.initialize, comme indiqué ci-dessous. (Un exemple plus robuste est inclus plus loin dans cet article.)

Office.onReady(() => {
    Office.context.ui.addHandlerAsync(Office.EventType.DialogParentMessageReceived,onMessageFromParent);
});

Ensuite, définissez le onMessageFromParent gestionnaire. Le code suivant poursuit l’exemple de la section précédente. Notez qu’Office transmet un argument au gestionnaire et que la message propriété de l’objet argument contient la chaîne de la page hôte. Dans cet exemple, le message est reconverti en objet et jQuery est utilisé pour définir le titre supérieur de la boîte de dialogue pour qu’il corresponde au nouveau nom de feuille de calcul.

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

Il est recommandé de vérifier que votre gestionnaire est correctement inscrit. Pour ce faire, passez un rappel à la addHandlerAsync méthode . Cette opération s’exécute lorsque la tentative d’inscription du gestionnaire est terminée. Utilisez le gestionnaire pour journaliser ou afficher une erreur si le gestionnaire n’a pas été correctement inscrit. Voici un exemple. Notez que reportError est une fonction, non définie ici, qui journalise ou affiche l’erreur.

Office.onReady(() => {
    Office.context.ui.addHandlerAsync(
        Office.EventType.DialogParentMessageReceived,
        onMessageFromParent,
        onRegisterMessageComplete
    );
});

function onRegisterMessageComplete(asyncResult) {
    if (asyncResult.status !== Office.AsyncResultStatus.Succeeded) {
        reportError(asyncResult.error.message);
    }
}

Messagerie conditionnelle de la page parente vers la boîte de dialogue

Étant donné que vous pouvez effectuer plusieurs messageChild appels à partir de la page hôte, mais que vous n’avez qu’un seul gestionnaire dans la boîte de dialogue pour l’événement DialogParentMessageReceived , le gestionnaire doit utiliser la logique conditionnelle pour distinguer les différents messages. Vous pouvez le faire d’une manière qui est précisément parallèle à la façon dont vous structurez la messagerie conditionnelle lorsque la boîte de dialogue envoie un message à la page hôte, comme décrit dans Messagerie conditionnelle.

Remarque

Dans certains cas, l’API messageChild , qui fait partie de l’ensemble de conditions requises DialogApi 1.2, peut ne pas être prise en charge. Par exemple, messageChild n’est pas pris en charge dans les Outlook 2016 perpétuels sous licence en volume et dans Outlook 2019 perpétuel sous licence en volume. D’autres méthodes de messagerie parent-à-boîte de dialogue sont décrites dans Autres façons de transmettre des messages à une boîte de dialogue à partir de sa page hôte.

Importante

L’ensemble de conditions requises DialogApi 1.2 ne peut pas être spécifié dans la <section Exigences> d’un manifeste de complément. Vous devrez case activée pour la prise en charge de DialogApi 1.2 lors de l’exécution à l’aide de la isSetSupported méthode décrite dans Vérifications de l’exécution pour la prise en charge de la méthode et de l’ensemble de conditions requises. La prise en charge des exigences de manifeste est en cours de développement.

Messagerie inter-domaines vers le runtime de dialogue

Une fois la boîte de dialogue ouverte, la boîte de dialogue ou le runtime parent peut s’éloigner du domaine du complément. Si l’une de ces choses se produit, les appels à messageChild échouent, sauf si votre code spécifie le domaine du runtime de la boîte de dialogue. Pour ce faire, ajoutez un paramètre DialogMessageOptions à l’appel de messageChild. Cet objet a une targetOrigin propriété qui spécifie le domaine auquel le message doit être envoyé. Si le paramètre n’est pas utilisé, Office suppose que la cible est le même domaine que celui que le runtime parent héberge actuellement.

Remarque

L’utilisation messageChild de pour envoyer un message inter-domaines nécessite l’ensemble de conditions requises Dialog Origin 1.1. Le DialogMessageOptions paramètre est ignoré sur les versions antérieures d’Office qui ne prennent pas en charge l’ensemble de conditions requises, de sorte que le comportement de la méthode n’est pas affecté si vous la transmettez.

Voici un exemple d’utilisation messageChild de pour envoyer un message inter-domaines.

dialog.messageChild(messageToDialog, { targetOrigin: "https://resource.contoso.com" });

Si le message n’inclut pas de données sensibles, vous pouvez définir sur targetOrigin « * », ce qui permet d’être envoyé à n’importe quel domaine. Voici un exemple.

dialog.messageChild(messageToDialog, { targetOrigin: "*" });

Étant donné que le runtime qui héberge la boîte de dialogue ne peut pas accéder à la <section AppDomains> du manifeste et ainsi déterminer si le domaine d’où provient le message est approuvé, vous devez utiliser le DialogParentMessageReceived gestionnaire pour le déterminer. L’objet passé au gestionnaire contient le domaine actuellement hébergé dans le parent en tant que origin propriété . Voici un exemple d’utilisation de la propriété .

function onMessageFromParent(arg) {
    if (arg.origin === "https://addin.fabrikam.com") {
        // Process the message.
    } else {
        // Signal the parent page to close the dialog.
        const messageObject = { messageType: "untrustedDomain" };
        Office.context.ui.messageParent(messageObject);
    }
}

Par exemple, votre code peut utiliser la fonction Office.onReady ou Office.initialize pour stocker un tableau de domaines approuvés dans une variable globale. La arg.origin propriété peut ensuite être vérifiée par rapport à cette liste dans le gestionnaire.

Conseil

Le DialogMessageOptions paramètre a été ajouté à la messageChild méthode en tant que paramètre obligatoire à la mi-2021. Les compléments plus anciens qui envoient un message inter-domaines avec la méthode ne fonctionnent plus tant qu’ils n’ont pas été mis à jour pour utiliser le nouveau paramètre. Tant que le complément n’est pas mis à jour, dans Office sur Windows uniquement, les utilisateurs et les administrateurs système peuvent permettre à ces compléments de continuer à fonctionner en spécifiant les domaines approuvés avec un paramètre de Registre : HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\AllowedDialogCommunicationDomains. Pour ce faire, créez un fichier avec une .reg extension, enregistrez-le sur l’ordinateur Windows, puis double-cliquez dessus pour l’exécuter. Voici un exemple du contenu d’un tel fichier.

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\AllowedDialogCommunicationDomains]
"My trusted domain"="https://www.contoso.com"
"Another trusted domain"="https://fabrikam.com"

Fermer la boîte de dialogue

Vous pouvez implémenter un bouton de fermeture dans la boîte de dialogue. Pour ce faire, le gestionnaire d'événements Click du bouton doit utiliser messageParent pour indiquer à la page hôte que vous avez cliqué sur le bouton. Voici un exemple.

function closeButtonClick() {
    const messageObject = { messageType: "dialogClosed" };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
}

Le gestionnaire de la page hôte pour DialogMessageReceived appelle dialog.close, comme dans cet exemple. (consultez les exemples précédents qui montrent comment l’objet dialog est initialisé).

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    if (messageFromDialog.messageType === "dialogClosed") {
       dialog.close();
    }
}

Même lorsque vous ne disposez pas de votre propre interface utilisateur de fermeture de boîte de dialogue, un utilisateur final peut fermer la boîte de dialogue en choisissant le X dans le coin supérieur droit. Cette action déclenche l’événement DialogEventReceived. Si votre volet hôte a besoin de savoir quand cela se produit, il doit déclarer un gestionnaire pour cet événement. Pour plus d’informations, consultez la section Erreurs et événements dans la boîte de dialogue.

Exemples de code

Tous les exemples suivants utilisent displayDialogAsync. Certains ont des serveurs basés sur NodeJS et d’autres ont des serveurs ASP.NET/IIS-based, mais la logique d’utilisation de la méthode est la même, quelle que soit la façon dont le complément est implémenté côté serveur.

Voir aussi