Teilen über

Angeben von Office-Anwendungen und API-Anforderungen mit dem einheitlichen Manifest

Hinweis

Informationen zum Angeben von Anforderungen mit dem reinen Add-In-Manifest finden Sie unter Angeben von Office-Hosts und API-Anforderungen mit dem reinen Add-In-Manifest.

Ihr Office-Add-In kann von einer bestimmten Office-Anwendung (auch als Office-Host bezeichnet) oder von bestimmten Mitgliedern der Office JavaScript-Bibliothek (office.js) abhängig sein. Beispielsweise kann für Ihr Add-In Folgendes gelten:

  • Es wird in einer einzelnen Office-Anwendung (z.B. Word oder Excel) oder mehreren Programmen ausgeführt.
  • Verwenden Sie Office-JavaScript-APIs, die nur in einigen Versionen von Office verfügbar sind. Beispielsweise unterstützt die volumenlizenzierte unbefristete Version von Excel 2016 nicht alle Excel-bezogenen APIs in der Office JavaScript-Bibliothek.
  • Sie sind nur für die Verwendung in einem mobilen Formfaktor konzipiert.

In diesen Situationen müssen Sie sicherstellen, dass Ihr Add-In niemals in Office-Anwendungen oder Office-Versionen installiert ist, in denen es nicht ausgeführt werden kann.

Es gibt auch Szenarien, in denen Sie steuern möchten, welche Features Ihres Add-Ins für Benutzer basierend auf ihrer Office-Anwendung und Office-Version sichtbar sind. Drei Beispiele sind:

  • Ihr Add-In verfügt über Features, die sowohl in Word als auch in PowerPoint nützlich sind, z. B. Textbearbeitung, aber es verfügt über einige zusätzliche Features, die nur in PowerPoint sinnvoll sind, z. B. Folienverwaltungsfeatures. Sie müssen die reinen PowerPoint-Features ausblenden, wenn das Add-In in Word ausgeführt wird.
  • Ihr Add-In verfügt über ein Feature, das eine Office JavaScript-API-Methode erfordert, die in einigen Versionen einer Office-Anwendung unterstützt wird, z. B. Microsoft 365-Abonnement Excel, aber in anderen nicht unterstützt wird, z. B. volumenlizenzierte unbefristete Excel 2016. Ihr Add-In verfügt jedoch über andere Features, die nur Office JavaScript-API-Methoden erfordern, die in volumenlizenzierten unbefristeten Excel 2016 unterstützt werden. In diesem Szenario muss das Add-In auf dieser Version von Excel 2016 installiert werden können, aber das Feature, das die nicht unterstützte Methode erfordert, sollte für diese Benutzer ausgeblendet werden.
  • Ihr Add-In verfügt über Features, die in Office Desktop unterstützt werden, aber nicht in mobilem Office.

In diesem Artikel erfahren Sie, wie Sie sicherstellen können, dass Ihr Add-In wie erwartet funktioniert und eine möglichst breite Zielgruppe erreicht.

Hinweis

Eine allgemeine Übersicht darüber, wo Office-Add-Ins derzeit unterstützt werden, finden Sie auf der Seite Office-Clientanwendung und Plattformverfügbarkeit für Office-Add-Ins .

Tipp

Viele der in diesem Artikel beschriebenen Aufgaben werden ganz oder teilweise für Sie ausgeführt, wenn Sie Ihr Add-In-Projekt mit einem Tool wie dem Yeoman-Generator für Office-Add-Ins oder einer der Office-Add-In-Vorlagen in Visual Studio erstellen. Interpretieren Sie in solchen Fällen die Aufgabe so, dass Sie überprüfen sollten, ob sie erledigt wurde.

Verwenden der neuesten Office JavaScript-API-Bibliothek

Ihr Add-In sollte die aktuellste Version der Office JavaScript-API-Bibliothek aus dem Content Delivery Network (CDN) laden. Stellen Sie dazu sicher, dass sie in der ersten HTML-Datei, die Ihr Add-In öffnet, über das folgende <script> Tag verfügen. Durch Verwenden von /1/ in der CDN-URL wird sichergestellt, dass Sie auf die neuste Version von Office.js verweisen.

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>

Angeben, welche Office-Anwendungen Ihr Add-In hosten können

Verwenden Sie das -Array, um die Office-Anwendungen anzugeben, auf denen "extensions.requirements.scopes" Ihr Add-In installiert werden kann. Geben Sie eine beliebige Teilmenge von "mail", "workbook", "document"und "presentation"an. Die folgende Tabelle zeigt, welche Office-Anwendungs- und Plattformkombinationen diesen Werten entsprechen. Außerdem wird gezeigt, welche Art von Add-In für jeden Bereich installiert werden kann.

Name Office-Clientanwendungen Verfügbare Add-In-Typen
Dokument Word im Web, Windows, Mac, iPad Aufgabenbereich
mail Outlook im Web, Windows (neu und klassisch), Android, iOS E-Mail
Präsentation PowerPoint im Web, Windows, Mac, iPad Aufgabenbereich, Inhalt
workbook Excel im Web, Windows, Mac, iPad Aufgabenbereich, Inhalt

