Freigeben über

Erstellen von Add-In-Befehlen mit dem einheitlichen Manifest für Microsoft 365

  • Artikel

Add-In-Befehle bieten eine einfache Möglichkeit zum Anpassen der standardmäßigen Office-Benutzeroberfläche mit angegebenen Benutzeroberflächenelementen, die Aktionen ausführen. Eine Einführung in Add-In-Befehle finden Sie unter Add-In-Befehle.

In diesem Artikel wird beschrieben, wie Sie das einheitliche Manifest für Microsoft 365 konfigurieren, um Add-In-Befehle zu definieren, und wie Sie den Code für Funktionsbefehle erstellen.

Tipp

Anweisungen zum Erstellen von Add-In-Befehlen mit dem reinen Add-In-Manifest finden Sie unter Erstellen von Add-In-Befehlen mit dem reinen Add-In-Manifest.

Hinweis

Office-Add-Ins, die das einheitliche Manifest für Microsoft 365 verwenden, werden direkt in Office im Web, in neuen Outlook unter Windows und in Office unter Windows, die mit einem Microsoft 365-Abonnement verbunden sind, Version 2304 (Build 16320.00000) oder höher unterstützt.

Wenn das App-Paket, das das einheitliche Manifest enthält, in AppSource oder im Microsoft 365 Admin Center bereitgestellt wird, wird ein reines Add-In-Manifest aus dem einheitlichen Manifest generiert und gespeichert, wenn das Manifest über eine gültige "alternateIcons"-Eigenschaft verfügt. Dieses Reine Add-In-Manifest ermöglicht die Installation des Add-Ins auf Plattformen, die das einheitliche Manifest nicht direkt unterstützen, einschließlich Office für Mac, Office auf Mobilgeräten, Abonnementversionen von Office unter Windows vor 2304 (Build 16320.00000) und unbefristete Versionen von Office unter Windows.

Ausgangspunkt und hauptschritte

Beide Tools, die Add-In-Projekte mit einem einheitlichen Manifest erstellen – der Office Yeoman-Generator und das Teams-Toolkit – erstellen Projekte mit einem oder mehreren Add-In-Befehlen. Das einzige Mal, dass Sie nicht bereits über einen Add-In-Befehl verfügen, ist, wenn Sie ein Add-In aktualisieren, das zuvor noch nicht über ein Add-In verfügte.

Zwei Entscheidungen

  • Entscheiden Sie, welche der beiden Arten von Add-In-Befehlen Sie benötigen: Aufgabenbereich oder Funktion
  • Entscheiden Sie, welche Art von UI-Element Sie benötigen: Schaltfläche oder Menüelement. Führen Sie dann die Schritte in den Abschnitten und Unterabschnitten unten aus, die Ihren Entscheidungen entsprechen.

Hinzufügen eines Aufgabenbereichbefehls

In den folgenden Unterabschnitten wird erläutert, wie Ein Aufgabenbereichbefehl in ein Add-In eingeschlossen wird.

