diff --git a/docs/design/contextual-tabs.md b/docs/design/contextual-tabs.md index 305097c4c8..6e50030861 100644 --- a/docs/design/contextual-tabs.md +++ b/docs/design/contextual-tabs.md @@ -27,7 +27,7 @@ Additionally, custom contextual tabs only work on platforms that support the fol - [SharedRuntime 1.1](/javascript/api/requirement-sets/common/shared-runtime-requirement-sets) > [!TIP] -> Use the runtime checks in your code to test whether the user's host and platform combination supports these requirement sets as described in [Runtime checks for method and requirement set support](../develop/specify-office-hosts-and-api-requirements.md#runtime-checks-for-method-and-requirement-set-support). (The technique of specifying the requirement sets in the manifest, which is also described in that article, doesn't currently work for RibbonApi 1.2.) Alternatively, you can [implement an alternate UI experience when custom contextual tabs aren't supported](#implement-an-alternate-ui-experience-when-custom-contextual-tabs-arent-supported). +> Use the runtime checks in your code to test whether the user's host and platform combination supports these requirement sets as described in [Check for API availability at runtime](../develop/specify-api-requirements-runtime.md). (The technique of specifying the requirement sets in the manifest, which is also described in that article, doesn't currently work for RibbonApi 1.2.) Alternatively, you can [implement an alternate UI experience when custom contextual tabs aren't supported](#implement-an-alternate-ui-experience-when-custom-contextual-tabs-arent-supported). ## Behavior of custom contextual tabs diff --git a/docs/develop/dialog-api-in-office-add-ins.md b/docs/develop/dialog-api-in-office-add-ins.md index 0ecf31fcac..d7292a71cb 100644 --- a/docs/develop/dialog-api-in-office-add-ins.md +++ b/docs/develop/dialog-api-in-office-add-ins.md @@ -330,7 +330,7 @@ Because you can make multiple `messageChild` calls from the host page, but you h > In some situations, the `messageChild` API, which is a part of the [DialogApi 1.2 requirement set](/javascript/api/requirement-sets/common/dialog-api-requirement-sets), may not be supported. For example, `messageChild` isn't supported in volume-licensed perpetual Outlook 2016 and volume-licensed perpetual Outlook 2019. Some alternative ways for parent-to-dialog-box messaging are described in [Alternative ways of passing messages to a dialog box from its host page](parent-to-dialog.md). > [!IMPORTANT] -> The [DialogApi 1.2 requirement set](/javascript/api/requirement-sets/common/dialog-api-requirement-sets) can't be specified in the **\** section of an add-in manifest. You will have to check for support for DialogApi 1.2 at runtime using the `isSetSupported` method as described in [Runtime checks for method and requirement set support](../develop/specify-office-hosts-and-api-requirements.md#runtime-checks-for-method-and-requirement-set-support). Support for manifest requirements is under development. +> The [DialogApi 1.2 requirement set](/javascript/api/requirement-sets/common/dialog-api-requirement-sets) can't be specified in the **\** section of an add-in manifest. You'll have to check for support for DialogApi 1.2 at runtime using the `isSetSupported` method as described in [Check for API availability at runtime](specify-api-requirements-runtime.md). Support for manifest requirements is under development. ### Cross-domain messaging to the dialog runtime diff --git a/docs/develop/specify-api-requirements-runtime.md b/docs/develop/specify-api-requirements-runtime.md new file mode 100644 index 0000000000..b55a4e2359 --- /dev/null +++ b/docs/develop/specify-api-requirements-runtime.md @@ -0,0 +1,81 @@ +--- +title: Check for API availability at runtime +description: Learn how to verify at runtime that the Office application supports your add-in's API calls. +ms.topic: best-practice +ms.date: 10/30/2024 +ms.localizationpriority: medium +--- + +# Check for API availability at runtime + +If your add-in uses a specific extensibility feature for some of its functionality, but has other useful functionality that doesn't require the extensibility feature, you should design the add-in so that it's installable on platform and Office version combinations that don't support the extensibility feature. It can provide a valuable, albeit diminished, experience on those combinations. + +When the difference in the two experiences consists entirely of differences in the Office JavaScript Library APIs that are called, and not in any features that are configured in the manifest, then you test at runtime to discover whether the user's Office client supports an [API requirement set](office-versions-and-requirement-sets.md). You can also [test at runtime whether APIs that aren't in a set are supported](#check-for-setless-api-support). + +> [!NOTE] +> To provide alternate experiences with features that require manifest configuration, follow the guidance in [Specify Office hosts and API requirements with the unified manifest](specify-office-hosts-and-api-requirements-unified.md) or [Specify Office applications and API requirements with the add-in only manifest](specify-office-hosts-and-api-requirements.md). + +## Check for requirement set support + +The [isSetSupported](/javascript/api/office/office.requirementsetsupport#office-office-requirementsetsupport-issetsupported-member(1)) method is used to check for requirement set support. Pass the requirement set's name and the minimum version as parameters. If the requirement set is supported, `isSetSupported` returns `true`. The following code shows an example. + +```js +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. + // For example, run alternate code when the user's Word is + // volume-licensed perpetual Word 2016 (which doesn't support WordApi 1.2). +} +``` + +About this code, note: + +- The first parameter is required. It's a string that represents the name of the requirement set. For more information about available requirement sets, see [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets). +- The second parameter is optional. It's a string that specifies the minimum requirement set version that the Office application must support in order for the code within the `if` statement to run (for example, "1.9"). If not used, version "1.1" is assumed. + +> [!WARNING] +> When calling the `isSetSupported` method, the value of the second parameter (if specified) should be a string, not a number. The JavaScript parser can't differentiate between numeric values such as 1.1 and 1.10, whereas it can for string values such as "1.1" and "1.10". + +The following table shows the requirement set names for the application-specific API models. + +|Office application|RequirementSetName| +|---|---| +|Excel|ExcelApi| +|OneNote|OneNoteApi| +|Outlook|Mailbox| +|PowerPoint|PowerPointApi| +|Word|WordApi| + +The following is an example of using the method with one of the Common API model requirement sets. + +```js +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. +} +``` + +> [!NOTE] +> The `isSetSupported` method and the requirement sets for these applications are available in the latest Office.js file on the CDN. If you don't use Office.js from the CDN, your add-in might generate exceptions if you are using an old version of the library in which `isSetSupported` is undefined. For more information, see [Use the latest Office JavaScript API library](specify-office-hosts-and-api-requirements-unified.md#use-the-latest-office-javascript-api-library). + +## Check for setless API support + +When your add-in depends on a method that isn't part of a requirement set, called a setless API, use a runtime check to determine whether the method is supported by the Office application, as shown in the following code example. For a complete list of methods that don't belong to a requirement set, see [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets#methods-that-arent-part-of-a-requirement-set). + +> [!NOTE] +> We recommend that you limit the use of this type of runtime check in your add-in's code. + +The following code example checks whether the Office application supports `document.setSelectedDataAsync`. + +```js +if (Office.context.document.setSelectedDataAsync) { + // Run code that uses `document.setSelectedDataAsync`. +} +``` + +## See also +- [Office requirement sets availability](office-versions-and-requirement-sets.md#office-requirement-sets-availability) +- [Specify Office hosts and API requirements with the unified manifest](specify-office-hosts-and-api-requirements-unified.md) +- [Specify Office hosts and API requirements with the add-in only manifest](specify-office-hosts-and-api-requirements.md) diff --git a/docs/develop/specify-office-hosts-and-api-requirements-unified.md b/docs/develop/specify-office-hosts-and-api-requirements-unified.md new file mode 100644 index 0000000000..7cdcef036f --- /dev/null +++ b/docs/develop/specify-office-hosts-and-api-requirements-unified.md @@ -0,0 +1,166 @@ +--- +title: Specify Office hosts and API requirements with the unified manifest +description: Learn how to specify in the unified manifest the Office applications and API requirements for your add-in to work as expected. +ms.topic: best-practice +ms.date: 10/30/2024 +ms.localizationpriority: medium +--- + +# Specify Office applications and API requirements with the unified manifest + +> [!NOTE] +> For information about specifying requirements with the add-in only manifest, see [Specify Office hosts and API requirements with the add-in only manifest](specify-office-hosts-and-api-requirements.md). + +Your Office Add-in might depend on a specific Office application (also called an Office host) or on specific members of the Office JavaScript Library (office.js). For example, your add-in might: + +- Run in a single Office application (e.g., Word or Excel), or several applications. +- Make use of Office JavaScript APIs that are only available in some versions of Office. For example, the volume-licensed perpetual version of Excel 2016 doesn't support all Excel-related APIs in the Office JavaScript library. +- Be designed for use only in a mobile form factor. + +In these situations, you need to ensure that your add-in is never installed on Office applications or Office versions in which it cannot run. + +There are also scenarios in which you want to control which features of your add-in are visible to users based on their Office application and Office version. Three examples are: + +- Your add-in has features that are useful in both Word and PowerPoint, such as text manipulation, but it has some additional features that only make sense in PowerPoint, such as slide management features. You need to hide the PowerPoint-only features when the add-in is running in Word. +- Your add-in has a feature that requires an Office JavaScript API method that is supported in some versions of an Office application, such as Microsoft 365 subscription Excel, but isn't supported in others, such as volume-licensed perpetual Excel 2016. But your add-in has other features that require only Office JavaScript API methods that *are* supported in volume-licensed perpetual Excel 2016. In this scenario, you need the add-in to be installable on that version of Excel 2016, but the feature that requires the unsupported method should be hidden from those users. +- Your add-in has features that are supported in desktop Office, but not in mobile Office. + +This article helps you understand how to ensure that your add-in works as expected and reaches the broadest audience possible. + +> [!NOTE] +> For a high-level view of where Office Add-ins are currently supported, see the [Office client application and platform availability for Office Add-ins](/javascript/api/requirement-sets) page. + +> [!TIP] +> Many of the tasks described in this article are done for you, in whole or in part, when you create your add-in project with a tool, such as the [Yeoman generator for Office Add-ins](yeoman-generator-overview.md) or one of the Office Add-in templates in Visual Studio. In such cases, please interpret the task as meaning that you should verify that it has been done. + +## Use the latest Office JavaScript API library + +Your add-in should load the most current version of the Office JavaScript API library from the content delivery network (CDN). To do this, be sure you have the following ` +``` + +## Specify which Office applications can host your add-in + +To specify the Office applications on which your add-in can be installed, use the "extensions.requirements.scopes" array. Specify any subset of "mail", "workbook", "document", and "presentation". The following table shows which Office application and platform combinations correspond to these values. It also shows what kind of add-in can be installed for each scope. + + +| Name | Office client applications | Available add-in types | +|:--------------|:-----------------------------------------------|:-----------------------| +| document | Word on the web, Windows, Mac, iPad | Task pane | +| mail | Outlook on the web, Windows ([new](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627) and classic), Android, iOS | Mail | +| presentation | PowerPoint on the web, Windows, Mac, iPad | Task pane, Content | +| workbook | Excel on the web, Windows, Mac, iPad | Task pane, Content | + +> [!NOTE] +> Content add-ins have an "extensions.contentRuntimes" property. They can't have an "extensions.runtimes" property so they can't be combined with a Task pane or Mail add-in. For more information about Content add-ins, see [Content Office Add-ins](../design/content-add-ins.md). + +For example, the following JSON specifies that the add-in can install on any release of Excel, which includes Excel on the web, Windows, and iPad, but can't be installed on any other Office application. + +```json +"extensions": [ + { + "requirements": { + "scopes": [ "workbook" ], + }, + ... + } +] +``` + +> [!NOTE] +> Office applications are supported on different platforms and run on desktops, web browsers, tablets, and mobile devices. You usually can't specify which platform can be used to run your add-in. For example, if you specify "workbook", both Excel on the web and on Windows can be used to run your add-in. However, if you specify "mail", your add-in won't run on Outlook mobile clients unless you define the [mobile extension point](/javascript/api/manifest/extensionpoint#mobilemessagereadcommandsurface). + +## Specify which Office APIs your add-in needs + +You can't explicitly specify the Office versions and builds or the platforms on which your add-in should be installable, and you wouldn't want to because you would have to revise your manifest whenever support for the add-in features that your add-in uses is extended to a new version or platform. Instead, specify in the manifest the APIs that your add-in needs. Office prevents the add-in from being installed on combinations of Office version and platform that don't support the APIs and ensures that the add-in won't appear in **My Add-ins**. + +> [!IMPORTANT] +> Only use the "requirements" property that is a direct child of "extensions" to specify the API members that your add-in must have to be of any significant value at all. If your add-in uses an API for some features, but has other useful features that don't require the API, you should design the add-in so that it's installable on platform and Office version combinations that don't support the API but provides a diminished experience on those combinations. For this purpose, use "requirements" properties that aren't direct children of "extensions". For more information, see [Design for alternate experiences](#design-for-alternate-experiences). + +### Requirement sets + +To simplify the process of specifying the APIs that your add-in needs, Office groups most APIs together in [requirement sets](office-versions-and-requirement-sets.md). The APIs in the [Common API Object Model](understanding-the-javascript-api-for-office.md#api-models) are grouped by the development feature that they support. For example, all the APIs connected to table bindings are in the requirement set called "TableBindings 1.1". The APIs in the [Application specific object models](understanding-the-javascript-api-for-office.md#api-models) are grouped by when they were released for use in production add-ins. + +Requirement sets are versioned. For example, the APIs that support [Dialog Boxes](../develop/dialog-api-in-office-add-ins.md) are in the requirement set DialogApi 1.1. When additional APIs that enable messaging from a task pane to a dialog were released, they were grouped into DialogApi 1.2, along with all the APIs in DialogApi 1.1. *Each version of a requirement set is a superset of all earlier versions.* + +Requirement set support varies by Office application, the version of the Office application, and the platform on which it is running. For example, DialogApi 1.2 isn't supported on volume-licensed perpetual versions of Office before Office 2021, but DialogApi 1.1 is supported on all perpetual versions back to Office 2016. You want your add-in to be installable on every combination of platform and Office version that supports the APIs that it uses, so you should always specify in the manifest the *minimum* version of each requirement set that your add-in requires. Details about how to do this are later in this article. + +> [!TIP] +> For more information about requirement set versioning, see [Office requirement sets availability](office-versions-and-requirement-sets.md#office-requirement-sets-availability), and for the complete lists of requirement sets and information about the APIs in each, start with [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets). The reference topics for most Office.js APIs also specify the requirement set they belong to (if any). + +### extensions.requirements.capabilities property + +Use the "requirements.capabilities" property to specify the minimum requirement sets that must be supported by the Office application to install your add-in. If the Office application or platform doesn't support the requirement sets or API members specified in the "requirements.capabilities" property, the add-in won't run in that application or platform, and won't display in **My Add-ins**. + +> [!TIP] +> All APIs in the application-specific models are in requirement sets, but some of those in the Common API model aren't. If your add-in requires an API that isn't in any requirement set, you can implement a runtime check for the availability of the API and display a message to the add-in's users if it isn't supported. For more information, see [Check for API availability at runtime](specify-api-requirements-runtime.md). + +The following code example shows how to configure an add-in that is installable in all Office application and platform combinations that support the following: + +- `TableBindings` requirement set, which has a minimum version of "1.1". +- `OOXML` requirement set, which has a minimum version of "1.1". + +```json +"extensions": [ + { + "requirements": { + "capabilities": [ + { + "name": "TableBindings", + "minVersion": "1.1" + }, + { + "name": "OOXML", + "minVersion": "1.1" + } + ], + }, + ... + } +] +``` + +> [!TIP] +> For more information and another example of using the "extensions.requirements" property, see the "extensions.requirements" section in [Specify Office Add-in requirements in the unified manifest for Microsoft 365](requirements-property-unified-manifest.md#extensionsrequirements). + +### Specify the form factors on which your add-in can be installed + +For an Outlook add-in, you can specify whether the add-in should be installable on desktop (includes tablets) or mobile form factors. To configure this, use the "extensions.requirements.formFactors" property. The following example show how to make the Outlook add-in installable on both form factors. + +```json +"extensions": [ + { + "requirements": { + ... + "formFactors": [ + "desktop", + "mobile" + ] + }, + ... + } +] +``` + +## Design for alternate experiences + +The extensibility features that the Office Add-in platform provides can be usefully divided into three kinds: + +- Extensibility features that are available immediately after the add-in is installed. An example of this kind of feature is [Add-in Commands](../design/add-in-commands.md), which are custom ribbon buttons and menus. +- Extensibility features that are available only when the add-in is running and that are implemented with Office.js JavaScript APIs; for example, [Dialog Boxes](../develop/dialog-api-in-office-add-ins.md). +- Extensibility features that are available only at runtime but are implemented with a combination of Office.js JavaScript and manifest configuration. Examples of these are [Excel custom functions](../excel/custom-functions-overview.md), [single sign-on](sso-in-office-add-ins.md), and [custom contextual tabs](../design/contextual-tabs.md). + +If your add-in uses a specific extensibility feature for some of its functionality but has other useful functionality that doesn't require the extensibility feature, you should design the add-in so that it's installable on platform and Office version combinations that don't support the extensibility feature. It can provide a valuable, albeit diminished, experience on those combinations. + +You implement this design differently depending on how the extensibility feature is implemented: + +- For features implemented entirely with JavaScript, see [Check for API availability at runtime](specify-api-requirements-runtime.md). +- For features that require you to configure the manifest, see the "Filter features" section of [Specify Office Add-in requirements in the unified manifest for Microsoft 365](requirements-property-unified-manifest.md#filter-features). + +## See also + +- [Office Add-ins manifest](add-in-manifests.md) +- [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets) +- [Specify Office Add-in requirements in the unified manifest for Microsoft 365](requirements-property-unified-manifest.md) diff --git a/docs/develop/specify-office-hosts-and-api-requirements.md b/docs/develop/specify-office-hosts-and-api-requirements.md index 91de39ec15..6c287dd97e 100644 --- a/docs/develop/specify-office-hosts-and-api-requirements.md +++ b/docs/develop/specify-office-hosts-and-api-requirements.md @@ -1,16 +1,19 @@ --- -title: Specify Office hosts and API requirements +title: Specify Office hosts and API requirements with the add-in only manifest description: Learn how to specify Office applications and API requirements for your add-in to work as expected. ms.topic: best-practice -ms.date: 10/03/2024 +ms.date: 10/30/2024 ms.localizationpriority: medium --- -# Specify Office applications and API requirements +# Specify Office applications and API requirements with the add-in only manifest -Your Office Add-in might depend on a specific Office application (also called an Office host) or on specific members of the Office JavaScript API (office.js). For example, your add-in might: +> [!NOTE] +> For information about specifying requirements with the [unified manifest for Microsoft 365](unified-manifest-overview.md), see [Specify Office hosts and API requirements with the unified manifest](specify-office-hosts-and-api-requirements-unified.md). + +Your Office Add-in might depend on a specific Office application (also called an Office host) or on specific members of the Office JavaScript Library (office.js). For example, your add-in might: -- Run in a single Office application (e.g., Word or Excel), or several applications. +- Run in a single Office application (for example, Word or Excel), or several applications. - Make use of Office JavaScript APIs that are only available in some versions of Office. For example, the volume-licensed perpetual version of Excel 2016 doesn't support all Excel-related APIs in the Office JavaScript library. In these situations, you need to ensure that your add-in is never installed on Office applications or Office versions in which it cannot run. @@ -30,7 +33,7 @@ This article helps you understand which options you should choose to ensure that ## Use the latest Office JavaScript API library -Your add-in should load the most current version of the Office JavaScript API library from the content delivery network (CDN). To do this, be sure you have the following `script` tag in the first HTML file your add-in opens. Using `/1/` in the CDN URL ensures that you reference the most recent version of Office.js. +Your add-in should load the most current version of the Office JavaScript API library from the content delivery network (CDN). To do this, be sure you have the following ` @@ -40,9 +43,9 @@ Your add-in should load the most current version of the Office JavaScript API li By default, an add-in is installable in all Office applications supported by the specified add-in type (that is, Mail, Task pane, or Content). For example, a task pane add-in is installable by default on Access, Excel, OneNote, PowerPoint, Project, and Word. -To ensure that your add-in is installable in a subset of Office applications, use the [Hosts](/javascript/api/manifest/hosts) and [Host](/javascript/api/manifest/host) elements in the manifest. +To ensure that your add-in is installable in only a subset of Office applications, use the [Hosts](/javascript/api/manifest/hosts) and [Host](/javascript/api/manifest/host) elements in the add-in only manifest. -For example, the following **\** and **\** declaration specifies that the add-in can install on any release of Excel, which includes Excel on the web, Windows, and iPad, but cannot be installed on any other Office application. +For example, the following **\** and **\** declaration specifies that the add-in can install on any release of Excel, which includes Excel on the web, Windows, and iPad, but can't be installed on any other Office application. ```xml @@ -66,7 +69,7 @@ The **\** element can contain one or more **\** elements. There s > Office applications are supported on different platforms and run on desktops, web browsers, tablets, and mobile devices. You usually can't specify which platform can be used to run your add-in. For example, if you specify `Workbook`, both Excel on the web and on Windows can be used to run your add-in. However, if you specify `Mailbox`, your add-in won't run on Outlook mobile clients unless you define the [mobile extension point](/javascript/api/manifest/extensionpoint#mobilemessagereadcommandsurface). > [!NOTE] -> It isn't possible for an add-in manifest to apply to more than one type: Mail, Task pane, or Content. This means that if you want your add-in to be installable on Outlook and on one of the other Office applications, you must create *two* add-ins, one with a Mail type manifest and the other with a Task pane or Content type manifest. +> It isn't possible for an add-in only manifest to apply to more than one type: Mail, Task pane, or Content. This means that if you want your add-in to be installable on Outlook and on one of the other Office applications, you must create *two* add-ins, one with a Mail type manifest and the other with a Task pane or Content type manifest. ## Specify which Office versions and platforms can host your add-in @@ -77,7 +80,7 @@ You can't explicitly specify the Office versions and builds or the platforms on ### Requirement sets -To simplify the process of specifying the APIs that your add-in needs, Office groups most APIs together in *requirement sets*. The APIs in the [Common API Object Model](understanding-the-javascript-api-for-office.md#api-models) are grouped by the development feature that they support. For example, all the APIs connected to table bindings are in the requirement set called "TableBindings 1.1". The APIs in the [Application specific object models](understanding-the-javascript-api-for-office.md#api-models) are grouped by when they were released for use in production add-ins. +To simplify the process of specifying the APIs that your add-in needs, Office groups most APIs together in [requirement sets](office-versions-and-requirement-sets.md). The APIs in the [Common API Object Model](understanding-the-javascript-api-for-office.md#api-models) are grouped by the development feature that they support. For example, all the APIs connected to table bindings are in the requirement set called "TableBindings 1.1". The APIs in the [Application specific object models](understanding-the-javascript-api-for-office.md#api-models) are grouped by when they were released for use in production add-ins. Requirement sets are versioned. For example, the APIs that support [Dialog Boxes](../develop/dialog-api-in-office-add-ins.md) are in the requirement set DialogApi 1.1. When additional APIs that enable messaging from a task pane to a dialog were released, they were grouped into DialogApi 1.2, along with all the APIs in DialogApi 1.1. *Each version of a requirement set is a superset of all earlier versions.* @@ -89,13 +92,11 @@ Requirement set support varies by Office application, the version of the Office > [!NOTE] > Some requirement sets also have manifest elements associated with them. See [Specifying requirements in a VersionOverrides element](#specify-requirements-in-a-versionoverrides-element) for information about when this fact is relevant to your add-in design. -#### APIs not in a requirement set - -All APIs in the application specific models are in requirement sets, but some of those in the Common API model are not. There is also a way that you can specify one of these setless APIs in the manifest when your add-in requires one. Details are later in this article. - ### Requirements element -Use the [Requirements](/javascript/api/manifest/requirements) element and its child elements [Sets](/javascript/api/manifest/sets) and [Methods](/javascript/api/manifest/methods) to specify the minimum requirement sets or API members that must be supported by the Office application to install your add-in. +Use the [Requirements](/javascript/api/manifest/requirements) element and its child element [Sets](/javascript/api/manifest/sets) to specify the minimum requirement sets that must be supported by the Office application to install your add-in. + +All APIs in the application specific models are in requirement sets, but some of those in the Common API model are not. Use the [Methods](/javascript/api/manifest/methods) to specify the setless API members that your add-in requires. You can't use the **\** element with Outlook add-ins. If the Office application or platform doesn't support the requirement sets or API members specified in the **\** element, the add-in won't run in that application or platform, and won't display in **My Add-ins**. @@ -144,70 +145,9 @@ If your add-in uses a specific extensibility feature for some of its functionali You implement this design differently depending on how the extensibility feature is implemented: -- For features implemented entirely with JavaScript, see [Runtime checks for method and requirement set support](#runtime-checks-for-method-and-requirement-set-support). +- For features implemented entirely with JavaScript, see [Check for API availability at runtime](specify-api-requirements-runtime.md). - For features that require you to configure a **\** element, see [Specifying requirements in a VersionOverrides element](#specify-requirements-in-a-versionoverrides-element). -### Runtime checks for method and requirement set support - -You test at runtime to discover whether the user's Office supports a requirement set with the [isSetSupported](/javascript/api/office/office.requirementsetsupport#office-office-requirementsetsupport-issetsupported-member(1)) method. Pass the requirement set's name and the minimum version as parameters. If the requirement set is supported, `isSetSupported` returns `true`. The following code shows an example. - -```js -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). -} -``` - -About this code, note: - -- The first parameter is required. It's a string that represents the name of the requirement set. For more information about available requirement sets, see [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets). -- The second parameter is optional. It's a string that specifies the minimum requirement set version that the Office application must support in order for the code within the `if` statement to run (e.g., "**1.9**"). If not used, version "1.1" is assumed. - -> [!WARNING] -> When calling the `isSetSupported` method, the value of the second parameter (if specified) should be a string not a number. The JavaScript parser cannot differentiate between numeric values such as 1.1 and 1.10, whereas it can for string values such as "1.1" and "1.10". - -The following table shows the requirement set names for the application specific API models. - -|Office application|RequirementSetName| -|---|---| -|Excel|ExcelApi| -|OneNote|OneNoteApi| -|Outlook|Mailbox| -|PowerPoint|PowerPointApi| -|Word|WordApi| - -The following is an example of using the method with one of the Common API model requirement sets. - -```js -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. -} -``` - -> [!NOTE] -> The `isSetSupported` method and the requirement sets for these applications are available in the latest Office.js file on the CDN. If you don't use Office.js from the CDN, your add-in might generate exceptions if you are using an old version of the library in which `isSetSupported` is undefined. For more information, see [Use the latest Office JavaScript API library](#use-the-latest-office-javascript-api-library). - -When your add-in depends on a method that isn't part of a requirement set, use the runtime check to determine whether the method is supported by the Office application, as shown in the following code example. For a complete list of methods that don't belong to a requirement set, see [Office Add-in requirement sets](/javascript/api/requirement-sets/common/office-add-in-requirement-sets#methods-that-arent-part-of-a-requirement-set). - -> [!NOTE] -> We recommend that you limit the use of this type of runtime check in your add-in's code. - -The following code example checks whether the Office application supports `document.setSelectedDataAsync`. - -```js -if (Office.context.document.setSelectedDataAsync) -{ - // Run code that uses `document.setSelectedDataAsync`. -} -``` - ### Specify requirements in a VersionOverrides element The [VersionOverrides](/javascript/api/manifest/versionoverrides) element was added to the manifest schema primarily, but not exclusively, to support features that must be available immediately after an add-in is installed, such as add-in commands (custom ribbon buttons and menus). Office must know about these features when it parses the add-in manifest. @@ -240,10 +180,10 @@ The following is an example. ``` > [!WARNING] -> Use great care before including a **\** element in a **\**, because on platform and version combinations that don't support the requirement, *none* of the add-in commands will be installed, *even those that invoke functionality that doesn't need the requirement*. Consider, for example, an add-in that has two custom ribbon buttons. One of them calls Office JavaScript APIs that are available in requirement set **ExcelApi 1.4** (and later). The other calls APIs that are only available in **ExcelApi 1.9** (and later). If you put a requirement for **ExcelApi 1.9** in the **\**, then when 1.9 is not supported *neither* button will appear on the ribbon. A better strategy in this scenario would be to use the technique described in [Runtime checks for method and requirement set support](#runtime-checks-for-method-and-requirement-set-support). The code invoked by the second button first uses `isSetSupported` to check for support of **ExcelApi 1.9**. If it isn't supported, the code gives the user a message saying that this feature of the add-in is not available on their version of Office. +> If your add-in includes [add-in commands](../design/add-in-commands.md), use great care before including a **\** element in a **\**. On platform and version combinations that don't support the requirement, *none* of the add-in commands will be installed, *even those that invoke functionality that doesn't need the requirement*. Consider, for example, an add-in that has two custom ribbon buttons. One of them calls Office JavaScript APIs that are available in requirement set **ExcelApi 1.4** (and later). The other calls APIs that are only available in **ExcelApi 1.9** (and later). If you put a requirement for **ExcelApi 1.9** in the **\**, then when 1.9 isn't supported, *neither* button will appear on the ribbon. A better strategy in this scenario would be to use the technique described in [Check for API availability at runtime](specify-api-requirements-runtime.md). The code invoked by the second button first uses `isSetSupported` to check for support of **ExcelApi 1.9**. If it isn't supported, the code gives the user a message saying that this feature of the add-in isn't available on their version of Office. > [!TIP] -> There's no point to repeating a **Requirement** element in a **\** that already appears in the base manifest. If the requirement is specified in the base manifest, then the add-in can't install where the requirement isn't supported so Office doesn't even parse the **\** element. +> There's no point to repeating a **\** element in a **\** that already appears in the base manifest. If the requirement is specified in the base manifest, then the add-in can't install where the requirement isn't supported so Office doesn't even parse the **\** element. ## See also diff --git a/docs/resources/resources-glossary.md b/docs/resources/resources-glossary.md index e7425d5809..511ec20cce 100644 --- a/docs/resources/resources-glossary.md +++ b/docs/resources/resources-glossary.md @@ -1,7 +1,7 @@ --- title: Office Add-ins glossary of terms description: A glossary of terms commonly used throughout the Office Add-ins documentation. -ms.date: 10/01/2024 +ms.date: 10/05/2024 ms.topic: glossary ms.localizationpriority: medium --- @@ -146,6 +146,12 @@ A **runtime** is the host environment (including a JavaScript engine and usually See also: [custom functions runtime](#custom-functions-runtime), [shared runtime](#shared-runtime), [webview](#webview). +## setless API + +An API in the Office JavaScript Library that is not included in any requirement set. + +See also [requirement set](#requirement-set). + ## shared runtime A **shared runtime**, enables code in your task pane, function commands, and custom functions, to run in the same runtime and continue running even when the task pane is closed. Code in dialogs generally runs in a separate runtime even when the add-in is configured to use a shared runtime. See [shared runtime](../testing/runtimes.md#shared-runtime) and [Tips for using the shared runtime in your Office Add-in](https://devblogs.microsoft.com/microsoft365dev/tips-for-using-the-shared-javascript-runtime-in-your-office-add-in%e2%80%af/) to learn more.