Надстройки Office с манифестом унифицированного приложения для Microsoft 365 (предварительная версия)

  • Статья

В этой статье представлен манифест унифицированного приложения для Microsoft 365 в предварительной версии. Предполагается, что вы знакомы с манифестом надстроек Office.

Совет

Корпорация Майкрософт вносит ряд улучшений в платформу разработчиков Microsoft 365. Эти улучшения повышают согласованность при разработке, развертывании, установке и администрировании всех типов расширений Microsoft 365, включая надстройки Office. Эти изменения совместимы с существующими надстройками.

Одним из важных улучшений, над которым мы работаем, является возможность создания единой единицы распространения для всех расширений Microsoft 365 (приложения Teams) с использованием одного формата манифеста и схемы на основе унифицированного манифеста приложения в формате JSON для Microsoft 365.

Примечание.

Любое расширение любой части платформы Microsoft 365 теперь называется "приложением Teams", даже если оно не расширяет само приложение Teams.

Мы сделали важный первый шаг к достижению этих целей, сделав возможным создание надстроек Outlook, работающих только в Windows, с унифицированным манифестом для Microsoft 365.

Примечание.

  • Унифицированный манифест доступен для предварительной версии и может быть изменен на основе отзывов. Мы рекомендуем опытным разработчикам надстроек поэкспериментировать с ним. Унифицированный манифест не следует использовать в рабочих надстройках.
  • Предварительная версия унифицированного манифеста поддерживает только надстройки Outlook и только в Office, скачанные из подписки Microsoft 365 и установленные в Windows. Мы работаем над расширением поддержки Excel, PowerPoint и Word, а также на других платформах.
  • Для единого манифеста требуется Office версии 2304 (сборка 16320.00000) или более поздней. Канал подписки На Microsoft 365 должен быть "Бета-версия".

Совет

Готовы приступить к работе с унифицированным манифестом предварительной версии? Начните с создания надстройки Outlook с унифицированным манифестом для Microsoft 365 (предварительная версия).

Ключевые свойства унифицированного манифеста

Справочная документация по предварительной версии манифеста единого приложения main приведена в разделе Схема манифеста общедоступной предварительной версии приложения для разработчиков для Teams. Эта статья содержит сведения о критических свойствах базового манифеста, но не может содержать документацию по свойству extensions, которое является свойством, в котором надстройки Office настраиваются в унифицированном манифесте. Поэтому в этой статье мы предоставим краткое описание значения базовых свойств, когда приложение Teams является (или включает) надстройку Office. За этим следует базовая документация по свойству extensions и его потомкам. Полный пример манифеста для надстройки приведен в разделе Пример унифицированного манифеста предварительной версии.

Базовые свойства

Каждое из базовых свойств, перечисленных в следующей таблице, содержит более подробную документацию по схеме манифеста общедоступной предварительной версии приложения для разработчиков для Teams. Базовые свойства, не включенные в эту таблицу, не имеют значения для надстроек Office.

Свойство JSON Назначение
"$schema" Определяет схему манифеста.
"manifestVersion" Версия схемы манифеста.
"id" GUID приложения или надстройки Teams.
"version" Версия приложения или надстройки Teams.
"name" Общедоступные короткие и длинные имена приложения или надстройки Teams. Короткое имя отображается в верхней части области задач надстройки.
"description" Общедоступные краткие и длинные описания приложения или надстройки Teams.
"developer" Сведения о разработчике приложения или надстройки Teams.
"localizationInfo" Настраивает языковой стандарт по умолчанию и другие поддерживаемые языковые стандарты.
"validDomains" См . раздел Указание безопасных доменов.
"webApplicationInfo" Определяет веб-приложение или надстройку Teams, известное в Azure Active Directory.
"authorization" Определяет все разрешения Microsoft Graph, необходимые надстройке.

Свойство extensions

Мы прилагаем все усилия, чтобы заполнить справочную документацию по свойству extensions и его потомкам. В то же время ниже приведена базовая документация. Большинство , но не все свойства имеют эквивалентный элемент (или атрибут) в XML-манифесте для надстроек. В большинстве случаев описание и ограничения, применяемые к xml-элементу или атрибуту, также применяются к эквиваленту свойства JSON в унифицированном манифесте. Таблицы в разделе "extensions" раздела "Сравнение XML-манифеста с унифицированным манифестом для Microsoft 365 " помогут определить XML-эквивалент свойства JSON.

