Angeben von Office-Anwendungen und API-Anforderungen mit dem Nur-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:

• Führen Sie die Ausführung in einer einzelnen Office-Anwendung (z. B. Word oder Excel) oder in mehreren Anwendungen aus.
• Nutzen Sie Office JavaScript-APIs, die nur in einigen Versionen von Office verfügbar sind. Beispielsweise unterstützt die unbefristete Volumenlizenzversion von Excel 2016 nicht alle Excel-bezogenen APIs in der Office JavaScript-Bibliothek.

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

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

• Ihr Add-In verfügt über Features, die sowohl in Word als auch in PowerPoint nützlich sind, wie z. B. Textbearbeitung, aber es verfügt auch über einige zusätzliche Features, die nur in PowerPoint sinnvoll sind, z. B. Features für die Folienverwaltung. Sie müssen die nur PowerPoint-Funktionen 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. in Excel mit Microsoft 365-Abonnement, aber in anderen, z. B. dem unbefristeten Excel 2016 mit Volumenlizenz, nicht unterstützt wird. Ihr Add-In verfügt jedoch über andere Features, für die nur Office JavaScript-API-Methoden erforderlich sind, die im unbefristeten Excel 2016 mit Volumenlizenz unterstützt werden . In diesem Szenario muss das Add-In unter dieser Version von Excel 2016 installierbar sein, aber das Feature, das die nicht unterstützte Methode erfordert, sollte für diese Benutzer ausgeblendet werden.

Dieser Artikel hilft Ihnen, zu verstehen, welche Optionen Sie verwenden sollten, um sicherzustellen, dass Ihr Add-In wie erwartet funktioniert und die größtmögliche Benutzergruppe erreicht.

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 hierzu sicher, dass die erste HTML-Datei, die Ihr Add-In öffnet, das folgende <script> Tag enthält. Durch Verwenden von /1/ in der CDN-URL wird sichergestellt, dass Sie auf die neuste Version von Office.js verweisen.

<script src="https://officeapis.public.onecdn.static.microsoft/1/office.js" type="text/javascript"></script>

Geben Sie an, welche Office-Anwendungen das Add-In hosten können

Standardmäßig kann ein Add-In in allen Office-Anwendungen installiert werden, die vom angegebenen Add-In-Typ unterstützt werden (d. h. E-Mail, Aufgabenbereich oder Inhalt). So kann beispielsweise ein Aufgabenbereich-Add-In standardmäßig in Access, Excel, OneNote, PowerPoint, Project und Word installiert werden.

Um sicherzustellen, dass Ihr Add-In nur in einer Teilmenge der Office-Anwendungen installierbar ist, verwenden Sie die Elemente "Hosts " und "Host " im Nur-Add-In-Manifest.

Die folgende <Hosts> und-Deklaration <Host> gibt beispielsweise an, dass das Add-In unter jeder Version von Excel installiert werden kann, einschließlich Excel im Web, Windows und iPad, aber nicht in einer anderen Office-Anwendung.

<Hosts>
  <Host Name="Workbook" />
</Hosts>

Das <Hosts> Element kann ein oder mehrere <Host> Elemente enthalten. Für jede Office-Anwendung, auf der das Add-In installiert werden kann, sollte ein eigenes <Host> Element vorhanden sein. Das Name Attribut ist erforderlich und kann auf einen der folgenden Werte festgelegt werden.

Geben Sie an, welche Office-Versionen und Plattformen das Add-In hosten können

Sie können die Office-Versionen und -Builds oder die Plattformen, auf denen das Add-In installiert werden soll, nicht explizit angeben. Das wird auch nicht gewünscht, weil Sie das Anwendungsmanifest immer dann überarbeiten müssten, wenn die Unterstützung für die von Ihrem Add-In verwendeten Add-In-Features 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, welche die APIs nicht unterstützen, und stellt sicher, dass das Add-In nicht unter "Meine Add-Ins" angezeigt wird.

Anforderungssätze

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

