Angeben von Office-Hosts und API-AnforderungenSpecify Office hosts and API requirements

Für eine erwartete Funktionsweise hängt Ihr Office-Add-In möglicherweise von einem bestimmten Office-Host, einem Anforderungssatz, einem API-Element oder einer Version der API ab. Beispielsweise kann für Ihr Add-In Folgendes gelten:Your Office Add-in might depend on a specific Office host, a requirement set, an API member, or a version of the API in order to work as expected. For example, your add-in might:

  • Es wird in einer einzelnen Office-Anwendung (Word oder Excel) oder mehreren Programmen ausgeführt.Run in a single Office application (Word or Excel), or several applications.

  • Es verwendet JavaScript-APIs, die nur in einigen Versionen von Office verfügbar sind. Möglicherweise verwenden Sie die Excel JavaScript-APIs in einem Add-In, das in Excel 2016 ausgeführt wird.Make use of JavaScript APIs that are only available in some versions of Office. For example, you might use the Excel JavaScript APIs in an add-in that runs in Excel 2016.

  • Es wird nur in Office-Versionen ausgeführt, die die von Ihrem Add-In verwendeten API-Member unterstützen.Run only in versions of Office that support API members that your add-in uses.

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.This article helps you understand which options you should choose to ensure that your add-in works as expected and reaches the broadest audience possible.

Hinweis

Eine allgemeine Übersicht darüber, wo Office-Add-Ins derzeit unterstützt werden, finden Sie auf der Seite Host -und Plattformverfügbarkeit für Office-Add-Ins.For a high-level view of where Office Add-ins are currently supported, see the Office Add-in host and platform availability page.

In der folgenden Tabelle sind die Kernkonzepte aufgeführt, die in diesem Artikel dargestellt werden.The following table lists core concepts discussed throughout this article.

KonzeptConcept BeschreibungDescription
Office-Anwendung, Office-Hostanwendung, Office-Host oder HostOffice application, Office host application, Office host, or host Die Office-Anwendung, die zum Ausführen Ihres Add-Ins verwendet wird, z. B. Word, Word Online, Excel usw.The Office application used to run your add-in. For example, Word, Word Online, Excel, and so on.
PlattformPlatform Die Plattform, auf der der Office-Host ausgeführt wird, z. B. Office Online oder Office für iPadWhere the Office host runs, such as Office Online or Office for iPad.
AnforderungssatzRequirement set Eine benannte Gruppe verwandter API-Member. Add-Ins verwenden Anforderungssätze, um festzustellen, ob der Office-Host die von Ihrem Add-In verwendeten API-Member unterstützt. Es ist einfacher, die Unterstützung für einen Anforderungssatz zu testen, als die Unterstützung für die einzelnen API-Elemente. Die Anforderungssatzunterstützung variiert je nach Office-Host und Version des Office-Hosts. A named group of related API members. Add-ins use requirement sets to determine whether the Office host supports API members used by your add-in. It's easier to test for the support of a requirement set than for the support of individual API members. Requirement set support varies by Office host and the version of the Office host.
Die Anforderungssätze sind in der Manifestdatei angegeben.Requirement sets are specified in the manifest file. Wenn Anforderungssätze im Manifest angegeben sind, legen Sie die minimale Stufe der API-Unterstützung fest, die der Office-Host bereitstellen muss, damit das Add-In ausgeführt wird. When you specify requirement sets in the manifest, you set the minimum level of API support that the Office host must provide in order to run your add-in. Office-Hosts, die die im Manifest angegebenen Anforderungssätze nicht unterstützen, können das Add-In nicht ausführen, und dieses wird nicht unter Meine Add-Ins angezeigt. Dadurch wird eingeschränkt, wo Ihr Add-In verfügbar ist. Im Code mithilfe der Laufzeitüberprüfung.Office hosts that don't support requirement sets specified in the manifest can't run your add-in, and your add-in won't display in My Add-ins. This restricts where your add-in is available.In code using runtime checks. Eine vollständige Liste der Anforderungssätze finden Sie unter Office-Add-In-Anforderungssätze.For the complete list of requirement sets, see Office Add-in requirement sets.
LaufzeitüberprüfungRuntime check Ein Test, der zur Laufzeit durchgeführt wird, um zu bestimmen, ob der Office-Host, auf dem Ihr Add-In ausgeführt wird, die von Ihrem Add-In verwendeten Anforderungssätze oder Methoden unterstützt. Zum Durchführen einer Laufzeitprüfung verwenden Sie eine if-Anweisung mit der Methode isSetSupported, den Anforderungssätzen oder den Methodennamen, die nicht Teil eines Anforderungssatzes sind.Mithilfe der Laufzeitüberprüfung wird sichergestellt, dass das Add-In die größte Anzahl von Kunden erreicht. Im Gegensatz zu Anforderungssätzen geben Laufzeitüberprüfungen nicht die minimale Stufe der API-Unterstützung an, die der Office-Host bereitstellen muss, damit Ihr Add-In ausgeführt wird. Verwenden Sie stattdessen die if-Anweisung, um zu überprüfen, ob ein API-Element unterstützt wird, und wenn dies der Fall, können Sie zusätzliche Funktionen in Ihrem Add-In bereitstellen. Ihr Add-In wird immer unter Meine-Add-Ins bei der Verwendung der Laufzeitüberprüfung angezeigt.A test that is performed at runtime to determine whether the Office host running your add-in supports requirement sets or methods used by your add-in. To perform a runtime check, you use an if statement with the isSetSupported method, the requirement sets, or the method names that aren't part of a requirement set.Use runtime checks to ensure that your add-in reaches the broadest number of customers. Unlike requirement sets, runtime checks don't specify the minimum level of API support that the Office host must provide for your add-in to run. Instead, you use the if statement to determine whether an API member is supported. If it is, you can provide additional functionality in your add-in. Your add-in will always display in My Add-ins when you use runtime checks.