Konfigurieren der Runtime für den Aufgabenbereichbefehl

  1. Öffnen Sie das einheitliche Manifest, und suchen Sie das Array "extensions.runtimes".

  2. Stellen Sie sicher, dass ein Laufzeitobjekt mit der Eigenschaft "actions.type" mit dem Wert "openPage" vorhanden ist. Dieser Laufzeittyp öffnet einen Aufgabenbereich.

  3. Stellen Sie sicher, dass das Array "requirements.capabilities" ein -Objekt enthält, das einen Anforderungssatz angibt, der Add-In-Befehle unterstützt. Für Outlook ist der Mindestanforderungssatz für Add-In-Befehle Mailbox 1.3.

    Hinweis

    Wenn die Unterstützung für das einheitliche Manifest auf andere Office-Hostanwendungen erweitert wird, lautet die Mindestanforderung für Add-In-Befehle in diesen anderen Hosts AddinCommands 1.1.

  4. Stellen Sie sicher, dass die "id" des Laufzeitobjekts einen beschreibenden Namen wie "TaskPaneRuntime" aufweist.

  5. Stellen Sie sicher, dass die Eigenschaft "code.page" des Laufzeitobjekts auf die URL der Seite festgelegt ist, die im Aufgabenbereich geöffnet werden soll, z "https://localhost:3000/taskpane.html". B. .

  6. Stellen Sie sicher, dass "actions.view" des Laufzeitobjekts einen Namen hat, der den Inhalt der Seite beschreibt, die Sie im vorherigen Schritt festgelegt haben, z. B. "Homepage" oder "Dashboard".

  7. Stellen Sie sicher, dass die "actions.id" des Laufzeitobjekts über einen beschreibenden Namen wie "ShowTaskPane" verfügt, der angibt, was geschieht, wenn der Benutzer die Add-In-Befehlsschaltfläche oder das Menüelement auswählt.

  8. Legen Sie die anderen Eigenschaften und Untereigenschaften des Laufzeitobjekts fest, wie im folgenden abgeschlossenen Beispiel eines Laufzeitobjekts gezeigt. Die Eigenschaften "type" und "lifetime" sind erforderlich, und in Outlook-Add-Ins (dies ist der einzige Host, der derzeit das einheitliche Manifest unterstützt) verfügen sie immer über die in diesem Beispiel gezeigten Werte.

    "runtimes": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "Mailbox",
                    "minVersion": "1.3"
                }
            ]
        },
        "id": "TaskPaneRuntime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/taskpane.html"
        },
        "lifetime": "short",
        "actions": [
            {
                "id": "ShowTaskPane",
                "type": "openPage",
                "view": "homepage"
            }
        ]
    }
]

