Partager via

Modifier la disponibilité des commandes de complément

  • Article

Lorsque certaines fonctionnalités de votre complément ne doivent être disponibles que dans certains contextes, vous pouvez configurer par programme vos commandes de complément personnalisées pour qu’elles soient disponibles uniquement dans ces contextes. Par exemple, une fonction qui modifie l’en-tête d’une table ne doit être disponible que lorsque le curseur se trouve dans une table.

Remarque

  • Cet article part du principe que vous êtes familiarisé avec les concepts de base des commandes de complément. Vérifiez-le si vous n’avez pas récemment utilisé les commandes de complément (éléments de menu personnalisés et boutons du ruban).

Fonctionnalités prises en charge

Vous pouvez modifier par programmation la disponibilité d’une commande de complément pour les fonctionnalités suivantes.

  • Boutons, menus et onglets du ruban.
  • Éléments de menu contextuel.

Prise en charge des applications Office et des ensembles de conditions requises

Le tableau suivant présente les applications Office qui prennent en charge la configuration de la disponibilité des commandes de complément. Il répertorie également les ensembles de conditions requises nécessaires pour utiliser l’API.

Fonctionnalité de commande de complément Ensemble de conditions requises Applications Office prises en charge
Onglets, menus et boutons du ruban RibbonAPI 1.1
  • Excel
  • PowerPoint
  • Word
Éléments du menu contextuel ContextMenuApi 1.1
  • Excel
  • PowerPoint
  • Word

Conseil

Pour savoir comment tester la prise en charge de la plateforme avec les ensembles de conditions requises, consultez Versions d’Office et ensembles de conditions requises.

Configurer un runtime partagé

Pour modifier la disponibilité d’un ruban ou d’un contrôle ou d’un élément de menu contextuel, le manifeste de votre complément doit d’abord être configuré pour utiliser un runtime partagé. Pour obtenir des conseils sur la configuration d’un runtime partagé, voir Configurer votre complément Office pour utiliser un runtime partagé.

Modifier par programmation la disponibilité d’une commande de complément

Désactiver les contrôles du ruban au lancement

Remarque

Seuls les contrôles du ruban peuvent être désactivés au démarrage de l’application Office. Vous ne pouvez pas désactiver les contrôles personnalisés ajoutés à un menu contextuel au lancement.

Par défaut, un bouton ou un élément de menu personnalisé sur le ruban peut être utilisé lors du lancement de l’application Office. Pour le désactiver au démarrage d’Office, vous devez le spécifier dans le manifeste. Le processus dépend du type de manifeste utilisé par votre complément.

Manifeste unifié pour Microsoft 365

Remarque

Le manifeste unifié pour Microsoft 365 peut être utilisé dans les compléments Outlook de production. Il est disponible uniquement en préversion pour les compléments Excel, PowerPoint et Word.

Ajoutez simplement une propriété « enabled » avec la valeur false à l’objet de contrôle ou d’élément de menu. La structure de base est la suivante.