Bevor Sie beginnenBefore you begin

Ihr Add-In muss die neuste Version des Add-In-Manifestschemas verwenden. Wenn Sie Laufzeitüberprüfungen in Ihrem Add-In verwenden, müssen Sie sicherstellen, dass Sie die neueste JavaScript-API für die Office-Bibliothek (office.js) verwenden.Your add-in must use the most current version of the add-in manifest schema. If you use runtime checks in your add-in, ensure that you use the latest JavaScript API for Office (office.js) library.

Angeben des neuesten Add-In-ManifestschemasSpecify the latest add-in manifest schema

Das Manifest des Add-Ins muss Version 1.1 des Add-In-Manifestschemas verwenden. Legen Sie das OfficeAppElement im Manifest Ihres Add-Ins wie folgt fest.Your add-in's manifest must use version 1.1 of the add-in manifest schema. Set the OfficeApp element in your add-in manifest as follows.

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:type="TaskPaneApp">

Angeben der neuesten Bibliothek der JavaScript-API für OfficeSpecify the latest JavaScript API for Office library

Verweisen Sie bei der Verwendung von Laufzeitüberprüfungen auf die neueste Version der Bibliothek der JavaScript-API für Office aus dem CDN (Content Delivery Network) verweisen. Fügen Sie dazu das folgende script-Tag zu Ihrem HTML-Code hinzu. Durch Verwenden von /1/ in der CDN-URL wird sichergestellt, dass Sie auf die neuste Version von Office.js verweisen.If you use runtime checks, reference the most current version of the JavaScript API for Office library from the content delivery network (CDN). To do this, add the following script tag to your HTML. Using /1/ in the CDN URL ensures that you reference the most recent version of Office.js.

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

Optionen zum Angeben von Office-Hosts oder API-AnforderungenOptions to specify Office hosts or API requirements

Bei der Angabe von Office-Hosts oder API-Anforderungen sind mehrere Faktoren zu berücksichtigen. Das folgende Diagramm zeigt, wie Sie entscheiden, welches Verfahren in Ihrem Add-In zu verwenden ist.When you specify Office hosts or API requirements, there are several factors to consider. The following diagram shows how to decide which technique to use in your add-in.