Konfigurieren der Benutzeroberfläche für den Aufgabenbereichbefehl

  1. Stellen Sie sicher, dass das Erweiterungsobjekt, für das Sie eine Laufzeit konfiguriert haben, über eine Arrayeigenschaft "Ribbons" als Peer zum Runtimes-Array verfügt. In der Regel gibt es nur ein Erweiterungsobjekt im Array "extensions".

  2. Stellen Sie sicher, dass das Array über ein Objekt mit den Arrayeigenschaften "contexts" und "tabs" verfügt, wie im folgenden Beispiel gezeigt.

    "ribbons": [
    {
        "contexts": [
            // child objects omitted
        ],
        "tabs": [
            // child objects omitted
        ]
    }
]

  3. Stellen Sie sicher, dass das Array "contexts" Zeichenfolgen enthält, die die Fenster oder Bereiche angeben, in denen die Benutzeroberfläche für den Aufgabenbereichsbefehl angezeigt werden soll. Beispielsweise bedeutet "mailRead", dass es im Lesebereich oder Nachrichtenfenster angezeigt wird, wenn eine E-Mail-Nachricht geöffnet ist, aber "mailCompose" bedeutet, dass sie angezeigt wird, wenn eine neue Nachricht oder eine Antwort erstellt wird. Im Folgenden sind die zulässigen Werte aufgeführt:

    • "mailRead"
    • "mailCompose"
    • "meetingDetailsOrganizer"
    • "meetingDetailsAttendee"

    Es folgt ein Beispiel.

    "contexts": [
    "mailRead"
],

  4. Stellen Sie sicher, dass das Array "tabs" über ein Objekt mit der Zeichenfolgeneigenschaft "builtInTabId" verfügt, die auf die ID der Menübandregisterkarte festgelegt ist, in der der Aufgabenbereichsbefehl angezeigt werden soll. Stellen Sie außerdem sicher, dass ein "Groups"-Array mit mindestens einem Objekt darin vorhanden ist. Es folgt ein Beispiel.

    "tabs": [
    {
        "builtInTabID": "TabDefault",
        "groups": [
            {
                // properties omitted
            }
        ]
    }
]

    Hinweis

    Der einzige zulässige Wert für die Eigenschaft "builtInTabID" ist "TabDefault", bei dem es sich in Outlook entweder um die Registerkarte "Start", " Nachricht" oder " Besprechung " handelt. Wenn unterstützung für das einheitliche Manifest zu anderen Office-Hostanwendungen hinzugefügt wird, gibt es weitere mögliche Werte.

  5. Stellen Sie sicher, dass das Array "groups" über ein -Objekt verfügt, um die benutzerdefinierte Steuerelementgruppe zu definieren, die ihre Add-In-Befehls-UI-Steuerelemente enthält. Es folgt ein Beispiel. Beachten Sie Folgendes zu diesem JSON-Code:

    • Die "ID" muss für alle Gruppen in allen Menübandobjekten im Manifest eindeutig sein. Die maximale Länge beträgt 64 Zeichen.
    • Die "Bezeichnung" wird in der Gruppe im Menüband angezeigt. Obwohl die maximale Länge 64 Zeichen beträgt, empfiehlt es sich, die "Bezeichnung" auf 16 Zeichen zu beschränken, um sicherzustellen, dass die Steuerelementgruppe ordnungsgemäß in das Menüband passt.
    • Eines der "Symbole" wird nur in der Gruppe angezeigt, wenn das Office-Anwendungsfenster und damit das Menüband vom Benutzer zu klein dimensioniert wurde, damit eines der Steuerelemente in der Gruppe angezeigt werden kann. Office entscheidet basierend auf der Größe des Fensters und der Auflösung des Geräts, wann eines dieser Symbole verwendet werden soll und welches verwendet werden soll. Sie können dies nicht steuern. Sie müssen Bilddateien für 16, 32 und 80 Pixel bereitstellen, während fünf andere Größen ebenfalls unterstützt werden (20, 24, 40, 48 und 64 Pixel). Sie müssen SSL (Secure Sockets Layer) für alle URLs verwenden.
    "groups": [
    {
        "id": "msgReadGroup",
        "label": "Contoso Add-in",
        "icons": [
            {
                "size": 16,
                "url": "https://localhost:3000/assets/icon-16.png"
            },
            {
                "size": 32,
                "url": "https://localhost:3000/assets/icon-32.png"
            },
            {
                "size": 80,
                "url": "https://localhost:3000/assets/icon-80.png"
            }
        ],
        "controls": [
            {
                // properties omitted
            }
        ]
    }
]

  6. Stellen Sie sicher, dass im Array "Steuerelemente" für jede gewünschte Schaltfläche oder jedes benutzerdefinierte Menü ein Steuerelementobjekt vorhanden ist. Es folgt ein Beispiel. Beachten Sie Folgendes zu diesem JSON-Code:

    • Die Eigenschaften "id", "label" und "icons" haben denselben Zweck und die gleichen Einschränkungen wie die entsprechenden Eigenschaften eines Gruppenobjekts, mit der Ausnahme, dass sie für eine bestimmte Schaltfläche oder ein bestimmtes Menü innerhalb der Gruppe gelten.
    • Die Eigenschaft "type" ist auf "button" festgelegt, was bedeutet, dass das Steuerelement eine Menübandschaltfläche ist. Sie können auch einen Aufgabenbereichbefehl so konfigurieren, dass er über ein Menüelement ausgeführt wird. Weitere Informationen finden Sie unter Menü- und Menüelemente.
    • "supertip.title" (maximale Länge: 64 Zeichen) und "supertip.description" (maximale Länge: 128 Zeichen) werden angezeigt, wenn der Cursor auf die Schaltfläche oder das Menü zeigt.
    • Die "actionId" muss eine genaue Übereinstimmung mit dem "runtimes.actions.id" sein, den Sie in Konfigurieren der Laufzeit für den Aufgabenbereichsbefehl festgelegt haben.
    {
    "id": "msgReadOpenPaneButton",
    "type": "button",
    "label": "Show Task Pane",
    "icons": [
        {
            "size": 16,
            "url": "https://localhost:3000/assets/icon-16.png"
        },
        {
            "size": 32,
            "url": "https://localhost:3000/assets/icon-32.png"
        },
        {
            "size": 80,
            "url": "https://localhost:3000/assets/icon-80.png"
        }
    ],
    "supertip": {
        "title": "Show Contoso Task Pane",
        "description": "Opens the Contoso task pane."
    },
    "actionId": "ShowTaskPane"
}

Sie haben nun das Hinzufügen eines Aufgabenbereichbefehls zu Ihrem Add-In abgeschlossen. Querladen und Testen.

Hinzufügen eines Funktionsbefehls

In den folgenden Unterabschnitten wird erläutert, wie ein Funktionsbefehl in ein Add-In eingeschlossen wird.