Свойство JSON Назначение
"requirements.capabilities" Определяет наборы требований , которые необходимо установить надстройке.
"requirements.scopes" Определяет приложения Office, в которых можно установить надстройку. Например, "почта" означает, что надстройку можно установить в Outlook.
"ribbons" Ленты, которые настраивает надстройка.
"ribbons.contexts" Указывает поверхности команд, которые настраивает надстройка. Например, "mailRead" или "mailCompose".
"ribbons.tabs" Настраивает пользовательские вкладки ленты.
"alternatives" Указывает обратную совместимость с эквивалентной надстройкой COM, XLL или обоими вариантами.
"runtimes" Настраивает внедренные среды выполнения , которые использует надстройка, в том числе различные типы надстроек, которые имеют практически или не имеют пользовательского интерфейса, например пользовательские надстройки только для функций и команды функций.
"autoRunEvents" Настраивает обработчик для указанного события.

Указание безопасных доменов

В файле манифеста есть массив validDomains, который используется для того, чтобы сообщить Office, к каким доменам следует разрешить переход вашей надстройке. Как отмечалось в разделе Указание доменов, которые нужно открыть в окне надстройки, при запуске в Office в Интернете область задач можно перейти по любому URL-адресу. Однако на классических платформах, если надстройка пытается перейти по URL-адресу в домене, отличном от домена, в котором размещена начальная страница, этот URL-адрес открывается в новом окне браузера за пределами области надстройки приложения Office.

Чтобы переопределить это поведение на настольных платформах, добавьте каждый домен, который нужно открыть в окне надстройки, в список доменов, указанных в массиве validDomains. URL-адреса в доменах из списка будут открываться в области задач как в классическом Office, так и в Office в Интернете. Если он пытается перейти по URL-адресу, который отсутствует в списке, в Office на рабочем столе этот URL-адрес открывается в новом окне браузера (за пределами области задач надстройки).

Пример унифицированного манифеста предварительного просмотра

Ниже приведен пример манифеста унифицированного приложения предварительной версии для надстройки.