Hinweis

Inhalts-Add-Ins verfügen über eine "extensions.contentRuntimes" -Eigenschaft. Sie können keine -Eigenschaft haben "extensions.runtimes" , sodass sie nicht mit einem Aufgabenbereich oder mail-Add-In kombiniert werden können. Weitere Informationen zu Inhalts-Add-Ins finden Sie unter Inhalts-Office-Add-Ins.

Der folgende JSON-Code gibt beispielsweise an, dass das Add-In in jeder Version von Excel installiert werden kann, die Excel im Web, Windows und iPad umfasst, aber nicht in einer anderen Office-Anwendung installiert werden kann.

"extensions": [
    {
        "requirements": {
            "scopes": [ "workbook" ],
        },
        ...
    }
]

Hinweis

Office-Anwendungen werden auf verschiedenen Plattformen unterstützt und auf Desktops, Webbrowsern, Tablets und mobilen Geräten ausgeführt. In der Regel können Sie nicht angeben, welche Plattform zum Ausführen Ihres Add-Ins verwendet werden kann. Wenn Sie beispielsweise angeben"workbook", können sowohl Excel im Web als auch unter Windows zum Ausführen des Add-Ins verwendet werden. Wenn Sie jedoch angeben "mail", wird Ihr Add-In nicht auf mobilen Outlook-Clients ausgeführt, es sei denn, Sie definieren den Mobilen Erweiterungspunkt.

Angeben der Office-APIs, die Ihr Add-In benötigt

Sie können nicht explizit die Office-Versionen und Builds oder die Plattformen angeben, auf denen Ihr Add-In installiert werden soll, und Sie möchten dies nicht, da Sie Ihr Manifest immer dann überarbeiten müssen, wenn die Unterstützung für die Add-In-Features, die Ihr Add-In verwendet, auf eine neue Version oder Plattform erweitert wird. Geben Sie stattdessen im Manifest die APIs an, die Ihr Add-In benötigt. Office verhindert, dass das Add-In auf Kombinationen aus Office-Version und Plattform installiert wird, die die APIs nicht unterstützen, und stellt sicher, dass das Add-In nicht in Meine Add-Ins angezeigt wird.

Wichtig

Verwenden Sie nur die "requirements" Eigenschaft, die ein direktes untergeordnetes Element von "extensions" ist, um die API-Member anzugeben, die Ihr Add-In überhaupt von einem signifikanten Wert haben muss. Wenn Ihr Add-In eine API für einige Features verwendet, aber über andere nützliche Features verfügt, für die die API nicht erforderlich ist, sollten Sie das Add-In so entwerfen, dass es auf Plattform- und Office-Versionskombinationen installiert werden kann, die die API nicht unterstützen, aber eine eingeschränkte Erfahrung für diese Kombinationen bieten. Verwenden Sie "requirements" zu diesem Zweck Eigenschaften, die keine direkten untergeordneten Elemente von "extensions"sind. Weitere Informationen finden Sie unter Entwerfen für alternative Umgebungen.

Anforderungssätze

Um die Angabe der APIs zu vereinfachen, die Ihr Add-In benötigt, gruppiert Office die meisten APIs in Anforderungssätzen. Die APIs im allgemeinen API-Objektmodell sind nach dem Entwicklungsfeature gruppiert, das sie unterstützen. Beispielsweise befinden sich alle apIs, die mit Tabellenbindungen verbunden sind, im Anforderungssatz "TableBindings 1.1". Die APIs in den anwendungsspezifischen Objektmodellen werden nach dem Zeitpunkt gruppiert, zu dem sie für die Verwendung in Produktions-Add-Ins freigegeben wurden.

Anforderungssätze werden mit Versionsverwaltung versehen. Die APIs, die Dialogfelder unterstützen, befinden sich beispielsweise im Anforderungssatz DialogApi 1.1. Wenn zusätzliche APIs veröffentlicht wurden, die Nachrichten aus einem Aufgabenbereich an einen Dialog ermöglichen, wurden sie zusammen mit allen APIs in DialogApi 1.1 in DialogApi 1.2 gruppiert. Jede Version eines Anforderungssatzes ist eine Obermenge aller früheren Versionen.

Die Unterstützung von Anforderungsmappen hängt von der Office-Anwendung, der Version der Office-Anwendung und der Plattform ab, auf der sie ausgeführt wird. ExcelApi 1.17 wird beispielsweise in volumenlizenzierten unbefristeten Versionen von Office vor Office 2024 nicht unterstützt, excelApi 1.14 wird jedoch zurück zu Office 2021 unterstützt. Sie möchten, dass Ihr Add-In auf jeder Kombination aus Plattform und Office-Version installiert werden kann, die die von ihr verwendeten APIs unterstützt. Daher sollten Sie im Manifest immer die Mindestversion jedes Anforderungssatzes angeben, den Ihr Add-In erfordert. Details dazu finden Sie weiter unten in diesem Artikel.

