使用正则表达式激活规则显示 Outlook 外接程序

  • 项目

可以将正则表达式规则指定为在邮件的特定字段中找到匹配项时激活上下文外接程序。 上下文加载项仅在读取模式下激活。 当用户撰写项目时，Outlook 不会激活上下文加载项。 还有其他情况，Outlook 不会激活加载项，例如，数字签名的项目。 有关详细信息，请参阅 Outlook 外接程序的激活规则。

重要

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

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

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

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

你可以将正则表达式指定为外接程序 XML 清单中的 ItemHasRegularExpressionMatch 规则或 ItemHasKnownEntity 规则的一部分。 在 DetectedEntity 扩展点中指定了这些规则。

注意

当加载项使用 Microsoft 365 的统一清单时 ，不支持上下文 Outlook 加载项 (预览版) 。

Outlook 根据客户端计算机上的浏览器或 Webview 控件使用的 JavaScript 解释器规则来评估正则表达式。 为简洁起见，本文使用“browser”来指代“浏览器或 Web 视图控件”。 Outlook 支持所有 XML 处理器也支持的相同特殊字符列表。 下表列出了这些特殊字符。 可以通过指定相应字符的转义序列在正则表达式中使用这些字符，如下表所述。

字符 说明 要使用的转义序列
" 双引号 "
& 与号 &
' 撇号 '
< 小于号 &lt;
> 大于号 &gt;

ItemHasRegularExpressionMatch 规则

ItemHasRegularExpressionMatch规则可用于根据受支持属性的特定值控制加载项的激活。 ItemHasRegularExpressionMatch 规则具有以下属性。

属性名 说明
RegExName 指定正则表达式的名称，以便能够在外接程序的代码中引用该表达式。
RegExValue 指定将对其求值的正则表达式，以确定是否应显示外接程序。
PropertyName 指定正则表达式进行计算所依据的属性名称。 允许的值为 BodyAsHTML、BodyAsPlaintext、SenderSMTPAddress 和 Subject。

如果指定 BodyAsHTML，则 Outlook 只会在项目正文为 HTML 时应用正则表达式。 否则，Outlook 将不会返回该正则表达式的匹配项。

如果指定 BodyAsPlaintext，则 Outlook 将始终对项目正文应用正则表达式。

重要：如果需要为 <Rule> 元素指定 Highlight 属性，必须将 PropertyName 属性设置为 BodyAsPlaintext。
IgnoreCase 指定当匹配由 RegExName 指定的正则表达式时是否忽略大小写。
Highlight 指定客户端应如何突出显示匹配的文本。 此元素仅适用于 ExtensionPoint 元素中的 Rule 元素。 可以是以下值之一：all 或 none。 如果未指定，则默认值为 all。

重要：若要在 Rule> 元素中<指定 Highlight 属性，必须将 PropertyName 属性设置为 BodyAsPlaintext。

在规则中使用正则表达式的最佳做法

使用正则表达式时，请特别注意以下事项。

  • 如果对项的正文指定 ItemHasRegularExpressionMatch 规则，则正则表达式应进一步筛选正文，并且不应尝试返回项的整个正文。 使用正则表达式（例如 .* ）尝试获取项的整个正文并不总是返回预期的结果。

  • 一个浏览器上返回的纯文本正文与另一个浏览器上返回的纯文本正文可能略有不同。 如果使用含有 BodyAsPlaintext 的 ItemHasRegularExpressionMatch 规则作为 PropertyName 属性，请在你的外接程序支持的所有浏览器上测试正则表达式。

    因为不同的浏览器获取所选项目的文本正文的方法不同，所以应确保你的正则表达式支持正文文本部分所返回的细微差异。 例如，一些浏览器（如 Internet Explorer 9）使用 DOM 的 innerText 属性，而其他浏览器（如 Firefox）使用..textContent() 方法来获取项目的文本正文。 同样，不同浏览器所返回的换行符也可能不同：在 Internet Explorer 上返回的换行符为 \r\n，而在 Firefox 和 Chrome 上返回的换行符为 \n。 有关详细信息，请参阅 W3C DOM 兼容性 - HTML。

  • 项目的 HTML 正文在 Windows 版或 Mac 版 Outlook 上略有不同，Outlook 网页版、移动设备上或新的 Windows 版 Outlook (预览版) 。 请仔细定义正则表达式。

  • 根据应用正则表达式的 Outlook 客户端、设备类型或属性，在将正则表达式设计为激活规则时，每个客户端都有其他最佳做法和限制。 有关详细信息，请参阅 Outlook 外接程序的激活和 JavaScript API 的限制。

示例

以下 ItemHasRegularExpressionMatch 规则将在发件人的 SMTP 电子邮件地址与 @contoso 匹配（不管是大写还是小写字符）时激活外接程序。

<Rule xsi:type="ItemHasRegularExpressionMatch"
    RegExName="addressMatches"
    RegExValue="@[cC][oO][nN][tT][oO][sS][oO]"
    PropertyName="SenderSMTPAddress"
/>

下面是使用 IgnoreCase 属性指定相同正则表达式的另一种方法。

<Rule xsi:type="ItemHasRegularExpressionMatch"
    RegExName="addressMatches"
    RegExValue="@contoso"
    PropertyName="SenderSMTPAddress"
    IgnoreCase="true"
