Правила активации контекстных надстроек Outlook

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

Важно!

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

• Office.context.mailbox.item.getEntities()
• Office.context.mailbox.item.getEntitiesByType(entityType)
• Office.context.mailbox.item.getFilteredEntitiesByName(name)
• Office.context.mailbox.item.getSelectedEntities()

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

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

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

Указание правил активации в манифесте

Примечание.

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

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

• элемент Rule (MailApp complexType), задающий отдельное правило;
• Элемент Rule (RuleCollection complexType), совмещающий несколько правил с помощью логических операторов.

Примечание.

Элемент Rule , используемый для указания отдельного правила, имеет абстрактный сложный тип Rule . Каждый из следующих типов правил расширяет этот абстрактный Rule сложный тип. Следовательно, указывая отдельное правило в манифесте, необходимо использовать атрибут xsi:type, чтобы определить один из перечисленных ниже типов правил.

Например, следующее правило определяет правило ItemIs . <Rule xsi:type="ItemIs" ItemType="Message" />

Атрибут FormType применяется к правилам активации в манифесте версии 1.1, но не определен в VersionOverrides версии 1.0. Поэтому его нельзя использовать, когда ItemIs используется в VersionOverrides узле.

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

Имя правила	Применимые формы	Описание
ItemIs	Чтение, создание	Проверяет, относится ли текущий элемент к определенному типу (сообщение или встреча). Кроме того, оно может проверять класс элемента, тип формы и, при необходимости, класс сообщения элемента.
ItemHasAttachment	Чтение	Проверяет, содержит ли выделенный элемент вложение.
ItemHasKnownEntity	Чтение	Проверяет, содержит ли выделенный элемент одну или несколько хорошо известных сущностей. Дополнительные сведения см. в статье Сопоставление строк в элементе Outlook как хорошо известных сущностей.
ItemHasRegularExpressionMatch	Чтение	Проверяет, содержит ли адрес электронной почты отправителя, тема и/или тело выбранного элемента совпадение с регулярным выражением. Подробнее: Использование регулярных правил активации выражений для отображения надстройки Outlook.
RuleCollection	Чтение, создание	Объединяет набор правил, чтобы можно было создавать более сложные правила.

Правило ItemIs

Сложный ItemIs тип определяет правило, которое вычисляет значение , true если текущий элемент соответствует типу элемента, и при необходимости класс сообщения элемента, если он указан в правиле.

Укажите один из следующих типов элементов в атрибуте ItemTypeItemIs правила. В манифесте можно указать несколько ItemIs правил. Значение simpleType атрибута ItemType определяет типы элементов Outlook, поддерживающих надстройки Outlook.

Value	Описание
Встреча	Указывает элемент в календаре Outlook. Это может быть элемент собрания, для которого был отправлен ответ и у которого есть организатор и участники, или встреча без организатора или участника, которая просто представляет собой элемент календаря. Соответствует классу сообщений IPM.Appointment в Outlook.
Сообщение	Указывает один из следующих элементов, получаемых обычно в папке "Входящие". Сообщение электронной почты. Соответствует классу сообщений IPM.Note в Outlook. Запрос на собрание, ответ или отклонение. Это соответствует следующим классам сообщений в Outlook. IPM.Schedule.Meeting.Request IPM.Schedule.Meeting.Neg IPM.Schedule.Meeting.Pos IPM.Schedule.Meeting.Tent IPM.Schedule.Meeting.Canceled

Атрибут FormType используется для указания режима (чтение или создание), в котором должна активироваться надстройка.

Примечание.

Атрибут ItemIs FormType определен в схеме версии 1.1 и более поздних версий, но не в VersionOverrides версии 1.0. Не включайте 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 , которое показывает надстройку, когда в элементе присутствует сущность указанного типа. В атрибуте правила можно указать следующие известные EntityTypeItemHasKnownEntity сущности.

• Address
• Contact
• EmailAddress
• MeetingSuggestion
• PhoneNumber
• TaskSuggestion
• URL-адрес

При необходимости в атрибут можно включить регулярное выражение RegularExpression , чтобы надстройка отображалось только в том случае, если сущность, соответствующая регулярному выражению в настоящем. Чтобы получить совпадения с регулярными выражениями, указанными в ItemHasKnownEntity правилах, можно использовать getRegExMatches метод или getFilteredEntitiesByName для выбранного элемента Outlook.

В следующем примере показана 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>

В следующем примере показано ItemHasKnownEntity правило с атрибутом RegularExpression , которое активирует надстройку, когда в сообщении присутствует URL-адрес, содержащий слово contoso.

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

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

Правило ItemHasRegularExpressionMatch

Сложный ItemHasRegularExpressionMatch тип определяет правило, которое использует регулярное выражение для сопоставления содержимого указанного свойства элемента. Если текст, соответствующий регулярному выражению, обнаруживается в заданном свойстве элемента, Outlook активирует панель надстроек и отображает надстройку. Для получения совпадений getRegExMatches для указанного регулярного выражения можно использовать метод или getRegExMatchesByName объекта , представляющего выбранный в данный момент элемент.

В следующем примере показан объект ItemHasRegularExpressionMatch , который активирует надстройку, если текст выбранного элемента содержит "apple", "banana" или "coconut", игнорируя регистр.

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

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

Правило RuleCollection

Сложный RuleCollection тип объединяет несколько правил в одно правило. С помощью атрибута Mode можно указать, должны ли правила в коллекции сочетаться с логическим ИЛИ или логическим И.

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

Вы можете объединять 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-интерфейсов. В следующей таблице показаны общие ограничения для регулярных выражений и правил, но существуют определенные правила для разных приложений. Дополнительные сведения см . в разделах Ограничения активации и API JavaScript для надстроек Outlook и Устранение неполадок с активацией надстройки Outlook.

Элемент надстройки	Рекомендации
Размер манифеста	Не более 256 КБ.
Правила	Не более 15 правил.
ItemHasKnownEntity	Outlook в Windows и mac применяет правило к первым 1 МБ основного текста, а не к остальной части текста.
Регулярные выражения	Для правил ItemHasKnownEntity или ItemHasRegularExpressionMatch для всех приложений Outlook: Укажите не более пяти регулярных выражений в правилах активации для надстройки Outlook. Вы не сможете установить надстройку, если превысите это ограничение. Задавайте регулярные выражения, ожидаемые результаты которых возвращаются в первых 50 совпадениях с помощью метода getRegExMatches. Важно! Текст выделяется на основе строк, которые являются результатом сопоставления регулярного выражения. Однако выделенные вхождения могут не точно соответствовать тому, что должно быть результатом фактических утверждений регулярных выражений, таких как отрицательный взгляд вперед (?!text), просмотр за спиной (?<=text)и отрицательный просмотр позади (?<!text). Например, если вы используете регулярное выражение under(?!score) "Like under, under score, and подчеркивание", строка "under" выделяется для всех вхождений, а не только для первых двух. Укажите регулярные выражения, совпадение которых не превышает ограничения, указанные в следующей таблице. Ограничение длины для результата, соответствующего регулярному выражению Outlook в Windows и на Mac Outlook для iOS и Android Основной текст элемента в виде простого текста 1,5 КБ 3 КБ Основной текст элемента в виде HTML-кода 3 КБ 3 КБ

См. также

• Создание надстроек Outlook для форм создания
• Ограничения активации и API JavaScript для надстроек Outlook
• Использование правил активации на основе регулярных выражений для отображения надстройки Outlook
• Сопоставление строк в элементе Outlook как известных сущностей