"extensions": [
    ...
    {
        ...
        "ribbons": [
            ...
            {
                ...
                "tabs": [
                    {
                        "id": "MyTab",
                        "groups": [
                            {
                                ...
                                "controls": [
                                    {
                                        "id": "Contoso.MyButton1",
                                        ...
                                        "enabled": false
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

Manifeste de complément uniquement

Il vous suffit d’ajouter un élément Enabled juste en dessous (et non à l’intérieur) de l’élément de contrôle. Ensuite, définissez sa valeur sur false.

L’exemple suivant montre la structure de base d’un manifeste qui configure l’élément <Enabled> .

<OfficeApp ...>
  ...
  <VersionOverrides ...>
    ...
    <Hosts>
      <Host ...>
        ...
        <DesktopFormFactor>
          <ExtensionPoint ...>
            <CustomTab ...>
              ...
              <Group ...>
                ...
                <Control ... id="Contoso.MyButton3">
                  ...
                  <Action ...>
                  <Enabled>false</Enabled>
...
</OfficeApp>

Modifier la disponibilité d’un contrôle de ruban

Pour mettre à jour la disponibilité d’un bouton ou d’un élément de menu sur le ruban, procédez comme suit.

  1. Créez un objet RibbonUpdaterData qui spécifie les éléments suivants :
    • ID de la commande, y compris son groupe parent et son onglet. Les ID doivent correspondre à ceux déclarés dans le manifeste.
    • Status de disponibilité de la commande.
  2. Transmettez l’objet RibbonUpdaterData à la méthode Office.ribbon.requestUpdate ().

Voici un exemple simple. Notez que « MyButton », « OfficeAddinTab1 » et « CustomGroup111 » sont copiés à partir du manifeste.

function enableButton() {
    const ribbonUpdaterData = {
        tabs: [
            {
                id: "OfficeAppTab1",
                groups: [
                    {
                      id: "CustomGroup111",
                      controls: [
                        {
                            id: "MyButton",
                            enabled: true
                        }
                      ]
                    }
                ]
            }
        ]
    };

    Office.ribbon.requestUpdate(ribbonUpdaterData);
}

Il existe plusieurs interfaces (types) pour faciliter la construction de l’objet RibbonUpdateData .

L’exemple suivant est l’équivalent de TypeScript et il utilise ces types.

const enableButton = async () => {
    const button: Control = { id: "MyButton", enabled: true };
    const parentGroup: Group = { id: "CustomGroup111", controls: [button] };
    const parentTab: Tab = { id: "OfficeAddinTab1", groups: [parentGroup] };
    const ribbonUpdater: RibbonUpdaterData = { tabs: [parentTab] };
    Office.ribbon.requestUpdate(ribbonUpdater);
}

Conseil

Vous pouvez await appeler requestUpdate() si la fonction parente est asynchrone, mais notez que l’application Office contrôle quand elle met à jour l’état du ruban. La méthode requestUpdate() met en file d’attente une demande de mise à jour. La méthode résout l’objet de promesse dès qu’elle a mis en file d’attente la requête, et non lorsque le ruban est réellement mis à jour.

Activer la visibilité des onglets et la status activée d’un bouton en même temps

La méthode requestUpdate est également utilisée pour activer/désactiver la visibilité d’un onglet contextuel personnalisé. Pour plus d’informations à ce sujet et un exemple de code, voir Créer des onglets contextuels personnalisés dans les compléments Office.

Modifier l’état en réponse à un événement

Un scénario courant dans lequel l’état d’un ruban ou d’un contrôle de menu contextuel doit changer est lorsqu’un événement initié par l’utilisateur modifie le contexte du complément. Imaginez un scénario dans lequel un bouton doit être disponible quand, et uniquement quand, un graphique est activé. Bien que l’exemple suivant utilise des contrôles de ruban, une implémentation similaire peut être appliquée à des éléments personnalisés dans un menu contextuel.

  1. Tout d’abord, définissez l’élément <Enabled> pour le bouton dans le manifeste sur false. Pour obtenir des conseils sur la façon de configurer cela, consultez Désactiver les contrôles du ruban au lancement.

  2. Ensuite, affectez des gestionnaires. Cette opération est généralement effectuée dans la fonction Office.onReady , comme dans l’exemple suivant. Dans l’exemple, les gestionnaires (créés à une étape ultérieure) sont affectés aux événements onActivated et onDeactivated de tous les graphiques d’une feuille de calcul Excel.

    Office.onReady(async () => {
    await Excel.run((context) => {
        const charts = context.workbook.worksheets
            .getActiveWorksheet()
            .charts;
        charts.onActivated.add(enableChartFormat);
        charts.onDeactivated.add(disableChartFormat);
        return context.sync();
    });
});

  3. Définissez le enableChartFormat gestionnaire. Voici un exemple simple. Pour obtenir un moyen plus robuste de modifier les status d’un contrôle, consultez Meilleure pratique : Tester les erreurs de status de contrôle.

    function enableChartFormat() {
    const button =
        {
            id: "ChartFormatButton",
            enabled: true
        };
    const parentGroup =
        {
            id: "MyGroup",
            controls: [button]
        };
    const parentTab =
        {
            id: "CustomChartTab",
            groups: [parentGroup]
        };
    const ribbonUpdater = { tabs: [parentTab] };
    Office.ribbon.requestUpdate(ribbonUpdater);
}

  4. Définissez le disableChartFormat gestionnaire. Il est identique au enableChartFormat gestionnaire, sauf que la propriété enabled de l’objet button a la valeur false.

Pratiques recommandées : test pour les erreurs de contrôle d'état

Dans certains cas, le ruban ou le menu contextuel ne se repeint pas après requestUpdate l’appel, de sorte que le status cliquable du contrôle ne change pas. Pour cette raison, il est recommandé pour le complément de suivre les status de ses contrôles. Le complément doit être conforme aux règles suivantes.

  • Lorsque requestUpdate est appelé, le code doit enregistrer l’état prévu des boutons et éléments de menu personnalisés.
  • Lorsqu’un contrôle personnalisé est sélectionné, le premier code du gestionnaire doit case activée pour voir si le bouton aurait dû être disponible. S’il n’aurait pas dû être disponible, le code doit signaler ou enregistrer une erreur, puis réessayer pour définir les boutons à l’état prévu.

L’exemple suivant montre une fonction qui désactive un bouton du ruban et enregistre les status du bouton. Dans cet exemple, chartFormatButtonEnabled est une variable booléenne globale qui est initialisée à la même valeur que l’élément Enabled pour le bouton dans le manifeste du complément. Bien que l’exemple utilise un bouton de ruban, une implémentation similaire peut être appliquée à des éléments personnalisés dans un menu contextuel.

function disableChartFormat() {
    const button =
    {
        id: "ChartFormatButton",
        enabled: false
    };
    const parentGroup =
    {
        id: "MyGroup",
        controls: [button]
    };
    const parentTab =
    {
        id: "CustomChartTab",
        groups: [parentGroup]
    };
    const ribbonUpdater = { tabs: [parentTab] };
    Office.ribbon.requestUpdate(ribbonUpdater);

    chartFormatButtonEnabled = false;
}

L’exemple suivant présente la façon dont le gestionnaire du bouton vérifie l’état d’un bouton incorrect. Veuillez noter que reportError est une fonction qui affiche ou consigne une erreur.

function chartFormatButtonHandler() {
    if (chartFormatButtonEnabled) {

        // Do work here.

    } else {
        // Report the error and try to make the button unavailable again.
        reportError("That action is not possible at this time.");
        disableChartFormat();
    }
}

Gestion des erreurs

Dans certains scénarios, Office ne peut pas mettre à jour le ruban ou le menu contextuel et retourne une erreur. Par exemple, si le complément est mis à niveau et que le complément mis à niveau dispose d'un autre groupe de commandes de complément personnalisé, l’application Office doit être fermée et ouverte de nouveau. La méthode requestUpdate renvoie l'erreur HostRestartNeeded jusqu'à ce que cela soit effectué. Voici comment vous pouvez gérer cette erreur. Dans ce cas, la méthode reportError affiche l’erreur à l’utilisateur. Bien que l’exemple utilise un bouton de ruban, une implémentation similaire peut être appliquée à des éléments personnalisés dans un menu contextuel.

function disableChartFormat() {
    try {
        const button =
        {
            id: "ChartFormatButton",
            enabled: false
        };
        const parentGroup =
        {
            id: "MyGroup",
            controls: [button]
        };
        const parentTab =
        {
            id: "CustomChartTab",
            groups: [parentGroup]
        };
        const ribbonUpdater = { tabs: [parentTab] };
        Office.ribbon.requestUpdate(ribbonUpdater);

        chartFormatButtonEnabled = false;
    }
    catch(error) {
        if (error.code == "HostRestartNeeded"){
            reportError("Contoso Awesome Add-in has been upgraded. Please save your work, close the Office application, and restart it.");
        }
    }
}

Voir aussi