Erstellen des Codes für den Funktionsbefehl

  1. Stellen Sie sicher, dass Ihr Quellcode eine JavaScript- oder Typescript-Datei mit der Funktion enthält, die Sie mit Ihrem Funktionsbefehl ausführen möchten. Es folgt ein Beispiel. Da es in diesem Artikel um das Erstellen von Add-In-Befehlen und nicht um das Unterrichten der Office JavaScript-Bibliothek geht, stellen wir ihnen nur minimale Kommentare zur Verfügung, beachten sie jedoch Folgendes:

    • Für die Zwecke dieses Artikels hat die Datei den Namen commands.js.
    • Die Funktion bewirkt, dass in einer geöffneten E-Mail-Nachricht eine kleine Benachrichtigung mit dem Text "Aktion ausgeführt" angezeigt wird.
    • Wie jeder Code, der APIs in der Office JavaScript-Bibliothek aufruft, muss er mit der Initialisierung der Bibliothek beginnen. Dazu wird aufgerufen Office.onReady.
    • Das letzte, was der Code aufruft, ist Office.actions.associate , um Office mitzuteilen, welche Funktion in der Datei ausgeführt werden soll, wenn die Benutzeroberfläche für Ihren Funktionsbefehl aufgerufen wird. Die Funktion ordnet den Funktionsnamen einer Aktions-ID zu, die Sie in einem späteren Schritt im Manifest konfigurieren. Wenn Sie mehrere Funktionsbefehle in derselben Datei definieren, muss Ihr Code für jede datei aufrufen associate .
    • Die Funktion muss einen Parameter vom Typ Office.AddinCommands.Event annehmen. Die letzte Zeile der Funktion muss event.completed aufrufen.
    Office.onReady(function() {
// Add any initialization code here.
});

function setNotification(event) {
const message = {
    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
    message: "Performed action.",
    icon: "Icon.80x80",
    persistent: true,
};

// Show a notification message.
Office.context.mailbox.item.notificationMessages.replaceAsync("ActionPerformanceNotification", message);

// Be sure to indicate when the add-in command function is complete.
event.completed();
}

// Map the function to the action ID in the manifest.
Office.actions.associate("SetNotification", setNotification);

  2. Stellen Sie sicher, dass Ihr Quellcode eine HTML-Datei enthält, die zum Laden der von Ihnen erstellten Funktionsdatei konfiguriert ist. Es folgt ein Beispiel. Beachten Sie Folgendes zu diesem JSON-Code:

    • Für die Zwecke dieses Artikels hat die Datei den Namen commands.html.

    • Das <body> Element ist leer, da die Datei über keine Benutzeroberfläche verfügt. Der einzige Zweck besteht darin, JavaScript-Dateien zu laden.

    • Die Office JavaScript-Bibliothek und die commands.js-Datei , die Sie im vorherigen Schritt erstellt haben, werden explizit geladen.

      Hinweis

      In der Office-Add-In-Entwicklung werden häufig Tools wie webpack und die zugehörigen Plug-Ins verwendet, um Tags zur Buildzeit automatisch in HTML-Dateien einzufügen <script> . Wenn Sie ein solches Tool verwenden, sollten Sie keine <script> Tags in Ihre Quelldatei aufnehmen, die vom Tool eingefügt werden sollen.

    <!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <meta http-equiv="X-UA-Compatible" content="IE=Edge" />

        <!-- Office JavaScript Library -->
        <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script>
        <!-- Function command file -->
        <script src="commands.js" type="text/javascript"></script>
    </head>
    <body>
    </body>
</html>