{
  "$schema": "https://raw.githubusercontent.com/OfficeDev/microsoft-teams-app-schema/op/extensions/MicrosoftTeams.schema.json",
  "id": "00000000-0000-0000-0000-000000000000",
  "version": "1.0.0",
  "manifestVersion": "devPreview",
  "name": {
    "short": "Name of your app (<=30 chars)",
    "full": "Full name of app, if longer than 30 characters (<=100 chars)"
  },
  "description": {
    "short": "Short description of your app (<= 80 chars)",
    "full": "Full description of your app (<= 4000 chars)"
  },
  "icons": {
    "outline": "outline.png",
    "color": "color.png"
  },
  "accentColor": "#230201",
  "developer": {
    "name": "Contoso",
    "websiteUrl": "https://www.contoso.com",
    "privacyUrl": "https://www.contoso.com/privacy",
    "termsOfUseUrl": "https://www.contoso.com/servicesagreement"
  },
  "localizationInfo": {
    "defaultLanguageTag": "en-us",
    "additionalLanguages": [
      {
        "languageTag": "es-es",
        "file": "es-es.json"
      }
    ]
  },
  "webApplicationInfo": {
    "id": "00000000-0000-0000-0000-000000000000",
    "resource": "api://www.contoso.com/prodapp"
  },
  "authorization": {
    "permissions": {
      "resourceSpecific": [
        {
          "name": "Mailbox.ReadWrite.User",
          "type": "Delegated"
        }
      ]
    }
  },
  "extensions": [
    {
      "requirements": {
        "scopes": [ "mail" ],
        "capabilities": [
          {
            "name": "Mailbox", "minVersion": "1.1"
          }
        ]
      },
      "runtimes": [
        {
          "requirements": {
            "capabilities": [
              {
                "name": "MailBox", "minVersion": "1.10"
              }
            ]
          },
          "id": "eventsRuntime",
          "type": "general",
          "code": {
            "page": "https://contoso.com/events.html",
            "script": "https://contoso.com/events.js"
          },
          "lifetime": "short",
          "actions": [
            {
              "id": "onMessageSending",
              "type": "executeFunction"
            },
            {
              "id": "onNewMessageComposeCreated",
              "type": "executeFunction"
            }
          ]
        },
        {
          "requirements": {
            "capabilities": [
              {
                "name": "MailBox", "minVersion": "1.1"
              }
            ]
          },
          "id": "commandsRuntime",
          "type": "general",
          "code": {
            "page": "https://contoso.com/commands.html",
            "script": "https://contoso.com/commands.js"
          },
          "lifetime": "short",
          "actions": [
            {
              "id": "action1",
              "type": "executeFunction"
            },
            {
              "id": "action2",
              "type": "executeFunction"
            },
            {
              "id": "action3",
              "type": "executeFunction"
            }
          ]
        }
      ],
      "ribbons": [
        {
          "contexts": [
            "mailCompose"
          ],
          "tabs": [
            {
              "builtInTabId": "TabDefault",
              "groups": [
                {
                  "id": "dashboard",
                  "label": "Controls",
                  "controls": [
                    {
                      "id": "control1",
                      "type": "button",
                      "label": "Action 1",
                      "icons": [
                        {
                          "size": 16,
                          "url": "test_16.png"
                        },
                        {
                          "size": 32,
                          "url": "test_32.png"
                        },
                        {
                          "size": 80,
                          "url": "test_80.png"
                        }
                      ],
                      "supertip": {
                        "title": "Action 1 Title",
                        "description": "Action 1 Description"
                      },
                      "actionId": "action1"
                    },
                    {
                      "id": "menu1",
                      "type": "menu",
                      "label": "My Menu",
                      "icons": [
                        {
                          "size": 16,
                          "url": "test_16.png"
                        },
                        {
                          "size": 32,
                          "url": "test_32.png"
                        },
                        {
                          "size": 80,
                          "url": "test_80.png"
                        }
                      ],
                      "supertip": {
                        "title": "My Menu",
                        "description": "Menu with 2 actions"
                      },
                      "items": [
                        {
                          "id": "menuItem1",
                          "type": "menuItem",
                          "label": "Action 2",
                          "supertip": {
                            "title": "Action 2 Title",
                            "description": "Action 2 Description"
                          },
                          "actionId": "action2"
                        },
                        {
                          "id": "menuItem2",
                          "type": "menuItem",
                          "label": "Action 3",
                          "icons": [
                            {
                              "size": 16,
                              "url": "test_16.png"
                            },
                            {
                              "size": 32,
                              "url": "test_32.png"
                            },
                            {
                              "size": 80,
                              "url": "test_80.png"
                            }
                          ],
                          "supertip": {
                            "title": "Action 3 Title",
                            "description": "Action 3 Description"
                          },
                          "actionId": "action3"
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "contexts": [ "mailRead" ],
          "tabs": [
            {
              "builtInTabId": "TabDefault",
              "groups": [
                {
                  "id": "dashboard",
                  "label": "Controls",
                  "controls": [
                    {
                      "id": "control1",
                      "type": "button",
                      "label": "Action 1",
                      "icons": [
                        {
                          "size": 16,
                          "url": "test_16.png"
                        },
                        {
                          "size": 32,
                          "url": "test_32.png"
                        },
                        {
                          "size": 80,
                          "url": "test_80.png"
                        }
                      ],
                      "supertip": {
                        "title": "Action 1 Title",
                        "description": "Action 1 Description"
                      },
                      "actionId": "action1"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "autoRunEvents": [
        {
          "requirements": {
            "capabilities": [
              {
                "name": "MailBox", "minVersion": "1.10"
              }
            ]
          },
          "events": [
            {
              "type": "newMessageComposeCreated",
              "actionId": "onNewMessageComposeCreated"
            },
            {
              "type": "messageSending",
              "actionId": "onMessageSending",
              "options": {
                "sendMode": "promptUser"
              }
            }
          ]
        }
      ],
      "alternates": [
        {
          "requirements": {
            "scopes": [ "mail" ]
          },
          "prefer": {
            "comAddin": {
              "progId": "ContosoExtension"
            }
          },
          "hide": {
            "storeOfficeAddin": {
              "officeAddinId": "00000000-0000-0000-0000-000000000000",
              "assetId": "WA000000000"
            }
          }
        }
      ]
    }
  ]
}

См. также