Anforderungssätze sind versioniert. Beispielsweise befinden sich die APIs, die Dialogfelder unterstützen, im Anforderungssatz DialogApi 1.1. Als zusätzliche APIs freigegeben wurden, die das Versenden von Nachrichten aus einem Aufgabenbereich an ein Dialogfeld 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 für Anforderungssätze variiert je nach Office-Anwendung, Version der Office-Anwendung und Plattform, auf der sie ausgeführt wird. Beispielsweise wird ExcelApi 1.17 in unbefristeten volumenlizenzierten Versionen von Office vor Office 2024 nicht unterstützt, aber ExcelApi 1.14 wird bis 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 ihm verwendeten APIs unterstützt. Deshalb sollten Sie im Manifest immer die Mindestversion jedes Anforderungssatzes angeben, die Ihr Add-In benötigt. Details dazu finden Sie weiter unten in diesem Artikel.

Requirements-Element

Verwenden Sie das Anforderungselement und dessen untergeordnete Elementsätze , um die Mindestanforderungssätze anzugeben, die von der Office-Anwendung unterstützt werden müssen, um Ihr Add-In zu installieren.

Alle APIs in den anwendungsspezifischen Modellen befinden sich in Anforderungssätzen, einige im allgemeinen API-Modell jedoch nicht. Verwenden Sie die Methoden , um die satzlosen API-Member anzugeben, die Ihr Add-In benötigt. Sie können das <Methods> Element nicht mit Outlook-Add-Ins verwenden.

Wenn die Office-Anwendung oder -Plattform die im <Requirements> Element 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.

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

• TableBindings Anforderungssatz, der eine Mindestversion von "1.1" aufweist.
• OoxmlCoercion Anforderungssatz, der eine Mindestversion von "1.1" aufweist.
• Document.getSelectedDataAsync Methode verwenden.

<OfficeApp ... >
  ...
  <Requirements>
     <Sets DefaultMinVersion="1.1">
        <Set Name="TableBindings" MinVersion="1.1"/>
        <Set Name="OoxmlCoercion" MinVersion="1.1"/>
     </Sets>
     <Methods>
        <Method Name="Document.getSelectedDataAsync"/>
     </Methods>
  </Requirements>
    ...
</OfficeApp>

Beachten Sie bei diesem Beispiel Folgendes.

• Das <Requirements> Element enthält die untergeordneten <Sets><Methods> and-Elemente.
• Das <Sets> Element kann ein oder mehrere <Set> Elemente enthalten. DefaultMinVersion Gibt den Standardwert MinVersion aller untergeordneten <Set> Elemente an.
• Ein Set-Element gibt einen Anforderungssatz an, den die Office-Anwendung unterstützen muss, damit das Add-In installiert werden kann. Das Name Attribut gibt den Namen des Anforderungssets an. Gibt MinVersion die Mindestversion des Anforderungssatzes an. MinVersion Überschreibt den Wert des Attributs DefaultMinVersion im übergeordneten <Sets>Element .
• Das <Methods> Element kann ein oder mehrere Method-Elemente enthalten. Sie können das <Methods> Element nicht mit Outlook-Add-Ins verwenden.
• Das <Method> Element gibt eine einzelne Methode an, die die Office-Anwendung unterstützen muss, damit das Add-In installierbar ist. Das Name Attribut ist erforderlich und gibt den Namen der Methode an, die mit ihrem übergeordneten Objekt qualifiziert ist.

Entwerfen für alternative Umgebungen

Die Erweiterungsfeatures, die die Office-Add-In-Plattform bereitstellt, können sinnvollerweise in drei Arten unterteilt werden:

• Erweiterbarkeitsfeatures, die unmittelbar nach der Installation des Add-Ins verfügbar sind. Sie können diese Art von Feature verwenden, indem Sie ein VersionOverrides-Element im Manifest konfigurieren. Ein Beispiel für diese Art von Feature sind Add-In-Befehle, bei denen es sich um benutzerdefinierte Schaltflächen und Menüs im Menüband handelt.
• Erweiterbarkeitsfeatures, die nur verfügbar sind, wenn das Add-In ausgeführt wird, und die mit Office.js JavaScript-APIs implementiert werden; z. B. Dialogfelder.
• Erweiterbarkeitsfeatures, die nur zur Laufzeit verfügbar sind, aber mit einer Kombination aus Office.js JavaScript und Konfiguration in einem <VersionOverrides> Element implementiert werden. Beispiele hierfür sind benutzerdefinierte Excel-Funktionen, einmaliges Anmelden und benutzerdefinierte Kontextregisterkarten.

