Créer des onglets contextuels personnalisés dans les compléments Office
Un onglet contextuel est un contrôle d’onglet masqué dans le ruban Office qui s’affiche dans la ligne d’onglet lorsqu’un événement spécifié se produit dans le document Office. Par exemple, l’onglet Création de tableau qui apparaît dans le ruban Excel lorsqu’un tableau est sélectionné. Vous incluez des onglets contextuels personnalisés dans votre complément Office et spécifiez quand ils sont visibles ou masqués, en créant des gestionnaires d’événements qui modifient la visibilité. (Toutefois, les onglets contextuels personnalisés ne répondent pas aux modifications de focus.)
Remarque
Cet article suppose que vous êtes familiarisé avec la documentation suivante. É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).
Importante
Les onglets contextuels personnalisés sont actuellement pris en charge uniquement sur Excel et uniquement sur ces plateformes et builds.
- Excel sur Windows : version 2102 (build 13801.20294) ou ultérieure.
- Excel sur Mac : version 16.53.806.0 ou ultérieure.
- Excel sur le web
Remarque
Les onglets contextuels personnalisés fonctionnent uniquement sur les plateformes qui prennent en charge les ensembles de conditions requises suivants. Pour plus d’informations sur les ensembles de conditions requises et leur utilisation, consultez Spécifier les applications Office et les exigences d’API.
Vous pouvez utiliser les vérifications d’exécution dans votre code pour tester si la combinaison de l’hôte et de la plateforme de l’utilisateur prend en charge ces ensembles de conditions requises, comme décrit dans Vérifications au moment de l’exécution pour la prise en charge de la méthode et de l’ensemble de conditions requises. (La technique de spécification des ensembles de conditions requises dans le manifeste, qui est également décrite dans cet article, ne fonctionne pas actuellement pour RibbonApi 1.2.) Vous pouvez également implémenter une autre expérience d’interface utilisateur lorsque les onglets contextuels personnalisés ne sont pas pris en charge.
Comportement des onglets contextuels personnalisés
L’expérience utilisateur pour les onglets contextuels personnalisés suit le modèle des onglets contextuels Office intégrés. Voici les principes de base pour les onglets contextuels personnalisés de placement.
- Lorsqu’un onglet contextuel personnalisé est visible, il apparaît à l’extrémité droite du ruban.
- Si un ou plusieurs onglets contextuels intégrés et un ou plusieurs onglets contextuels personnalisés des compléments sont visibles en même temps, les onglets contextuels personnalisés sont toujours à droite de tous les onglets contextuels intégrés.
- Si votre complément comporte plusieurs onglets contextuels et qu’il existe des contextes dans lesquels plusieurs sont visibles, ils apparaissent dans l’ordre dans lequel ils sont définis dans votre complément. (La direction est la même que la langue d’Office; autrement dit, est de gauche à droite dans les langues de gauche à droite, mais de droite à gauche dans les langues de droite à gauche.) Pour plus d’informations sur la façon dont vous les définissez, consultez Définir les groupes et les contrôles qui s’affichent sous l’onglet .
- Si plusieurs compléments ont un onglet contextuel visible dans un contexte spécifique, ils apparaissent dans l’ordre dans lequel les compléments ont été lancés.
- Les onglets contextuels personnalisés, contrairement aux onglets principaux personnalisés, ne sont pas ajoutés définitivement au ruban de l’application Office. Ils sont présents uniquement dans les documents Office sur lesquels votre complément est en cours d’exécution.
Étapes principales pour inclure un onglet contextuel dans un complément
Voici les principales étapes pour inclure un onglet contextuel personnalisé dans un complément.
- Configurez le complément pour utiliser un runtime partagé.
- Définissez l’onglet et les groupes et contrôles qui s’y affichent.
- Inscrivez l’onglet contextuel auprès d’Office.
- Spécifiez les circonstances dans lesquelles l’onglet sera visible.
Configurer le complément pour utiliser un runtime partagé
L’ajout d’onglets contextuels personnalisés nécessite que votre complément utilise le runtime partagé. Pour plus d’informations, consultez Configurer un complément pour utiliser un runtime partagé.
Définir les groupes et les contrôles qui s’affichent sous l’onglet
Contrairement aux onglets principaux personnalisés, qui sont définis avec du code XML dans le manifeste, les onglets contextuels personnalisés sont définis au moment de l’exécution avec un objet blob JSON. Votre code analyse l’objet blob dans un objet JavaScript, puis passe l’objet à la méthode Office.ribbon.requestCreateControls . Les onglets contextuels personnalisés sont uniquement présents dans les documents sur lesquels votre complément est en cours d’exécution. Cela diffère des onglets principaux personnalisés qui sont ajoutés au ruban de l’application Office lors de l’installation du complément et restent présents lors de l’ouverture d’un autre document. En outre, la requestCreateControls méthode ne peut être exécutée qu’une seule fois dans une session de votre complément. S’il est appelé à nouveau, une erreur est générée.
Remarque
La structure des propriétés et sous-propriétés de l’objet blob JSON (ainsi que les noms de clés) est à peu près parallèle à la structure de l’élément CustomTab et de ses éléments descendants dans le manifeste XML.
Nous allons construire un exemple d’objet blob JSON d’onglets contextuels pas à pas. Le schéma complet de l’onglet contextuel JSON se trouve dans dynamic-ribbon.schema.json. Si vous travaillez dans Visual Studio Code, vous pouvez utiliser ce fichier pour obtenir IntelliSense et valider votre json. Pour plus d’informations, consultez Modification de JSON avec Visual Studio Code - Schémas et paramètres JSON.
Commencez par créer une chaîne JSON avec deux propriétés de tableau nommées
actionsettabs. Leactionstableau est une spécification de toutes les fonctions qui peuvent être exécutées par des contrôles sous l’onglet contextuel. Letabstableau définit un ou plusieurs onglets contextuels, jusqu’à un maximum de 20.'{ "actions": [ ], "tabs": [ ] }'Cet exemple simple d’un onglet contextuel n’aura qu’un seul bouton et, par conséquent, une seule action. Ajoutez ce qui suit en tant que seul membre du
actionstableau. À propos de ce balisage, notez :- Les
idpropriétés ettypesont obligatoires. - La valeur de
typepeut être « ExecuteFunction » ou « ShowTaskpane ». - La
functionNamepropriété est utilisée uniquement lorsque la valeur detypeestExecuteFunction. Il s’agit du nom d’une fonction définie dans functionFile. Pour plus d’informations sur functionFile, consultez Concepts de base pour les commandes de complément. - Dans une étape ultérieure, vous mapperez cette action à un bouton sous l’onglet contextuel.
{ "id": "executeWriteData", "type": "ExecuteFunction", "functionName": "writeData" }- Les
Ajoutez ce qui suit en tant que seul membre du
tabstableau. À propos de ce balisage, notez :- La propriété
idest requise. Utilisez un ID bref et descriptif unique parmi tous les onglets contextuels de votre complément. - La propriété
labelest requise. Il s’agit d’une chaîne conviviale qui sert d’étiquette de l’onglet contextuel. - La propriété
groupsest requise. Il définit les groupes de contrôles qui s’afficheront sous l’onglet . Il doit avoir au moins un membre et pas plus de 20. (Il existe également des limites sur le nombre de contrôles que vous pouvez avoir sur un onglet contextuel personnalisé, ce qui limite également le nombre de groupes dont vous disposez. Pour plus d’informations, consultez l’étape suivante.)
Remarque
L’objet tab peut également avoir une propriété facultative
visiblequi spécifie si l’onglet est visible immédiatement au démarrage du complément. Étant donné que les onglets contextuels sont normalement masqués jusqu’àfalsece qu’un événement utilisateur déclenche leur visibilité (par exemple, l’utilisateur sélectionnant une entité d’un type quelconque dans le document), la propriété prend par défaut lavisiblevaleur lorsqu’elle n’est pas présente. Dans une section ultérieure, nous montrons comment définir la propriété surtrueen réponse à un événement.{ "id": "CtxTab1", "label": "Contoso Data", "groups": [ ] }- La propriété
Dans l’exemple simple en cours, l’onglet contextuel n’a qu’un seul groupe. Ajoutez ce qui suit en tant que seul membre du
groupstableau. À propos de ce balisage, notez :- Toutes les propriétés sont requises.
- La
idpropriété doit être unique parmi tous les groupes du manifeste. Utilisez un ID bref et descriptif de 125 caractères maximum. - est
labelune chaîne conviviale qui sert d’étiquette du groupe. - La
iconvaleur de la propriété est un tableau d’objets qui spécifient les icônes que le groupe aura sur le ruban en fonction de la taille du ruban et de la fenêtre de l’application Office. - La
controlsvaleur de la propriété est un tableau d’objets qui spécifient les boutons et les menus du groupe. Il doit y en avoir au moins un.
Importante
Le nombre total de contrôles sur l’ensemble de l’onglet ne peut pas être supérieur à 20. Par exemple, vous pouvez avoir 3 groupes avec 6 contrôles chacun et un quatrième groupe avec 2 contrôles, mais vous ne pouvez pas avoir 4 groupes avec 6 contrôles chacun.
{ "id": "CustomGroup111", "label": "Insertion", "icon": [ ], "controls": [ ] }Chaque groupe doit avoir une icône d’au moins deux tailles, 32 x 32 px et 80 x 80 px. Si vous le souhaitez, vous pouvez également avoir des icônes de tailles 16 x 16 px, 20 x 20 px, 24 x 24 px, 40 x 40 px, 48 x 48 px et 64 x 64 px. Office décide de l’icône à utiliser en fonction de la taille du ruban et de la fenêtre de l’application Office. Ajoutez les objets suivants au tableau d’icônes. (Si les tailles de fenêtre et de ruban sont suffisamment grandes pour qu’au moins l’un des contrôles du groupe s’affiche, aucune icône de groupe n’apparaît. Pour obtenir un exemple, watch le groupe Styles dans le ruban Word lorsque vous réduisez et développez la fenêtre Word.) À propos de ce balisage, notez :
- Les deux propriétés sont obligatoires.
- L’unité
sizede propriété de mesure est pixels. Les icônes étant toujours carrées, le nombre correspond à la fois à la hauteur et à la largeur. - La
sourceLocationpropriété spécifie l’URL complète de l’icône.
Importante
Tout comme vous devez généralement modifier les URL dans le manifeste du complément lorsque vous passez du développement à la production (par exemple, en changeant le domaine de localhost à contoso.com), vous devez également modifier les URL dans vos onglets contextuels JSON.
{ "size": 32, "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png" }, { "size": 80, "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png" }Dans notre exemple simple en cours, le groupe n’a qu’un seul bouton. Ajoutez l’objet suivant comme seul membre du
controlstableau. À propos de ce balisage, notez :- Toutes les propriétés, à l’exception
enabledde , sont obligatoires. typespécifie le type de contrôle. Les valeurs peuvent être « Button », « Menu » ou « MobileButton ».idpeut comporter jusqu’à 125 caractères.actionIddoit être l’ID d’une action définie dans leactionstableau. (Consultez l’étape 1 de cette section.)labelest une chaîne conviviale qui sert d’étiquette du bouton.superTipreprésente une forme enrichie d’info-bulle.titleLes propriétés et sontdescriptionrequises.iconspécifie les icônes du bouton. Les remarques précédentes sur l’icône de groupe s’appliquent également ici.enabled(facultatif) spécifie si le bouton est activé lorsque l’onglet contextuel apparaît au démarrage. La valeur par défaut s’il n’est pas présent esttrue.
{ "type": "Button", "id": "CtxBt112", "actionId": "executeWriteData", "enabled": false, "label": "Write Data", "superTip": { "title": "Data Insertion", "description": "Use this button to insert data into the document." }, "icon": [ { "size": 32, "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png" }, { "size": 80, "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png" } ] }- Toutes les propriétés, à l’exception
Voici l’exemple complet de l’objet blob JSON.
`{
"actions": [
{
"id": "executeWriteData",
"type": "ExecuteFunction",
"functionName": "writeData"
}
],
"tabs": [
{
"id": "CtxTab1",
"label": "Contoso Data",
"groups": [
{
"id": "CustomGroup111",
"label": "Insertion",
"icon": [
{
"size": 32,
"sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"
},
{
"size": 80,
"sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"
}
],
"controls": [
{
"type": "Button",
"id": "CtxBt112",
"actionId": "executeWriteData",
"enabled": false,
"label": "Write Data",
"superTip": {
"title": "Data Insertion",
"description": "Use this button to insert data into the document."
},
"icon": [
{
"size": 32,
"sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"
},
{
"size": 80,
"sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"
}
]
}
]
}
]
}
]
}`
Inscrire l’onglet contextuel auprès d’Office avec requestCreateControls
L’onglet contextuel est inscrit auprès d’Office en appelant la méthode Office.ribbon.requestCreateControls . Cette opération est généralement effectuée dans la fonction affectée à Office.initialize ou avec la Office.onReady fonction . Pour plus d’informations sur ces fonctions et l’initialisation du complément, voir Initialiser votre complément Office. Toutefois, vous pouvez appeler la méthode à tout moment après l’initialisation.
Importante
La requestCreateControls méthode ne peut être appelée qu’une seule fois dans une session donnée d’un complément. Une erreur est générée si elle est appelée à nouveau.
Voici un exemple. Notez que la chaîne JSON doit être convertie en objet JavaScript avec la JSON.parse méthode avant de pouvoir être passée à une fonction JavaScript.
Office.onReady(async () => {
const contextualTabJSON = ` ... `; // Assign the JSON string such as the one at the end of the preceding section.
const contextualTab = JSON.parse(contextualTabJSON);
await Office.ribbon.requestCreateControls(contextualTab);
});
Spécifier les contextes où l’onglet sera visible avec requestUpdate
En règle générale, un onglet contextuel personnalisé doit apparaître lorsqu’un événement initié par l’utilisateur modifie le contexte du complément. Imaginez un scénario dans lequel l’onglet doit être visible quand, et seulement quand, un graphique (sur la feuille de calcul par défaut d’un classeur Excel) est activé.
Commencez par attribuer des gestionnaires. Cela est généralement effectué dans la Office.onReady fonction, comme dans l’exemple suivant, qui affecte des gestionnaires (créés à une étape ultérieure) aux onActivated événements et onDeactivated de tous les graphiques de la feuille de calcul.
Office.onReady(async () => {
const contextualTabJSON = ` ... `; // Assign the JSON string.
const contextualTab = JSON.parse(contextualTabJSON);
await Office.ribbon.requestCreateControls(contextualTab);
await Excel.run(context => {
const charts = context.workbook.worksheets
.getActiveWorksheet()
.charts;
charts.onActivated.add(showDataTab);
charts.onDeactivated.add(hideDataTab);
return context.sync();
});
});
Ensuite, définissez les gestionnaires. Voici un exemple simple de , mais consultez Gestion de showDataTabl’erreur HostRestartNeeded plus loin dans cet article pour obtenir une version plus robuste de la fonction. Tenez compte du code suivant :
- Office effectue un contrôle lorsqu’il met à jour l’état du ruban. La méthode Office.ribbon.requestUpdate met en file d’attente une demande de mise à jour. La méthode résout l’objet
Promisedès qu’elle a mis en file d’attente la requête, et non lorsque le ruban est réellement mis à jour. - Le paramètre de la
requestUpdateméthode est un objet RibbonUpdaterData qui (1) spécifie l’onglet par son ID exactement comme spécifié dans le JSON et (2) spécifie la visibilité de l’onglet. - Si vous avez plusieurs onglets contextuels personnalisés qui doivent être visibles dans le même contexte, vous ajoutez simplement des objets tabulation supplémentaires au
tabstableau.
async function showDataTab() {
await Office.ribbon.requestUpdate({
tabs: [
{
id: "CtxTab1",
visible: true
}
]});
}
Le gestionnaire permettant de masquer l’onglet est presque identique, sauf qu’il rétablit la visible propriété sur false.
La bibliothèque JavaScript Office fournit également plusieurs interfaces (types) pour faciliter la construction de l’objetRibbonUpdateData . La fonction suivante dans showDataTab TypeScript utilise ces types.
const showDataTab = async () => {
const myContextualTab: Office.Tab = {id: "CtxTab1", visible: true};
const ribbonUpdater: Office.RibbonUpdaterData = { tabs: [ myContextualTab ]};
await Office.ribbon.requestUpdate(ribbonUpdater);
}
Activer la visibilité des onglets et la status activée d’un bouton en même temps
La requestUpdate méthode est également utilisée pour activer ou désactiver l’status d’un bouton personnalisé sur un onglet contextuel personnalisé ou un onglet principal personnalisé. Pour plus d’informations à ce sujet, consultez Activer et désactiver les commandes de complément. Il peut y avoir des scénarios dans lesquels vous souhaitez modifier simultanément la visibilité d’un onglet et la status activée d’un bouton. Vous effectuez cette opération avec un seul appel de requestUpdate. Voici un exemple dans lequel un bouton sur un onglet principal est activé en même temps qu’un onglet contextuel est rendu visible.
function myContextChanges() {
Office.ribbon.requestUpdate({
tabs: [
{
id: "CtxTab1",
visible: true
},
{
id: "OfficeAppTab1",
groups: [
{
id: "CustomGroup111",
controls: [
{
id: "MyButton",
enabled: true
}
]
}
]
]}
]
});
}
Dans l’exemple suivant, le bouton activé se trouve sous le même onglet contextuel que celui qui est visible.
function myContextChanges() {
Office.ribbon.requestUpdate({
tabs: [
{
id: "CtxTab1",
visible: true,
groups: [
{
id: "CustomGroup111",
controls: [
{
id: "MyButton",
enabled: true
}
]
}
]
}
]
});
}
Ouvrir un volet Office à partir d’onglets contextuels
Pour ouvrir votre volet Office à partir d’un bouton sur un onglet contextuel personnalisé, créez une action dans le JSON avec un type de ShowTaskpane. Définissez ensuite un bouton avec la actionId propriété définie sur le id de l’action. Cela ouvre le volet Office par défaut spécifié par l’élément <Runtime> dans votre manifeste.
`{
"actions": [
{
"id": "openChartsTaskpane",
"type": "ShowTaskpane",
"title": "Work with Charts",
"supportPinning": false
}
],
"tabs": [
{
// some tab properties omitted
"groups": [
{
// some group properties omitted
"controls": [
{
"type": "Button",
"id": "CtxBt112",
"actionId": "openChartsTaskpane",
"enabled": false,
"label": "Open Charts Taskpane",
// some control properties omitted
}
]
}
]
}
]
}`
Pour ouvrir un volet Office qui n’est pas le volet Office par défaut, spécifiez une sourceLocation propriété dans la définition de l’action. Dans l’exemple suivant, un deuxième volet office est ouvert à partir d’un autre bouton.
Importante
- Quand un
sourceLocationest spécifié pour l’action, le volet Office n’utilise pas le runtime partagé. Il s’exécute dans un nouveau runtime distinct. - Pas plus d’un volet Office peut utiliser le runtime partagé, donc pas plus d’une action de type
ShowTaskpanene peut omettre lasourceLocationpropriété.
`{
"actions": [
{
"id": "openChartsTaskpane",
"type": "ShowTaskpane",
"title": "Work with Charts",
"supportPinning": false
},
{
"id": "openTablesTaskpane",
"type": "ShowTaskpane",
"title": "Work with Tables",
"supportPinning": false
"sourceLocation": "https://MyDomain.com/myPage.html"
}
],
"tabs": [
{
// some tab properties omitted
"groups": [
{
// some group properties omitted
"controls": [
{
"type": "Button",
"id": "CtxBt112",
"actionId": "openChartsTaskpane",
"enabled": false,
"label": "Open Charts Taskpane",
// some control properties omitted
},
{
"type": "Button",
"id": "CtxBt113",
"actionId": "openTablesTaskpane",
"enabled": false,
"label": "Open Tables Taskpane",
// some control properties omitted
}
]
}
]
}
]
}`
Localiser le texte JSON
L’objet blob JSON qui est passé à requestCreateControls n’est pas localisé de la même façon que le balisage de manifeste pour les onglets principaux personnalisés est localisé (ce qui est décrit dans Contrôler la localisation à partir du manifeste). Au lieu de cela, la localisation doit se produire au moment de l’exécution à l’aide d’objets blob JSON distincts pour chaque paramètre régional. Nous vous suggérons d’utiliser une switch instruction qui teste la propriété Office.context.displayLanguage . Voici un exemple.
function GetContextualTabsJsonSupportedLocale () {
const displayLanguage = Office.context.displayLanguage;
switch (displayLanguage) {
case 'en-US':
return `{
"actions": [
// actions omitted
],
"tabs": [
{
"id": "CtxTab1",
"label": "Contoso Data",
"groups": [
// groups omitted
]
}
]
}`;
case 'fr-FR':
return `{
"actions": [
// actions omitted
],
"tabs": [
{
"id": "CtxTab1",
"label": "Contoso Données",
"groups": [
// groups omitted
]
}
]
}`;
// Other cases omitted
}
}
Ensuite, votre code appelle la fonction pour obtenir l’objet blob localisé qui est passé à requestCreateControls, comme dans l’exemple suivant.
const contextualTabJSON = GetContextualTabsJsonSupportedLocale();
Meilleures pratiques pour les onglets contextuels personnalisés
Implémenter une autre expérience d’interface utilisateur lorsque les onglets contextuels personnalisés ne sont pas pris en charge
Certaines combinaisons de plateforme, d’application Office et de build Office ne prennent pas en charge requestCreateControls. Votre complément doit être conçu pour fournir une autre expérience aux utilisateurs qui exécutent le complément sur l’une de ces combinaisons. Les sections suivantes décrivent deux façons de fournir une expérience de secours.
Utiliser des onglets ou des contrôles non textuels
Il existe un élément manifeste, OverriddenByRibbonApi, conçu pour créer une expérience de secours dans un complément qui implémente des onglets contextuels personnalisés lorsque le complément s’exécute sur une application ou une plateforme qui ne prend pas en charge les onglets contextuels personnalisés.
La stratégie la plus simple pour utiliser cet élément consiste à définir un onglet principal personnalisé (autrement dit, un onglet personnalisé non contextuel ) dans le manifeste qui duplique les personnalisations du ruban des onglets contextuels personnalisés dans votre complément. Mais vous ajoutez <OverriddenByRibbonApi>true</OverriddenByRibbonApi> en tant que premier élément enfant des éléments Group, Control et Item> de menu< en double dans les onglets principaux personnalisés. L’effet de cette opération est le suivant :
- Si le complément s’exécute sur une application et une plateforme qui prennent en charge des onglets contextuels personnalisés, les groupes principaux et les contrôles personnalisés n’apparaissent pas sur le ruban. Au lieu de cela, l’onglet contextuel personnalisé est créé lorsque le complément appelle la
requestCreateControlsméthode . - Si le complément s’exécute sur une application ou une plateforme qui ne prend pas en charge
requestCreateControls, les éléments apparaissent sous l’onglet cœur personnalisé.
Voici un exemple. Notez que « MyButton » s’affiche sous l’onglet principal personnalisé uniquement lorsque les onglets contextuels personnalisés ne sont pas pris en charge. Toutefois, le groupe parent et l’onglet cœur personnalisé s’affichent, que les onglets contextuels personnalisés soient ou non pris en charge.
<OfficeApp ...>
...
<VersionOverrides ...>
...
<Hosts>
<Host ...>
...
<DesktopFormFactor>
<ExtensionPoint ...>
<CustomTab ...>
...
<Group ...>
...
<Control ... id="Contoso.MyButton1">
<OverriddenByRibbonApi>true</OverriddenByRibbonApi>
...
<Action ...>
...
</OfficeApp>
Pour plus d’exemples, consultez OverriddenByRibbonApi.
Lorsqu’un groupe parent ou un menu est marqué avec <OverriddenByRibbonApi>true</OverriddenByRibbonApi>, il n’est pas visible et tout son balisage enfant est ignoré lorsque les onglets contextuels personnalisés ne sont pas pris en charge. Par conséquent, peu importe si l’un de ces éléments enfants a l’élément <OverriddenByRibbonApi> ou quelle est sa valeur. Cela implique que si un élément de menu ou un contrôle doit être visible dans tous les contextes, non seulement il ne doit pas être marqué avec <OverriddenByRibbonApi>true</OverriddenByRibbonApi>, mais son menu et son groupe ancêtres ne doivent pas non plus être marqués de cette façon.
Importante
Ne marquez pas tous les éléments enfants d’un groupe ou d’un menu avec <OverriddenByRibbonApi>true</OverriddenByRibbonApi>. Cela est inutile si l’élément parent est marqué avec <OverriddenByRibbonApi>true</OverriddenByRibbonApi> pour les raisons indiquées dans le paragraphe précédent. En outre, si vous laissez l’api <OverriddenByRibbonApi> sur le parent (ou si vous la définissez falsesur ), le parent s’affiche, que les onglets contextuels personnalisés soient ou non pris en charge, mais il sera vide lorsqu’ils sont pris en charge. Par conséquent, si tous les éléments enfants ne doivent pas apparaître lorsque les onglets contextuels personnalisés sont pris en charge, marquez le parent avec <OverriddenByRibbonApi>true</OverriddenByRibbonApi>.
Utiliser des API qui affichent ou masquent un volet Office dans des contextes spécifiés
En guise d’alternative à <OverriddenByRibbonApi>, votre complément peut définir un volet Office avec des contrôles d’interface utilisateur qui dupliquent les fonctionnalités des contrôles dans un onglet contextuel personnalisé. Utilisez ensuite les méthodes Office.addin.showAsTaskpane et Office.addin.hide pour afficher le volet Office lorsque l’onglet contextuel aurait été affiché s’il était pris en charge. Pour plus d’informations sur l’utilisation de ces méthodes, voir Afficher ou masquer le volet Office de votre complément Office.
Gérer l’erreur HostRestartNeeded
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é. Votre code doit gérer cette erreur. Voici un exemple de procédure. Dans ce cas, la méthode reportError affiche l’erreur à l’utilisateur.
function showDataTab() {
try {
Office.ribbon.requestUpdate({
tabs: [
{
id: "CtxTab1",
visible: true
}
]});
}
catch(error) {
if (error.code == "HostRestartNeeded"){
reportError("Contoso Awesome Add-in has been upgraded. Please save your work, then close and reopen the Office application.");
}
}
}
Ressources
Exemple de code : Créer des onglets contextuels personnalisés sur le ruban
Exemple de démonstration communautaire d’onglets contextuels
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