Konfigurieren der Laufzeit für den Funktionsbefehl

  1. Öffnen Sie das einheitliche Manifest, und suchen Sie das Array "extensions.runtimes".

  2. Stellen Sie sicher, dass ein Laufzeitobjekt mit der Eigenschaft "actions.type" mit dem Wert "executeFunction" vorhanden ist.

  3. Stellen Sie sicher, dass das Array "requirements.capabilities" Objekte enthält, die alle Anforderungssätze angeben, die zur Unterstützung der APIs-Add-In-Befehle erforderlich sind. Für Outlook ist die Mindestanforderung für Add-In-Befehle Mailbox 1.3. Wenn Ihr Funktionsbefehl jedoch diese API aufruft, die Teil eines späteren Postfachanforderungssatzes ist, z. B. Postfach 1.5, müssen Sie die spätere Version (z. B. "1.5") als "minVersion"-Wert angeben.

    Hinweis

    Wenn die Unterstützung für das einheitliche Manifest auf andere Office-Hostanwendungen erweitert wird, lautet die Mindestanforderung für Add-In-Befehle in diesen anderen Hosts AddinCommands 1.1.

  4. Stellen Sie sicher, dass die "id" des Laufzeitobjekts einen beschreibenden Namen wie "CommandsRuntime" aufweist.

  5. Stellen Sie sicher, dass die Eigenschaft "code.page" des Laufzeitobjekts auf die URL der HTML-Seite ohne Benutzeroberfläche festgelegt ist, die Ihre Funktionsdatei lädt, z "https://localhost:3000/commands.html". B. .

  6. Stellen Sie sicher, dass der "actions.id" des Laufzeitobjekts über einen beschreibenden Namen wie "SetNotification" verfügt, der angibt, was geschieht, wenn der Benutzer die Add-In-Befehlsschaltfläche oder das Menüelement auswählt.

    Wichtig

    Der Wert von "actions.id" muss genau mit dem ersten Parameter des Aufrufs von Office.actions.associate in der Funktionsdatei übereinstimmen.

  7. Legen Sie die anderen Eigenschaften und Untereigenschaften des Laufzeitobjekts fest, wie im folgenden abgeschlossenen Beispiel eines Laufzeitobjekts gezeigt. Die Eigenschaften "type" und "lifetime" sind erforderlich und weisen immer die Werte auf, die in Outlook-Add-Ins angezeigt werden. Dies ist der einzige Host, der derzeit das einheitliche Manifest unterstützt.

    "runtimes": [
    {
        "id": "CommandsRuntime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/commands.html"
        },
        "lifetime": "short",
        "actions": [
            {
                "id": "SetNotification",
                "type": "executeFunction",
            }
        ]
    }       
]

