Вызов надстройки Outlook из окна сообщения с действиями

  • Статья

Сообщения с действиями позволяют пользователям быстро выполнять действия с сообщениями электронной почты или карточками соединителя, а надстройки Outlook позволяют вам расширить возможности Outlook, добавив новые способы взаимодействия. Благодаря типу действий Action.InvokeAddInCommand можно объединить эти два типа интеграции, чтобы увеличить функциональность и привлекательность интерфейса. Вы могли бы сделать, например, следующее:

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

Действия Action.InvokeAddInCommand подходят как для установленных, так и не установленных пользователем надстроек. Если требуемая надстройка не установлена, пользователю предлагается установить ее, всего лишь раз щелкнув мышью.

Примечание.

Установка необходимой надстройки одним щелчком поддерживается только в том случае, если надстройка опубликована в AppSource.

В приведенном ниже примере показано окно запроса, которое отображается для пользователей, если надстройка не установлена.

Снимок экрана: запрос на установку надстройки при вызове из сообщения с действиями.

Вызов надстройки

Сообщения с действиями позволяют вызывать надстройки, когда указано действие Action.InvokeAddInCommand. Оно указывает надстройку, которую требуется вызвать, а также идентификатор кнопки надстройки, позволяющей открыть нужную область задач.

Нужные сведения приведены в манифесте надстройки. Сперва понадобится идентификатор надстройки, указанный в элементе Id.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp
  xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
  xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
  xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0"
  xsi:type="MailApp">
  <Id>527104a1-f1a5-475a-9199-7a968161c870</Id>
  <Version>1.0.0.0</Version>
  ...
</OfficeApp>

Для этой надстройки используется идентификатор 527104a1-f1a5-475a-9199-7a968161c870.

Далее понадобится атрибут id для элемента Control, который определяет кнопку надстройки, позволяющую открыть нужную область задач. Помните о том, что элемент Control ДОЛЖЕН:

<ExtensionPoint xsi:type="MessageReadCommandSurface">
  <OfficeTab id="TabDefault">
    <Group id="msgReadCmdGroup">
      <Label resid="groupLabel"/>
      <Control xsi:type="Button" id="showInitContext">
        <Label resid="readButtonLabel"/>
        <Supertip>
          <Title resid="readButtonTitle"/>
          <Description resid="readButtonDesc"/>
        </Supertip>
        <Icon>
          <bt:Image size="16" resid="icon-16"/>
          <bt:Image size="32" resid="icon-32"/>
          <bt:Image size="80" resid="icon-80"/>
        </Icon>
        <Action xsi:type="ShowTaskpane">
          <SourceLocation resid="readPaneUrl"/>
          <SupportsPinning>true</SupportsPinning>
        </Action>
      </Control>
    </Group>
  </OfficeTab>
</ExtensionPoint>

Идентификатор этой кнопки надстройки: showInitContext.

Используя эти данные, мы можем создать базовое действие Action.InvokeAddInCommand, как показано в следующем примере:

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Invoking an add-in command from an Actionable Message card",
      "size": "large"
    }
  ],
  "actions": [
    {
      "type": "Action.InvokeAddInCommand",
      "title": "Invoke \"View Initialization Context\"",
      "addInId": "527104a1-f1a5-475a-9199-7a968161c870",
      "desktopCommandId": "showInitContext"
    }
  ]
}

Передача данных инициализации надстройке

Действие Action.InvokeAddInCommand обеспечивает также дополнительный контекст для надстройки, благодаря чему она может не только активироваться. Например, с помощью действия можно предоставить начальные значения для формы, а также данные, которые позволяют надстройке "перейти" к некоему элементу во внутренней службе.

Чтобы обеспечить передачу данных инициализации, включите свойство initializationContext в действие Action.InvokeAddInCommand. Для свойства initializationContext не предусмотрено готовой схемы, вы можете включить любой допустимый объект JSON.

Например, чтобы расширить пример действия, указанный выше, мы можем изменить это действие так:

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Invoking an add-in command from an Actionable Message card",
      "size": "large"
    }
  ],
  "actions": [
    {
      "type": "Action.InvokeAddInCommand",
      "title": "Invoke \"View Initialization Context\"",
      "addInId": "527104a1-f1a5-475a-9199-7a968161c870",
      "desktopCommandId": "showInitContext",
      "initializationContext": {
        "property1": "Hello world",
        "property2": 5,
        "property3": true
      }
    }
  ]
}

Получение данных инициализации в надстройке

Если ваше действие обеспечивает передачу данных инициализации, надстройку нужно подготовить к их получению. Надстройки могут получать данные инициализации, вызывая метод Office.context.mailbox.item.getInitializationContextAsync. Это должно выполняться каждый раз, когда в области задач открывается или загружается новое сообщение.

// Get the initialization context (if present).
Office.context.mailbox.item.getInitializationContextAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    if (asyncResult.value.length > 0) {
      // The value is a string, parse to an object.
      const context = JSON.parse(asyncResult.value);
      // Do something with context.
    } else {
      // Empty context, treat as no context.
    }
  } else {
    // Handle the error.
  }
});

Ресурсы