Wählen Sie die beste Option für Ihr Add-In aus, wenn Sie Office-Hosts oder API-Anforderungen angeben

  • Wenn das Add-In in einem Office-Host ausgeführt wird, legen Sie das Hosts-Element im Manifest fest. Weitere Informationen finden Sie unter Festlegen des Hosts-Elements.If your add-in runs in one Office host, set the Hosts element in the manifest. For more information, see Set the Hosts element.

  • Um den minimalen Anforderungssatz oder die API-Elemente festzulegen, die ein Office-Host zum Ausführen des Add-Ins unterstützen muss, müssen Sie das Element Requirements im Manifest festlegen. Weitere Informationen finden Sie unter Festlegen des Requirements-Elements im Manifest.To set the minimum requirement set or API members that an Office host must support to run your add-in, set the Requirements element in the manifest. For more information, see Set the Requirements element in the manifest.

  • Wenn Sie zusätzliche Funktionen bereitstellen möchten, wenn bestimmte Anforderungssätze oder API-Elemente im Office-Host verfügbar sind, müssen Sie eine Laufzeitüberprüfung im JavaScript-Code Ihres Add-Ins durchführen. Wenn das Add-In z. B. in Excel 2016 ausgeführt wird, verwenden Sie API-Elemente aus der neuen JavaScript-API für Excel, um zusätzliche Funktionen bereitzustellen. Weitere Informationen finden Sie unter Verwenden von Laufzeitüberprüfungen im JavaScript-Code.If you would like to provide additional functionality if specific requirement sets or API members are available in the Office host, perform a runtime check in your add-in's JavaScript code. For example, if your add-in runs in Excel 2016, use API members from the new JavaScript API for Excel to provide additional functionality. For more information, see Use runtime checks in your JavaScript code.

Festlegen des Hosts-ElementsSet the Hosts element

Verwenden Sie zum Ausführen des Add-Ins in einer Office-Hostanwendung die Elemente Hosts und Host im Manifest. Wenn Sie das Element Hosts nicht angeben, wird Ihr Add-In in allen Hosts ausgeführt.To make your add-in run in one Office host application, use the Hosts and Host elements in the manifest. If you don't specify the Hosts element, your add-in will run in all hosts.

Beispielsweise gibt die folgende Hosts- und Host-Deklaration an, dass das Add-In mit einer beliebigen Version von Excel arbeitet, einschließlich Excel für Windows, Excel Online und Excel für iPad.For example, the following Hosts and Host declaration specifies that the add-in will work with any release of Excel, which includes Excel for Windows, Excel Online, and Excel for iPad.

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

Das Element Hosts kann ein oder mehrere Host-Elemente enthalten. Das Element Host gibt den Office-Host an, der für Ihr Add-In erforderlich ist. Das Attribut Name ist erforderlich und kann auf einen der folgenden Werte festgelegt werden.The Hosts element can contain one or more Host elements. The Host element specifies the Office host your add-in requires. The Name attribute is required and can be set to one of the following values.

NameName Office-HostanwendungenOffice host applications
DatenbankDatabase Access Web AppsAccess web apps
DokumentDocument Word unter Windows, Word für Mac, Word für iPad, Word OnlineWord on Windows, word for Mac, Word for iPad, and Word Online
PostfachMailbox Outlook unter Windows, Outlook für Mac, Outlook im Web und Outlook.comOutlook on Windows, Outlook for Mac, Outlook on the web, and Outlook.com
PräsentationPresentation PowerPoint unter Windows, PowerPoint für Mac, PowerPoint für iPad und PowerPoint OnlinePowerPoint on Windows, PowerPoint for Mac, PowerPoint for iPad, and PowerPoint Online
ProjektProject ProjectProject
ArbeitsmappeWorkbook Excel unter Windows, Excel für Mac, Excel für iPad und Excel OnlineExcel on Windows, Excel for Mac, Excel for iPad, and Excel Online