/>

以下 ItemHasRegularExpressionMatch 规则将在股票代号包含在当前项目的正文中时激活外接程序。

<Rule xsi:type="ItemHasRegularExpressionMatch"
    PropertyName="BodyAsPlaintext"
    RegExName="TickerSymbols"
    RegExValue="\b(NYSE|NASDAQ|AMEX):\s*[A-Za-z]+\b"/>

ItemHasKnownEntity 规则

ItemHasKnownEntity 规则根据所选项目的主题或正文中是否存在实体来激活外接程序。 EntityType 类型定义受支持的实体。 在 ItemHasKnownEntity 规则中应用正则表达式，可为基于实体（例如，一组特定的 URL，或含有某个区号的电话号码）的值子集进行的激活提供便利。

注意

Outlook 只能提取用英语编写的实体字符串，无论清单中指定的默认区域设置如何。 只有邮件支持 MeetingSuggestion 实体类型;约会不支持此类型。 无法从 “已发送邮件” 文件夹中的项目中提取实体，也不能使用 ItemHasKnownEntity 规则激活“ 已发送邮件 ”文件夹中项目的加载项。

ItemHasKnownEntity 规则支持下表中的属性。 请注意，尽管在 ItemHasKnownEntity 规则中指定正则表达式是可选项，如果选择使用正则表达式作为实体筛选器，则必须同时指定 RegExFilter 和 FilterName 属性。

属性名 说明
EntityType 指定若想规则计算结果为 true 而必须存在的实体类型。 请使用多个规则来指定多个类型的实体。
RegExFilter 指定用于进一步筛选由 EntityType 指定的实体实例的正则表达式。
FilterName 指定由 RegExFilter 指定的正则表达式的名称，以便稍后可通过代码引用它。
IgnoreCase 指定当匹配由 RegExFilter 指定的正则表达式时是否忽略大小写。

示例

下面的 ItemHasKnownEntity 规则将在当前项目的主题或正文中存在 URL 且该 URL 包含字符串 youtube 时激活外接程序，而不考虑字符串的大小写。

<Rule xsi:type="ItemHasKnownEntity"
    EntityType="Url"
    RegExFilter="youtube"
    FilterName="youtube"
    IgnoreCase="true"/>

在代码中使用正则表达式结果

可以通过对当前项使用以下方法获取与正则表达式的匹配项。

  • getRegExMatches 为在外接程序的 ItemHasRegularExpressionMatch 和 ItemHasKnownEntity 规则中指定的所有正则表达式返回当前项目中的匹配项。

  • getRegExMatchesByName 为外接程序的 ItemHasRegularExpressionMatch 规则中指定的已标识正则表达式返回当前项目中的匹配项。

  • getFilteredEntitiesByName 对于包含在外接程序的 ItemHasKnownEntity 规则中指定的已标识正则表达式匹配项的实体，将返回完整实例。

计算正则表达式时，匹配项将以数组对象的形式返回到你的外接程序。 对于 getRegExMatches，该对象具有正则表达式名称的标识符。

注意

Outlook 不会以数组中的任何特定顺序返回匹配项。 此外，不应假定匹配项在此数组中以相同顺序返回，即使在同一邮箱中的同一项目上运行相同的每个客户端也是如此。

示例

下面是规则集合的示例，该集合包含一个 ItemHasRegularExpressionMatch 规则，该规则具有名为 的 videoURL正则表达式。

<Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="ItemIs" ItemType="Message"/>
    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="videoURL" RegExValue="http://www\.youtube\.com/watch\?v=[a-zA-Z0-9_-]{11}" PropertyName="BodyAsPlaintext"/>
</Rule>

以下示例使用当前项目的 getRegExMatches 将变量 videos 设置为上一个 ItemHasRegularExpressionMatch 规则的结果。

const videos = Office.context.mailbox.item.getRegExMatches().videoURL;

多个匹配项将作为数组元素存储在该对象中。 下面的代码示例演示如何循环访问名为 reg1 的正则表达式的匹配项，以生成要显示为 HTML 的字符串。

function initDialer()
{
    let myEntities;
    let myString;
    let myCell;
    myEntities = Office.context.mailbox.item.getRegExMatches();

    myString = "";
    myCell = document.getElementById('dialerholder');
    // Loop over the myEntities collection.
    for (let i in myEntities.reg1) {
        myString += "<p><a href='callto:tel:" + myEntities.reg1[i] + "'>" + myEntities.reg1[i] + "</a></p>";
    }

    myCell.innerHTML = myString;
}

以下是指定 MeetingSuggestion 实体和名为 CampSuggestion 的正则表达式的 ItemHasKnownEntity 规则的示例。 Outlook 在检测到当前所选项目包含会议建议，并且主题或正文包含术语 WonderCamp 时将激活外接程序。

<Rule xsi:type="ItemHasKnownEntity"
    EntityType="MeetingSuggestion"
    RegExFilter="WonderCamp"
    FilterName="CampSuggestion"
    IgnoreCase="false"/>

以下代码示例使用当前项目中的 getFilteredEntitiesByName 设置变量 suggestions，以获取针对上一个 ItemHasKnownEntity 规则检测到的一组会议建议。

const suggestions = Office.context.mailbox.item.getFilteredEntitiesByName("CampSuggestion");

另请参阅