Использование правил активации на основе регулярных выражений для отображения надстройки Outlook

  • Статья

Вы можете указать правила на основе регулярных выражений для активации контекстной надстройки при обнаружении соответствия в определенных полях сообщения. Контекстные надстройки активируются только в режиме чтения. Outlook не активирует контекстные надстройки, когда пользователь создает элемент. Существуют и другие сценарии, в которых Outlook не активирует надстройки, например элементы с цифровой подписью. Дополнительные сведения см. в статье Правила активации для надстроек Outlook.

Важно!

Контекстные надстройки Outlook на основе сущностей будут прекращены во 2-м квартале 2024 г. Работа по прекращению использования этой функции начнется в мае и продолжится до конца июня. После июня контекстные надстройки больше не смогут обнаруживать сущности в почтовых элементах для выполнения задач над ними. Следующие API также будут прекращены.

Чтобы свести к минимуму возможные перебои, после прекращения использования контекстных надстроек на основе сущностей будет по-прежнему поддерживаться следующее.

  • Разрабатывается альтернативная реализация кнопки "Присоединиться к собранию ", которая активируется надстройками собраний по сети. После завершения поддержки контекстных надстроек на основе сущностей надстройки собраний по сети автоматически переходят на альтернативную реализацию для активации кнопки Присоединиться к собранию .
  • Правила регулярных выражений будут поддерживаться после прекращения использования контекстных надстроек на основе сущностей. Мы рекомендуем обновить контекстную надстройку, чтобы использовать правила регулярных выражений в качестве альтернативного решения.

Дополнительные сведения см. в разделе Прекращение использования контекстных надстроек Outlook на основе сущностей.

Вы можете указать регулярное выражение в составе правила ItemHasRegularExpressionMatch или ItemHasKnownEntity в XML-файле манифеста надстройки. Правила указываются в точке расширения DetectedEntity.

Примечание.

Контекстные надстройки Outlook не поддерживаются, если надстройка использует унифицированный манифест для Microsoft 365 (предварительная версия).

Outlook вычисляет регулярные выражения на основе правил интерпретатора JavaScript, используемых браузером или элементом управления webview на клиентском компьютере. Для краткости далее в этой статье используется "браузер" для ссылки на "браузер или элемент управления webview". Outlook поддерживает те же специальные знаки, что и все обработчики XML. Они перечислены в следующей таблице. Эти символы можно использовать в регулярном выражении, указав escape-последовательность соответствующего символа, как описано в следующей таблице.

Знак Описание Escape-последовательность
" Двойная кавычка "
& Амперсанд &
' Апостроф '
< Знак "меньше" &lt;
> Знак "больше" &gt;

Правило ItemHasRegularExpressionMatch

Правило ItemHasRegularExpressionMatch полезно для управления активацией надстройки на основе определенных значений поддерживаемого свойства. Ниже описаны атрибуты правила ItemHasRegularExpressionMatch.

Имя атрибута Описание
RegExName Указывает имя регулярного выражения, чтобы вы могли сослаться на него в коде надстройки.
RegExValue Указывает регулярное выражение, которое будет рассчитано для определения необходимости отображения надстройки.
PropertyName Указывает имя свойства, которое будет использоваться для вычисления регулярного выражения. Допустимые значения — BodyAsHTML, BodyAsPlaintext, SenderSMTPAddress и Subject.

Если вы укажете BodyAsHTML, Outlook будет применять регулярное выражение, только если текст элемента представлен в формате HTML. В противном случае Outlook возвращает отсутствие совпадений для этого регулярного выражения.

Если вы укажете BodyAsPlaintext, Outlook всегда будет применять регулярное выражение для текста элемента.

Важно: Если необходимо указать атрибут Highlight для <элемента Rule> , необходимо задать для атрибута PropertyName значение BodyAsPlaintext.
IgnoreCase Указывает, следует ли игнорировать регистр при поиске соответствий регулярному выражению, заданному атрибутом RegExName.
Highlight Указывает, как клиент должен выделять соответствующий текст. Этот элемент может применяться только к элементам Rule, вложенным в элементы ExtensionPoint. Допустимые значения: all и none. Если этот атрибут не задан, по умолчанию используется значение all.

Важно: Чтобы указать атрибут Highlight в элементе <Rule> , необходимо задать для атрибута PropertyName значение BodyAsPlaintext.

Рекомендации по использованию регулярных выражений в правилах

При использовании регулярных выражений обратите особое внимание на следующее.

  • Если указать ItemHasRegularExpressionMatch правило в тексте элемента, регулярное выражение должно дополнительно фильтровать текст и не пытаться вернуть весь текст элемента. Использование регулярного выражения, такого как .* попытка получить весь текст элемента, не всегда возвращает ожидаемые результаты.

  • Возвращаемый обычный текст может несколько отличаться в зависимости браузера. Если вы используете правило ItemHasRegularExpressionMatch с таким значением атрибута PropertyName: BodyAsPlaintext, проверьте свое регулярное выражение во всех поддерживаемых надстройкой браузерах.

    Так как в разных браузерах основной текст выбранного элемента считывается разными способами, ваше регулярное выражение должно учитывать мелкие различия, которые могут быть возвращены в составе основного текста. Например, в некоторых браузерах, таких как Internet Explorer 9, для получения основного текста элемента используется свойство innerText модели DOM, а в других (например, Firefox) — метод .textContent(). Кроме того, различные браузеры могут по-разному возвращать разрывы строк (в Internet Explorer — \r\n, а в Firefox и Chrome — \n). Дополнительные сведения см. в документе Консорциум W3C: совместимость с моделью DOM (HTML).

  • Html-текст элемента немного отличается от классического Outlook для Windows или Outlook на Mac и Outlook в Интернете, на мобильных устройствах или нового Outlook в Windows (предварительная версия). Будьте внимательны, задавая регулярные выражения.

  • В зависимости от клиента Outlook, типа устройства или свойства, к которому применяется регулярное выражение, существуют другие рекомендации и ограничения для каждого из клиентов, которые следует учитывать при разработке регулярных выражений в качестве правил активации. Дополнительные сведения см. в разделе Ограничения для активации и API JavaScript для надстроек Outlook .

Примеры

Следующее правило 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-адреса в теме или основном тексте текущего элемента и строки 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;
}

Ниже приведен пример правила ItemHasKnownEntity, которое указывает сущность MeetingSuggestion и регулярное выражение CampSuggestion. 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");

См. также