Hinweis

Das Name-Attribut gibt die Office-Hostanwendung an, die Ihr Add-In ausführen kann. Office-Hosts werden auf unterschiedlichen Plattformen unterstützt und auf Desktop-PCs, in Webbrowsern, auf Tablets und Mobilgeräten ausgeführt. Sie können nicht angeben, welche Plattform zum Ausführen Ihres Add-Ins verwendet werden soll. Wenn Sie beispielsweise Mailbox angeben, kann Outlook und Outlook Web App zum Ausführen Ihres Add-Ins verwendet werden.The Name attribute specifies the Office host application that can run your add-in. Office hosts are supported on different platforms and run on desktops, web browsers, tablets, and mobile devices. You can't specify which platform can be used to run your add-in. For example, if you specify Mailbox, both Outlook and Outlook Web App can be used to run your add-in.

Festlegen des Requirements-Elements im ManifestSet the Requirements element in the manifest

Das Requirements-Element gibt die Mindestanforderungssätze oder API-Elemente an, die vom Office-Host unterstützt werden müssen, damit Ihr Add-In ausgeführt werden kann. Das Requirements-Element kann sowohl Anforderungsätze als auch einzelne Methoden angeben, die in Ihrem Add-In verwendet werden. In Version 1.1 des Add-In-Manifestschemas ist das Requirements-Element für alle Add-Ins mit Ausnahme von Outlook-Add-Ins optional.The Requirements element specifies the minimum requirement sets or API members that must be supported by the Office host to run your add-in. The Requirements element can specify both requirement sets and individual methods used in your add-in. In version 1.1 of the add-in manifest schema, the Requirements element is optional for all add-ins, except for Outlook add-ins.

Warnung

Verwenden Sie nur das Requirements-Element zum Angeben wichtiger Anforderungssätze oder API-Elemente, die Ihr Add-In verwenden muss. Wenn der Office-Host oder die Plattform die im Element Requirements angegebenen Anforderungssätze oder API-Elemente nicht unterstützt, wird Ihr Add-In nicht in diesem Host oder auf dieser Plattform ausgeführt und nicht unter Meine Add-Ins angezeigt. Stattdessen wird empfohlen, Ihr Add-In auf allen Plattformen wie Excel unter Windows, Excel Online und Excel für iPad eines Office-Hosts zur Verfügung zu stellen. Um das Add-In auf allen Office-Hosts und Plattformen zur Verfügung zu stellen, verwenden Sie Laufzeitüberprüfungen anstelle des Requirements-Elements.Only use the Requirements element to specify critical requirement sets or API members that your add-in must use. If the Office host or platform doesn't support the requirement sets or API members specified in the Requirements element, the add-in won't run in that host or platform, and won't display in My Add-ins. Instead, we recommend that you make your add-in available on all platforms of an Office host, such as Excel for Windows, Excel Online, and Excel for iPad. To make your add-in available on all Office hosts and platforms, use runtime checks instead of the Requirements element.

Der folgende Code zeigt ein Add-In, das in allen Office-Hostanwendungen geladen wird, die Folgendes unterstützen:The following code example shows an add-in that loads in all Office host applications that support the following:

  • TableBindings-Anforderungssatz mit mindestens Version 1.1TableBindings requirement set, which has a minimum version of 1.1.

  • OOXML-Anforderungssatz mit mindestens Version 1.1OOXML requirement set, which has a minimum version of 1.1.

  • Document.getSelectedDataAsync-MethodeDocument.getSelectedDataAsync method.

