Commandes Activé et Désactivé pour les compléments
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 connaissez la documentation décrite ci-après. É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 uniquement disponibles dans Excel. Toutefois, la prise en charge de la préversion est actuellement disponible dans PowerPoint et Word. Pour plus d’informations sur la prise en charge, consultez l’ensemble de conditions requises RibbonApi 1.1 .
Effectuez un test pour la prise en charge des plateformes avec les ensembles de conditions requises
Les ensembles de conditions requises sont des groupes nommés de membres d’API. Les compléments Office utilisent des ensembles de conditions requises spécifiés dans le manifeste ou utilisent un case activée d’exécution pour déterminer si une combinaison d’applications Et de plateformes Office prend en charge les API dont un complément a besoin. Pour plus d’informations, consultez Versions d’Office et ensembles de conditions requises.
Les API enable/disable appartiennent à l’ensemble de conditions requises RibbonApi 1.1 .
Remarque
L’ensemble de conditions requises RibbonApi 1.1 n’étant pas encore pris en charge dans le manifeste, vous ne pouvez pas le spécifier dans la section Exigences> du< manifeste. Pour tester la prise en charge, votre code doit appeler Office.context.requirements.isSetSupported('RibbonApi', '1.1'). Si, et uniquement si, cet appel retourne true, votre code peut appeler les API d’activation/désactivation. Si l’appel de isSetSupported retourne false, toutes les commandes de complément personnalisées sont activées en permanence. Vous devez concevoir votre complément de production et toutes les instructions dans l’application pour tenir compte de son fonctionnement lorsque l’ensemble de conditions requises RibbonApi 1.1 n’est pas pris en charge. Pour plus d’informations et des exemples d’utilisation isSetSupportedde , consultez Spécifier les applications Office et les exigences d’API, en particulier les vérifications d’exécution pour la prise en charge des méthodes et des ensembles de conditions requises. (La section Spécifier les versions et plateformes Office qui peuvent héberger votre complément de cet article ne s’applique pas au Ruban 1.1.)
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.
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> .)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" />.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
residde l’Action.Élément SourceLocation vers exactement la même chaîne que celle utilisée pour leresidde 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
residde la page.Élément SourceLocation exactement la même chaîne que celle utilisée pour leresidde 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
residde l’élément FunctionFile sur exactement la même chaîne que celle utilisée pour leresidde l’élément Runtime> à l’étape< 1 ; par exemple,Contoso.SharedRuntime.Url. Le fichier doit ressembler à ceci :<FunctionFile resid="Contoso.SharedRuntime.Url"/>.
- Si le complément contient un volet Office, définissez l’attribut
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 :
- 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.
- 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 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.
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.
- Lorsque
requestUpdateest appelé, le code doit enregistrer l’état prévu des boutons et éléments de menu personnalisés. - 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.");
}
}
}
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