Outlook 加载项的激活和 JavaScript API 限制

项目
03/02/2024

为了向 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 方法	可应用于消息的标头的总大小限制。
提取已知实体	2000 个字符	Item.getEntities 方法 Item.getEntitiesByType 方法 Item.getFilteredEntitiesByName 方法	在项目正文上提取常见实体的 Exchange Server 限制。 Exchange Server 将忽略超过该限制的实体。请注意，此限制与加载项是否使用 `ItemHasKnownEntity` 规则无关。
Exchange Web 服务	从版本 2303 (内部版本 16225.10000) ) 开始的 Windows (Outlook 网页版中 5 MB 字符数，在 Mac (从版本 16.73 (23042601) ) 开始，在 Windows (预览版中 ) Windows 和 Mac 上早期版本的 Outlook 中的 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 网页版、移动设备和 Windows 版 Outlook 中的 499 个文件 (预览版)	Item.addFileAttachmentAsync 方法	限制可附加到发送项目的文件数量。 Outlook 网页版和移动设备上，新的 Outlook on Windows (预览版) 通常通过用户界面和`addFileAttachmentAsync`方法限制最多附加 499 个文件。 Windows 版和 Mac 版 Outlook 不会明确限制文件附件的数量。但是，所有 Outlook 客户端都遵守用户确定的附件大小的限制Exchange Server (请参阅此表中的“附件大小”行) 。
附件大小	取决于 Exchange Server	Item.addFileAttachmentAsync 方法	邮件项目的所有附件的大小都有限制，管理员可以在用户邮箱的Exchange Server上对其进行配置。对于 Windows 版和 Mac 版 Outlook，这会限制项目的附件数。对于Outlook 网页版和移动设备，以及新的 Windows 版 Outlook (预览版) ，两个限制中的较小一个（附件数量和所有附件的大小）将限制项目的实际附件。
附件的文件名	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 加载项将在 2024 年第 2 季度停用。停用此功能的工作将于 5 月开始，并持续到 6 月底。 6 月之后，上下文加载项将无法再检测邮件项目中的实体以对其执行任务。以下 API 也将停用。

为了帮助最大程度地减少潜在的中断，在基于实体的上下文加载项停用后，仍支持以下内容。

正在开发由联机会议加载项激活的 “加入 会议”按钮的替代实现。结束对基于实体的上下文加载项的支持后，联机会议加载项将自动转换为替代实现，以激活“ 加入会议 ”按钮。
基于实体的上下文加载项停用后，将继续支持正则表达式规则。建议更新上下文加载项，以使用正则表达式规则作为替代解决方案。有关如何实现这些规则的指南，请参阅使用正则表达式激活规则显示 Outlook 加载项。

有关详细信息，请参阅基于实体的上下文 Outlook 加载项的停用。

为上下文 Outlook 加载项设计激活规则时，请遵循这些准则。

将清单的大小限制为 256 KB。如果超过该限制，则无法为 Exchange 邮箱安装 Outlook 加载项。

注意

当外接程序使用 Microsoft 365 的统一清单时，不支持依赖于激活规则的 Outlook 外接程序功能。
可为外接程序最多指定 15 条激活规则。如果超过该限制，则无法安装加载项。
在 Outlook on Windows 和 Mac 中，如果在所选项目的正文上使用 ItemHasKnownEntity 规则，则预期该规则仅应用于正文的前 1 MB，而不应用于超过该限制的正文的其余部分。如果匹配项仅在正文的第一 MB 之后存在，则外接程序不会激活。如果预计这是一个可能的方案，请重新设计激活条件。
如果在或 ItemHasRegularExpressionMatch 规则中使用ItemHasKnownEntity正则表达式，请注意以下限制和准则，这些限制和准则通常适用于任何 Outlook 应用程序，以及后续部分表中描述的限制和准则，这些限制和准则因应用程序而异。
- 在外接程序的激活规则中最多只指定五个正则表达式。如果超过该限制，则无法安装加载项。
- 指定正则表达式，以便方法调用在前 50 个匹配项内返回 getRegExMatches 预期结果。
- 重要提示：根据匹配正则表达式而生成的字符串突出显示文本。但是，突出显示的出现次数可能无法完全匹配实际正则表达式断言（如负前 (?!text)向、后向 (?<=text)和负后 (?<!text)视）。例如，如果在“like under，score under， and 下划线”上使用正则表达式 under(?!score) ，则会为所有匹配项突出显示字符串“under”，而不仅仅是前两个。

正则表达式支持的差异

下表列出了这些限制，并介绍了在 Outlook 客户端中对正则表达式的支持差异。这种支持不依赖于任何特定类型的设备和项目正文。

Outlook 网页版、移动设备和新的 Windows 客户端 (预览)	Windows 版和 Mac 版 Outlook
客户端使用属于 JavaScript 的正则表达式计算。它由浏览器提供，并支持 ECMAScript 5 的超集。	客户端使用作为 Visual Studio 标准模板库的一部分提供的 C++ 正则表达式引擎。该引擎符合 ECMAScript 5 标准。
应在每个 Outlook 客户端上全面测试每个正则表达式。如果正则表达式返回不同的结果，请重写正则表达式。	由于正则表达式引擎不同，因此包含基于预定义字符类的自定义字符类的正则表达式可能会在 Windows 和 Mac 上的 Outlook 中返回与Outlook 网页版、移动设备以及新 Outlook on Windows (预览版) 返回不同的结果。例如，正则表达式 `[\s\S]{0,100}` 匹配任何介于 0 到 100 之间的单个字符（即空格或非空格）的数字。此正则表达式根据 Outlook 客户端返回不同的结果。解决方法是，应将正则表达式重写为 `(\s\\|\S){0,100}`。此正则表达式匹配空格或非空格的任意数字（介于 0 到 100 之间）。应在每个 Outlook 客户端上全面测试每个正则表达式。如果正则表达式返回不同的结果，请重写正则表达式。
windows 版和 Mac 版 Outlook 中支持的资源监视和注册表设置在Outlook 网页版、移动设备和新的 Outlook on Windows (预览版) 中不受支持。但是，对于所有 Outlook 客户端上的同一邮箱，具有正则表达式的加载项在 Windows 版和 Mac 版中需要过多的评估时间。	默认情况下，外接程序的所有正则表达式的计算限制为 1 秒。超过此限制会导致重新计算最多三次。如果超出重新计算限制，Windows 版和 Mac 版 Outlook 会阻止加载项在任何 Outlook 客户端中为同一邮箱运行。管理员可以通过使用 `OutlookActivationAlertThreshold` 和 `OutlookActivationManagerRetryLimit` 注册表项来覆盖这些评估限制。

计算的项正文的大小限制

下表列出了限制，并描述了每个 Outlook 客户端应用正则表达式的项目正文部分的差异。如果对项正文应用了正则表达式，则其中某些限制取决于设备和项正文的类型。

	Outlook 网页版和新的 Windows 客户端 (预览)	经典 Windows 客户端和 Mac 上的 Outlook	移动设备上的 Outlook
外形规格	Android 智能手机、iPad 和 iPhone 以外的任何受支持的设备。	任何受支持的设备。	Android 智能手机、iPad 或 iPhone。
纯文本项正文	仅当正文 < 为 500,000 个字符时，才会激活加载项。	对正文数据的第一个 1 MB 而不对超出该限制的其余正文应用正则表达式。	仅当正文 < 为 16,000 个字符时，才会激活加载项。
HTML 项正文	仅当正文 < 为 500,000 个字符时，才会激活加载项。	对正文数据的前 512 KB 应用正则表达式，但不应用于超过该限制的正文的其余部分。 (实际字符数取决于编码，其范围可以是每个字符 1 到 4 个字节。)	对前 64,000 个字符（包括 HTML 标记字符）而不对超出该限制的其余正文应用正则表达式。

返回的匹配项限制

下表列出了限制，并描述了每个 Outlook 客户端在计算正则表达式后返回的匹配项的差异。这种支持不依赖于任何特定设备类型，但是，如果对项正文应用了正则表达式，则该支持可能依赖于项正文的类型。

	Outlook 网页版、移动设备和新的 Windows 客户端 (预览)	经典 Windows 客户端和 Mac 上的 Outlook
返回的匹配项的顺序	`getRegExMatches`假设方法返回不同匹配项的相同正则表达式，这些正则表达式应用于 Outlook on Windows 和 Mac 上的同一邮件项目，而不是在Outlook 网页版、移动设备上，以及新 Outlook on Windows (预览版) 。	`getRegExMatches`假设方法返回适用于 Windows 和 Mac 中相同邮件项目的同一个正则表达式的不同匹配项，而不是在Outlook 网页版、移动设备上，以及新 Outlook on Windows (预览版) 。
纯文本项正文	`getRegExMatches` 返回最多 3,072 (3 KB) 个字符的任何匹配项，最多包含 50 个匹配项。	该方法 `getRegExMatches` 返回最多 1,536 (1.5 KB) 个字符的任何匹配项，最多包含 50 个匹配项。注意： `getRegExMatches` 在返回的数组中，不按任何特定顺序返回匹配项。通常，假设在 Windows 版 Outlook 和 Mac 上对相同邮件项应用的同一正则表达式的匹配顺序不同于Outlook 网页版、移动设备和 Windows 版新 Outlook (预览版) 中的匹配顺序。
HTML 项正文	`getRegExMatches` 返回最多 3,072 (3 KB) 个字符的任何匹配项，最多包含 50 个匹配项。	`getRegExMatches` 返回最多 3,072 (3 KB) 个字符的任何匹配项，最多包含 50 个匹配项。注意： `getRegExMatches` 在返回的数组中，不按任何特定顺序返回匹配项。通常，假设在 Windows 版 Outlook 和 Mac 上对相同邮件项应用的同一正则表达式的匹配顺序不同于Outlook 网页版、移动设备和 Windows 版新 Outlook (预览版) 中的匹配顺序。

Share via