Angeben von Office-Anwendungen und Anforderungssätzen

  • Artikel

Ihr Office-Add-In kann von einer bestimmten Office-Anwendung (auch als Office-Host bezeichnet) oder von bestimmten Mitgliedern der Office JavaScript-API (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.

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. Zwei 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.

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.

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

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

Um sicherzustellen, dass Ihr Add-In in einer Teilmenge von Office-Anwendungen installiert werden kann, verwenden Sie die Elemente Hosts und Host im Manifest.

Die folgende <Host>- und <Hostdeklaration> 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.

<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 separates <Host-Element> vorhanden sein. Das Name Attribut ist erforderlich und kann auf einen der folgenden Werte festgelegt werden.

Name Office-Clientanwendungen Verfügbare Add-In-Typen
Dokument Word im Web, Windows, Mac, iPad Aufgabenbereich
Postfach Outlook im Web, Windows (klassisch und neu (Vorschau)), Mac, Android, iOS E-Mail
Notizbuch OneNote im Web Aufgabenbereich, Inhalt
Präsentation PowerPoint im Web, Windows, Mac, iPad Aufgabenbereich, Inhalt
Project Project unter Windows Aufgabenbereich
Arbeitsmappe Excel im Web, Windows, Mac, iPad Aufgabenbereich, Inhalt
Datenbank Zugriff (veraltet) Aufgabenbereich

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 angebenWorkbook, können sowohl Excel im Web als auch unter Windows zum Ausführen des Add-Ins verwendet werden. Wenn Sie jedoch angeben Mailbox, wird Ihr Add-In nicht auf mobilen Outlook-Clients ausgeführt, es sei denn, Sie definieren den Mobilen Erweiterungspunkt.

Hinweis

Es ist nicht möglich, dass ein Add-In-Manifest auf mehrere Typen angewendet wird: E-Mail, Aufgabenbereich oder Inhalt. Dies bedeutet, dass Sie zwei Add-Ins erstellen müssen, eines mit einem Mail-Typmanifest und das andere mit einem Aufgabenbereich oder Inhaltstypmanifest, wenn Ihr Add-In in Outlook und in einer der anderen Office-Anwendungen installiert werden kann.

Angeben, welche Office-Versionen und Plattformen Ihr Add-In hosten können

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 das Basismanifest, 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. 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. DialogApi 1.2 wird beispielsweise in volumenlizenzierten unbefristeten Versionen von Office vor Office 2021 nicht unterstützt, aber DialogApi 1.1 wird in allen unbefristeten Versionen zurück zu Office 2016 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).

Hinweis

Einigen Anforderungssätzen sind auch Manifestelemente zugeordnet. Informationen dazu, wann diese Tatsache für Ihr Add-In-Design relevant ist, finden Sie unter Angeben von Anforderungen in einem VersionOverrides-Element .

APIs, die nicht in einem Anforderungssatz enthalten sind

Alle APIs in den anwendungsspezifischen Modellen befinden sich in Anforderungssätzen, einige im allgemeinen API-Modell jedoch nicht. Es gibt auch eine Möglichkeit, eine dieser setless-APIs im Manifest anzugeben, wenn ihr Add-In eine solche erfordert. Details erhalten Sie weiter unten in diesem Artikel.

Requirements-Element

Verwenden Sie das Requirements-Element und seine untergeordneten Elemente Sets und Methoden , um die Mindestanforderungssätze oder API-Member anzugeben, die von der Office-Anwendung unterstützt werden müssen, um Ihr Add-In zu installieren.

Wenn die Office-Anwendung oder -Plattform die im <Requirements-Element> angegebenen Anforderungssätze oder API-Member nicht unterstützt, wird das Add-In in dieser Anwendung oder Plattform nicht ausgeführt und nicht in Meine Add-Ins angezeigt.

Hinweis

Das <Requirements-Element> ist für alle Add-Ins mit Ausnahme von Outlook-Add-Ins optional. Wenn das xsi:type Attribut des Stammelements OfficeApp ist MailApp, muss ein <Requirements-Element> vorhanden sein, das die Mindestversion des Postfachanforderungssatzes angibt, den das Add-In benötigt. Weitere Informationen finden Sie unter Outlook JavaScript-API-Anforderungssätze.

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 über eine Mindestversion von "1.1" verfügt.
  • OOXML Anforderungssatz, der über eine Mindestversion von "1.1" verfügt.
  • Document.getSelectedDataAsync Methode.
<OfficeApp ... >
  ...
  <Requirements>
     <Sets DefaultMinVersion="1.1">
        <Set Name="TableBindings" MinVersion="1.1"/>
        <Set Name="OOXML" MinVersion="1.1"/>
     </Sets>
     <Methods>
        <Method Name="Document.getSelectedDataAsync"/>
     </Methods>
  </Requirements>
    ...
</OfficeApp>

Beachten Sie Folgendes zu diesem Beispiel.

  • Das <Requirements-Element> enthält die <untergeordneten Elemente Sets> und <Methods> .
  • 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 Anforderungssatzes an. Gibt MinVersion die Mindestversion des Anforderungssatzes an. MinVersion überschreibt den Wert des DefaultMinVersion Attributs in den übergeordneten <Sets>.
  • 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 installiert werden kann. Das Name -Attribut ist erforderlich und gibt den Namen der Methode an, die mit dem übergeordneten Objekt qualifiziert ist.

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. 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 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 Konfiguration in einem <VersionOverrides-Element> 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:

Laufzeitüberprüfungen für Methoden- und Anforderungssatzunterstützung