<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>
  • Das Requirements-Element enthält die untergeordnete Elemente Sets und Methods.The Requirements element contains the Sets and Methods child elements.

  • Das Element Sets kann ein oder mehrere Set-Elemente enthalten. DefaultMinVersion gibt den MinVersion -Standardwert aller untergeordneten Set-Elemente an.The Sets element can contain one or more Set elements. DefaultMinVersion specifies the default MinVersion value of all child Set elements.

  • Das Set-Element gibt Anforderungssätze an, die der Office-Host zum Ausführen des Add-Ins unterstützen muss.The Set element specifies requirement sets that the Office host must support to run the add-in. Das Name-Attribut gibt den Namen des Anforderungssatzes an.The Name attribute specifies the name of the requirement set. MinVersion gibt die Mindestversion des Anforderungssatzes an.The MinVersion specifies the minimum version of the requirement set. MinVersion setzt den Wert von DefaultMinVersion außer Kraft.MinVersion overrides the value of DefaultMinVersion. Weitere Informationen zu Anforderungssätzen und Versionen von Anforderungssätzen, zu denen Ihre API-Mitglieder gehören, finden Sie unter Office-Add-In-Anforderungssätze.For more information about requirement sets and requirement set versions that your API members belong to, see Office Add-in requirement sets.

  • Das Methods-Element kann ein oder mehrere Method-Elemente enthalten. Das Methods-Element kann nicht mit Outlook-Add-Ins verwendet werden.The Methods element can contain one or more Method elements. You can't use the Methods element with Outlook add-ins.

  • Das Element Method gibt eine einzelne Methode an, die im Office-Host unterstützt werden muss, in dem Ihr Add-In ausgeführt wird. Das Attribut Name ist erforderlich und gibt den Namen der Methode an, die mit ihrem übergeordneten Objekt qualifiziert ist.The Method element specifies an individual method that must be supported in the Office host where your add-in runs. The Name attribute is required and specifies the name of the method qualified with its parent object.

Verwenden von Laufzeitüberprüfungen im JavaScript-CodeUse runtime checks in your JavaScript code

Möglicherweise möchten Sie zusätzliche Funktionalität in Ihrem Add-In bereitstellen, wenn bestimmte Anforderungssätze vom Office-Host unterstützt werden. Möglicherweise möchten Sie z. B. die neue Word JavaScript-API in Ihrem vorhandenen Add-In verwenden, wenn das Add-In in Word 2016 ausgeführt wird. Verwenden Sie dazu die Methode isSetSupported mit dem Namen des Anforderungssatzes. isSetSupported bestimmt zur Laufzeit, ob der Office-Host, in dem das Add-In ausgeführt wird, den Anforderungssatz unterstützt. Wenn der Anforderungssatz unterstützt wird, gibt isSetSupported den Wert true zurück und führt den zusätzlichen Code aus, der die API-Elemente aus dem Anforderungssatz verwendet. Wenn der Office-Host den Anforderungssatz nicht unterstützt, gibt isSetSupported den Wert false zurück, und der zusätzliche Code wird nicht ausgeführt. Im Folgenden finden Sie die mit isSetSupported zu verwendende Syntax.You might want to provide additional functionality in your add-in if certain requirement sets are supported by the Office host. For example, you might want to use the new Word JavaScript APIs Word in your existing add-in if your add-in runs in Word 2016. To do this, you use the isSetSupported method with the name of the requirement set. isSetSupported determines, at runtime, whether the Office host running the add-in supports the requirement set. If the requirement set is supported, isSetSupported returns true and runs the additional code that uses the API members from that requirement set. If the Office host doesn't support the requirement set, isSetSupported returns false and the additional code won't run. The following code shows the syntax to use with isSetSupported.

if (Office.context.requirements.isSetSupported(RequirementSetName , VersionNumber))
{
   // Code that uses API members from RequirementSetName.
}

  • RequirementSetName (erforderlich) ist eine Zeichenfolge, die den Namen des Anforderungssatzes darstellt.RequirementSetName (required) is a string that represents the name of the requirement set. Weitere Informationen zu verfügbaren Anforderungssätzen finden Sie unter Office-Add-In-Anforderungssätze.For more information about available requirement sets, see Office Add-in requirement sets.

  • VersionNumber (optional) ist die Version des Anforderungssatzes.VersionNumber (optional) is the version of the requirement set.

