diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 4bdddea2b..8bf31e3ed 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -1289,6 +1289,10 @@ "source_path": "docs/outlook/use-regular-expressions-to-show-an-outlook-add-in.md", "redirect_url": "/office/dev/add-ins/outlook/contextual-outlook-add-ins" }, + { + "source_path": "docs/develop/extended-overrides.md", + "redirect_url": "/javascript/api/manifest/extendedoverrides" + }, { "source_path": "docs/outlook/activation-rules.md", "redirect_url": "/javascript/api/manifest/rule" diff --git a/docs/design/keyboard-shortcuts.md b/docs/design/keyboard-shortcuts.md index 2d452fb5b..6ad5bb941 100644 --- a/docs/design/keyboard-shortcuts.md +++ b/docs/design/keyboard-shortcuts.md @@ -12,9 +12,9 @@ Keyboard shortcuts, also known as key combinations, make it possible for your ad There are three steps to add keyboard shortcuts to an add-in. -1. [Configure the add-in's manifest](#configure-the-manifest). -1. [Create or edit the shortcuts JSON file](#create-or-edit-the-shortcuts-json-file) to define actions and their keyboard shortcuts. -1. [Map custom actions to their functions](#map-custom-actions-to-their-functions) using the [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) API. +1. [Configure the add-in's manifest to use a shared runtime](#define-custom-keyboard-shortcuts). +1. [Define custom keyboard shortcuts](#define-custom-keyboard-shortcuts) and the actions they'll run. +1. [Map custom actions to their functions](#map-custom-actions-to-their-functions) using the [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member) API. ## Prerequisites @@ -36,31 +36,102 @@ Additionally, keyboard shortcuts only work on platforms that support the followi > [!TIP] > To start with a working version of an add-in with keyboard shortcuts already configured, clone and run the [Use keyboard shortcuts for Office Add-in actions](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/office-keyboard-shortcuts) sample. When you're ready to add keyboard shortcuts to your own add-in, continue with this article. -## Configure the manifest +## Define custom keyboard shortcuts -There are two small changes to make to the manifest. One is to enable the add-in to use a shared runtime and the other is to point to a JSON-formatted file where you defined the keyboard shortcuts. +The process to define custom keyboard shortcuts for your add-in varies depending on the type of manifest your add-in uses. Select the tab for the type of manifest you're using. -### Configure the add-in to use a shared runtime +> [!TIP] +> To learn more about manifests for Office Add-ins, see [Office Add-ins manifest](../develop/add-in-manifests.md). -Adding custom keyboard shortcuts requires your add-in to use the [shared runtime](../testing/runtimes.md#shared-runtime). For more information, see [Configure an add-in to use a shared runtime](../develop/configure-your-add-in-to-use-a-shared-runtime.md). +# [Unified app manifest for Microsoft 365](#tab/jsonmanifest) -### Link the mapping file to the manifest +> [!NOTE] +> Implementing keyboard shortcuts with the unified app manifest for Microsoft 365 is in public developer preview. It's currently only available in **Excel**. This shouldn't be used in production add-ins. We invite you to try it out in test or development environments. For more information, see the [Public developer preview app manifest schema](/microsoftteams/platform/resources/schema/manifest-schema-dev-preview). -Immediately *below* (not inside) the **\** element in the manifest, add an [ExtendedOverrides](/javascript/api/manifest/extendedoverrides) element. Set the `Url` attribute to the full URL of a JSON file in your project that you'll create in a later step. +If your add-in uses the unified app manifest for Microsoft 365, custom keyboard shortcuts and their actions are defined in the manifest. -```xml - ... - - - -``` +1. In your add-in project, open the **manifest.json** file. +1. Add the following object to the "extensions.runtimes" array. Note the following about this markup. + - The "actions" objects specify the functions your add-in can run. In the following example, an add-in will be able to show and hide a task pane. You'll create these functions in a later section. Currently, custom keyboard shortcuts can only run actions that are of type "executeFunction". + - While the "actions.displayName" property is optional, it's required if a custom keyboard shortcut will be created for the action. This property is used to describe the action of a keyboard shortcut. The description you provide appears in the dialog that's shown to a user when there's a shortcut conflict between multiple add-ins or with Microsoft 365. Office appends the name of the add-in in parentheses at the end of the description. For more information on how conflicts with keyboard shortcuts are handled, see [Avoid key combinations in use by other add-ins](#avoid-key-combinations-in-use-by-other-add-ins). -## Create or edit the shortcuts JSON file + ```json + "runtimes": [ + { + "id": "TaskPaneRuntime", + "type": "general", + "code": { + "page": "https://localhost:3000/taskpane.html" + }, + "lifetime": "long", + "actions": [ + { + "id": "ShowTaskpane", + "type": "executeFunction", + "displayName": "Show task pane (Contoso Add-in)" + }, + { + "id": "HideTaskpane", + "type": "executeFunction", + "displayName": "Hide task pane (Contoso Add-in)" + } + ], + } + ] + ``` -Custom keyboard shortcuts are defined in a JSON file. This file describes your keyboard shortcuts and the actions that they'll invoke. The complete schema for the JSON file is at [extended-manifest.schema.json](https://developer.microsoft.com/json-schemas/office-js/extended-manifest.schema.json). +1. Add the following to the "extensions" array. Note the following about the markup. + - The SharedRuntime 1.1 requirement set is specified in the "requirements.capabilities" object to support custom keyboard shortcuts. + - Each "shortcuts" object represents a single action that's invoked by a keyboard shortcut. It specifies the supported key combinations for various platforms, such as Office on the web, on Windows, and on Mac. For guidance on how to create custom key combinations, see [Guidelines for custom key combinations](#guidelines-for-custom-key-combinations). + - A default key combination must be specified. It's used on all supported platforms if there isn't a specific combination configured for a particular platform. + - The value of the "actionId" property must match the value specified in the "id" property of the applicable "extensions.runtimes.actions" object. -1. In your add-in project, create a JSON file. Be sure the path of the file matches the location you specified for the `Url` attribute of the [ExtendedOverrides](/javascript/api/manifest/extendedoverrides) element. + ```json + "keyboardShortcuts": [ + { + "requirements": { + "capabilities": [ + { + "name": "SharedRuntime", + "minVersion": "1.1" + } + ] + }, + "shortcuts": [ + { + "key": { + "default": "Ctrl+Alt+Up", + "mac": "Command+Shift+Up", + "web": "Ctrl+Alt+1", + "windows": "Ctrl+Alt+Up" + }, + "actionId": "ShowTaskpane" + }, + { + "key": { + "default": "Ctrl+Alt+Down", + "mac": "Command+Shift+Down", + "web": "Ctrl+Alt+2", + "windows": "Ctrl+Alt+Up" + }, + "actionId": "HideTaskpane" + } + ] + } + ] + ``` +# [Add-in only manifest](#tab/xmlmanifest) + +### Configure the manifest to use a shared runtime + +To customize keyboard shortcuts for your add-in, you must first configure the add-in manifest to use a [shared runtime](../testing/runtimes.md#shared-runtime). For guidance on how to configure your add-in to use a shared runtime, see [Configure an add-in to use a shared runtime](../develop/configure-your-add-in-to-use-a-shared-runtime.md). + +### Create or edit the shortcuts JSON file + +If your add-in uses an add-in only manifest, custom keyboard shortcuts are defined in a JSON file. This file describes your keyboard shortcuts and the actions that they'll invoke. The complete schema for the JSON file is at [extended-manifest.schema.json](https://developer.microsoft.com/json-schemas/office-js/extended-manifest.schema.json). + +1. In your add-in project, create a JSON file. 1. Add the following markup to the file. Note the following about the code. - The "actions" array contains objects that define the actions to be invoked. The "actions.id" and "actions.name" properties are required. - The "actions.id" property uniquely identifies the action to invoke using a keyboard shortcut. @@ -111,22 +182,37 @@ Custom keyboard shortcuts are defined in a JSON file. This file describes your k } ``` +### Link the mapping file to the manifest + +1. In your add-in project, open the **manifest.xml** file. +1. Immediately *below* (not inside) the **\** element in the manifest, add an [ExtendedOverrides](/javascript/api/manifest/extendedoverrides) element. Set the `Url` attribute to the full URL of the JSON file you created in a previous step. + +```xml + ... + + + +``` + +--- + ## Map custom actions to their functions 1. In your project, open the JavaScript file loaded by your HTML page in the **\** element. -1. In the JavaScript file, use the [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member(1)) API to map each action that you specified in the JSON file to a JavaScript function. Add the following JavaScript to the file. Note the following about the code. - - - The first parameter is one of the actions from the JSON file. - - The second parameter is the function that runs when a user presses the key combination that's mapped to the action in the JSON file. +1. In the JavaScript file, use the [Office.actions.associate](/javascript/api/office/office.actions#office-office-actions-associate-member) API to map each action you specified in an earlier step to a JavaScript function. Add the following JavaScript to the file. Note the following about the code. + - The first parameter is the name of an action that you mapped to a keyboard shortcut. The location of the name of the action depends on the type of manifest your add-in uses. + - **Unified app manifest for Microsoft 365**: The value of the "extensions.keyboardShortcuts.shortcuts.actionId" property in the **manifest.json** file. + - **Add-in only manifest**: The value of the "actions.id" property in the shortcuts JSON file. + - The second parameter is the function that runs when a user presses the key combination that's mapped to an action. ```javascript - Office.actions.associate("ShowTaskpane", () => { - return Office.addin.showAsTaskpane() - .then(() => { + Office.actions.associate("ShowTaskpane", () => { + return Office.addin.showAsTaskpane() + .then(() => { return; }) - .catch((error) => { - return error.code; + .catch((error) => { + return error.code; }); }); ``` @@ -157,7 +243,7 @@ Use the following guidelines to create custom key combinations for your add-ins. > [!NOTE] > Custom keyboard shortcuts must be pressed simultaneously. KeyTips, also known as sequential key shortcuts (for example, Alt+H, H), aren't supported in Office Add-ins. -### Browser shortcuts that cannot be overridden +### Browser shortcuts that can't be overridden When using custom keyboard shortcuts on the web, some keyboard shortcuts that are used by the browser can't be overridden by add-ins. The following list is a work in progress. If you discover other combinations that can't be overridden, please let us know by using the feedback tool at the bottom of this page. @@ -172,7 +258,9 @@ When using custom keyboard shortcuts on the web, some keyboard shortcuts that ar There are many keyboard shortcuts that are already in use by Microsoft 365. Avoid registering keyboard shortcuts for your add-in that are already in use. However, there may be some instances where it's necessary to override existing keyboard shortcuts or handle conflicts between multiple add-ins that have registered the same keyboard shortcut. -In the case of a conflict, the user will see a dialog box the first time they attempt to use a conflicting keyboard shortcut. Note that the text for the add-in option that's displayed in this dialog comes from the "actions.name" property in the shortcuts JSON file. +In the case of a conflict, the user will see a dialog box the first time they attempt to use a conflicting keyboard shortcut. Note that the source of the text for the add-in option that's displayed in this dialog varies depending on the type of manifest your add-in uses. + - **Unified app manifest for Microsoft 365**: The value of the "extensions.runtimes.actions.displayName" property in the **manifest.json** file. + - **Add-in only manifest**: The value of the "actions.name" property in the shortcuts JSON file. ![A conflict modal with two different actions for a single shortcut.](../images/add-in-shortcut-conflict-modal.png) @@ -180,12 +268,10 @@ The user can select which action the keyboard shortcut will take. After making t ![The Tell me search box in Excel showing the reset Office Add-in shortcut preferences action.](../images/add-in-reset-shortcuts-action.png) -For the best user experience, we recommend that you minimize keyboard shortcut conflicts with these good practices. +For the best user experience, we recommend that you minimize conflicts with Excel with these good practices. - Use only keyboard shortcuts with the following pattern: **Ctrl+Shift+Alt+*x***, where *x* is some other key. -- Avoid using established keyboard shortcuts in Excel and Word. For a list, see the following: - - [Keyboard shortcuts in Excel](https://support.microsoft.com/office/1798d9d5-842a-42b8-9c99-9b7213f0040f) - - [Keyboard shortcuts in Word](https://support.microsoft.com/office/95ef89dd-7142-4b50-afb2-f762f663ceb2) +- If you need more keyboard shortcuts, check the [list of Excel keyboard shortcuts](https://support.microsoft.com/office/1798d9d5-842a-42b8-9c99-9b7213f0040f), and avoid using any of them in your add-in. - When the keyboard focus is inside the add-in UI, **Ctrl+Spacebar** and **Ctrl+Shift+F10** won't work as these are essential accessibility shortcuts. - On a Windows or Mac computer, if the **Reset Office Add-ins shortcut preferences** command isn't available on the search menu, the user can manually add the command to the ribbon by customizing the ribbon through the context menu. @@ -196,7 +282,108 @@ You may need to localize your custom keyboard shortcuts in the following scenari - Your add-in supports multiple locales. - Your add-in supports different alphabets, writing systems, or keyboard layouts. -For information about how to localize the keyboard shortcuts JSON, see [Localize extended overrides](../develop/localization.md#localize-extended-overrides). +Guidance on how to localize your keyboard shortcuts varies depending on the type of manifest your add-in uses. + +# [Unified app manifest for Microsoft 365](#tab/jsonmanifest) + +To learn how to localize your custom keyboard shortcuts with the unified app manifest for Microsoft 365, see [Localize strings in your app manifest](/microsoftteams/platform/concepts/build-and-test/apps-localization). + +# [Add-in only manifest](#tab/xmlmanifest) + +Use the `ResourceUrl` attribute of the [ExtendedOverrides](/javascript/api/manifest/extendedoverrides) element to point Microsoft 365 to a file of localized resources. The following is an example. + +```xml + ... + + + + +``` + +The extended overrides file then uses tokens instead of strings. The tokens name strings in the resource file. The following is an example that assigns a keyboard shortcut to a function (defined elsewhere) that displays the add-in's task pane. Note about this markup: + +- The example isn't quite valid. (We add a required additional property to it in a later step.) +- The tokens must have the format **${resource.*name-of-resource*}**. + +```json +{ + "actions": [ + { + "id": "ShowTaskpane", + "type": "ExecuteFunction", + "name": "${resource.ShowTaskpane_action_name}" + } + ], + "shortcuts": [ + { + "action": "ShowTaskpane", + "key": { + "default": "${resource.ShowTaskpane_default_shortcut}" + } + } + ] +} +``` + +The resource file, which is also JSON-formatted, has a top-level `resources` property that's divided into subproperties by locale. For each locale, a string is assigned to each token that was used in the extended overrides file. The following is an example which has strings for `en-us` and `fr-fr`. In this example, the keyboard shortcut is the same in both locales, but that won't always be the case, especially when you are localizing for locales that have a different alphabet or writing system, and hence a different keyboard. + +```json +{ + "resources":{ + "en-us": { + "ShowTaskpane_default_shortcut": { + "value": "CTRL+SHIFT+A", + }, + "ShowTaskpane_action_name": { + "value": "Show task pane for add-in", + }, + }, + "fr-fr": { + "ShowTaskpane_default_shortcut": { + "value": "CTRL+SHIFT+A", + }, + "ShowTaskpane_action_name": { + "value": "Afficher le volet de tâche pour add-in", + } + } + } +} +``` + +There is no `default` property in the file that's a peer to the `en-us` and `fr-fr` sections. This is because the default strings, which are used when the locale of the Microsoft 365 host application doesn't match any of the *ll-cc* properties in the resources file, *must be defined in the extended overrides file itself*. Defining the default strings directly in the extended overrides file ensures that Microsoft 365 doesn't download the resource file when the locale of the Microsoft 365 application matches the default locale of the add-in (as specified in the manifest). The following is a corrected version of the preceding example of an extended overrides file that uses resource tokens. + +```json +{ + "actions": [ + { + "id": "ShowTaskpane", + "type": "ExecuteFunction", + "name": "${resource.ShowTaskpane_action_name}" + } + ], + "shortcuts": [ + { + "action": "ShowTaskpane", + "key": { + "default": "${resource.ShowTaskpane_default_shortcut}" + } + } + ], + "resources": { + "default": { + "ShowTaskpane_default_shortcut": { + "value": "CTRL+SHIFT+A", + }, + "ShowTaskpane_action_name": { + "value": "Show task pane for add-in", + } + } + } +} +``` + +--- ## Turn on shortcut customization for specific users @@ -230,19 +417,20 @@ To find out what shortcuts are already in use for the user, call the [Office.act - If there was a conflict with the shortcut and the user has chosen to use a different action (either native or another add-in) for that keyboard combination, the value returned will be `null` since the shortcut has been overridden and there's no keyboard combination the user can currently use to invoke that add-in action. - If the shortcut has been customized using the [Office.actions.replaceShortcuts](/javascript/api/office/office.actions#office-office-actions-replaceshortcuts-member) method, the value returned will be the customized keyboard combination. -- If the shortcut hasn't been overridden or customized, it will return the value from the add-in's extended manifest JSON. +- If the shortcut hasn't been overridden or customized, the value returned varies depending on the type of manifest the add-in uses. + - **Unified app manifest for Microsoft 365**: The shortcut specified in the **manifest.json** file of the add-in. + - **Add-in only manifest**: The shortcut specified in the shortcuts JSON file of the add-in. The following is an example. ```javascript Office.actions.getShortcuts() - .then(function (userShortcuts) { + .then((userShortcuts) => { for (const action in userShortcuts) { let shortcut = userShortcuts[action]; console.log(action + ": " + shortcut); } }); - ``` As described in [Avoid key combinations in use by other add-ins](#avoid-key-combinations-in-use-by-other-add-ins), it's a good practice to avoid conflicts in shortcuts. To discover if one or more key combinations are already in use, pass them as an array of strings to the [Office.actions.areShortcutsInUse](/javascript/api/office/office.actions#office-office-actions-areshortcutsinuse-member) method. The method returns a report containing key combinations that are already in use in the form of an array of objects of type `{shortcut: string, inUse: boolean}`. The `shortcut` property is a key combination, such as "Ctrl+Shift+1". If the combination is already registered to another action, the `inUse` property is set to `true`. For example, `[{shortcut: "Ctrl+Shift+1", inUse: true}, {shortcut: "Ctrl+Shift+2", inUse: false}]`. The following code snippet is an example. diff --git a/docs/develop/extended-overrides.md b/docs/develop/extended-overrides.md deleted file mode 100644 index 0f13ed36c..000000000 --- a/docs/develop/extended-overrides.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Work with extended overrides of the manifest -description: Learn how to configure extensibility features with extended overrides of the manifest. -ms.topic: how-to -ms.date: 08/18/2023 -ms.localizationpriority: medium ---- - -# Work with Extended Overrides of the manifest - -When your add-in uses the XML-formatted add-in only manifest, some extensibility features of Office Add-ins are configured with JSON files that are hosted on your server, instead of with the add-in's manifest. - -> [!NOTE] -> This article assumes that you're familiar with Office Add-in manifests and their role in add-ins. Please read [Office Add-ins manifest](add-in-manifests.md), if you haven't recently. - -The following table specifies the extensibility features that require an extended override along with links to documentation of the feature. - -| Feature | Development Instructions | -| :----- | :----- | -| Keyboard shortcuts | [Add Custom keyboard shortcuts to your Office Add-ins](../design/keyboard-shortcuts.md) | - - -The schema that defines the JSON format is [extended-manifest schema](https://developer.microsoft.com/json-schemas/office-js/extended-manifest.schema.json). - -> [!TIP] -> This article is somewhat abstract. Consider reading one of the articles in the table to add clarity to the concepts. - -## Tell Office where to find the JSON file - -Use the manifest to tell Office where to find the JSON file. Immediately *below* (not inside) the **\** element in the manifest, add an [ExtendedOverrides](/javascript/api/manifest/extendedoverrides) element. Set the `Url` attribute to the full URL of a JSON file. The following is an example of the simplest possible **\** element. - -```xml - ... - - - -``` - -The following is an example of a very simple extended overrides JSON file. It assigns keyboard shortcut CTRL+SHIFT+A to a function (defined elsewhere) that opens the add-in's task pane. - -```json -{ - "actions": [ - { - "id": "SHOWTASKPANE", - "type": "ExecuteFunction", - "name": "Show task pane for add-in" - } - ], - "shortcuts": [ - { - "action": "SHOWTASKPANE", - "key": { - "default": "CTRL+SHIFT+A" - } - } - ] -} -``` - -## Localize the extended overrides file - -If your add-in supports multiple locales, you can use the `ResourceUrl` attribute of the **\** element to point Office to a file of localized resources. The following is an example. - -```xml - ... - - - - -``` - -For more details about how to create and use the resources file, how to refer to its resources in the extended overrides file, and for additional options not discussed here, see [Localize extended overrides](localization.md#localize-extended-overrides). diff --git a/docs/develop/json-manifest-overview.md b/docs/develop/json-manifest-overview.md index 7e41364df..c6f923612 100644 --- a/docs/develop/json-manifest-overview.md +++ b/docs/develop/json-manifest-overview.md @@ -91,9 +91,10 @@ The following table shows a mapping of *some* high-level child properties of the | "requirements.capabilities" | Identifies the [requirement sets](office-versions-and-requirement-sets.md#office-requirement-sets-availability) that the add-in needs to be installable. that the add-in needs to be installable. | **\** and **\** |*None* | | "requirements.scopes" | Identifies the Office applications in which the add-in can be installed. | **\** |*None* | | "ribbons" | The ribbons that the add-in customizes. | **\**, **ExtensionPoints**, and various **\*FormFactor** elements | The "ribbons" property is an array of anonymous objects that each merge the purposes of the these three elements. See ["ribbons" table](#ribbons-table).| -| "alternates" | Specifies backwards compatibility with an equivalent COM add-in, XLL, or both. | **\** | See the [EquivalentAddins - See also](/javascript/api/manifest/equivalentaddins#see-also) for background information. | -| "runtimes" | Configures the [embedded runtimes](../testing/runtimes.md) that the add-in uses, including various kinds of add-ins that have little or no UI, such as custom function-only add-ins and [function commands](../design/add-in-commands.md#types-of-add-in-commands). | **\**. **\**, and **\** (of type CustomFunctions) |*None* | -| "autoRunEvents" | Configures an event handler for a specified event. | **\** (of type LaunchEvent) |*None* | +| "alternatives" | Specifies backwards compatibility with an equivalent COM add-in, XLL, or both. | **\** | See the [EquivalentAddins - See also](/javascript/api/manifest/equivalentaddins#see-also) for background information. | +| "runtimes" | Configures the [embedded runtimes](../testing/runtimes.md) that the add-in uses, including various kinds of add-ins that have little or no UI, such as custom function-only add-ins and [function commands](../design/add-in-commands.md#types-of-add-in-commands). | **\**. **\**, and **\** (of type CustomFunctions) |*None.* | +| "autoRunEvents" | Configures an event handler for a specified event. | **\** (of type LaunchEvent) |*None.* | +| "keyboardShortcuts" (developer preview) | Defines custom keyboard shortcuts or key combinations to run specific actions. | **\** | *None.* | #### "ribbons" table diff --git a/docs/develop/localization.md b/docs/develop/localization.md index 602bab751..de4647731 100644 --- a/docs/develop/localization.md +++ b/docs/develop/localization.md @@ -1,7 +1,7 @@ --- title: Localization for Office Add-ins description: Use the Office JavaScript API to determine a locale and display strings based on the locale of the Office application, or to interpret or display data based on the locale of the data. -ms.date: 04/12/2024 +ms.date: 07/18/2024 ms.topic: how-to ms.localizationpriority: medium --- @@ -43,7 +43,40 @@ The Office JavaScript API provides two properties that support displaying or int ## Control localization from the manifest -The techniques for localizing with the manifest differ depending on whether you are using the add-in only manifest or the unified manifest for Microsoft 365, which is supported only on Outlook. +The techniques for localizing with the manifest differ depending on whether you're using the add-in only manifest or the unified app manifest for Microsoft 365. + +# [Unified app manifest for Microsoft 365](#tab/jsonmanifest) + +When using the unified app manifest for Microsoft 365, localize the public-facing strings in the manifest as described in [Localize strings in your app manifest](/microsoftteams/platform/concepts/build-and-test/apps-localization#localize-strings-in-your-app-manifest). The following is an example for an Outlook add-in. First is the "localizationInfo" object in the manifest. Below that is the fr-fr.json file with the translated strings. The add-in has a task pane (with a French version of the home page), localized French icons, and a custom ribbon button that opens a video player in a dialog box. + +```json +"localizationInfo": { + "defaultLanguageTag": "en", + "additionalLanguages": [ + { + "languageTag": "fr-fr", + "file": "fr-fr.json" + } + ] +} +``` + +```json +{ + "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.Localization.schema.json", + "name.short": "Lecteur vidéo", + "name.full": "Lecteur vidéo pour Outlook", + "description.short": "Voir les vidéos YouTube dans Outlook via les mails.", + "description.full": "Visualisez les vidéos YouTube référencées dans vos courriers électronique directement depuis Outlook.", + "icons.color": "https://localhost:3000/assets/fr-fr/icon-128.png", + "extensions[0].audienceClaimUrl": "https://localhost:3000/fr-fr/taskpane.html", + "extensions[0].ribbons[0].tabs[0].groups[0].label": "Outils de médias", + "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].icons[0].url": "https://localhost:3000/assets/fr-fr/player-icon.png", + "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].label": "Ouvrir le lecteur vidéo", + "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].supertip.description": "Cliquez pour ouvrir le lecteur vidéo.", + "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].supertip.title": "Ouvrir le lecteur vidéo", +} +``` # [Add-in only manifest](#tab/xmlmanifest) @@ -140,141 +173,8 @@ For Outlook add-ins, the [SourceLocation] element also aligns to the form factor ``` -# [Unified manifest](#tab/jsonmanifest) - -When using the unified manifest, localize the public-facing strings in the manifest as described in [Localize strings in your app manifest](/microsoftteams/platform/concepts/build-and-test/apps-localization#localize-strings-in-your-app-manifest). The following is an example for an Outlook add-in. First is the "localizationInfo" object in the manifest. Below that is the fr-fr.json file with the translated strings. The add-in has a task pane (with a French version of the home page), localized French icons, and a custom ribbon button that opens a video player in a dialog box. - -```json -"localizationInfo": { - "defaultLanguageTag": "en", - "additionalLanguages": [ - { - "languageTag": "fr-fr", - "file": "fr-fr.json" - } - ] -} -``` - -```json -{ - "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.Localization.schema.json", - "name.short": "Lecteur vidéo", - "name.full": "Lecteur vidéo pour Outlook", - "description.short": "Voir les vidéos YouTube dans Outlook via les mails.", - "description.full": "Visualisez les vidéos YouTube référencées dans vos courriers électronique directement depuis Outlook.", - "icons.color": "https://localhost:3000/assets/fr-fr/icon-128.png", - "extensions[0].audienceClaimUrl": "https://localhost:3000/fr-fr/taskpane.html", - "extensions[0].ribbons[0].tabs[0].groups[0].label": "Outils de médias", - "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].icons[0].url": "https://localhost:3000/assets/fr-fr/player-icon.png", - "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].label": "Ouvrir le lecteur vidéo", - "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].supertip.description": "Cliquez pour ouvrir le lecteur vidéo.", - "extensions[0].ribbons[0].tabs[0].groups[0].controls[0].supertip.title": "Ouvrir le lecteur vidéo", -} -``` - --- -## Localize extended overrides - -> [!NOTE] -> This section isn't applicable if you're using the unified manifest. - -When the add-in is using an add-in only manifest, some extensibility features of Office Add-ins, such as keyboard shortcuts, are configured with JSON files that are hosted on your server, instead of with the add-in's XML-formatted manifest. This section assumes that you're familiar with extended overrides. See [Work with extended overrides of the manifest](extended-overrides.md) and [ExtendedOverrides](/javascript/api/manifest/extendedoverrides) element. - -Use the `ResourceUrl` attribute of the [ExtendedOverrides](/javascript/api/manifest/extendedoverrides) element to point Office to a file of localized resources. The following is an example. - -```xml - ... - - - - -``` - -The extended overrides file then uses tokens instead of strings. The tokens name strings in the resource file. The following is an example that assigns a keyboard shortcut to a function (defined elsewhere) that displays the add-in's task pane. Note about this markup: - -- The example isn't quite valid. (We add a required additional property to it below.) -- The tokens must have the format **${resource.*name-of-resource*}**. - -```json -{ - "actions": [ - { - "id": "SHOWTASKPANE", - "type": "ExecuteFunction", - "name": "${resource.SHOWTASKPANE_action_name}" - } - ], - "shortcuts": [ - { - "action": "SHOWTASKPANE", - "key": { - "default": "${resource.SHOWTASKPANE_default_shortcut}" - } - } - ] -} -``` - -The resource file, which is also JSON-formatted, has a top-level `resources` property that is divided into subproperties by locale. For each locale, a string is assigned to each token that was used in the extended overrides file. The following is an example which has strings for `en-us` and `fr-fr`. In this example, the keyboard shortcut is the same in both locales, but that won't always be the case, especially when you are localizing for locales that have a different alphabet or writing system, and hence a different keyboard. - -```json -{ - "resources":{ - "en-us": { - "SHOWTASKPANE_default_shortcut": { - "value": "CTRL+SHIFT+A", - }, - "SHOWTASKPANE_action_name": { - "value": "Show task pane for add-in", - }, - }, - "fr-fr": { - "SHOWTASKPANE_default_shortcut": { - "value": "CTRL+SHIFT+A", - }, - "SHOWTASKPANE_action_name": { - "value": "Afficher le volet de tâche pour add-in", - } - } - } -} -``` - -There is no `default` property in the file that is a peer to the `en-us` and `fr-fr` sections. This is because the default strings, which are used when the locale of the Office host application doesn't match any of the *ll-cc* properties in the resources file, *must be defined in the extended overrides file itself*. Defining the default strings directly in the extended overrides file ensures that Office doesn't download the resource file when the locale of the Office application matches the default locale of the add-in (as specified in the manifest). The following is a corrected version of the preceding example of an extended overrides file that uses resource tokens. - -```json -{ - "actions": [ - { - "id": "SHOWTASKPANE", - "type": "ExecuteFunction", - "name": "${resource.SHOWTASKPANE_action_name}" - } - ], - "shortcuts": [ - { - "action": "SHOWTASKPANE", - "key": { - "default": "${resource.SHOWTASKPANE_default_shortcut}" - } - } - ], - "resources": { - "default": { - "SHOWTASKPANE_default_shortcut": { - "value": "CTRL+SHIFT+A", - }, - "SHOWTASKPANE_action_name": { - "value": "Show task pane for add-in", - } - } - } -} -``` - ## Match date/time format with client locale You can get the locale of the user interface of the Office client application by using the **[displayLanguage]** property. You can then display date and time values in a format consistent with the current locale of the Office application. One way to do that is to prepare a resource file that specifies the date/time display format to use for each locale that your Office Add-in supports. At run time, your add-in can use the resource file and match the appropriate date/time format with the locale obtained from the **[displayLanguage]** property. @@ -309,7 +209,7 @@ After you install the Language Accessory Pack, you can configure Office to use t You'll need to create a Visual Studio Office Add-in project. > [!NOTE] -> If you haven't installed Visual Studio, see the [Visual Studio IDE page](https://visualstudio.microsoft.com/vs/) for download instructions. During installation you'll need to select the Office/SharePoint development workload. If you have previously installed Visual Studio 2019 or later, [use the Visual Studio Installer](/visualstudio/install/modify-visual-studio/) to ensure that the Office/SharePoint development workload is installed. +> If you haven't installed Visual Studio, see the [Visual Studio IDE page](https://visualstudio.microsoft.com/vs/) for download instructions. During installation you'll need to select the Office/SharePoint development workload. If you've previously installed Visual Studio 2019 or later, [use the Visual Studio Installer](/visualstudio/install/modify-visual-studio/) to ensure that the Office/SharePoint development workload is installed. 1. Choose **Create a new project**. @@ -331,7 +231,7 @@ The text that you want to localize for another language appears in two areas. 1. In **Solution Explorer**, expand **WorldReadyAddIn**, **WorldReadyAddInManifest**, and then choose **WorldReadyAddIn.xml**. -1. In WorldReadyAddInManifest.xml, replace the [DisplayName] and [Description] elements with the following block of code. +1. In **WorldReadyAddInManifest.xml**, replace the [DisplayName] and [Description] elements with the following block of code. > [!NOTE] > You can replace the Spanish language localized strings used in this example for the [DisplayName] and [Description] elements with the localized strings for any other language. @@ -351,7 +251,7 @@ The text that you want to localize for another language appears in two areas. 1. In Visual Studio, in **Solution Explorer**, choose **Home.html**. -1. Replace the `` element contents in Home.html with the following HTML, and save the file. +1. Replace the `` element contents in **Home.html** with the following HTML, and save the file. ```html @@ -383,44 +283,39 @@ To enable localized strings for the heading and paragraph, you place the strings #### Add the resource file to the add-in project -1. In **Solution Explorer** in Visual Studio, right-click (or select and hold) the **WorldReadyAddInWeb** project and choose **Add** > **New Item**. +1. In **Solution Explorer** in Visual Studio, right-click (or select and hold) the **WorldReadyAddInWeb** project, then choose **Add** > **New Item**. 1. In the **Add New Item** dialog box, choose **JavaScript File**. 1. Enter **UIStrings.js** as the file name and choose **Add**. -1. Add the following code to the UIStrings.js file, and save the file. +1. Add the following code to the **UIStrings.js** file, and save the file. ```js /* Store the locale-specific strings */ - const UIStrings = (function () - { + const UIStrings = (() => { "use strict"; const UIStrings = {}; // JSON object for English strings - UIStrings.EN = - { + UIStrings.EN = { "Greeting": "Welcome", "Introduction": "This is my localized add-in." }; // JSON object for Spanish strings - UIStrings.ES = - { + UIStrings.ES = { "Greeting": "Bienvenido", "Introduction": "Esta es mi aplicación localizada." }; - UIStrings.getLocaleStrings = function (locale) - { + UIStrings.getLocaleStrings = (locale) => { let text; // Get the resource strings that match the language. - switch (locale) - { + switch (locale) { case 'en-US': text = UIStrings.EN; break; @@ -439,11 +334,11 @@ To enable localized strings for the heading and paragraph, you place the strings })(); ``` -The UIStrings.js resource file creates an object, **UIStrings**, which contains the localized strings for your add-in UI. +The **UIStrings.js** resource file creates an object, **UIStrings**, which contains the localized strings for your add-in UI. #### Localize the text used for the add-in UI -To use the resource file in your add-in, you'll need to add a script tag for it on Home.html. When Home.html is loaded, UIStrings.js executes and the **UIStrings** object that you use to get the strings is available to your code. Add the following HTML in the head tag for Home.html to make **UIStrings** available to your code. +To use the resource file in your add-in, you'll need to add a script tag for it on **Home.html**. When **Home.html** is loaded, **UIStrings.js** executes and the **UIStrings** object that you use to get the strings is available to your code. Add the following HTML in the head tag for **Home.html** to make **UIStrings** available to your code. ```html @@ -458,7 +353,7 @@ If you want to change the localization for your add-in based on what language is After you know the language the application is using, you can use **UIStrings** to get the set of localized strings that matches the application language. -Replace the code in the Home.js file with the following code. The code shows how you can change the strings used in the UI elements on Home.html based on either the display language of the application or the editing language of the application. +Replace the code in the **Home.js** file with the following code. The code shows how you can change the strings used in the UI elements on **Home.html** based on either the display language of the application or the editing language of the application. > [!NOTE] > To switch between changing the localization of the add-in based on the language used for editing, uncomment the line of code `const myLanguage = Office.context.contentLanguage;` and comment out the line of code `const myLanguage = Office.context.displayLanguage;` @@ -468,33 +363,31 @@ Replace the code in the Home.js file with the following code. The code shows how /// -(function () { +(() => { "use strict"; // The initialize function must be run each time a new page is loaded. - Office.initialize = function (reason) - { - - $(document).ready(function () { + Office.onReady(() => { + $(document).ready(() => { // Get the language setting for editing document content. // To test this, uncomment the following line and then comment out the // line that uses Office.context.displayLanguage. // const myLanguage = Office.context.contentLanguage; - + // Get the language setting for UI display in the Office application. const myLanguage = Office.context.displayLanguage; let UIText; - + // Get the resource strings that match the language. // Use the UIStrings object from the UIStrings.js file // to get the JSON object with the correct localized strings. UIText = UIStrings.getLocaleStrings(myLanguage); - + // Set localized text for UI elements. $("#greeting").text(UIText.Greeting); $("#about").text(UIText.Introduction); }); - }; + }); })(); ``` @@ -504,8 +397,6 @@ To test your localized add-in, change the language used for display or editing i 1. In Word, choose **File** > **Options** > **Language**. The following figure shows the **Word Options** dialog box opened to the Language tab. - *Figure 2. Language options in the Word Options dialog box* - ![Word Options dialog.](../images/office15-app-how-to-localize-fig04.png) 2. Under **Choose Display Language**, select the language that you want for display, for example Spanish, and then choose the up arrow to move the Spanish language to the first position in the list. Alternatively, to change the language used for editing, under **Choose Editing Languages**, choose the language you want to use for editing, for example, Spanish, and then choose **Set as Default**. diff --git a/docs/develop/requirements-property-unified-manifest.md b/docs/develop/requirements-property-unified-manifest.md index efe33cc78..ff616345f 100644 --- a/docs/develop/requirements-property-unified-manifest.md +++ b/docs/develop/requirements-property-unified-manifest.md @@ -1,7 +1,7 @@ --- title: Specify Office Add-in requirements in the unified manifest for Microsoft 365 description: Learn how to use requirements to configure on which host and platforms an add-in can be installed and which features are available. -ms.date: 07/03/2024 +ms.date: 07/18/2024 ms.topic: how-to ms.localizationpriority: medium --- @@ -230,3 +230,32 @@ The previous example shown in [extensions.autoRunEvents.requirements](#extension ``` Similarly, for the example in [extensions.ribbons.requirements](#extensionsribbonsrequirements), if the action linked to the custom button is the only action configured in a runtime object, then that runtime object should be blocked in the same circumstances in which the ribbon object is blocked. + +### extensions.keyboardShortcuts.requirements (developer preview) + +The `extensions.keyboardShortcuts` property defines custom keyboard shortcuts or key combinations to run specific actions. To learn how to create custom shortcuts, see [Add custom keyboard shortcuts to your Office Add-ins](../design/keyboard-shortcuts.md). + +The "requirements" subproperty can be used to ensure that the custom shortcuts are only available on platforms that support the [SharedRuntime 1.1 API](/javascript/api/requirement-sets/common/shared-runtime-requirement-sets). The following example shows how to configure this in your manifest. + +```json +"extensions": [ + ... + { + ... + "keyboardShortcuts": [ + { + //Insert details of the keyboard shortcut configuration here. + + "requirements" : { + "capabilities": [ + { + "name": "SharedRuntime", + "minVersion": "1.1" + } + ] + } + } + ] + } +] +``` diff --git a/docs/develop/unified-manifest-overview.md b/docs/develop/unified-manifest-overview.md index a1133da3b..df8779381 100644 --- a/docs/develop/unified-manifest-overview.md +++ b/docs/develop/unified-manifest-overview.md @@ -59,7 +59,7 @@ We're working hard to complete reference documentation for the "extensions" prop > This table contains only some selected representative descendant properties of "extensions". *It isn't an exhaustive list of all child properties of "extensions".* For the full reference of the unified manifest, see [Unified manifest for Microsoft 365](/microsoftteams/platform/resources/schema/manifest-schema). For the manifest reference that includes all the latest preview features, see [Public developer preview for the unified manifest for Microsoft 365](/microsoftteams/platform/resources/schema/manifest-schema-dev-preview). |JSON property|Purpose| -|:-----|:-----|:-----|:-----| +|:-----|:-----| | "requirements.capabilities" | Identifies the [requirement sets](office-versions-and-requirement-sets.md#office-requirement-sets-availability) that the add-in needs to be installable. | | "requirements.scopes" | Identifies the Office applications in which the add-in can be installed. For example, "mail" means the add-in can be installed in Outlook. | | "ribbons" | The ribbons that the add-in customizes. | @@ -70,6 +70,7 @@ We're working hard to complete reference documentation for the "extensions" prop | "alternates" | Specifies backwards compatibility with an equivalent COM add-in, XLL, or both. Also specifies the main icons that are used to represent the add-in on older versions of Office. | | "runtimes" | Configures the [embedded runtimes](../testing/runtimes.md) that the add-in uses, including various kinds of add-ins that have little or no UI, such as custom function-only add-ins and [function commands](../design/add-in-commands.md#types-of-add-in-commands). | | "autoRunEvents" | Configures an event handler for a specified event. | +| "keyboardShortcuts" (developer preview) | Defines custom keyboard shortcuts or key combinations to run specific actions. | ## Specify safe domains