上下文 Outlook 加载项的激活规则

项目
02/16/2024

如果用户正在读取或撰写的邮件或约会符合加载项的激活规则，则 Outlook 将激活某些类型的加载项。这一点对使用 1.1 清单架构的所有外接程序均适用。然后，用户可从 Outlook UI 选择外接程序，以开始将其用于当前项目。

重要

基于实体的上下文 Outlook 加载项将在 2024 年第 2 季度停用。停用此功能的工作将于 5 月开始，并持续到 6 月底。 6 月之后，上下文加载项将无法再检测邮件项目中的实体以对其执行任务。以下 API 也将停用。

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

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

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

在清单中指定激活规则

注意

当外接程序使用 Microsoft 365 统一清单时，不支持依赖于激活规则的 Outlook 外接程序功能， (预览版) 。

若要让 Outlook 针对特定条件激活加载项，请使用以下 Rule 元素之一在外接程序清单中指定激活规则。

Rule 元素 (MailApp complexType) - 指定单个规则。
Rule 元素 (RuleCollection complexType) - 使用逻辑操作组合多个规则。

注意

Rule用于指定单个规则的元素属于抽象 Rule 复杂类型。以下每种规则类型都扩展了此抽象 Rule 复杂类型。因此当你在清单中指定单个规则时，你必须使用 xsi:type 属性来进一步定义某个以下类型的规则。

例如，以下规则定义 ItemIs 规则。 <Rule xsi:type="ItemIs" ItemType="Message" />

属性 FormType 适用于清单 v1.1 中的激活规则，但在 v1.0 中 VersionOverrides 未定义。因此，在节点中使用 ItemIs 时，无法使用它 VersionOverrides 。

下表列出了可用的规则类型。你可以在表后面以及创建适用于阅读窗体的 Outlook 外接程序中指定的文章中查找更多信息。

规则名称	适用的窗体	说明
ItemIs	读取，撰写	检查当前项目是指定类型 (邮件还是约会) 。还可以检查项类和窗体 type。还可以选择项目邮件类。
ItemHasAttachment	读取	检查所选项是否包含附件。
ItemHasKnownEntity	读取	检查所选项是否包含一个或多个已知实体。更多信息：将 Outlook 项中的字符串作为已知实体进行匹配。
ItemHasRegularExpressionMatch	读取	检查发件人的电子邮件地址、所选项的主题和/或所选项的正文是否包含正则表达式的匹配项。更多信息：使用正则表达式激活规则显示 Outlook 外接程序。
RuleCollection	读取，撰写	组合一组规则以便形成更复杂的规则。

ItemIs 规则

复杂 ItemIs 类型定义一个规则，该规则的计算结果 true 为（如果当前项与项类型匹配），还可以定义项目消息类（如果规则中已说明）。

在规则的属性中 ItemType 指定以下项类型之一 ItemIs 。可以在清单中指定多个 ItemIs 规则。 ItemType simpleType 定义了支持 Outlook 加载项的 Outlook 项类型。

Value	说明
约会	在 Outlook 日历中指定一个项目。这包括已获取响应并且具有组织者和参与者的会议项目，或者没有组织者或参与者且仅为日历上的一个项目的约会。这与 Outlook 中的 IPM.Appointment 邮件类别相对应。
邮件	指定通常收件箱中收到的以下项目之一。电子邮件。这与 Outlook 中的 IPM.Note 邮件类别相对应。会议请求、响应或取消。这对应于 Outlook 中的以下邮件类。 IPM.Schedule.Meeting.Request IPM.Schedule.Meeting.Neg IPM.Schedule.Meeting.Pos IPM.Schedule.Meeting.Tent IPM.Schedule.Meeting.Canceled

属性 FormType 用于指定 (读取或撰写) 应激活加载项的模式。

注意

ItemIs FormType 属性在架构 v1.1 及更高版本中定义，但不在 v1.0 中 VersionOverrides 定义。定义外接程序命令时，不要包含 FormType 属性。

激活外接程序后，可以使用 mailbox.item 属性获取 Outlook 中的当前所选项，以及使用 item.itemType 属性获取当前项的类型。

可以选择使用 ItemClass 属性来指定项的消息类，并使用 IncludeSubClasses 属性来指定当项是指定类的子类时是否应 true 使用规则。

若要详细了解邮件类，请参阅项类型和邮件类。

以下示例是一个 ItemIs 规则，允许用户在用户阅读邮件时在 Outlook 外接程序栏中看到加载项。

<Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />

以下示例是一个 ItemIs 规则，允许用户在阅读邮件或约会时在 Outlook 外接程序栏中看到加载项。

<Rule xsi:type="RuleCollection" Mode="Or">
  <Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
  <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read" />
</Rule>

ItemHasAttachment 规则

复杂 ItemHasAttachment 类型定义一个规则，用于检查所选项目是否包含附件。

<Rule xsi:type="ItemHasAttachment" />

ItemHasKnownEntity 规则

在项对外接程序可用之前，服务器将对其进行检查以确定主题和正文是否包含可能为某个已知实体的任何文本。如果找到这些实体中的任何一个，则会将其置于使用 getEntities 该项的或 getEntitiesByType 方法访问的已知实体集合中。

