Merge branch 'main' into live

github-actions · github-actions · commit c465b8831a0b · 2025-03-26T02:31:52.000Z
diff --git a/docs/design/contextual-tabs.md b/docs/design/contextual-tabs.md
@@ -1,7 +1,7 @@
 ---
 title: Create custom contextual tabs in Office Add-ins
 description: Learn how to add custom contextual tabs to your Office Add-in.
-ms.date: 03/11/2025
+ms.date: 03/26/2025
 ms.topic: how-to
 ms.localizationpriority: medium
 ---
@@ -635,12 +635,12 @@ The add-in's manifest provides a way to create a fallback experience in an add-i
 
 [!include[Unified manifest host application support note](../includes/unified-manifest-support-note.md)]
 
-Begin by defining a custom core tab (that is, *noncontextual* custom tab) in the manifest that duplicates the ribbon customizations of the custom contextual tabs in your add-in. Then, add an "overriddenByRibbonApi" property to each of the control objects and menu items and set its value to "true". The effect of doing so is the following:
+Begin by defining a custom core tab (that is, *noncontextual* custom tab) in the manifest that duplicates the ribbon customizations of the custom contextual tabs in your add-in. Then, mark any control groups, or individual controls, or menu items that shouldn't be visible on platforms that support contextual tabs. You mark a group, control, or menu item object by adding an "overriddenByRibbonApi" property to it and setting its value to "true". The effect of doing so is the following:
 
-- If the add-in runs on an application and platform that support custom contextual tabs, then the custom controls and menu items won't appear on the ribbon. Instead, the custom contextual tab will be created when the add-in calls the `requestCreateControls` method.
-- If the add-in runs on an application or platform that *doesn't* support `requestCreateControls`, then the controls and menu items do appear on the custom core tab.
+- If the add-in runs on an application and platform that support custom contextual tabs, then the marked custom groups, controls, and menu items won't appear on the ribbon. Instead, the custom contextual tab will be created when the add-in calls the `requestCreateControls` method.
+- If the add-in runs on an application or platform that *doesn't* support `requestCreateControls`, then the groups, controls, and menu items do appear on the custom core tab.
 
-The following is an example. Note that "Contoso.MyButton1" will appear on the custom core tab only when custom contextual tabs aren't supported. However, the parent group and custom core tab will appear regardless of whether custom contextual tabs are supported.
+The following is an example. Note that "Contoso.MyButton1" will appear on the custom core tab only when custom contextual tabs aren't supported. However, the parent group (with "ContosoButton2") and the custom core tab will appear regardless of whether custom contextual tabs are supported.
 
 ```json
 "extensions": [
@@ -662,6 +662,10 @@ The following is an example. Note that "Contoso.MyButton1" will appear on the cu
                                         "id": "Contoso.MyButton1",
                                         ...
                                         "overriddenByRibbonApi": true
+                                    },
+                                    {
+                                        "id": "Contoso.MyButton2",
+                                        ...
                                     }
                                 ]
                             }
@@ -674,10 +678,48 @@ The following is an example. Note that "Contoso.MyButton1" will appear on the cu
 ]
 ```
 