Konfigurieren der Benutzeroberfläche für den Funktionsbefehl

  1. Stellen Sie sicher, dass das Erweiterungsobjekt, für das Sie eine Laufzeit konfiguriert haben, über eine Arrayeigenschaft "Ribbons" als Peer zum Runtimes-Array verfügt. In der Regel gibt es nur ein Erweiterungsobjekt im Array "extensions".

  2. Stellen Sie sicher, dass das Array über ein Objekt mit den Arrayeigenschaften "contexts" und "tabs" verfügt, wie im folgenden Beispiel gezeigt.

    "ribbons": [
    {
        "contexts": [
            // child objects omitted
        ],
        "tabs": [
            // child objects omitted
        ]
    }
]

  3. Stellen Sie sicher, dass das Array "contexts" Zeichenfolgen enthält, die die Fenster oder Bereiche angeben, in denen die Benutzeroberfläche für den Funktionsbefehl angezeigt werden soll. Beispielsweise bedeutet "mailRead", dass es im Lesebereich oder Nachrichtenfenster angezeigt wird, wenn eine E-Mail-Nachricht geöffnet ist, aber "mailCompose" bedeutet, dass sie angezeigt wird, wenn eine neue Nachricht oder eine Antwort erstellt wird. Im Folgenden sind die zulässigen Werte aufgeführt:

    • mailRead
    • mailCompose
    • meetingDetailsOrganizer
    • meetingDetailsAttendee

    Es folgt ein Beispiel.

    "contexts": [
    "mailRead"
],

  4. Stellen Sie sicher, dass das Array "tabs" über ein Objekt mit einer Zeichenfolgeneigenschaft "builtInTabId" verfügt, die auf die ID der Menübandregisterkarte festgelegt ist, in der der Funktionsbefehl angezeigt werden soll, und ein Array "groups" mit mindestens einem Objekt darin. Es folgt ein Beispiel.

    "tabs": [
    {
        "builtInTabID": "TabDefault",
        "groups": [
            {
                // properties omitted
            }
        ]
    }
]

    Hinweis

    Der einzige zulässige Wert für die Eigenschaft "builtInTabID" ist "TabDefault", bei dem es sich in Outlook entweder um die Registerkarte "Start", " Nachricht" oder " Besprechung " handelt. Wenn unterstützung für das einheitliche Manifest zu anderen Office-Hostanwendungen hinzugefügt wird, gibt es weitere mögliche Werte.

  5. Stellen Sie sicher, dass das Array "groups" über ein -Objekt verfügt, um die benutzerdefinierte Steuerelementgruppe zu definieren, die ihre Add-In-Befehls-UI-Steuerelemente enthält. Es folgt ein Beispiel. Beachten Sie Folgendes zu diesem JSON-Code:

    • Die "ID" muss für alle Gruppen in allen Menübandobjekten im Manifest eindeutig sein. Die maximale Länge beträgt 64 Zeichen.
    • Die "Bezeichnung" wird in der Gruppe im Menüband angezeigt. Obwohl die maximale Länge 64 Zeichen beträgt, empfiehlt es sich, die "Bezeichnung" auf 16 Zeichen zu beschränken, um sicherzustellen, dass die Steuerelementgruppe ordnungsgemäß in das Menüband passt.
    • Eines der "Symbole" wird nur in der Gruppe angezeigt, wenn das Office-Anwendungsfenster und damit das Menüband vom Benutzer zu klein dimensioniert wurde, damit eines der Steuerelemente in der Gruppe angezeigt werden kann. Office entscheidet basierend auf der Größe des Fensters und der Auflösung des Geräts, wann eines dieser Symbole verwendet werden soll und welches verwendet werden soll. Sie können dies nicht steuern. Sie müssen Bilddateien für 16, 32 und 80 Pixel bereitstellen, während fünf andere Größen ebenfalls unterstützt werden (20, 24, 40, 48 und 64 Pixel). Sie müssen SSL (Secure Sockets Layer) für alle URLs verwenden.
    "groups": [
    {
        "id": "msgReadGroup",
        "label": "Contoso Add-in",
        "icons": [
            {
                "size": 16,
                "url": "https://localhost:3000/assets/icon-16.png"
            },
            {
                "size": 32,
                "url": "https://localhost:3000/assets/icon-32.png"
            },
            {
                "size": 80,
                "url": "https://localhost:3000/assets/icon-80.png"
            }
        ],
        "controls": [
            {
                // properties omitted
            }
        ]
    }
]

  6. Stellen Sie sicher, dass im Array "Steuerelemente" für jede gewünschte Schaltfläche oder jedes benutzerdefinierte Menü ein Steuerelementobjekt vorhanden ist. Es folgt ein Beispiel. Beachten Sie Folgendes zu diesem JSON-Code:

    • Die Eigenschaften "id", "label" und "icons" haben denselben Zweck und die gleichen Einschränkungen wie die entsprechenden Eigenschaften eines Gruppenobjekts, mit der Ausnahme, dass sie für eine bestimmte Schaltfläche oder ein bestimmtes Menü innerhalb der Gruppe gelten.
    • Die Eigenschaft "type" ist auf "button" festgelegt, was bedeutet, dass das Steuerelement eine Menübandschaltfläche ist. Sie können auch einen Funktionsbefehl so konfigurieren, dass er über ein Menüelement ausgeführt wird. Weitere Informationen finden Sie unter Menü- und Menüelemente.
    • "supertip.title" (maximale Länge: 64 Zeichen) und "supertip.description" (maximale Länge: 128 Zeichen) werden angezeigt, wenn der Cursor auf die Schaltfläche oder das Menü zeigt.
    • Die "actionId" muss eine genaue Übereinstimmung mit dem "runtime.actions.id" sein, den Sie in Konfigurieren der Laufzeit für den Funktionsbefehl festgelegt haben.
    {
    "id": "msgReadSetNotificationButton",
    "type": "button",
    "label": "Set Notification",
    "icons": [
        {
            "size": 16,
            "url": "https://localhost:3000/assets/icon-16.png"
        },
        {
            "size": 32,
            "url": "https://localhost:3000/assets/icon-32.png"
        },
        {
            "size": 80,
            "url": "https://localhost:3000/assets/icon-80.png"
        }
    ],
    "supertip": {
        "title": "Set Notification",
        "description": "Displays a notification message on the current message."
    },
    "actionId": "SetNotification"
}

Sie haben nun das Hinzufügen eines Funktionsbefehls zu Ihrem Add-In abgeschlossen. Querladen und Testen.