Verwenden Sie in Excel 2016 oder Word 2016 isSetSupported mit dem ExcelAPI- oder WordAPI-Anforderungssatz. Die Methode isSetSupported und die ExcelAPI- und WordAPI-Anforderungssätze stehen in der neuesten Office.js-Datei zur Verfügung, die im CDN verfügbar ist. Wenn Sie nicht die Office.js aus dem CDN verwenden, generiert Ihr Add-In möglicherweise Ausnahmen, da isSetSupported nicht definiert ist. Weitere Informationen finden Sie unter Angeben der neuesten Bibliothek der JavaScript-API für Office.In Excel 2016 or Word 2016, use isSetSupported with the ExcelAPI or WordAPI requirement sets. The isSetSupported method, and the ExcelAPI and WordAPI requirement sets, are available in the latest Office.js file available from the CDN. If you don't use Office.js from the CDN, your add-in might generate exceptions because isSetSupported will be undefined. For more information, see Specify the latest JavaScript API for Office library.

Hinweis

isSetSupported funktioniert nicht in Outlook oder Outlook Web App. Benutzen Sie zur Verwendung der Laufzeitüberprüfung in Outlook oder Outlook Web App das Verfahren, das unter Laufzeitüberprüfungen mithilfe von Methoden, die nicht in einem Anforderungssatz enthalten sind beschrieben ist.isSetSupported does not work in Outlook or Outlook Web App. To use a runtime check in Outlook or Outlook Web App, use the technique described in Runtime checks using methods not in a requirement set.

Das folgende Codebeispiel zeigt, wie ein Add-In unterschiedliche Funktionalität für unterschiedliche Office-Hosts bereitstellen kann, die ggf. verschiedene Anforderungssätze oder API-Elemente unterstützen.The following code example shows how an add-in can provide different functionality for different Office hosts that might support different requirement sets or API members.

if (Office.context.requirements.isSetSupported('WordApi', 1.1))
{
    // Run code that provides additional functionality using the JavaScript API for Word when the add-in runs in Word 2016.
}
else if (Office.context.requirements.isSetSupported('CustomXmlParts'))
{
    // Run code that uses API members from the CustomXmlParts requirement set.
}
else
{
    // Run additional code when the Office host is not Word 2016, and when the Office host does not support the CustomXmlParts requirement set.
}

Laufzeitüberprüfungen mithilfe von Methoden, die nicht in einem Anforderungssatz enthalten sind.Runtime checks using methods not in a requirement set

Einige API-Elemente gehören nicht zu Anforderungssätzen.Some API members don't belong to requirement sets. Dies gilt nur für API-Elemente, die Teil des JavaScript-API für OfficeNamespace sind (alles unter Office), nicht für API-Elemente, die zur JavaScript-API für Word (alles in Word) oder zur JavaScript-API-Referenz für Excel-Add-Ins (alles in Excel) gehören.This only applies to API members that are part of the JavaScript API for Office namespace (anything under Office.), not API members that belong to the Word JavaScript API (anything in Word.) or Excel add-ins JavaScript API reference (anything in Excel.) namespaces. Wenn Ihr Add-In von einer Methode abhängt, die nicht Teil eines Anforderungssatzes ist, können Sie die Laufzeitüberprüfung verwenden, um zu ermitteln, ob die Methode vom Office-Host unterstützt wird, wie im folgenden Codebeispiel dargestellt.When your add-in depends on a method that is not part of a requirement set, you can use the runtime check to determine whether the method is supported by the Office host, as shown in the following code example. Eine vollständige Liste von Methoden, die nicht zum Anforderungssatz gehören, finden Sie unter Office-Add-In-Anforderungssätze.For a complete list of methods that don't belong to a requirement set, see Office Add-in requirement sets.

Hinweis

Es wird empfohlen, die Verwendung dieser Art von Laufzeitüberprüfungen im Code Ihres Add-In einzuschränken.We recommend that you limit the use of this type of runtime check in your add-in's code.

Der folgende Code überprüft, ob der Host document.setSelectedDataAsync unterstützt.The following code example checks whether the host supports document.setSelectedDataAsync.

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

Siehe auchSee also