-When a parent menu control is marked with `"overriddenByRibbonApi": true`, then it isn't visible, and all of its child markup is ignored when custom contextual tabs aren't supported. So, it doesn't matter if any of those child menu items have the "overriddenByRibbonApi" property or what its value is. The implication of this is that if a menu item must be visible in all contexts, then not only should it not be marked with `"overriddenByRibbonApi": true`, but *its ancestor menu control must also not be marked this way*.
+The following is another example. Note that "MyControlGroup" will appear on the custom core tab only when custom contextual tabs aren't supported. However, the parent custom core tab (with unmarked groups) will appear regardless of whether custom contextual tabs are supported.
+
+```json
+"extensions": [
+    ...
+    {
+        ...
+        "ribbons": [
+            ...
+            {
+                ...
+                "tabs": [
+                    {
+                        "id": "MyTab",
+                        "groups": [
+                            {
+                                "id": "MyControlGroup",
+                                "overriddenByRibbonApi": true
+                                ...
+                                "controls": [
+                                    {
+                                        "id": "Contoso.MyButton1",
+                                        ...
+                                    }
+                                ]
+                            },
+                            ... other groups configured here
+                        ]
+                    }
+                ]
+            }
+        ]
+    }
+]
+```
+
+When a parent menu control is marked with `"overriddenByRibbonApi": true`, then it isn't visible, and all of its child markup is ignored when custom contextual tabs aren't supported. So, it doesn't matter if any of those child menu items have the "overriddenByRibbonApi" property or what its value is. The implication of this is that if a menu item must be visible in all contexts, then not only should it not be marked with `"overriddenByRibbonApi": true`, but *its ancestor menu control must also not be marked this way*. A similar point applies to ribbon controls. If a control must be visible in all contexts, then not only should it not be marked with `"overriddenByRibbonApi": true`, but its parent group must also not be marked this way.
 
 > [!IMPORTANT]
 > Don't mark *all* of the child items of a menu with `"overriddenByRibbonApi": true`. This is pointless if the parent element is marked with `"overriddenByRibbonApi": true` for reasons given in the preceding paragraph. Moreover, if you leave out the "overriddenByRibbonApi" property on the parent menu control (or set it to `false`), then the parent will appear regardless of whether custom contextual tabs are supported, but it will be empty when they are supported. So, if all the child elements shouldn't appear when custom contextual tabs are supported, mark the *parent* menu control with `"overriddenByRibbonApi": true`.
+>
+> A parallel point applies to groups and controls, don't mark all of the controls in a group with `"overriddenByRibbonApi": true`. This is pointless if the parent group is marked with `"overriddenByRibbonApi": true`. Moreover, if you leave out the "overriddenByRibbonApi" property on the parent group (or set it to `false`), then the group will appear regardless of whether custom contextual tabs are supported, but it will have no controls in it when they are supported. So, if all the controls shouldn't appear when custom contextual tabs are supported, mark the parent group with `"overriddenByRibbonApi": true`.
 
 # [Add-in only manifest](#tab/xmlmanifest)
 
diff --git a/docs/outlook/limits-for-activation-and-javascript-api-for-outlook-add-ins.md b/docs/outlook/limits-for-activation-and-javascript-api-for-outlook-add-ins.md
@@ -1,7 +1,7 @@
 ---
 title: Limits for activation and API usage in Outlook add-ins
 description: Be aware of certain activation and API usage guidelines, and implement your add-ins to stay within these limits.
-ms.date: 02/11/2025
+ms.date: 03/25/2025
 ms.topic: best-practice
 ms.localizationpriority: medium
 ---