Zusätzlich zu benutzerdefinierten Schaltflächen können Sie dem Office-Menüband auch benutzerdefinierte Dropdownmenüs hinzufügen. In diesem Abschnitt wird anhand eines Beispiels mit zwei Menüelementen erläutert. Einer ruft einen Aufgabenbereichsbefehl auf. Die andere ruft einen Funktionsbefehl auf.

Konfigurieren der Runtimes und des Codes

Führen Sie die Schritte in den folgenden Abschnitten aus:

Konfigurieren der Benutzeroberfläche für das Menü

  1. Stellen Sie sicher, dass das Erweiterungsobjekt, für das Sie eine Laufzeit konfiguriert haben, über eine Arrayeigenschaft "Ribbons" als Peer zum Runtimes-Array verfügt. In der Regel gibt es nur ein Erweiterungsobjekt im Array "extensions".

  2. Stellen Sie sicher, dass das Array über ein Objekt mit den Arrayeigenschaften "contexts" und "tabs" verfügt, wie im folgenden Beispiel gezeigt.

    "ribbons": [
    {
        "contexts": [
            // child objects omitted
        ],
        "tabs": [
            // child objects omitted
        ]
    }
]

  3. Stellen Sie sicher, dass das Array "contexts" Zeichenfolgen enthält, die die Fenster oder Bereiche angeben, in denen das Menü auf dem Menüband angezeigt werden soll. Beispielsweise bedeutet "mailRead", dass es im Lesebereich oder Nachrichtenfenster angezeigt wird, wenn eine E-Mail-Nachricht geöffnet ist, aber "mailCompose" bedeutet, dass sie angezeigt wird, wenn eine neue Nachricht oder eine Antwort erstellt wird. Im Folgenden sind die zulässigen Werte aufgeführt:

    • mailRead
    • mailCompose
    • meetingDetailsOrganizer
    • meetingDetailsAttendee

    Es folgt ein Beispiel.

    "contexts": [
    "mailRead"
],

  4. Stellen Sie sicher, dass das Array "tabs" über ein Objekt mit einer Zeichenfolgeneigenschaft "builtInTabId" verfügt, die auf die ID der Menübandregisterkarte festgelegt ist, in der der Aufgabenbereichsbefehl angezeigt werden soll, und ein Array "groups" mit mindestens einem Objekt darin. Es folgt ein Beispiel.

    "tabs": [
    {
        "builtInTabID": "TabDefault",
        "groups": [
            {
                // properties omitted
            }
        ]
    }
]

    Hinweis

    Der einzige zulässige Wert für die Eigenschaft "builtInTabID" ist "TabDefault", bei dem es sich in Outlook entweder um die Registerkarte "Start", " Nachricht" oder " Besprechung " handelt. Wenn unterstützung für das einheitliche Manifest zu anderen Office-Hostanwendungen hinzugefügt wird, gibt es weitere mögliche Werte.

  5. Stellen Sie sicher, dass das Array "groups" über ein -Objekt verfügt, um die benutzerdefinierte Steuerelementgruppe zu definieren, die das Dropdownmenü-Steuerelement enthält. Es folgt ein Beispiel. Beachten Sie Folgendes zu diesem JSON-Code:

    • Die "ID" muss für alle Gruppen in allen Menübandobjekten im Manifest eindeutig sein. Die maximale Länge beträgt 64 Zeichen.
    • Die "Bezeichnung" wird in der Gruppe im Menüband angezeigt. Obwohl die maximale Länge 64 Zeichen beträgt, empfiehlt es sich, die "Bezeichnung" auf 16 Zeichen zu beschränken, um sicherzustellen, dass die Steuerelementgruppe ordnungsgemäß in das Menüband passt.
    • Eines der "Symbole" wird nur in der Gruppe angezeigt, wenn das Office-Anwendungsfenster und damit das Menüband vom Benutzer zu klein dimensioniert wurde, damit eines der Steuerelemente in der Gruppe angezeigt werden kann. Office entscheidet basierend auf der Größe des Fensters und der Auflösung des Geräts, wann eines dieser Symbole verwendet werden soll und welches verwendet werden soll. Sie können dies nicht steuern. Sie müssen Bilddateien für 16, 32 und 80 Pixel bereitstellen, während fünf andere Größen ebenfalls unterstützt werden (20, 24, 40, 48 und 64 Pixel). Sie müssen SSL (Secure Sockets Layer) für alle URLs verwenden.
    "groups": [
    {
        "id": "msgReadGroup",
        "label": "Contoso Add-in",
        "icons": [
            {
                "size": 16,
                "url": "https://localhost:3000/assets/icon-16.png"
            },
            {
                "size": 32,
                "url": "https://localhost:3000/assets/icon-32.png"
            },
            {
                "size": 80,
                "url": "https://localhost:3000/assets/icon-80.png"
            }
        ],
        "controls": [
            {
                // properties omitted
            }
        ]
    }
]

  6. Stellen Sie sicher, dass im Array "controls" ein Steuerelementobjekt vorhanden ist. Es folgt ein Beispiel. Beachten Sie Folgendes zu diesem JSON-Code:

    • Die Eigenschaften "id", "label" und "icons" haben denselben Zweck und die gleichen Einschränkungen wie die entsprechenden Eigenschaften eines Gruppenobjekts, mit der Ausnahme, dass sie für das Dropdownmenü innerhalb der Gruppe gelten.
    • Die Eigenschaft "type" ist auf "menu" festgelegt, was bedeutet, dass das Steuerelement ein Dropdownmenü ist.
    • Die Optionen "supertip.title" (maximale Länge: 64 Zeichen) und "supertip.description" (maximale Länge: 128 Zeichen) werden angezeigt, wenn der Cursor auf das Menü zeigt.
    • Die Eigenschaft "items" enthält den JSON-Code für die beiden Menüoptionen. Die Werte werden in späteren Schritten hinzugefügt.
    {
    "id": "msgReadMenu",
    "type": "menu",
    "label": "Contoso Menu",
    "icons": [
        {
            "size": 16,
            "url": "https://localhost:3000/assets/icon-16.png"
        },
        {
            "size": 32,
            "url": "https://localhost:3000/assets/icon-32.png"
        },
        {
            "size": 80,
            "url": "https://localhost:3000/assets/icon-80.png"
        }
    ],
    "supertip": {
        "title": "Show Contoso Actions",
        "description": "Opens the Contoso menu."
    },
    "items": [
        {
            "id": "",
            "type": "",
            "label": "",
            "supertip": {},
            "actionId": ""
        },
        {
            "id": "",
            "type": "",
            "label": "",
            "supertip": {},
            "actionId": ""
        }
    ]
}

  7. Das erste Element zeigt einen Aufgabenbereich an. Es folgt ein Beispiel. Beachten Sie Folgendes zu diesem Code:

    • Die Eigenschaften "id", "label" und "supertip" haben denselben Zweck und die gleichen Einschränkungen wie die entsprechenden Eigenschaften des übergeordneten Menüobjekts, mit der Ausnahme, dass sie nur für diese Menüoption gelten.
    • Die Eigenschaft "symbole" ist für Menüelemente optional, und in diesem Beispiel ist keines vorhanden. Wenn Sie ein Element einschließen, gelten die gleichen Zwecke und Einschränkungen wie die Eigenschaft "Symbole" des übergeordneten Menüs, mit der Ausnahme, dass das Symbol im Menüelement neben der Bezeichnung angezeigt wird.
    • Die Eigenschaft "type" ist auf "menuItem" festgelegt.
    • Die "actionId" muss eine genaue Übereinstimmung mit dem "runtimes.actions.id" sein, den Sie in Konfigurieren der Laufzeit für den Aufgabenbereichsbefehl festgelegt haben.
    {
    "id": "msgReadOpenPaneMenuItem",
    "type": "menuItem",
    "label": "Show Task Pane",
    "supertip": {
        "title": "Show Contoso Task Pane",
        "description": "Opens the Contoso task pane."
    },
    "actionId": "ShowTaskPane"
},

  8. Das zweite Element führt einen Funktionsbefehl aus. Es folgt ein Beispiel. Beachten Sie Folgendes zu diesem Code:

    {
    "id": "msgReadSetNotificationMenuItem",
    "type": "menuItem",
    "label": "Set Notification",
    "supertip": {
        "title": "Set Notification",
        "description": "Displays a notification message on the current message."
    },
    "actionId": "SetNotification"
}

Sie haben nun das Hinzufügen eines Menüs zu Ihrem Add-In abgeschlossen. Querladen und Testen.

Siehe auch