Sie testen zur Laufzeit, um zu ermitteln, ob das Office des Benutzers einen Anforderungssatz mit der isSetSupported-Methode unterstützt. Übergeben Sie den Namen des Anforderungssatzes und die Mindestversion als Parameter. Wenn der Anforderungssatz unterstützt wird, isSetSupported gibt zurück true. Im folgenden Code ist ein Beispiel dargestellt:

if (Office.context.requirements.isSetSupported('WordApi', '1.2'))
{
   // Code that uses API members from the WordApi 1.2 requirement set.
} else {
   // Provide diminished experience here. E.g., run alternate code when the user's Word is volume-licensed perpetual Word 2016 (which doesn't support WordApi 1.2).
}

Bei diesem Code ist Folgendes zu beachten:

  • Der erste Parameter ist erforderlich. Es handelt sich um eine Zeichenfolge, die den Namen des Anforderungssatzes darstellt. Weitere Informationen zu verfügbaren Anforderungssätzen finden Sie unter Office-Add-In-Anforderungssätze.
  • Der zweite Parameter ist optional. Dabei handelt es sich um eine Zeichenfolge, die die Mindestversion des Anforderungssatzes angibt, die die Office-Anwendung unterstützen muss, damit der Code in der if Anweisung ausgeführt werden kann (z. B. "1.9"). Wenn sie nicht verwendet wird, wird version "1.1" angenommen.

Warnung

Beim Aufrufen der isSetSupported -Methode sollte der Wert des zweiten Parameters (sofern angegeben) eine Zeichenfolge und keine Zahl sein. Der JavaScript-Parser kann nicht zwischen numerischen Werten wie 1.1 und 1.10 unterscheiden, während er für Zeichenfolgenwerte wie "1.1" und "1.10" geeignet ist.

Die folgende Tabelle zeigt die Namen der Anforderungssätze für die anwendungsspezifischen API-Modelle.

Office-Anwendung RequirementSetName
Excel ExcelApi
OneNote OneNoteApi
Outlook Postfach
PowerPoint PowerPointApi
Word WordApi

Im Folgenden finden Sie ein Beispiel für die Verwendung der -Methode mit einem der Allgemeinen API-Modellanforderungssätze.

if (Office.context.requirements.isSetSupported('CustomXmlParts'))
{
    // Run code that uses API members from the CustomXmlParts requirement set.
}
else
{
    // Run alternate code when the user's Office application doesn't support the CustomXmlParts requirement set.
}

Hinweis

Die isSetSupported -Methode und die Anforderungssätze für diese Anwendungen sind in der neuesten Office.js-Datei im CDN verfügbar. Wenn Sie keine Office.js aus dem CDN verwenden, generiert Ihr Add-In möglicherweise Ausnahmen, wenn Sie eine alte Version der Bibliothek verwenden, isSetSupported in der nicht definiert ist. Weitere Informationen finden Sie unter Verwenden der neuesten Office JavaScript-API-Bibliothek.

Wenn Ihr Add-In von einer Methode abhängt, die nicht Teil eines Anforderungssatzes ist, verwenden Sie die Laufzeitüberprüfung, um zu bestimmen, ob die Methode von der Office-Anwendung unterstützt wird, wie im folgenden Codebeispiel gezeigt. Eine vollständige Liste von Methoden, die nicht zum Anforderungssatz gehören, finden Sie unter Office-Add-In-Anforderungssätze.

Hinweis

Es wird empfohlen, die Verwendung dieser Art von Laufzeitüberprüfungen im Code Ihres Add-In einzuschränken.

Im folgenden Codebeispiel wird überprüft, ob die Office-Anwendung unterstützt document.setSelectedDataAsync.

if (Office.context.document.setSelectedDataAsync)
{
    // Run code that uses `document.setSelectedDataAsync`.
}

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 diese Features kennen, wenn es das Add-In-Manifest analysiert.

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

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

Informationen zu den untergeordneten Elementen des <Requirements-Elements> finden Sie weiter oben in diesem Artikel unter Requirements-Element .

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>

Warnung

Seien Sie vorsichtig, bevor Sie ein <Requirements-Element> in eine <VersionOverrides-Instanz> einschließen, da bei Plattform- und Versionskombinationen, die die Anforderung nicht unterstützen, keine Add-In-Befehle installiert werden, selbst solche, die Funktionen aufrufen, die die Anforderung nicht benötigen. Betrachten Sie beispielsweise ein Add-In mit zwei benutzerdefinierten Menübandschaltflächen. Eine davon ruft Office-JavaScript-APIs auf, die in Anforderungssatz ExcelApi 1.4 (und höher) verfügbar sind. Die andere ruft APIs auf, die nur in ExcelApi 1.9 (und höher) verfügbar sind. Wenn Sie eine Anforderung für ExcelApi 1.9 in VersionOverrides<> angeben, wird keine Schaltfläche im Menüband angezeigt, wenn 1.9 nicht unterstützt wird. Eine bessere Strategie in diesem Szenario wäre die Verwendung der unter Laufzeitüberprüfungen beschriebenen Technik für die Unterstützung von Methoden und Anforderungsmappen. Der Code, der von der zweiten Schaltfläche aufgerufen wird, verwendet isSetSupported zuerst, um die Unterstützung von ExcelApi 1.9 zu überprüfen. Wenn dies nicht unterstützt wird, gibt der Code dem Benutzer eine Meldung, dass dieses Feature des Add-Ins in seiner Office-Version nicht verfügbar ist.

Tipp

Es macht keinen Sinn, ein Requirement-Element in einer <VersionOverrides> zu wiederholen, das bereits im Basismanifest angezeigt wird. Wenn die Anforderung im Basismanifest angegeben ist, kann das Add-In nicht installiert werden, wenn die Anforderung nicht unterstützt wird, sodass Office nicht einmal das <VersionOverrides-Element> analysiert.

Siehe auch