Wenn Ihr Add-In ein bestimmtes Erweiterungsfeature für einen Teil seiner Funktionalität verwendet, aber über andere nützliche Funktionen verfügt, die das Erweiterungsfeature nicht erfordern, sollten Sie das Add-In so entwerfen, dass es auf Kombinationen aus Plattform und Office-Versionen installiert werden kann, die das Erweiterungsfeature nicht unterstützen. Es kann eine wertvolle, wenn auch verminderte Erfahrung mit diesen Kombinationen bieten.

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

• Für Features, die vollständig mit JavaScript implementiert sind, siehe Überprüfen der API-Verfügbarkeit zur Laufzeit.
• Informationen zu Funktionen, bei denen Sie ein <VersionOverrides> Element konfigurieren müssen, finden Sie unter Festlegen von Anforderungen in einem VersionOverrides-Element.

Angeben von Anforderungen in einem VersionOverrides-Element

Das VersionOverrides-Element wurde dem Manifestschema hauptsächlich, aber nicht ausschließlich, hinzugefügt, um Features zu unterstützen, die unmittelbar nach der Installation eines Add-Ins verfügbar sein müssen, z. B. Add-In-Befehle (benutzerdefinierte Menübandschaltflächen und Menüs). Office muss über diese Features Bescheid wissen, wenn das Add-In-Manifest analysiert wird.

Angenommen, Ihr Add-In verwendet eines dieser Features, das Add-In ist jedoch wertvoll und sollte auch unter Office-Versionen installiert werden können, die das Feature nicht unterstützen. Identifizieren Sie in diesem Szenario das Feature mithilfe eines Requirements-Elements (und seiner untergeordneten Sets - und Methods-Elemente ), das Sie als untergeordnetes <VersionOverrides> Element des Elements selbst und nicht als untergeordnetes Element des Basiselements OfficeApp einschließen. Dies hat zur Folge, dass Office die Installation des Add-Ins zulässt, aber bestimmte untergeordnete Elemente des <VersionOverrides> Elements in Office-Versionen ignoriert, in denen das Feature nicht unterstützt wird.

Insbesondere werden die untergeordneten Elemente des <VersionOverrides> Elemente, die Elemente im Basismanifest überschreiben, wie z. B. ein <Hosts> Element, ignoriert und stattdessen die entsprechenden Elemente des Basismanifests verwendet. Es kann jedoch untergeordnete Elemente in einem <VersionOverrides> geben, die tatsächlich zusätzliche Features implementieren, anstatt Einstellungen im Basismanifest zu überschreiben. Zwei Beispiele sind die WebApplicationInfo und EquivalentAddins. Diese Teile <VersionOverrides> werden nicht ignoriert, vorausgesetzt, die Plattform und Version von Office unterstützen das entsprechende Feature.

Informationen zu den nachgeordneten Elementen des <Requirements> Elements finden Sie weiter oben in diesem Artikel unter Anforderungselement .

Es folgt ein Beispiel.

<VersionOverrides ... >
   ...
   <Requirements>
      <Sets DefaultMinVersion="1.1">
         <Set Name="WordApi" MinVersion="1.2"/>
      </Sets>
   </Requirements>
   <Hosts>

      <!-- ALL MARKUP INSIDE THE HOSTS ELEMENT IS IGNORED WHEREVER WordApi 1.2 IS NOT SUPPORTED -->

      <Host xsi:type="Workbook">
         <!-- markup for custom add-in commands -->
      </Host>
   </Hosts>
</VersionOverrides>

Siehe auch

• Manifest für Office-Add-Ins
• Office-Add-In-Anforderungssätze
• Office-Add-In-Beispiele