Erstellen benutzerdefinierter kontextbezogener Registerkarten 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 grundlegenden Konzepten für Add-In-Befehle vertraut sind. Überprüfen Sie es, wenn Sie in letzter Zeit nicht mit Add-In-Befehlen (benutzerdefinierte Menüelemente und Menübandschaltflächen) gearbeitet haben.

Voraussetzungen

Benutzerdefinierte kontextbezogene Registerkarten werden derzeit nur in Excel und nur auf den folgenden Plattformen und Builds unterstützt.

• Excel im Web
• Excel unter Windows: Version 2102 (Build 13801.20294) und höher.
• Excel für Mac: Version 16.53 (21080600) und höher.

Darüber hinaus funktionieren benutzerdefinierte Kontextregisterkarten 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.

• RibbonApi 1.2
• SharedRuntime 1.1

Tipp

Verwenden Sie die Laufzeitüberprüfungen in Ihrem Code, 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.

Warnung

Derzeit kann die Verwendung von benutzerdefinierten kontextbezogenen Registerkarten verhindern, dass der Benutzer seine vorherigen Excel-Aktionen rückgängigmachen kann. Dies ist ein bekanntes Problem (siehe diesen GitHub-Thread) und wird derzeit untersucht.

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.

1. Konfigurieren Sie das Add-In für die Verwendung einer freigegebenen Runtime.
2. Geben Sie die Symbole für Ihre kontextbezogene Registerkarte an.
3. Definieren Sie die Gruppen und Steuerelemente, die auf der Registerkarte angezeigt werden.
4. Registrieren Sie die Kontextregisterkarte bei Office.
5. 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.

Geben Sie die Symbole für Ihre kontextbezogene Registerkarte an.

Bevor Sie Ihre kontextbezogene Registerkarte anpassen können, müssen Sie zuerst alle Symbole angeben, die darauf mit einem Image-Element im Abschnitt Resources des Add-In-Manifests angezeigt werden. Jedes Symbol muss mindestens drei Größen aufweisen: 16x16 px, 32x32 px und 80x80 px.

Es folgt ein Beispiel.

<Resources>
    <bt:Images>
        <bt:Image id="contextual-tab-icon-16" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"/>
        <bt:Image id="contextual-tab-icon-32" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"/>
        <bt:Image id="contextual-tab-icon-80" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"/>
        <bt:Image id="contextual-button-icon-16" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"/>
        <bt:Image id="contextual-button-icon-32" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"/>
        <bt:Image id="contextual-button-icon-80" DefaultValue="https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"/>
    </bt:Images>
    ...
</Resources>

Wichtig

Wenn Sie Ihr Add-In von der Entwicklung in die Produktion verschieben, denken Sie daran, die URLs in Ihrem Manifest nach Bedarf zu aktualisieren (z. B. ändern Sie die Domäne von localhost in contoso.com).

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.

1. Erstellen Sie zunächst eine JSON-Zeichenfolge mit zwei Arrayeigenschaften namens actions und tabs. Das actions Array ist eine Spezifikation aller Funktionen, die von Steuerelementen auf der Kontextregisterkarte ausgeführt werden können. Das tabs Array definiert eine oder mehrere kontextbezogene Registerkarten bis zu maximal 20.

   '{
     "actions": [
   
     ],
     "tabs": [
   
     ]
   }'
   

2. 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 actions Arrays hinzu. Beachten Sie zu diesem Markup:

   • Die id Eigenschaften und type sind obligatorisch.
   • Der Wert von type kann entweder "ExecuteFunction" oder "ShowTaskpane" sein.
   • Die functionName -Eigenschaft wird nur verwendet, wenn der Wert von type ist ExecuteFunction. 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"
   }
   

3. Fügen Sie Folgendes als einziges Element des tabs Arrays hinzu. Beachten Sie zu diesem Markup:

   • Die Eigenschaft id muss angegeben werden. Verwenden Sie eine kurze, beschreibende ID, die für alle kontextbezogenen Registerkarten in Ihrem Add-In eindeutig ist.
   • Die Eigenschaft label muss angegeben werden. Es handelt sich um eine benutzerfreundliche Zeichenfolge, die als Bezeichnung der kontextbezogenen Registerkarte dient.
   • Die Eigenschaft groups muss 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 visible Eigenschaft 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 die visible Eigenschaft standardmäßig auf false festgelegt, wenn sie nicht vorhanden ist. In einem späteren Abschnitt wird gezeigt, wie die -Eigenschaft true als Reaktion auf ein Ereignis auf festgelegt wird.

   {
     "id": "CtxTab1",
     "label": "Contoso Data",
     "groups": [
   
     ]
   }
   

4. Im einfachen fortlaufenden Beispiel enthält die Kontextregisterkarte nur eine einzelne Gruppe. Fügen Sie Folgendes als einziges Element des groups Arrays 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 label eine benutzerfreundliche Zeichenfolge, die als Bezeichnung der Gruppe dient.
   • Der icon Wert 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 controls Wert 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": [
   
       ]
   }
   

5. Jede Gruppe muss über ein Symbol von mindestens drei Größen verfügen: 16x16 px, 32x32 px und 80x80 px. Optional können Sie auch Symbole der Größen 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 size Maß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. Sein Wert muss mit der URL übereinstimmen, die <im Image-Element> des <Abschnitts Resources> Ihres Manifests angegeben ist (siehe Angeben der Symbole für Ihre kontextbezogene Registerkarte).

   Wichtig

   So wie Sie normalerweise die URLs im Manifest des Add-Ins ändern müssen, wenn Sie von der Entwicklung in die Produktion wechseln, müssen Sie auch die URLs im JSON-Code Ihrer Kontextregisterkarten ändern.

   {
       "size": 16,
       "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"
   },
   {
       "size": 32,
       "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group32x32.png"
   },
   {
       "size": 80,
       "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group80x80.png"
   }
   

6. 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 controls Arrays hinzu. Beachten Sie zu diesem Markup:

   • Alle Eigenschaften mit Ausnahme enabledvon sind erforderlich.
   • type gibt den Typ des Steuerelements an. Die Werte können "Button", "Menu" oder "MobileButton" sein.
   • id kann bis zu 125 Zeichen lang sein.
   • actionId muss die ID einer im Array definierten actions Aktion sein. (Siehe Schritt 1 dieses Abschnitts.)
   • label ist eine benutzerfreundliche Zeichenfolge, die als Bezeichnung der Schaltfläche dienen soll.
   • superTip stellt eine umfangreiche Form von QuickInfos dar. Sowohl die -Eigenschaft als description auch die title -Eigenschaft sind erforderlich.
   • icon gibt 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, ist true.

   {
       "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": 16,
               "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"
           },
           {
               "size": 32,
               "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton32x32.png"
           },
           {
               "size": 80,
               "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton80x80.png"
           }
       ]
   }
   

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": 16,
                "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/Group16x16.png"
            },
            {
                "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": 16,
                        "sourceLocation": "https://cdn.contoso.com/addins/datainsertion/Images/WriteDataButton16x16.png"
                    },
                    {
                        "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 Promise Objekt auf, sobald die Anforderung in die Warteschlange eingereiht wurde, und nicht, wenn das Menüband tatsächlich aktualisiert wird.
• Der Parameter für die requestUpdate Methode 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 tabs Array 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 sourceLocation angegeben 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 ShowTaskpane weggelassen sourceLocation werden 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: Erstellen benutzerdefinierter kontextbezogener Registerkarten im Menüband

• Beispiel für kontextbezogene Registerkarten in der Community