当项目中存在指定类型的实体时，可以使用来指定显示加载项的规则 ItemHasKnownEntity 。可以在规则的 ItemHasKnownEntity 属性中EntityType指定以下已知实体。

Address
Contact
EmailAddress
MeetingSuggestion
PhoneNumber
TaskSuggestion
URL

可以选择在属性中包含 RegularExpression 正则表达式，以便仅当与当前中的正则表达式匹配的实体时才显示加载项。若要获取与规则中指定的 ItemHasKnownEntity 正则表达式的匹配项，可以对当前选定的 Outlook 项目使用 getRegExMatches 或 getFilteredEntitiesByName 方法。

以下示例显示了一个元素集合， Rule 这些元素在消息中存在指定的已知实体之一时显示加载项。

<Rule xsi:type="RuleCollection" Mode="Or">
    <Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
    <Rule xsi:type="ItemHasKnownEntity" EntityType="MeetingSuggestion" />
    <Rule xsi:type="ItemHasKnownEntity" EntityType="TaskSuggestion" />
</Rule>

以下示例演示一个ItemHasKnownEntityRegularExpression具有属性的规则，该规则在消息中存在包含单词“contoso”的 URL 时激活加载项。

<Rule xsi:type="ItemHasKnownEntity" EntityType="Url" RegularExpression="contoso" />

有关激活规则中的实体的详细信息，请参阅将 Outlook 项中的字符串作为已知实体进行匹配。

ItemHasRegularExpressionMatch 规则

复杂 ItemHasRegularExpressionMatch 类型定义一个规则，该规则使用正则表达式来匹配项的指定属性的内容。如果在项的指定属性中发现与正则表达式匹配的文本，则 Outlook 会激活外接程序栏并显示外接程序。可以使用 getRegExMatches 表示当前选定项的对象的或 getRegExMatchesByName 方法获取指定正则表达式的匹配项。

以下示例演示当 ItemHasRegularExpressionMatch 所选项的正文包含“apple”、“香蕉”或“椰子”（忽略大小写）时激活加载项的。

<Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="fruits" RegExValue="apple|banana|coconut" PropertyName="BodyAsPlaintext" IgnoreCase="true" />

有关使用 ItemHasRegularExpressionMatch 规则的详细信息，请参阅使用正则表达式激活规则显示 Outlook 加载项。

RuleCollection 规则

RuleCollection复杂类型将多个规则合并为一个规则。可以使用属性指定集合中的规则是应与逻辑 OR 还是逻辑 AND Mode 组合。

指定逻辑 AND 时，项必须与集合中的所有指定规则匹配才能显示外接程序。指定逻辑 OR 时，与集合中的任何指定规则匹配的项将显示加载项。

可以组合 RuleCollection 规则以形成复杂规则。以下示例在用户查看约会或邮件项目（项目的主题或正文包含地址）时激活外接程序。

<Rule xsi:type="RuleCollection" Mode="And">
  <Rule xsi:type="RuleCollection" Mode="Or">
    <Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
    <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read"/>
  </Rule>
  <Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
</Rule>

以下示例在用户撰写邮件时或查看约会（约会的标题或正文包含地址）时激活外接程序。

<Rule xsi:type="RuleCollection" Mode="Or"> 
  <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit" /> 
  <Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read" />
    <Rule xsi:type="ItemHasKnownEntity" EntityType="Address" />
  </Rule> 
</Rule>

规则和正则表达式的限制

为了提供使用 Outlook 外接程序的满意体验，您应该遵守激活和 API 使用准则。下表显示了正则表达式和规则的一般限制，但有适用于不同应用程序的特定规则。有关详细信息，请参阅 Outlook 外接程序的激活和 JavaScript API 的限制和排查 Outlook 外接程序激活问题。

外接程序元素 准则

清单大小不大于 256 KB。

规则不超过 15 条规则。

ItemHasKnownEntity Windows 版和 Mac 版 Outlook 将规则应用于正文的前 1 MB，而不应用于正文的其余部分。

正则表达式

对于所有 Outlook 应用程序的 ItemHasKnownEntity 或 ItemHasRegularExpressionMatch 规则：

在 Outlook 外接程序的激活规则中指定不超过 5 个正则表达式。如果超过该限制，则无法安装加载项。
指定由 getRegExMatches 方法调用在前 50 个匹配项内返回其预期结果的正则表达式。
重要提示：根据匹配正则表达式而生成的字符串突出显示文本。但是，突出显示的出现次数可能无法完全匹配实际正则表达式断言（如负前 (?!text)向、后向 (?<=text)和负后 (?<!text)视）。例如，如果在“like under，score under， and 下划线”上使用正则表达式 under(?!score) ，则会为所有匹配项突出显示字符串“under”，而不仅仅是前两个。
指定匹配项不超过下表中限制的正则表达式。

正则表达式匹配项的长度限制 Windows 版和 Mac 版 Outlook iOS 版和 Android 版 Outlook
项目正文采用纯文本 1.5 KB 3 KB
项目正文采用 HTML 3 KB 3KB