Правила активации контекстных надстроек 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
узле.
В следующей таблице перечислены типы доступных правил. Дополнительные сведения можно найти в таблице и в указанных статьях в разделе Create надстройки Outlook для форм чтения.
Имя правила | Применимые формы | Описание |
---|---|---|
ItemIs | Чтение, создание | Проверяет, относится ли текущий элемент к определенному типу (сообщение или встреча). Кроме того, оно может проверять класс элемента, тип формы и, при необходимости, класс сообщения элемента. |
ItemHasAttachment | Чтение | Проверяет, содержит ли выделенный элемент вложение. |
ItemHasKnownEntity | Чтение | Проверяет, содержит ли выделенный элемент одну или несколько хорошо известных сущностей. Дополнительные сведения см. в статье Сопоставление строк в элементе Outlook как хорошо известных сущностей. |
ItemHasRegularExpressionMatch | Чтение | Проверяет, содержит ли адрес электронной почты отправителя, тема и/или тело выбранного элемента совпадение с регулярным выражением. Подробнее: Использование регулярных правил активации выражений для отображения надстройки Outlook. |
RuleCollection | Чтение, создание | Объединяет набор правил, чтобы можно было создавать более сложные правила. |
Правило ItemIs
Сложный ItemIs
тип определяет правило, которое вычисляет значение , true
если текущий элемент соответствует типу элемента, и при необходимости класс сообщения элемента, если он указан в правиле.
Укажите один из следующих типов элементов в атрибуте ItemType
ItemIs
правила. В манифесте можно указать несколько ItemIs
правил. Значение simpleType атрибута ItemType определяет типы элементов Outlook, поддерживающих надстройки Outlook.
Value | Описание |
---|---|
Встреча | Указывает элемент в календаре Outlook. Это может быть элемент собрания, для которого был отправлен ответ и у которого есть организатор и участники, или встреча без организатора или участника, которая просто представляет собой элемент календаря. Соответствует классу сообщений IPM.Appointment в Outlook. |
Сообщение | Указывает один из следующих элементов, получаемых обычно в папке "Входящие".
|
Атрибут 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
, которое показывает надстройку, когда в элементе присутствует сущность указанного типа. В атрибуте правила можно указать следующие известные EntityType
ItemHasKnownEntity
сущности.
- 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:
|
См. также
Office Add-ins
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по