Tipp

Weitere Informationen zur Versionsverwaltung von Anforderungssätzen finden Sie unter Verfügbarkeit von Office-Anforderungssätzen. Die vollständigen Listen der Anforderungssätze und Informationen zu den apIs in den einzelnen ApIs finden Sie unter Office-Add-In-Anforderungssätze. In den Referenzthemen für die meisten Office.js-APIs wird auch der Anforderungssatz angegeben, zu dem sie gehören (sofern vorhanden).

extensions.requirements.capabilities-Eigenschaft

Verwenden Sie die "requirements.capabilities" -Eigenschaft, um die Mindestanforderungssätze anzugeben, die von der Office-Anwendung unterstützt werden müssen, um Ihr Add-In zu installieren. Wenn die Office-Anwendung oder -Plattform die in der "requirements.capabilities" -Eigenschaft angegebenen Anforderungssätze oder API-Member nicht unterstützt, wird das Add-In nicht in dieser Anwendung oder Plattform ausgeführt und nicht in Meine Add-Ins angezeigt.

Tipp

Alle APIs in den anwendungsspezifischen Modellen befinden sich in Anforderungssätzen, einige im allgemeinen API-Modell jedoch nicht. Wenn Ihr Add-In eine API erfordert, die in keinem Anforderungssatz enthalten ist, können Sie eine Laufzeitüberprüfung auf die Verfügbarkeit der API implementieren und den Benutzern des Add-Ins eine Meldung anzeigen, wenn diese nicht unterstützt wird. Weitere Informationen finden Sie unter Überprüfen der API-Verfügbarkeit zur Laufzeit.

Das folgende Codebeispiel zeigt, wie Sie ein Add-In konfigurieren, das in allen Office-Anwendungs- und Plattformkombinationen installiert werden kann, die Folgendes unterstützen:

  • TableBindings Anforderungssatz, der über eine Mindestversion von "1.1" verfügt.
  • OOXML Anforderungssatz, der über eine Mindestversion von "1.1" verfügt.
"extensions": [
    {
        "requirements": {
            "capabilities": [ 
                {
                    "name": "TableBindings",
                    "minVersion": "1.1"
                },
                {
                    "name": "OOXML",
                    "minVersion": "1.1"
                }
            ],
        },
        ...
    }
]

Tipp

Weitere Informationen und ein weiteres Beispiel für die Verwendung der "extensions.requirements" -Eigenschaft finden Sie im "extensions.requirements" Abschnitt Angeben von Office-Add-In-Anforderungen im einheitlichen Manifest für Microsoft 365.

Geben Sie die Formfaktoren an, auf denen Ihr Add-In installiert werden kann.

Für ein Outlook-Add-In können Sie angeben, ob das Add-In auf dem Desktop (einschließlich Tablets) oder mobilen Formfaktoren installiert werden kann. Verwenden Sie die -Eigenschaft, um dies "extensions.requirements.formFactors" zu konfigurieren. Das folgende Beispiel zeigt, wie Das Outlook-Add-In auf beiden Formfaktoren installiert werden kann.

"extensions": [
    {
        "requirements": {
            ...
            "formFactors": [
                "desktop",
                "mobile"
            ]
        },
        ...
    }
]

Entwerfen für alternative Umgebungen

Die Erweiterbarkeitsfeatures, die die Office-Add-In-Plattform bereitstellt, können nützlich in drei Arten unterteilt werden:

  • Erweiterbarkeitsfeatures, die unmittelbar nach der Installation des Add-Ins verfügbar sind. Ein Beispiel für diese Art von Feature sind Add-In-Befehle, bei denen es sich um benutzerdefinierte Menübandschaltflächen und Menüs handelt.
  • Erweiterbarkeitsfeatures, die nur verfügbar sind, wenn das Add-In ausgeführt wird und die mit Office.js JavaScript-APIs implementiert werden; Beispiel : Dialogfelder.
  • Erweiterbarkeitsfeatures, die nur zur Laufzeit verfügbar sind, aber mit einer Kombination aus Office.js JavaScript- und Manifestkonfiguration implementiert werden. Beispiele hierfür sind benutzerdefinierte Excel-Funktionen, einmaliges Anmelden und benutzerdefinierte Kontextregisterkarten.

Wenn Ihr Add-In für einen Teil der Funktionen ein bestimmtes Erweiterbarkeitsfeature verwendet, aber über andere nützliche Funktionen verfügt, für die das Erweiterbarkeitsfeature nicht erforderlich ist, sollten Sie das Add-In so entwerfen, dass es auf Plattform- und Office-Versionskombinationen installiert werden kann, die das Erweiterbarkeitsfeature nicht unterstützen. Es kann eine wertvolle, wenn auch verringerte Erfahrung mit diesen Kombinationen bieten.

Sie implementieren diesen Entwurf unterschiedlich, je nachdem, wie das Erweiterbarkeitsfeature implementiert wird:

Siehe auch

  • Last updated on