Partager via

Commandes Activé et Désactivé pour les compléments

  • Article

Lorsque seulement quelques fonctionnalités de votre complément doivent être disponibles dans certains contextes, vous pouvez activer ou désactiver vos commandes de complément personnalisées par programme. Par exemple, une fonction qui modifie l’en-tête d’un tableau doit être uniquement activée lorsque le curseur se trouve dans un tableau.

Vous pouvez également spécifier si la commande est activée ou désactivée lorsque l’application cliente Office s’ouvre.

Remarque

Cet article suppose que vous êtes familiarisé avec les concepts de base des commandes de complément. Étudiez-la si vous n’avez pas récemment utilisé les commandes de complément (éléments de menu et boutons de ruban personnalisés).

Prise en charge des applications et des plateformes Office

Les API décrites dans cet article sont disponibles dans Excel, PowerPoint et Word dans le cadre de l’ensemble de conditions requises RibbonApi 1.1 . 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.

Runtime partagé requis

Les API et le balisage de manifeste décrits dans cet article nécessitent que le manifeste du complément spécifie qu’il doit utiliser un runtime partagé. Pour ce faire, procédez comme suit.

  1. Dans l'élément Runtimes du manifeste, ajoutez l’élément enfant suivant : <Runtime resid="Contoso.SharedRuntime.Url" lifetime="long" />. (S’il n’existe pas encore d’élément <Runtimes> dans le manifeste, créez-le en tant que premier enfant sous l’élément <Host> dans la <section VersionOverrides> .)

  2. Dans la section Resources.Urls du manifeste, ajoutez l’élément enfant suivant : <bt:Url id="Contoso.SharedRuntime.Url" DefaultValue="https://{MyDomain}/{path-to-start-page}" />, où {MyDomain} est le domaine du complément et {path-to-start-page} le chemin d’accès de la page de démarrage du complément. par exemple : <bt:Url id="Contoso.SharedRuntime.Url" DefaultValue="https://localhost:3000/index.html" />.

  3. Selon que votre complément contient un volet Office, un fichier de fonction ou une fonction personnalisée Excel, vous devez effectuer une ou plusieurs des trois étapes suivantes.

    • Si le complément contient un volet Office, définissez l’attribut resid de l’Action.Élément SourceLocation vers exactement la même chaîne que celle utilisée pour le resid de l’élément Runtime> à l’étape< 1 ; par exemple, Contoso.SharedRuntime.Url. Le fichier doit ressembler à ceci : <SourceLocation resid="Contoso.SharedRuntime.Url"/>.
    • Si le complément contient une fonction personnalisée Excel, définissez l’attribut resid de la page.Élément SourceLocation exactement la même chaîne que celle utilisée pour le resid de l’élément Runtime> à l’étape< 1 ; par exemple, Contoso.SharedRuntime.Url. Le fichier doit ressembler à ceci : <SourceLocation resid="Contoso.SharedRuntime.Url"/>.
    • Si le complément contient un fichier de fonction, définissez l’attribut resid de l’élément FunctionFile sur exactement la même chaîne que celle utilisée pour le resid de l’élément Runtime> à l’étape< 1 ; par exemple, Contoso.SharedRuntime.Url. Le fichier doit ressembler à ceci : <FunctionFile resid="Contoso.SharedRuntime.Url"/>.

Configurer l'état par défaut sur désactivé

Les commandes de complément sont activées par défaut au démarrage de l’application Office. Si vous souhaitez qu’un bouton ou un élément de menu personnalisé soit désactivé au démarrage de l’application Office, vous devez le spécifier dans le manifeste. Il vous suffit d’ajouter un élément activé (avec la valeur false) juste au-dessous (non à l’intérieur) de l'élément Action dans la déclaration du contrôle. La structure de base est la suivante.

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

Modifier l’état par programme

Les principales étapes pour modifier l’état activé d’une commande de complément sont les suivantes :

  1. Créez un objet RibbonUpdaterData qui (1) spécifie la commande, ainsi que son groupe parent et son onglet, par leurs ID tels que déclarés dans le manifeste ; et (2) spécifie l’état activé ou désactivé 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() {
    Office.ribbon.requestUpdate({
        tabs: [
            {
                id: "OfficeAppTab1", 
                groups: [
                    {
                      id: "CustomGroup111",
                      controls: [
                        {
                            id: "MyButton", 
                            enabled: true
                        }
                      ]
                    }
                ]
            }
        ]
    });
}

Nous proposons également 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);
}

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.

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

Un scénario courant est celui lors duquel l’état du ruban peut être modifié lorsqu’un événement initié par l’utilisateur modifie le contexte du complément.

Imaginez un scénario dans lequel un bouton doit être activé lorsque, et seulement lorsqu'un graphique est activé. La première étape consiste à définir l'élément Activé pour le bouton dans le manifeste false. Voir l'exemple ci-dessus.

Deuxièmement, assignez des gestionnaires. Cette opération est généralement effectuée dans la fonction Office.onReady , comme dans l’exemple suivant, qui affecte des gestionnaires (créés dans une étape ultérieure) aux événements onActivated et onDeactivated de tous les graphiques de la feuille de calcul.

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

Troisièmement, définissez le gestionnaire enableChartFormat. Voici un exemple simple, mais consultez les Pratiques recommandées : test pour les erreurs de contrôle d’état ci-dessous pour modifier l’état d’un contrôle de façon plus efficace.

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

Quatrièmement, définissez le gestionnaire disableChartFormat. Il est identique à enableChartFormat, sauf que la propriété activé de l’objet bouton a la valeur false.

Activer la visibilité des onglets et l’état activé 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.

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

Le ruban ne se redessine pas, dans certains cas, une fois que requestUpdate est appelé, de sorte que l’état du contrôle cliquable ne change pas. Il est pour cette raison recommandé de suivre l'état des contrôles du complément. Le complément doit être conforme aux règles suivantes.

  1. Lorsque requestUpdate est appelé, le code doit enregistrer l’état prévu des boutons et éléments de menu personnalisés.
  2. Lorsque l’utilisateur clique sur un contrôle personnalisé, le premier code dans le gestionnaire doit vérifier si le bouton aurait dû être cliquable. Dans la négative, le code doit signaler une erreur ou consigner une erreur et réessayer de définir les boutons de l'état prévu.

L’exemple suivant présente une fonction qui désactive un bouton et enregistre l’état du bouton. Veuillez noter que chartFormatButtonEnabled est une variable Boolean globale qui est initialisée sur la même valeur que l'élément Activé pour le bouton dans le manifeste.

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 again to disable.
        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 et renvoie 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.

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