Angeben der Office-Add-In-Anforderungen im einheitlichen Manifest für Microsoft 365
Es gibt mehrere "Requirements"-Eigenschaften im einheitlichen Manifest für Microsoft 365. Die extensions.requirements-Eigenschaft steuert die Office-Anwendungen und -Versionen, auf denen das Add-In installiert werden kann. Andere "Requirements"-Eigenschaften werden verwendet, um selektiv einige Features eines Add-Ins für bestimmte Office-Anwendungen oder -Versionen zu unterdrücken, bei denen diese Features nicht benötigt oder nicht unterstützt werden. Weitere Informationen finden Sie unter Filterfeatures.
extensions.requirements
Die Eigenschaft "extensions.requirements" gibt die Bereiche, Formfaktoren und Anforderungssätze für Microsoft 365-Add-Ins an. Wenn die Microsoft 365-Version die angegebenen Anforderungen nicht unterstützt, steht die Erweiterung nicht für die Installation zur Verfügung. Benutzern wird sie nicht auf der Office-Benutzeroberfläche zum Suchen und Installieren von Add-Ins angezeigt. Einige Beispiele:
- Wenn die Eigenschaft "requirements.capabilities.name" auf "Mailbox" und "requirements.capabilities.minVersion" auf "1.10" festgelegt ist, kann das Add-In nicht in älteren Versionen von Office installiert werden, die keine Postfachanforderungssätze unterstützen, die höher als Version 1.9 sind.
- Wenn "requirements.scopes" auf "mail" festgelegt ist, kann das Add-In nur in Outlook installiert werden.
- Wenn "requirements.formFactors" nur auf "desktop" festgelegt ist, kann das Add-In nicht auf Office installiert werden, das auf einem mobilen Gerät ausgeführt wird.
Sie können über mehrere Funktionsobjekte verfügen. Das folgende Beispiel zeigt, wie Sie sicherstellen können, dass ein Add-In nur in Versionen von Office installiert werden kann, die zwei verschiedene Anforderungssätze unterstützen und nicht auf mobilen Geräten.
"extensions": [
...
"requirements": {
"capabilities": [
{
"name": "Mailbox",
"minVersion": "1.10"
},
{
"name": "DialogAPI",
"minVersion": "1.2"
}
],
"formFactors": [
"desktop"
]
}
]
Filterfeatures
Die Eigenschaften "requirements" in Nachfolgerobjekten von "Extensions" werden verwendet, um einige Features eines Add-Ins zu blockieren, während das Add-In weiterhin installiert werden kann. Die Implementierung dieser Filterung erfolgt an der Quelle der Installation, z. B. AppSource oder Microsoft 365 Admin Center. Wenn die Office-Version die für das Feature angegebenen Anforderungen nicht unterstützt, wird der JSON-Knoten für das Feature aus dem Manifest entfernt, bevor er in der Office-Anwendung installiert wird.
Tipp
Schließen Sie keine Funktions-, FormFactor- oder Bereichsanforderung in ein Nachfolgerobjekt von "extensions" ein, das weniger restriktiv ist als die entsprechende Funktions-, FormFactor- oder Bereichsanforderung in der vorgängern "extensions.requirements"-Eigenschaft, sofern vorhanden. Da das Add-In nicht auf Clients installiert werden kann, die die Vorgängeranforderung nicht erfüllen, würde trotzdem keine Featurefilterung erfolgen. Wenn beispielsweise eine "extensions.requirements.capabilities"-Eigenschaft Mailbox 1.10 erfordert, ist es sinnlos , Postfach 1.9 in untergeordneten Objekten zu erfordern.
extensions.alternates.requirements
Die Eigenschaft "extensions.alternates" ermöglicht Add-In-Entwicklern folgendes:
- Verwalten Sie eine Version eines Add-Ins, die auf einer älteren Erweiterbarkeitsplattform (z. B. COM- oder VSTO-Add-Ins) erstellt wurde, oder verwenden Sie zusätzlich zur Version, die das einheitliche Manifest verwendet.
- Blenden Sie entweder die Version aus, die die ältere Technologie verwendet, oder bevorzugen Sie sie.
- Geben Sie Symbole an, die erforderlich sind, damit die einheitliche Manifestversion des Add-Ins in Office-Versionen installiert werden kann, die das einheitliche Manifest nicht direkt unterstützen.
Hinweis
Office-Add-Ins, die das einheitliche Manifest für Microsoft 365 verwenden, werden direkt in Office im Web, in outlook unter Windows und in Office unter Windows unterstützt, die mit einem Microsoft 365-Abonnement, Version 2304 (Build 16320.00000) oder höher verbunden sind.
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. 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.
Weitere Informationen finden Sie unter Verwalten eines einheitlichen Manifests und einer reinen Add-In-Manifestversion Ihres Office-Add-Ins.
Die Untereigenschaft "requirements" von "extensions.alternates", um die Untereigenschaften "hide" oder "prefer" nur dann selektiv anzuwenden, wenn bestimmte Anforderungen erfüllt sind.
Angenommen, Sie möchten (auf der Office-Benutzeroberfläche zum Installieren von Add-Ins) eine ältere Version Ihres Add-Ins ausblenden, jedoch nur in Office-Versionen, die den Anforderungssatz Mailbox 1.10 unterstützen. Sie könnten dies mit Markup ähnlich dem folgenden tun:
"extensions": [
...
{
...
"alternates": [
...
{
...
"hide": {
"storeOfficeAddin": {
"officeAddinId": "b5a2794d-4aa5-4023-a84b-c60a3cbd33d4",
"assetId": "WA999999999"
}
},
"requirements": {
"capabilities": [
{
"name": "Mailbox",
"minVersion": "1.10"
}
]
}
}
]
}
]
extensions.autoRunEvents.requirements
Die Eigenschaft "extensions.autoRunEvents" konfiguriert ein Add-In so, dass der angegebene Code automatisch als Reaktion auf angegebene Ereignisse ausgeführt wird. Die Untereigenschaft "requirements" kann verwendet werden, um dieses Verhalten in einigen Versionen von Office zu blockieren.
Angenommen, ein Outlook-Add-In ist für den automatischen Start als Reaktion auf das OnMailSend-Ereignis konfiguriert, und angenommen, der Code in der Funktion, die ausgeführt wird, erfordert den Anforderungssatz Mailbox 1.13 . Das Add-In verfügt jedoch über andere Features, die in Office-Versionen nützlich wären, die nur Version 1.12 unterstützen. Um sicherzustellen, dass das Add-In in Versionen installiert werden kann, die 1.12 unterstützen, kann ein Entwickler die Eigenschaft "extensions.requirements.capabilities" auf den Anforderungssatz Mailbox 1.12 anstelle von 1.13 festlegen. Um jedoch das Feature für den automatischen Start in Versionen zu blockieren, die 1.13 nicht unterstützen, kann der Entwickler eine Eigenschaft "extensions.autoRunEvents.requirements.capabilities" hinzufügen, die Mailbox 1.13 angibt. Es folgt ein Beispiel.
"extensions": [
...
{
...
"autoRunEvents": [
...
{
...
"events": {
"type": "OnMailSend",
"actionId": "logOutgoingEmail",
"options": {
"sendMode": "promptUser"
}
},
"requirements": {
"capabilities": [
{
"name": "Mailbox",
"minVersion": "1.13"
}
]
}
}
]
}
]
extensions.contextMenus.requirements
Die Eigenschaft "extensions.contextMenus" konfiguriert die Kontextmenüs des Add-Ins. Ein Kontextmenü ist ein Kontextmenü, das angezeigt wird, wenn Sie mit der rechten Maustaste auf die Office-Benutzeroberfläche klicken (oder auswählen und halten). Die Untereigenschaft "requirements" kann verwendet werden, um Kontextmenüs nur dann zuzulassen, wenn bestimmte Anforderungen erfüllt sind.
Angenommen, Sie möchten Kontextmenüs nur in Excel-Versionen anzeigen, die den Anforderungssatz AddinCommands 1.1 unterstützen. Sie könnten dies mit Markup ähnlich dem folgenden tun:
"extensions": [
...
{
...
"contextMenus": [
...
{
// Insert details of the context menu configuration here.
"requirements": {
"scopes": [
"workbook"
],
"capabilities": [
{
"name": "AddinCommands",
"minVersion": "1.1"
}
]
}
}
]
}
]
extensions.getStartedMessages.requirements
Die Objekte im extensions.getStartedMessages Array stellen Informationen zu einem Office-Add-In bereit, das an verschiedenen Stellen in Office angezeigt wird, z. B. die Legende, die in Office angezeigt wird, wenn ein Office-Add-In installiert wird. Das Array kann bis zu drei Objekte enthalten. Wenn mehrere Objekte vorhanden sind, verwenden Sie die extensions.getStartedMessages.requirements -Eigenschaft, um sicherzustellen, dass in einem bestimmten Office-Client nicht mehr als eines dieser Objekte verwendet wird. Wenn extensions.getStartedMessages ausgelassen wird oder alle Objekte im Array herausgefiltert werden, verwendet die Legende stattdessen die Werte aus den Manifesteigenschaften "name.short" und "description.short".
Angenommen, ein Excel-Add-In vereinfacht das Hinzufügen von bedingter Formatierung zu Bereichen. Einige der APIs, die das Add-In verwendet, wurden mit dem ExcelApi 1.17-Anforderungssatz eingeführt, aber das Add-In bietet weiterhin nützliche Funktionen, die nur den ExcelApi 1.6-Anforderungssatz erfordern. Das extensions.getStartedMessages Array kann so konfiguriert werden, dass es eine Beschreibung des Add-Ins für Excel-Clients bereitstellt, die die Anforderungssätze von 1.6 bis 1.16 unterstützen, aber eine andere Beschreibung für Clients, die 1.17 und höher unterstützen. Es folgt ein Beispiel. Beachten Sie, dass in diesem Beispiel, wenn das Add-In so konfiguriert ist, dass es auf Excel-Clients installiert werden kann, die den Anforderungssatz 1.6 nicht unterstützen, auf diesen Clients keines dieser getStartedMessage-Objekte verwendet wird. Stattdessen verwendet Office die Eigenschaften "name.short" und "description.short".
"extensions": [
...
{
...
"getStartedMessages": [
{
"title": "Contoso Excel Formatting",
"description": "Use conditional formatting with our add-in.",
"learnMoreUrl": "https://contoso.com/simple-conditional-formatting-details.html",
"requirements": {
"capabilities": [
{
"name": "ExcelApi",
"minVersion": "1.6",
"maxVersion": "1.16"
}
]
}
},
{
"title": "Contoso Advanced Excel Formatting",
"description": "Use conditional formatting and dynamic formatting changes with our add-in.",
"learnMoreUrl": "https://contoso.com/advanced-conditional-formatting-details.html",
"requirements": {
"capabilities": [
{
"name": "ExcelApi",
"minVersion": "1.17"
}
]
}
}
]
}
]
extensions.ribbons.requirements
Die Eigenschaft "extensions.ribbons" wird verwendet, um das Menüband der Office-Anwendung anzupassen, wenn das Add-In installiert ist. Die Untereigenschaft "requirements" kann verwendet werden, um anpassungen in einigen Versionen von Office zu verhindern.
Angenommen, ein Outlook-Add-In ist so konfiguriert, dass dem Menüband eine benutzerdefinierte Schaltfläche hinzugefügt wird, und die Schaltfläche führt eine Funktion aus, die Code verwendet, der im Anforderungssatz Mailbox 1.9 eingeführt wurde. Das Add-In verfügt jedoch über andere Features, die für Office-Versionen nützlich wären, die nur Version 1.8 unterstützen. Um sicherzustellen, dass das Add-In in Versionen installiert werden kann, die Version 1.8 unterstützen, kann ein Entwickler die Eigenschaft "extensions.requirements.capabilities" auf den Anforderungssatz Mailbox 1.8 anstelle von 1.9 festlegen. Um jedoch zu verhindern, dass die benutzerdefinierte Schaltfläche in Versionen, die 1.9 nicht unterstützen, auf dem Menüband angezeigt wird, kann der Entwickler eine "extensions.ribbons.requirements.capabilities"-Eigenschaft hinzufügen, die Mailbox 1.9 angibt. Es folgt ein Beispiel. Ausführliche Informationen zur konfiguration des benutzerdefinierten Menübands finden Sie unter Erstellen von Add-In-Befehlen mit dem einheitlichen Manifest für Microsoft 365.
"extensions": [
...
{
...
"ribbons": [
...
{
// Insert details of the ribbon configuration here.
"requirements": {
"capabilities": [
{
"name": "Mailbox",
"minVersion": "1.9"
}
]
}
}
]
}
]
extensions.runtimes.requirements
Die Eigenschaft "extensions.runtimes" konfiguriert die Sätze von Laufzeiten und Aktionen, die jeder Erweiterungspunkt verwenden kann. Weitere Informationen zur Verwendung finden Sie unter Erstellen von Add-In-Befehlen, Konfigurieren der Laufzeit für einen Aufgabenbereich und Konfigurieren der Laufzeit für den Funktionsbefehl. Weitere Informationen zu Runtimes in Office-Add-Ins finden Sie unter Runtimes in Office-Add-Ins.
Die Untereigenschaft "requirements" kann verwendet werden, um zu verhindern, dass die Runtime in Versionen von Office oder in Office-Anwendungen enthalten ist, in denen sie nicht verwendet würde.
Das vorherige Beispiel in extensions.autoRunEvents.requirements zeigt, wie das Feature für den automatischen Start in Versionen blockiert wird, die nicht den gesamten Code in der logOutgoingEmail Funktion unterstützen, einschließlich Code, der Mailbox 1.13 erfordert. Angenommen, in diesem Szenario ist das "runtime"-Objekt, das für die Unterstützung der Aktion "logOutgoingEmail" konfiguriert ist, nicht für die Unterstützung anderer Aktionen konfiguriert. In diesem Fall sollte der Entwickler das Laufzeitobjekt in Versionen blockieren, die Mailbox 1.13 nicht unterstützen, da es nie verwendet würde. Es folgt ein Beispiel. Ausführliche Informationen zur Laufzeitkonfiguration finden Sie unter Erstellen von Add-In-Befehlen mit dem einheitlichen Manifest für Microsoft 365.
"extensions": [
...
{
...
"runtimes": [
...
{
// Insert details of the runtime configuration here.
"requirements": {
"capabilities": [
{
"name": "Mailbox",
"minVersion": "1.13"
}
]
}
}
]
}
]
Wenn die mit der benutzerdefinierten Schaltfläche verknüpfte Aktion für das Beispiel in extensions.ribbons.requirements die einzige in einem Laufzeitobjekt konfigurierte Aktion ist, sollte dieses Laufzeitobjekt unter den gleichen Umständen blockiert werden, unter denen das Menübandobjekt blockiert wird.
extensions.keyboardShortcuts.requirements (Entwicklervorschau)
Die extensions.keyboardShortcuts -Eigenschaft definiert benutzerdefinierte Tastenkombinationen oder Tastenkombinationen zum Ausführen bestimmter Aktionen. Informationen zum Erstellen benutzerdefinierter Tastenkombinationen finden Sie unter Hinzufügen benutzerdefinierter Tastenkombinationen zu Ihren Office-Add-Ins.
Die Untereigenschaft "requirements" kann verwendet werden, um sicherzustellen, dass die benutzerdefinierten Verknüpfungen nur auf Plattformen verfügbar sind, die die SharedRuntime 1.1-API unterstützen. Das folgende Beispiel zeigt, wie Sie dies in Ihrem Manifest konfigurieren.
"extensions": [
...
{
...
"keyboardShortcuts": [
{
//Insert details of the keyboard shortcut configuration here.
"requirements" : {
"capabilities": [
{
"name": "SharedRuntime",
"minVersion": "1.1"
}
]
}
}
]
}
]
Office Add-ins