@@ -37,11 +37,11 @@ Each Outlook client enforces certain limits in the JavaScript object model, as d
 |Display the body of an existing item|32 KB number of characters|[Mailbox.displayAppointmentForm](/javascript/api/outlook/office.mailbox#outlook-office-mailbox-displaynewappointmentform-member(1)) method<br/><br/>[Mailbox.displayMessageForm](/javascript/api/outlook/office.mailbox#outlook-office-mailbox-displaymessageform-member(1)) method|For Outlook on the web, mobile devices, and [new Outlook on Windows](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627): limit for the body in an existing appointment or message form.|
 |Set the body|1 MB number of characters|[Body.prependAsync](/javascript/api/outlook/office.body#outlook-office-body-prependasync-member(1)) method<br/><br/>[Body.setAsync](/javascript/api/outlook/office.body#outlook-office-body-setasync-member(1))<br/><br/>[Body.setSelectedDataAsync](/javascript/api/outlook/office.body#outlook-office-body-setselecteddataasync-member(1)) method<br/><br/>[DisplayedBody.setAsync](/javascript/api/outlook/office.displayedbody?view=outlook-js-preview&preserve-view=true#outlook-office-displayedbody-setasync-member(1)) (preview)|Limit for setting the body of an appointment or message item.|
 |Set the signature|30,000 characters|[Body.setSignatureAsync](/javascript/api/outlook/office.body#outlook-office-body-setsignatureasync-member(1)) method|Limit for the length of a signature in an appointment or message.|
-|Number of attachments|499 files in Outlook on the web and [new Outlook on Windows](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627)|[Item.addFileAttachmentAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method|Limit for the number of files that can be attached to an item for sending. Outlook on the web and [new Outlook on Windows](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627) generally limit attaching up to 499 files through the user interface and `addFileAttachmentAsync` method. Outlook on Windows (classic) and on Mac don't specifically limit the number of file attachments. However, all Outlook clients observe the limit for the size of attachments (see the "Size of attachments" row in this table).|
-|Size of attachments|Dependent on Exchange Server in classic Outlook on Windows and Outlook on Mac<br/><br/>25 MB in Outlook on the web and new Outlook on Windows|[Item.addFileAttachmentAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method|Limit for the size of all the attachments added to a mail item. In classic Outlook on Windows and Outlook on Mac, the limit is configured by an administrator on the Exchange Server of the user's mailbox. In these clients, this also limits the number of attachments of an item. For Outlook on the web and [new Outlook on Windows](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627), the lesser of the two limits—the number of attachments and the size of all attachments—restricts the actual attachments of an item.|
-|Attachment filename|255 characters|[Item.addFileAttachmentAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method|Limit for the length of the filename of an attachment to be added to an item.|
-|Attachment URI|2,048 characters|[Item.addFileAttachmentAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method<br/><br/>[Item.addFileAttachmentFromBase64Async](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method|Limit of the URI of the filename to be added as an attachment to an item.|
-|Base64-encoded string of an attachment|27,892,122 characters (about 25 MB)|[Item.addFileAttachmentFromBase64Async](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method|Limit of the Base64-encoded string to be added as an attachment to an item.|
+|Number of attachments|499 files in Outlook on the web and [new Outlook on Windows](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627)|[Item.addFileAttachmentAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method<br/><br/>[ReplyFormData.attachments](/javascript/api/outlook/office.replyformdata#outlook-office-replyformdata-attachments-member)|Limit for the number of files that can be attached to an item for sending. Outlook on the web and [new Outlook on Windows](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627) generally limit attaching up to 499 files through the user interface and `addFileAttachmentAsync` method. Outlook on Windows (classic) and on Mac don't specifically limit the number of file attachments. However, all Outlook clients observe the limit for the size of attachments (see the "Size of attachments" row in this table).|
+|Size of attachments|Dependent on Exchange Server in classic Outlook on Windows and Outlook on Mac<br/><br/>25 MB in Outlook on the web and new Outlook on Windows|[Item.addFileAttachmentAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method<br/><br/>[ReplyFormData.attachments](/javascript/api/outlook/office.replyformdata#outlook-office-replyformdata-attachments-member)|Limit for the size of all the attachments added to a mail item. In classic Outlook on Windows and Outlook on Mac, the limit is configured by an administrator on the Exchange Server of the user's mailbox. In these clients, this also limits the number of attachments of an item. For Outlook on the web and [new Outlook on Windows](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627), the lesser of the two limits—the number of attachments and the size of all attachments—restricts the actual attachments of an item.|
+|Attachment filename|255 characters|[Item.addFileAttachmentAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method<br/><br/>[ReplyFormAttachment.name](/javascript/api/outlook/office.replyformattachment#outlook-office-replyformattachment-name-member)|Limit for the length of the filename of an attachment to be added to an item.|
+|Attachment URI|2,048 characters|[Item.addFileAttachmentAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method<br/><br/>[Item.addFileAttachmentFromBase64Async](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method<br/><br/>[ReplyFormData.url](/javascript/api/outlook/office.replyformattachment)|Limit of the URI of the filename to be added as an attachment to an item.|
+|Base64-encoded string of an attachment|27,892,122 characters (about 25 MB)|[Item.addFileAttachmentFromBase64Async](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method<br/><br/>[ReplyFormAttachment.base64file](/javascript/api/outlook/office.replyformattachment#outlook-office-replyformattachment-base64file-member)|Limit of the Base64-encoded string to be added as an attachment to an item.|
 |Attachment ID|100 characters|[Item.addItemAttachmentAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method<br/><br/>[Item.removeAttachmentAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method|Limit for the length of the ID of the attachment to be added to or removed from an item.|
 |Asynchronous calls|3 calls|[Item.addFileAttachmentAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method<br/><br/>[Item.addItemAttachmentAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method<br/><br/>[Item.removeAttachmentAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method<br/><br/>[Body.getTypeAsync](/javascript/api/outlook/office.body#outlook-office-body-gettypeasync-member(1)) method<br/><br/>[Body.prependAsync](/javascript/api/outlook/office.body#outlook-office-body-prependasync-member(1)) method<br/><br/>[Body.setSelectedDataAsync](/javascript/api/outlook/office.body#outlook-office-body-setselecteddataasync-member(1)) method<br/><br/>[CustomProperties.saveAsync](/javascript/api/outlook/office.customproperties#outlook-office-customproperties-saveasync-member(1)) method<br/><br/>[Item.LoadCustomPropertiesAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox.item#methods) method<br/><br/>[Location.getAsync](/javascript/api/outlook/office.location#outlook-office-location-getasync-member(1)) method<br/><br/>[Location.setAsync](/javascript/api/outlook/office.location#outlook-office-location-setasync-member(1)) method<br/><br/>[Mailbox.getCallbackTokenAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox#methods) method<br/><br/>[Mailbox.getUserIdentityTokenAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox#methods) method<br/><br/>[Mailbox.makeEwsRequestAsync](/javascript/api/requirement-sets/outlook/preview-requirement-set/office.context.mailbox#methods) method<br/><br/>[Recipients.addAsync](/javascript/api/outlook/office.recipients#outlook-office-recipients-addasync-member(1)) method<br/><br/>[Recipients.getAsync](/javascript/api/outlook/office.recipients#outlook-office-recipients-getasync-member(1)) method<br/><br/>[Recipients.setAsync](/javascript/api/outlook/office.recipients#outlook-office-recipients-setasync-member(1)) method<br/><br/>[RoamingSettings.saveAsync](/javascript/api/outlook/office.roamingsettings#outlook-office-roamingsettings-saveasync-member(1)) method<br/><br/>[Subject.getAsync](/javascript/api/outlook/office.subject#outlook-office-subject-getasync-member(1)) method<br/><br/>[Subject.setAsync](/javascript/api/outlook/office.subject#outlook-office-subject-setasync-member(1)) method<br/><br/>[Time.getAsync](/javascript/api/outlook/office.time#outlook-office-time-getasync-member(1)) method<br/><br/>[Time.setAsync](/javascript/api/outlook/office.time#outlook-office-time-setasync-member(1)) method|For Outlook on the web and on mobile devices, and [new Outlook on Windows](https://support.microsoft.com/office/656bb8d9-5a60-49b2-a98b-ba7822bc7627): limit of the number of simultaneous asynchronous calls at any one time, as browsers allow only a limited number of asynchronous calls to servers. |
 |Append-on-send|5,000 characters|[Body.appendOnSendAsync](/javascript/api/outlook/office.body#outlook-office-body-appendonsendasync-member(1)) method|Limit of the content to be appended to a message or appointment body on send.|
diff --git a/docs/overview/explore-with-script-lab.md b/docs/overview/explore-with-script-lab.md
@@ -1,7 +1,7 @@
 ---
 title: Explore Office JavaScript API using Script Lab
 description: Use Script Lab to explore the Office JS API and to prototype functionality.
-ms.date: 02/20/2025
+ms.date: 03/21/2025
 ms.topic: concept-article
 ms.custom: scenarios:getting-started
 ms.localizationpriority: high
@@ -84,9 +84,17 @@ Keep your snippets and hard-coded data small since storing several large snippet
 > [!div class="nextstepaction"]
 > [Get Script Lab for Outlook](https://appsource.microsoft.com/product/office/wa200001603)
 
-Once you've prototyped your code in Script Lab, turn it into a real add-in with the steps in [Create a standalone Office Add-in from your Script Lab code](./create-an-office-add-in-from-script-lab.md).
+Once you've prototyped your code in Script Lab, turn it into a real add-in with the steps in [Create a standalone Office Add-in from your Script Lab code](create-an-office-add-in-from-script-lab.md).
+
+## Issues
+
+If you find an issue or have feedback for us, let us know!
+
+- Issue in this article? See the "Office Add-ins feedback" section at the end of this article.
+- Problem with a Script Lab code sample? Open a new issue in the [office-js-snippets GitHub repository](https://github.com/OfficeDev/office-js-snippets/issues).
+- Feedback or issue with the Script Lab tool? Open a new issue in the [office-js GitHub repository](https://aka.ms/script-lab-issues).
 
 ## See also
 
-- [Script Lab sample GitHub repository](https://github.com/OfficeDev/office-js-snippets#office-js-snippets)
+- [Script Lab samples GitHub repository](https://github.com/OfficeDev/office-js-snippets#office-js-snippets)
 - [Developing Office Add-ins](../develop/develop-overview.md)
