Outlook 加载项的激活和 JavaScript API 限制
为了向 Outlook 外接程序的用户提供令人满意的体验，您必须了解特定的激活和 API 使用准则，并执行外接程序使其不超过这些限制。 这些准则的存在使得单个外接程序不能要求Exchange Server或 Outlook 花费异常长的时间来处理其激活规则或对 Office JavaScript API 的调用，从而影响 Outlook 和其他加载项的整体用户体验。这些限制适用于在外接程序清单中设计激活规则，以及使用自定义属性、漫游设置、收件人、Exchange Web Services (EWS) 请求和响应以及异步调用。
注意
还必须验证加载项是否在某些运行时资源使用限制内执行。 有关详细信息，请参阅 Office 外接程序中的运行时。
外接程序激活位置的限制
若要详细了解加载项在何处执行和不激活，请参阅 Outlook 加载项概述的“可用于加载项的邮箱项目”部分。
JavaScript API 的限制
每个 Outlook 客户端在 JavaScript 对象模型中强制实施某些限制，如下表所述。
| 功能 | 限制 | 相关 API | 说明 |
|---|---|---|---|
| 自定义属性 | 2500 个字符 |
CustomProperties 对象 Item.loadCustomPropertiesAsync 方法 |
约会或邮件项目的所有自定义属性的限制。 如果加载项的所有自定义属性的总大小超过此限制，则所有 Outlook 客户端都会返回错误。 |
| 漫游设置 | 32 KB 字符数 |
RoamingSettings 对象 Context.roamingSettings 属性 |
外接程序的所有漫游设置的限制。 如果设置超过此限制，所有 Outlook 客户端都会返回错误。 |
| Internet 标头： | Exchange Online中每条消息 256 KB 由组织管理员在本地 Exchange 中确定的标头大小限制 |
InternetHeaders.setAsync 方法 | 可应用于消息的标头的总大小限制。 |
| Exchange Web 服务 | 在从版本 2303 (内部版本 16225.10000) ) 开始的 Windows (上，在 Mac (从版本 16.73 (23042601) ) 开始，在新的 Windows 版 Outlook 中，Outlook 网页版 5 MB 字符数 早期版本的 Outlook on Windows (经典) 和 Mac 中的 1 MB 字符 |
Mailbox.makeEwsRequestAsync 方法 | 请求或对呼叫的 Mailbox.makeEwsRequestAsync 响应的限制。 |
| 项多选 | 100 条消息 | Mailbox.getSelectedItemsAsync 方法 | Outlook 加载项可激活的所选邮件的最大数目。 |
| 收件人 | 因 Outlook 客户端而异 |
Item.requiredAttendees 属性 Item.optionalAttendees 属性 Item.to 属性 Item.cc 属性 Recipients.addAsync 方法 Recipients.getAsync 方法 Recipients.setAsync 方法 |
每个属性或方法中指定的收件人的限制。 若要了解特定 Outlook 客户端的收件人限制，请参阅 属性或方法的 API 文档。 |
| 显示名称 | 255 个字符 |
EmailAddressDetails.displayName 属性 Recipients 对象 Item.requiredAttendees 属性 Item.optionalAttendees 属性 Item.to 属性 Item.cc 属性 |
约会或邮件中显示名称的长度限制。 |
| 设置主题 | 255 个字符 |
DisplayedSubject.setAsync (预览) Mailbox.displayNewAppointmentForm 方法 Subject.setAsync 方法 |
新的约会窗体中的主题限制，或设置约会或邮件主题的限制。 |
| 设置位置 | 255 个字符 | Location.setAsync 方法 | 设置约会或会议请求地点的限制。 |
| 新的约会窗体的正文 | 32 KB 字符数 | Mailbox.displayNewAppointmentForm 方法 | 新的约会窗体中正文的限制。 |
| 显示现有项的正文 | 32 KB 字符数 |
Mailbox.displayAppointmentForm 方法 Mailbox.displayMessageForm 方法 |
对于Outlook 网页版、移动设备和新 Outlook on Windows：现有约会或邮件表单中的正文限制。 |
| 设置正文 | 1 MB 字符数 |
Body.prependAsync 方法 Body.setAsync Body.setSelectedDataAsync 方法 DisplayedBody.setAsync (预览) |
设置约会或邮件项目正文的限制。 |
| 设置签名 | 30,000 个字符 | Body.setSignatureAsync 方法 | 约会或邮件中签名长度的限制。 |
| 附件数 | Outlook 网页版和新 Outlook on Windows 中的 499 个文件 | Item.addFileAttachmentAsync 方法 | 限制可附加到发送项目的文件数量。 Outlook 网页版和新的 Outlook on Windows 通常限制通过用户界面和addFileAttachmentAsync方法最多附加 499 个文件。 Windows 上的 Outlook (经典) 和 Mac 上的 Outlook 不会明确限制文件附件的数量。 但是，所有 Outlook 客户端都遵守附件大小的限制， (看到此表中的“附件大小”行) 。 |
| 附件大小 | 依赖于经典 Outlook on Windows 和 Outlook on Mac 中的Exchange Server Outlook 网页版和新的 Windows 版 Outlook 中的 25 MB |
Item.addFileAttachmentAsync 方法 | 添加到邮件项目的所有附件的大小限制。 在经典 Outlook on Windows 和 Outlook on Mac 中，限制由管理员对用户邮箱的Exchange Server进行配置。 在这些客户端中，这还会限制项的附件数。 对于Outlook 网页版和新 Outlook on Windows，两个限制中的较小一个（附件数量和所有附件的大小）限制项目的实际附件。 |
| 附件的文件名 | 255 个字符 | Item.addFileAttachmentAsync 方法 | 要添加到项目的附件的文件名长度限制。 |
| 附件的 URI | 2048 个字符 |
Item.addFileAttachmentAsync 方法 Item.addFileAttachmentFromBase64Async 方法 |
要添加为项目附件的文件名 URI 的限制。 |
| 附件的 Base64 编码字符串 | 27,892,122 个字符 (大约 25 MB) | Item.addFileAttachmentFromBase64Async 方法 | 要作为附件添加到项的 Base64 编码字符串的限制。 |
| 附件 ID | 100 个字符 |
Item.addItemAttachmentAsync 方法 Item.removeAttachmentAsync 方法 |
要添加或从项目中删除的附件 ID 的长度限制。 |
| 异步调用 | 3 次调用 |
Item.addFileAttachmentAsync 方法 Item.addItemAttachmentAsync 方法 Item.removeAttachmentAsync 方法 Body.getTypeAsync 方法 Body.prependAsync 方法 Body.setSelectedDataAsync 方法 CustomProperties.saveAsync 方法 Item.LoadCustomPropertiesAsync 方法 Location.getAsync 方法 Location.setAsync 方法 Mailbox.getCallbackTokenAsync 方法 Mailbox.getUserIdentityTokenAsync 方法 Mailbox.makeEwsRequestAsync 方法 Recipients.addAsync 方法 Recipients.getAsync 方法 Recipients.setAsync 方法 RoamingSettings.saveAsync 方法 Subject.getAsync 方法 Subject.setAsync 方法 Time.getAsync 方法 Time.setAsync 方法 |
对于Outlook 网页版和移动设备，以及新的 Outlook on Windows：限制随时同时异步调用的数量，因为浏览器只允许有限数量的异步调用服务器。 |
| Append-on-send | 5,000 个字符 | Body.appendOnSendAsync 方法 | 发送时要追加到邮件或约会正文的内容限制。 |
| prepend-on-send | 5,000 个字符 | Body.prependOnSendAsync 方法 | 发送邮件或约会正文之前要附加的内容的限制。 |
上下文 Outlook 加载项的激活规则限制
重要
基于实体的上下文 Outlook 加载项现已停用。 作为替代解决方案，请在上下文加载项中实现正则表达式规则。 有关如何实现这些规则的指南，请参阅 上下文 Outlook 加载项。
为 上下文 Outlook 加载项设计激活规则时，请遵循这些准则。
将清单的大小限制为 256 KB。 如果超过该限制，则无法为 Exchange 邮箱安装 Outlook 加载项。
注意
当外接程序使用 Microsoft 365 的统一应用清单时，不支持依赖于激活规则的 Outlook 外接程序功能。
可为外接程序最多指定 15 条激活规则。 如果超过该限制，则无法安装加载项。
在 ItemHasRegularExpressionMatch 规则中使用正则表达式时，请注意以下限制和准则，这些限制和准则通常适用于任何 Outlook 应用程序，以及后续部分的表中描述的限制和准则，这些限制和准则因应用程序而异。
- 在外接程序的激活规则中最多只指定五个正则表达式。 如果超过该限制，则无法安装加载项。
- 指定正则表达式，以便方法调用在前 50 个匹配项内返回
getRegExMatches预期结果。 -
重要提示：根据匹配正则表达式而生成的字符串突出显示文本。 但是，突出显示的出现次数可能无法完全匹配实际正则表达式断言（如负前
(?!text)向、后向(?<=text)和负后(?<!text)视）。 例如，如果在“like under，score under， and 下划线”上使用正则表达式under(?!score)，则会为所有匹配项突出显示字符串“under”，而不仅仅是前两个。
正则表达式支持的差异
下表列出了这些限制，并介绍了在 Outlook 客户端中对正则表达式的支持差异。 这种支持不依赖于任何特定类型的设备和项目正文。
| 在新的 Windows 客户端和移动设备上Outlook 网页版 | Windows 上的 Outlook (经典) 和 Mac 版 |
|---|---|
| 客户端使用属于 JavaScript 的正则表达式计算。 它由浏览器提供，并支持 ECMAScript 5 的超集。 | 客户端使用作为 Visual Studio 标准模板库的一部分提供的C++正则表达式引擎。 该引擎符合 ECMAScript 5 标准。 |
| 应在每个 Outlook 客户端上全面测试每个正则表达式。 如果正则表达式返回不同的结果，请重写正则表达式。 | 由于正则表达式引擎不同，包含基于预定义字符类的自定义字符类的正则表达式可能会在 Windows 上的 Outlook (经典) 和 Mac 上返回不同的结果，而不是在Outlook 网页版、移动设备和新的 Outlook on Windows 中返回不同的结果。 例如，正则表达式 [\s\S]{0,100} 匹配任何介于 0 到 100 之间的单个字符（即空格或非空格）的数字。 此正则表达式根据 Outlook 客户端返回不同的结果。解决方法是，应将正则表达式重写为 (\s\|\S){0,100}。 此正则表达式匹配空格或非空格的任意数字（介于 0 到 100 之间）。应在每个 Outlook 客户端上全面测试每个正则表达式。 如果正则表达式返回不同的结果，请重写正则表达式。 |
| Outlook 网页版、移动设备和新的 Outlook on Windows 中不支持 Outlook (经典) 和 Mac 中支持的资源监视和注册表设置。 但是，所有 Outlook 客户端上的同一邮箱在 Windows (经典) 和 Mac 中需要过多评估时间的正则表达式加载项将被禁用。 | 默认情况下，外接程序的所有正则表达式的计算限制为 1 秒。 超过此限制会导致重新计算最多三次。 除了重新计算限制之外，Windows 版 Outlook (经典) ，Mac 上会阻止加载项在任何 Outlook 客户端中为同一邮箱运行。 管理员可以通过使用 OutlookActivationAlertThreshold 和 OutlookActivationManagerRetryLimit 注册表项来覆盖这些评估限制。 |
计算的项正文的大小限制
下表列出了限制，并描述了每个 Outlook 客户端应用正则表达式的项目正文部分的差异。 如果对项正文应用了正则表达式，则其中某些限制取决于设备和项正文的类型。
| 在新的 Windows 客户端上Outlook 网页版和 | Windows 上的 Outlook (经典) 和 Mac 版 | 移动设备上的 Outlook | |
|---|---|---|---|
| 外形规格 | Android 智能手机、iPad 和 iPhone 以外的任何受支持的设备。 | 任何受支持的设备。 | Android 智能手机、iPad 或 iPhone。 |
| 纯文本项正文 | 仅当正文 < 为 500,000 个字符时，才会激活加载项。 | 对正文数据的第一个 1 MB 而不对超出该限制的其余正文应用正则表达式。 | 仅当正文 < 为 16,000 个字符时，才会激活加载项。 |
| HTML 项正文 | 仅当正文 < 为 500,000 个字符时，才会激活加载项。 | 对正文数据的前 512 KB 应用正则表达式，但不应用于超过该限制的正文的其余部分。 (实际字符数取决于编码，其范围可以是每个字符 1 到 4 个字节。) | 对前 64,000 个字符（包括 HTML 标记字符）而不对超出该限制的其余正文应用正则表达式。 |
返回的匹配项限制
下表列出了限制，并描述了每个 Outlook 客户端在计算正则表达式后返回的匹配项的差异。 这种支持不依赖于任何特定设备类型，但是，如果对项正文应用了正则表达式，则该支持可能依赖于项正文的类型。
| 在新的 Windows 客户端和移动设备上Outlook 网页版 | Windows 上的 Outlook (经典) 和 Mac 版 | |
|---|---|---|
| 返回的匹配项的顺序 |
getRegExMatches假设 方法返回适用于 Windows 版 Outlook 中的同一邮件项目的同一个正则表达式的不同匹配项， (经典) 和 Mac 上的Outlook 网页版、移动设备和新的 Outlook on Windows。 |
getRegExMatches假设 方法返回适用于 Windows 版 Outlook 中的同一邮件项目的同一个正则表达式的不同匹配项， (经典) 和 Mac 上与Outlook 网页版、移动设备和新的 Outlook on Windows 中的相同正则表达式。 |
| 纯文本项正文 |
getRegExMatches 返回最多 3,072 (3 KB) 个字符的任何匹配项，最多包含 50 个匹配项。 |
该方法 getRegExMatches 返回最多 1,536 (1.5 KB) 个字符的任何匹配项，最多包含 50 个匹配项。注意： getRegExMatches 在返回的数组中，不按任何特定顺序返回匹配项。 一般情况下，假设 Windows 版 Outlook (经典) 和 Mac 上应用于同一邮件项目的同一正则表达式的匹配顺序与Outlook 网页版、移动设备和新 Outlook on Windows 中的匹配顺序不同。 |
| HTML 项正文 |
getRegExMatches 返回最多 3,072 (3 KB) 个字符的任何匹配项，最多包含 50 个匹配项。 |
getRegExMatches 返回最多 3,072 (3 KB) 个字符的任何匹配项，最多包含 50 个匹配项。注意： getRegExMatches 在返回的数组中，不按任何特定顺序返回匹配项。 一般情况下，假设 Windows 版 Outlook (经典) 和 Mac 上应用于同一邮件项目的同一正则表达式的匹配顺序与Outlook 网页版、移动设备和新 Outlook on Windows 中的匹配顺序不同。 |