Create benutzerdefinierte Kontextregisterkarten in Office-Add-Ins
Eine Kontextregisterkarte ist ein ausgeblendetes Registerkartensteuerelement im Office-Menüband, das in der Registerkartenzeile angezeigt wird, wenn ein angegebenes Ereignis im Office-Dokument auftritt. Beispielsweise die Registerkarte Tabellenentwurf , die im Excel-Menüband angezeigt wird, wenn eine Tabelle ausgewählt ist. Sie schließen benutzerdefinierte kontextbezogene Registerkarten in Ihr Office-Add-In ein und geben an, wann sie sichtbar oder ausgeblendet sind, indem Sie Ereignishandler erstellen, die die Sichtbarkeit ändern. (Benutzerdefinierte kontextbezogene Registerkarten reagieren jedoch nicht auf Fokusänderungen.)
Hinweis
In diesem Artikel wird davon ausgegangen, dass Sie mit der folgenden Dokumentation vertraut sind. Lesen Sie diese Dokumentation, wenn Sie in der letzten Zeit nicht mit Add-In-Befehlen (benutzerdefinierten Menüelementen und Schaltflächen des Menübands) gearbeitet haben.
Wichtig
Benutzerdefinierte kontextbezogene Registerkarten werden derzeit nur in Excel und nur auf diesen Plattformen und Builds unterstützt.
- Excel im Web
- Excel unter Windows: Version 2102 (Build 13801.20294) oder höher.
- Excel für Mac: Version 16.53.806.0 oder höher.
Hinweis
Benutzerdefinierte kontextbezogene Registerkarten funktionieren nur auf Plattformen, die die folgenden Anforderungssätze unterstützen. Weitere Informationen zu Anforderungssätzen und deren Verwendung finden Sie unter Angeben von Office-Anwendungen und API-Anforderungen.
Sie können die Laufzeitüberprüfungen in Ihrem Code verwenden, um zu testen, ob die Kombination aus Host und Plattform des Benutzers diese Anforderungssätze unterstützt, wie unter Laufzeitüberprüfungen für die Unterstützung von Methoden und Anforderungssätzen beschrieben. (Die Technik zum Angeben der Anforderungssätze im Manifest, die auch in diesem Artikel beschrieben wird, funktioniert derzeit nicht für RibbonApi 1.2.) Alternativ können Sie eine alternative Benutzeroberfläche implementieren, wenn benutzerdefinierte kontextbezogene Registerkarten nicht unterstützt werden.
Verhalten von benutzerdefinierten kontextbezogenen Registerkarten
Die Benutzeroberfläche für benutzerdefinierte kontextbezogene Registerkarten folgt dem Muster integrierter Office-Kontextregisterkarten. Im Folgenden sind die Grundprinzipien für die Platzierung benutzerdefinierter kontextbezogener Registerkarten aufgeführt.
- Wenn eine benutzerdefinierte kontextbezogene Registerkarte angezeigt wird, wird sie am rechten Ende des Menübands angezeigt.
- Wenn eine oder mehrere integrierte kontextbezogene Registerkarten und eine oder mehrere benutzerdefinierte kontextbezogene Registerkarten aus Add-Ins gleichzeitig sichtbar sind, befinden sich die benutzerdefinierten kontextbezogenen Registerkarten immer rechts neben allen integrierten kontextbezogenen Registerkarten.
- Wenn Ihr Add-In über mehrere kontextbezogene Registerkarten verfügt und Kontexte vorhanden sind, in denen mehrere sichtbar sind, werden sie in der Reihenfolge angezeigt, in der sie in Ihrem Add-In definiert sind. (Die Richtung entspricht der Office-Sprache, d. h. ist in Sprachen von links nach rechts, in Sprachen von rechts nach links, aber von rechts nach links in Sprachen von rechts nach links.) Ausführliche Informationen dazu, wie Sie diese definieren, finden Sie unter Definieren der Gruppen und Steuerelemente, die auf der Registerkarte angezeigt werden .
- Wenn mehrere Add-Ins über eine kontextbezogene Registerkarte verfügen, die in einem bestimmten Kontext sichtbar ist, werden sie in der Reihenfolge angezeigt, in der die Add-Ins gestartet wurden.
- Benutzerdefinierte kontextbezogene Registerkarten werden im Gegensatz zu benutzerdefinierten Kernregisterkarten nicht dauerhaft zum Menüband der Office-Anwendung hinzugefügt. Sie sind nur in Office-Dokumenten vorhanden, auf denen Ihr Add-In ausgeführt wird.
Hauptschritte zum Einschließen einer kontextbezogenen Registerkarte in ein Add-In
Im Folgenden sind die wichtigsten Schritte zum Einschließen einer benutzerdefinierten kontextbezogenen Registerkarte in ein Add-In aufgeführt.
- Konfigurieren Sie das Add-In für die Verwendung einer freigegebenen Runtime.
- Definieren Sie die Registerkarte und die Gruppen und Steuerelemente, die darauf angezeigt werden.
- Registrieren Sie die Kontextregisterkarte bei Office.
- Geben Sie die Umstände an, unter der die Registerkarte angezeigt wird.
Konfigurieren des Add-Ins für die Verwendung einer freigegebenen Runtime
Das Hinzufügen benutzerdefinierter kontextbezogener Registerkarten erfordert, dass Ihr Add-In die freigegebene Runtime verwendet. Weitere Informationen finden Sie unter Konfigurieren eines Add-Ins für die Verwendung einer freigegebenen Runtime.
Definieren der Gruppen und Steuerelemente, die auf der Registerkarte angezeigt werden
Im Gegensatz zu benutzerdefinierten Kernregisterkarten, die im Manifest mit XML definiert werden, werden benutzerdefinierte Kontextregisterkarten zur Laufzeit mit einem JSON-Blob definiert. Ihr Code analysiert das Blob in einem JavaScript-Objekt und übergibt das Objekt dann an die Office.ribbon.requestCreateControls-Methode . Benutzerdefinierte kontextbezogene Registerkarten sind nur in Dokumenten vorhanden, auf denen das Add-In derzeit ausgeführt wird. Dies unterscheidet sich von benutzerdefinierten Kernregisterkarten, die dem Menüband der Office-Anwendung hinzugefügt werden, wenn das Add-In installiert ist und beim Öffnen eines anderen Dokuments vorhanden bleiben. Außerdem kann die requestCreateControls Methode nur einmal in einer Sitzung Ihres Add-Ins ausgeführt werden. Wenn es erneut aufgerufen wird, wird ein Fehler ausgelöst.
Hinweis
Die Struktur der Eigenschaften und Untereigenschaften des JSON-Blobs (und der Schlüsselnamen) ist ungefähr parallel zur Struktur des CustomTab-Elements und seiner Nachfolgerelemente im Manifest-XML.The structure of the CustomTab element and its descendant elements in the manifest XML.
Wir erstellen Schritt für Schritt ein Beispiel für ein JSON-Blob mit kontextbezogenen Registerkarten. Das vollständige Schema für die Kontextregisterkarte JSON befindet sich bei dynamic-ribbon.schema.json. Wenn Sie in Visual Studio Code arbeiten, können Sie diese Datei verwenden, um IntelliSense abzurufen und Ihren JSON-Code zu überprüfen. Weitere Informationen finden Sie unter Bearbeiten von JSON mit Visual Studio Code – JSON-Schemas und -Einstellungen.
Erstellen Sie zunächst eine JSON-Zeichenfolge mit zwei Arrayeigenschaften namens
actionsundtabs. DasactionsArray ist eine Spezifikation aller Funktionen, die von Steuerelementen auf der Kontextregisterkarte ausgeführt werden können. DastabsArray definiert eine oder mehrere kontextbezogene Registerkarten bis zu maximal 20.'{ "actions": [ ], "tabs": [ ] }'Dieses einfache Beispiel für eine kontextbezogene Registerkarte enthält nur eine einzelne Schaltfläche und somit nur eine einzige Aktion. Fügen Sie Folgendes als einziges Element des
actionsArrays hinzu. Beachten Sie zu diesem Markup:- Die
idEigenschaften undtypesind obligatorisch. - Der Wert von
typekann entweder "ExecuteFunction" oder "ShowTaskpane" sein. - Die
functionName-Eigenschaft wird nur verwendet, wenn der Wert vontypeistExecuteFunction. Dies ist der Name einer Funktion, die in der FunctionFile definiert ist. Weitere Informationen zur FunctionFile finden Sie unter Grundlegende Konzepte für Add-In-Befehle. - In einem späteren Schritt ordnen Sie diese Aktion einer Schaltfläche auf der Kontextregisterkarte zu.
{ "id": "executeWriteData", "type": "ExecuteFunction", "functionName": "writeData" }- Die
Fügen Sie Folgendes als einziges Element des
tabsArrays hinzu. Beachten Sie zu diesem Markup:- Die Eigenschaft
idmuss angegeben werden. Verwenden Sie eine kurze, beschreibende ID, die für alle kontextbezogenen Registerkarten in Ihrem Add-In eindeutig ist. - Die Eigenschaft
labelmuss angegeben werden. Es handelt sich um eine benutzerfreundliche Zeichenfolge, die als Bezeichnung der kontextbezogenen Registerkarte dient. - Die Eigenschaft
groupsmuss angegeben werden. Es definiert die Gruppen von Steuerelementen, die auf der Registerkarte angezeigt werden. Sie muss mindestens ein Mitglied und nicht mehr als 20 haben. (Es gibt auch Grenzwerte für die Anzahl von Steuerelementen, die auf einer benutzerdefinierten kontextbezogenen Registerkarte vorhanden sein können, und dies schränkt auch die Anzahl der Gruppen ein. Weitere Informationen finden Sie im nächsten Schritt.)
Hinweis
Das tab-Objekt kann auch über eine optionale
visibleEigenschaft verfügen, die angibt, ob die Registerkarte beim Starten des Add-Ins sofort sichtbar ist. Da kontextbezogene Registerkarten normalerweise ausgeblendet werden, bis ein Benutzerereignis ihre Sichtbarkeit auslöst (z. B. wenn der Benutzer eine Entität eines bestimmten Typs im Dokument auswählt), wird dievisibleEigenschaft standardmäßig auffalsefestgelegt, wenn sie nicht vorhanden ist. In einem späteren Abschnitt wird gezeigt, wie die -Eigenschafttrueals Reaktion auf ein Ereignis auf festgelegt wird.{ "id": "CtxTab1", "label": "Contoso Data", "groups": [ ] }- Die Eigenschaft
Im einfachen fortlaufenden Beispiel enthält die Kontextregisterkarte nur eine einzelne Gruppe. Fügen Sie Folgendes als einziges Element des
groupsArrays hinzu. Beachten Sie zu diesem Markup:- Alle Eigenschaften sind erforderlich.
- Die
id-Eigenschaft muss für alle Gruppen im Manifest eindeutig sein. Verwenden Sie eine kurze, beschreibende ID mit bis zu 125 Zeichen. - ist
labeleine benutzerfreundliche Zeichenfolge, die als Bezeichnung der Gruppe dient. - Der
iconWert der Eigenschaft ist ein Array von Objekten, die die Symbole angeben, die die Gruppe abhängig von der Größe des Menübands und des Office-Anwendungsfensters auf dem Menüband haben wird. - Der
controlsWert der Eigenschaft ist ein Array von -Objekten, die die Schaltflächen und Menüs in der Gruppe angeben. Es muss mindestens eine vorhanden sein.
Wichtig
Die Gesamtzahl der Steuerelemente auf der gesamten Registerkarte darf nicht mehr als 20 sein. Beispielsweise könnten Sie 3 Gruppen mit jeweils 6 Steuerelementen und eine vierte Gruppe mit 2 Steuerelementen haben, aber Sie können nicht über vier Gruppen mit jeweils 6 Steuerelementen verfügen.
{ "id": "CustomGroup111", "label": "Insertion", "icon": [ ], "controls": [ ] }Jede Gruppe muss über ein Symbol von mindestens zwei Größen verfügen: 32x32 px und 80x80 px. Optional können Sie auch Symbole der Größen 16x16 px, 20x20 px, 24x24 px, 40x40 px, 48x48 px und 64x64 px verwenden. Office entscheidet basierend auf der Größe des Menübands und des Office-Anwendungsfensters, welches Symbol verwendet werden soll. Fügen Sie dem Symbolarray die folgenden Objekte hinzu. (Wenn die Fenster- und Menübandgrößen groß genug sind, damit mindestens eines der Steuerelemente in der Gruppe angezeigt wird, wird überhaupt kein Gruppensymbol angezeigt. Beispiel: watch die Gruppe Formatvorlagen auf dem menüband Word, während Sie das fenster Word verkleinern und erweitern.) Beachten Sie zu diesem Markup:
- Beide Eigenschaften sind erforderlich.
- Die
sizeMaßeinheit der Eigenschaft ist Pixel. Symbole sind immer quadratisch, sodass die Zahl sowohl die Höhe als auch die Breite ist. - Die
sourceLocation-Eigenschaft gibt die vollständige URL zum Symbol an.
Wichtig
Genauso wie Sie die URLs im Manifest des Add-Ins in der Regel ändern müssen, wenn Sie von der Entwicklung in die Produktion wechseln (z. B. die Domäne von localhost in contoso.com ändern), müssen Sie auch die URLs im JSON-Code Ihrer Kontextregisterkarten ändern.
{ "size": 32, "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png" }, { "size": 80, "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png" }In unserem einfachen fortlaufenden Beispiel verfügt die Gruppe nur über eine einzelne Schaltfläche. Fügen Sie das folgende Objekt als einziges Element des
controlsArrays hinzu. Beachten Sie zu diesem Markup:- Alle Eigenschaften mit Ausnahme
enabledvon sind erforderlich. typegibt den Typ des Steuerelements an. Die Werte können "Button", "Menu" oder "MobileButton" sein.idkann bis zu 125 Zeichen lang sein.actionIdmuss die ID einer im Array definiertenactionsAktion sein. (Siehe Schritt 1 dieses Abschnitts.)labelist eine benutzerfreundliche Zeichenfolge, die als Bezeichnung der Schaltfläche dienen soll.superTipstellt eine umfangreiche Form von QuickInfos dar. Sowohl die -Eigenschaft alsdescriptionauch dietitle-Eigenschaft sind erforderlich.icongibt die Symbole für die Schaltfläche an. Die vorherigen Hinweise zum Gruppensymbol gelten auch hier.enabled(optional) gibt an, ob die Schaltfläche aktiviert ist, wenn die kontextbezogene Registerkarte angezeigt wird. Der Standardwert, wenn nicht vorhanden ist, isttrue.
{ "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" } ] }- Alle Eigenschaften mit Ausnahme
Im Folgenden ist das vollständige Beispiel für das JSON-Blob dargestellt.
`{
"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"
}
]
}
]
}
]
}
]
}`
Registrieren der Kontextregisterkarte bei Office mit requestCreateControls
Die Kontextregisterkarte wird bei Office registriert, indem die Office.ribbon.requestCreateControls-Methode aufgerufen wird. Dies erfolgt in der Regel entweder in der Funktion, die zugewiesen ist, Office.initialize oder mit der Office.onReady Funktion. Weitere Informationen zu diesen Funktionen und zum Initialisieren des Add-Ins finden Sie unter Initialisieren Ihres Office-Add-Ins. Sie können die -Methode jedoch jederzeit nach der Initialisierung aufrufen.
Wichtig
Die requestCreateControls -Methode kann nur einmal in einer bestimmten Sitzung eines Add-Ins aufgerufen werden. Ein Fehler wird ausgelöst, wenn er erneut aufgerufen wird.
Es folgt ein Beispiel. Beachten Sie, dass die JSON-Zeichenfolge mit der JSON.parse -Methode in ein JavaScript-Objekt konvertiert werden muss, bevor sie an eine JavaScript-Funktion übergeben werden kann.
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);
});
Geben Sie die Kontexte an, wenn die Registerkarte mit requestUpdate angezeigt wird.
In der Regel sollte eine benutzerdefinierte kontextbezogene Registerkarte angezeigt werden, wenn ein vom Benutzer initiiertes Ereignis den Add-In-Kontext ändert. Stellen Sie sich ein Szenario vor, in dem die Registerkarte sichtbar sein sollte, wenn und nur dann ein Diagramm (auf dem Standardarbeitsblatt einer Excel-Arbeitsmappe) aktiviert wird.
Beginnen Sie mit dem Zuweisen von Handlern. Dies erfolgt in der Regel in der Office.onReady -Funktion wie im folgenden Beispiel, die Handler (die in einem späteren Schritt erstellt wurden) den onActivated Ereignissen und onDeactivated aller Diagramme im Arbeitsblatt zuweist.
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();
});
});
Definieren Sie als Nächstes die Handler. Im Folgenden finden Sie ein einfaches Beispiel für , showDataTababer eine stabilere Version der Funktion finden Sie unter Behandeln des Fehlers HostRestartNeeded weiter unten in diesem Artikel. Bei diesem Code ist Folgendes zu beachten:
- Office steuert, wann der Status des Menübands aktualisiert wird. Die Office.ribbon.requestUpdate-Methode stellt eine Anforderung in die Warteschlange, um sie zu aktualisieren. Die -Methode löst das
PromiseObjekt auf, sobald die Anforderung in die Warteschlange eingereiht wurde, und nicht, wenn das Menüband tatsächlich aktualisiert wird. - Der Parameter für die
requestUpdateMethode ist ein RibbonUpdaterData-Objekt , das (1) die Registerkarte anhand ihrer ID genau wie im JSON-Code und (2) die Sichtbarkeit der Registerkarte angibt. - Wenn Sie über mehrere benutzerdefinierte kontextbezogene Registerkarten verfügen, die im selben Kontext sichtbar sein sollen, fügen Sie dem
tabsArray einfach zusätzliche Tab-Objekte hinzu.
async function showDataTab() {
await Office.ribbon.requestUpdate({
tabs: [
{
id: "CtxTab1",
visible: true
}
]});
}
Der Handler zum Ausblenden der Registerkarte ist nahezu identisch, mit der Ausnahme, dass die visible -Eigenschaft wieder auf falsefestgelegt wird.
Die Office JavaScript-Bibliothek bietet auch mehrere Schnittstellen (Typen), um das Erstellen desRibbonUpdateData Objekts zu vereinfachen. Es folgt die showDataTab Funktion in TypeScript, die diese Typen verwendet.
const showDataTab = async () => {
const myContextualTab: Office.Tab = {id: "CtxTab1", visible: true};
const ribbonUpdater: Office.RibbonUpdaterData = { tabs: [ myContextualTab ]};
await Office.ribbon.requestUpdate(ribbonUpdater);
}
Gleichzeitiges Umschalten der Registerkartensichtbarkeit und aktivierter status einer Schaltfläche
Die requestUpdate -Methode wird auch verwendet, um die aktivierte oder deaktivierte status einer benutzerdefinierten Schaltfläche auf einer benutzerdefinierten kontextbezogenen Registerkarte oder einer benutzerdefinierten Kernregisterkarte umzuschalten. Ausführliche Informationen hierzu finden Sie unter Aktivieren und Deaktivieren von Add-In-Befehlen. Es kann Szenarien geben, in denen Sie sowohl die Sichtbarkeit einer Registerkarte als auch die aktivierte status einer Schaltfläche gleichzeitig ändern möchten. Dies geschieht mit einem einzelnen Aufruf von requestUpdate. Im Folgenden sehen Sie ein Beispiel, in dem eine Schaltfläche auf einer Kernregisterkarte gleichzeitig aktiviert wird, während eine kontextbezogene Registerkarte sichtbar gemacht wird.
function myContextChanges() {
Office.ribbon.requestUpdate({
tabs: [
{
id: "CtxTab1",
visible: true
},
{
id: "OfficeAppTab1",
groups: [
{
id: "CustomGroup111",
controls: [
{
id: "MyButton",
enabled: true
}
]
}
]
]}
]
});
}
Im folgenden Beispiel befindet sich die aktivierte Schaltfläche auf der kontextbezogenen Registerkarte, die sichtbar gemacht wird.
function myContextChanges() {
Office.ribbon.requestUpdate({
tabs: [
{
id: "CtxTab1",
visible: true,
groups: [
{
id: "CustomGroup111",
controls: [
{
id: "MyButton",
enabled: true
}
]
}
]
}
]
});
}
Öffnen eines Aufgabenbereichs über kontextbezogene Registerkarten
Um den Aufgabenbereich über eine Schaltfläche auf einer benutzerdefinierten kontextbezogenen Registerkarte zu öffnen, erstellen Sie eine Aktion im JSON-Code mit einem type von ShowTaskpane. Definieren Sie dann eine Schaltfläche, bei der die actionId -Eigenschaft auf den der id Aktion festgelegt ist. Dadurch wird der Standardaufgabenbereich geöffnet, der durch das <Runtime-Element> in Ihrem Manifest angegeben wird.
`{
"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
}
]
}
]
}
]
}`
Um einen Aufgabenbereich zu öffnen, der nicht der Standardaufgabenbereich ist, geben Sie eine sourceLocation Eigenschaft in der Definition der Aktion an. Im folgenden Beispiel wird ein zweiter Aufgabenbereich über eine andere Schaltfläche geöffnet.
Wichtig
- Wenn für die Aktion ein
sourceLocationangegeben wird, verwendet der Aufgabenbereich nicht die freigegebene Runtime. Sie wird in einer neuen separaten Runtime ausgeführt. - Nicht mehr als ein Aufgabenbereich kann die freigegebene Runtime verwenden, sodass die Eigenschaft nicht mehr als eine Aktion vom Typ
ShowTaskpaneweggelassensourceLocationwerden kann.
`{
"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
}
]
}
]
}
]
}`
Lokalisieren des JSON-Texts
Das JSON-Blob, das an requestCreateControls übergeben wird, wird nicht auf die gleiche Weise lokalisiert wie das Manifestmarkup für benutzerdefinierte Kernregisterkarten (siehe Steuern der Lokalisierung aus dem Manifest). Stattdessen muss die Lokalisierung zur Laufzeit mit unterschiedlichen JSON-Blobs für jedes Gebietsschema erfolgen. Es wird empfohlen, eine switch -Anweisung zu verwenden, die die Office.context.displayLanguage-Eigenschaft testet . Es folgt ein Beispiel.
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
}
}
Anschließend ruft Ihr Code die -Funktion auf, um das lokalisierte Blob abzurufen, das an requestCreateControlsübergeben wird, wie im folgenden Beispiel gezeigt.
const contextualTabJSON = GetContextualTabsJsonSupportedLocale();
Bewährte Methoden für benutzerdefinierte kontextbezogene Registerkarten
Implementieren einer alternativen Benutzeroberfläche, wenn benutzerdefinierte kontextbezogene Registerkarten nicht unterstützt werden
Einige Kombinationen aus Plattform, Office-Anwendung und Office-Build unterstützen requestCreateControlsnicht . Ihr Add-In sollte so konzipiert sein, dass es Benutzern, die das Add-In auf einer dieser Kombinationen ausführen, eine alternative Benutzeroberfläche bietet. In den folgenden Abschnitten werden zwei Möglichkeiten zum Bereitstellen eines Fallbacks beschrieben.
Verwenden nicht textbezogener Registerkarten oder Steuerelemente
Es gibt ein Manifestelement, OverriddenByRibbonApi, das zum Erstellen einer Fallbackumgebung in einem Add-In entwickelt wurde, das benutzerdefinierte kontextbezogene Registerkarten implementiert, wenn das Add-In auf einer Anwendung oder Plattform ausgeführt wird, die keine benutzerdefinierten Kontextregisterkarten unterstützt.
Die einfachste Strategie für die Verwendung dieses Elements besteht darin, eine benutzerdefinierte Kernregisterkarte (d. h. eine nicht kontextbezogene benutzerdefinierte Registerkarte) im Manifest zu definieren, die die Menübandanpassungen der benutzerdefinierten kontextbezogenen Registerkarten in Ihrem Add-In dupliziert. Sie fügen <OverriddenByRibbonApi>true</OverriddenByRibbonApi> jedoch als erstes untergeordnetes Element der doppelten Group-, Control- und Menüelementelemente<> auf den benutzerdefinierten Kernregisterkarten hinzu. Dies hat folgende Auswirkungen:
- Wenn das Add-In auf einer Anwendung und Plattform ausgeführt wird, die benutzerdefinierte kontextbezogene Registerkarten unterstützen, werden die benutzerdefinierten Kerngruppen und -steuerelemente nicht im Menüband angezeigt. Stattdessen wird die benutzerdefinierte Kontextregisterkarte erstellt, wenn das Add-In die
requestCreateControls-Methode aufruft. - Wenn das Add-In auf einer Anwendung oder Plattform ausgeführt wird, die nicht unterstützt
requestCreateControls, werden die Elemente auf der Registerkarte "Benutzerdefinierter Kern" angezeigt.
Es folgt ein Beispiel. Beachten Sie, dass "MyButton" nur dann auf der benutzerdefinierten Kernregisterkarte angezeigt wird, wenn benutzerdefinierte kontextbezogene Registerkarten nicht unterstützt werden. Die übergeordnete Gruppe und die benutzerdefinierte Kernregisterkarte werden jedoch unabhängig davon angezeigt, ob benutzerdefinierte kontextbezogene Registerkarten unterstützt werden.
<OfficeApp ...>
...
<VersionOverrides ...>
...
<Hosts>
<Host ...>
...
<DesktopFormFactor>
<ExtensionPoint ...>
<CustomTab ...>
...
<Group ...>
...
<Control ... id="Contoso.MyButton1">
<OverriddenByRibbonApi>true</OverriddenByRibbonApi>
...
<Action ...>
...
</OfficeApp>
Weitere Beispiele finden Sie unter OverriddenByRibbonApi.
Wenn eine übergeordnete Gruppe oder ein Menü mit <OverriddenByRibbonApi>true</OverriddenByRibbonApi>markiert ist, ist sie nicht sichtbar, und ihr gesamtes untergeordnetes Markup wird ignoriert, wenn benutzerdefinierte Kontextregisterkarten nicht unterstützt werden. Es spielt also keine Rolle, ob eines dieser untergeordneten Elemente über das <OverriddenByRibbonApi-Element> verfügt oder wie dessen Wert ist. Dies hat zur Folge, dass, wenn ein Menüelement oder Steuerelement in allen Kontexten sichtbar sein muss, nicht nur nicht mit <OverriddenByRibbonApi>true</OverriddenByRibbonApi>gekennzeichnet werden sollte, sondern auch das Vorgängermenü und die Übergeordnete Gruppe nicht auf diese Weise markiert werden dürfen.
Wichtig
Markieren Sie nicht alle untergeordneten Elemente einer Gruppe oder eines Menüs mit <OverriddenByRibbonApi>true</OverriddenByRibbonApi>. Dies ist sinnlos, wenn das übergeordnete Element aus gründen, die im vorherigen Absatz angegeben sind, mit <OverriddenByRibbonApi>true</OverriddenByRibbonApi> gekennzeichnet ist. Wenn Sie die <OverriddenByRibbonApi> auf dem übergeordneten Element weglassen (oder auf falsefestlegen), wird das übergeordnete Element unabhängig davon angezeigt, ob benutzerdefinierte kontextbezogene Registerkarten unterstützt werden, aber sie sind leer, wenn sie unterstützt werden. Wenn also nicht alle untergeordneten Elemente angezeigt werden sollen, wenn benutzerdefinierte kontextbezogene Registerkarten unterstützt werden, markieren Sie das übergeordnete Element mit <OverriddenByRibbonApi>true</OverriddenByRibbonApi>.
Verwenden von APIs, die einen Aufgabenbereich in angegebenen Kontexten ein- oder ausblenden
Als Alternative zu <OverriddenByRibbonApi> kann Ihr Add-In einen Aufgabenbereich mit Ui-Steuerelementen definieren, die die Funktionalität der Steuerelemente auf einer benutzerdefinierten Kontextregisterkarte duplizieren. Verwenden Sie dann die Methoden Office.addin.showAsTaskpane und Office.addin.hide , um den Aufgabenbereich anzuzeigen, wenn die kontextbezogene Registerkarte angezeigt worden wäre, wenn sie unterstützt wurde. Ausführliche Informationen zur Verwendung dieser Methoden finden Sie unter Ein- oder Ausblenden des Aufgabenbereichs Ihres Office-Add-Ins.
Behandeln des HostRestartNeeded-Fehlers
In einigen Szenarien ist Office nicht in der Lage, das Menüband zu aktualisieren und gibt einen Fehler zurück. Wenn das Add-In beispielsweise aktualisiert wird und das aktualisierte Add-In einen anderen Satz von benutzerdefinierten Add-In-Befehlen enthält, muss die Office-Anwendung geschlossen und erneut geöffnet werden. Bis dahin gibt die Methode requestUpdate den Fehler HostRestartNeeded zurück. Ihr Code sollte diesen Fehler behandeln. Im Folgenden finden Sie ein Beispiel dafür. In diesem Fall zeigt die Methode reportError dem Benutzer den Fehler an.
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.");
}
}
}
Ressourcen
Codebeispiel: Create benutzerdefinierte Kontextregisterkarten im Menüband
Beispiel für kontextbezogene Registerkarten in der Community
Office Add-ins
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für