XML-манифест надстроек Office

XML-файл манифеста надстройки Office описывает способ ее активации, когда пользователь устанавливает и использует эту надстройку для работы с документами и приложениями Office.

Совет

В этой статье описывается текущий манифест в формате XML. Кроме того, существует манифест в формате JSON Teams который доступен в предварительной версии. Дополнительные сведения см. в Манифест Teams для надстроек Office (предварительная версия).

С помощью XML-файла манифеста надстройка Office может выполнять следующие действия:

  • предоставлять идентификатор, версию, описание, отображаемое имя и языковой стандарт по умолчанию.

  • указывать изображения, используемые для фирменного оформления надстройки, и значки, используемые для команд надстройки на ленте приложения Office;

  • указывать, как надстройка интегрируется с Office, включая создаваемые ею элементы пользовательского интерфейса, например кнопки на ленте;

  • определять запрошенные размеры по умолчанию для контентных надстроек, а также запрошенную высоту для надстроек Outlook;

  • объявлять разрешения, в которых нуждается надстройка Office, например чтение или запись документа;

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

Примечание

Если вы планируете опубликовать надстройку в AppSource и сделать ее доступной в интерфейсе Office, необходимо выполнить требованияполитик сертификации для коммерческих магазинов приложений. Например, для успешного прохождения проверки ваша надстройка должна работать на всех платформах, поддерживающих определяемые вами методы (дополнительные сведения см. в разделе 1120.3 и на странице применимости и доступности надстроек Office).

Совет

Если вы будете тестировать надстройку в нескольких средах (например, в среде разработки, в промежуточной среде, в демонстрационной среде и т. п.), рекомендуем использовать отдельный XML-файл манифеста для каждой среды. В каждом файле манифеста можно:

  • Указать URL-адреса, соответствующие среде.
  • Настроить значения метаданных, такие как DisplayName, и метки в Resources для указания среды, чтобы конечные пользователи могли определить соответствующую среду надстройки, загруженной без публикации.
  • Настроить пользовательские функции namespace, чтобы указать среду, если ваша надстройка определяет пользовательские функции.

Соблюдение этих рекомендаций поможет вам упорядочить процесс тестирования и избежать проблем, которые могли бы возникнуть при одновременной загрузке вашей надстройки для нескольких сред.

Обязательные элементы

В приведенной ниже таблице указаны обязательные элементы для трех типов надстроек Office.

Примечание

Кроме того, есть обязательный порядок размещения элементов в родительском элементе. Дополнительные сведения см. в статье Как определить правильный порядок элементов манифеста.

Обязательные элементы по типам надстроек Office

Элемент Контентная Для области задач Outlook
OfficeApp Обязательный Обязательный Обязательный
Id Обязательный Обязательный Обязательный
Version Обязательный Обязательный Обязательный
ProviderName Обязательный Обязательный Обязательный
DefaultLocale Обязательный Обязательный Обязательный
DisplayName Обязательный Обязательный Обязательный
Description Обязательный Обязательный Обязательный
IconUrl Обязательный Обязательный Обязательный
SupportUrl** Обязательный Обязательный Обязательный
DefaultSettings (ContentApp)
DefaultSettings (TaskPaneApp)
Обязательный Обязательный Недоступно
SourceLocation (ContentApp)
SourceLocation (TaskPaneApp)
SourceLocation (MailApp)
Обязательный Обязательный Обязательный
DesktopSettings Недоступно Недоступно Обязательный
Permissions (ContentApp)
Permissions (TaskPaneApp)
Permissions (MailApp)
Обязательный Обязательный Обязательный
Rule (RuleCollection)
Rule (MailApp)
Недоступно Недоступно Обязательный
Requirements (MailApp)* Неприменимо Недоступно Обязательный
Set*
Sets (Requirements)*
Sets (MailAppRequirements)*
Обязательный Обязательный Обязательный
Form*
FormSettings*
Недоступно Недоступно Обязательный
Hosts* Обязательный Обязательный Необязательный

*Элемент добавлен в схеме манифеста для надстроек Office версии 1.1.

** SupportUrl требуется только для надстроек распространяемых с помощью AppSource.

Требования к размещению

Все URI изображений, в частности используемые для команд надстройки, должны поддерживать кэширование. Сервер с изображением не должен возвращать заголовок Cache-Control, содержащий no-cache, no-store или подобные параметры в ответе HTTP.

Все URL-адреса, например адреса исходных файлов, указанные в элементе SourceLocation, должны быть защищены с помощью SSL (HTTPS). Использовать конечную точку HTTPS для надстройки не обязательно, но настоятельно рекомендуется. Надстройки без SSL-защиты (HTTPS) выдают предупреждения о небезопасном контенте и ошибки во время использования. Для запуска в Office в Интернете и публикации в AppSource надстройка должна быть защищена с помощью SSL. Если надстройка получает данные из внешнего источника, она должна использовать SSL-соединение для защиты данных при передаче. Самозаверяющие сертификаты можно использовать для разработки и тестирования, если они добавлены в список доверенных сертификатов на локальном компьютере.

Рекомендации по отправке решений в AppSource

Убедитесь, что идентификатор надстройки представляет собой допустимый и уникальный GUID. В Интернете доступно множество генераторов, с помощью которых можно создать уникальный GUID.

Надстройки, отправляемые в AppSource, также должны включать элемент SupportUrl. Дополнительные сведения см. в статье Политики проверки для приложений и надстроек, отправляемых в AppSource.

Чтобы указать домены, отличные от указанного в элементе SourceLocation для сценариев проверки подлинности, используйте только элемент AppDomains.

Укажите домены, которые необходимо открыть в окне надстройки

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

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

Примечание

Из этого правила есть два исключения.

  • Это относится только к корневой области надстройки. Если в страницу надстройки внедрен iframe, его можно перенаправить на любой URL-адрес, независимо от того, указан ли он в элементе <AppDomains>, даже в классической версии Office.
  • Если диалоговое окно открыто с помощью API displayDialogAsync, URL-адрес, передаваемый методу, должен находиться в том же домене, что и надстройка. Затем диалоговое окно можно перенаправить на любой URL-адрес, независимо от того, указан ли он в элементе <AppDomains>, даже в классической версии Office.

В приведенном ниже примере XML-манифеста главная страница надстройки размещена в домене https://www.contoso.com, указанном в элементе <SourceLocation>. В нем также указан домен https://www.northwindtraders.com с помощью элемента AppDomain из списка <AppDomains>. Страница в домене www.northwindtraders.com будет открываться в области надстроек даже в классической версии Office.

<?xml version="1.0" encoding="UTF-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="TaskPaneApp">
  <!--IMPORTANT! Id must be unique for each add-in. If you copy this manifest ensure that you change this id to your own GUID. -->
  <Id>c6890c26-5bbb-40ed-a321-37f07909a2f0</Id>
  <Version>1.0</Version>
  <ProviderName>Contoso, Ltd</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Northwind Traders Excel" />
  <Description DefaultValue="Search Northwind Traders data from Excel"/>
  <SupportUrl DefaultValue="[Insert the URL of a page that provides support information for the app]" />
  <AppDomains>
    <AppDomain>https://www.northwindtraders.com</AppDomain>
  </AppDomains>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://www.contoso.com/search_app/Default.aspx" />
  </DefaultSettings>
  <Permissions>ReadWriteDocument</Permissions>
</OfficeApp>

Переопределение версии в манифесте

Необязательный элемент VersionOverrides заслуживает особого упоминания. Он содержит вложенную дочернюю разметку, которая активирует дополнительные функции надстройки. Вот некоторые из этих функций:

  • Настройка ленты и меню Office.
  • Настройка работы Office со встроенными средами выполнения, в которых выполняются надстройки.
  • Настройка взаимодействия надстройки с Azure Active Directory и Microsoft Graph для единого входа в систему.

Некоторые дочерние элементы VersionOverrides имеют значения, переопределяющие значения родительского OfficeApp элемента. Например, элемент Hosts в VersionOverrides переопределяет элемент Hosts в OfficeApp.

Элемент VersionOverrides имеет собственную схему, точнее — четыре схемы, в зависимости от типа надстройки и используемых функций. Вот эти схемы:

Когда используется элемент VersionOverrides, элемент OfficeApp должен иметь атрибут xmlns, который определяет соответствующую схему. Возможные значения атрибута:

  • http://schemas.microsoft.com/office/taskpaneappversionoverrides
  • http://schemas.microsoft.com/office/contentappversionoverrides
  • http://schemas.microsoft.com/office/mailappversionoverrides

Сам элемент VersionOverrides также должен иметь атрибут xmlns, определяющий схему. Возможные значения: три, приведенные выше, а также следующие:

  • http://schemas.microsoft.com/office/mailappversionoverrides/1.1

Элемент VersionOverrides также должен иметь атрибут xsi:type, который определяет версию схемы. Возможные значения:

  • VersionOverridesV1_0
  • VersionOverridesV1_1

Ниже приводятся примеры использования VersionOverrides в надстройке области задач и в надстройке почты соответственно. Обратите внимание, что когда используется почта VersionOverrides с версией 1.1, она должна быть последним дочерним элементом родительского элемента VersionOverrides типа 1.0. Значения дочерних элементов во внутреннем VersionOverrides переопределяют значения одноименных элементов в родительском вложении VersionOverrides и прародительском OfficeApp элементе.

<VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    <!-- child elements omitted -->
</VersionOverrides>
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <!-- other child elements omitted -->
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    <!-- child elements omitted -->
  </VersionOverrides>
</VersionOverrides>

Пример манифеста, включающего элемент VersionOverrides, см. в примерах и схемах XML-файлов Манифеста версии 1.1.

Указание доменов, из которых выполняются вызовы API Office.js

Ваша надстройка может выполнять вызовы API Office.js из домена, указанного в элементе SourceLocation файла манифеста. Если в вашей надстройке есть другие блоки IFrame, которым требуется доступ к API Office.js, добавьте домен этого исходного URL-адреса в список, указанный в элементе AppDomains файла манифеста. Если блок IFrame с источником, не содержащимся в списке AppDomains, попытается выполнить вызов API Office.js, надстройка получит ошибку об отказе в разрешении.

XML-файлы манифеста версии 1.1: примеры и схемы

Ниже показаны примеры XML-файлов манифеста версии 1.1 для надстроек области задач, контентных надстроек и надстроек Outlook.

Схемы манифестов надстроек

<?xml version="1.0" encoding="utf-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0" xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="TaskPaneApp">

  <!-- See https://github.com/OfficeDev/Office-Add-in-Commands-Samples for documentation-->

  <!-- BeginBasicSettings: Add-in metadata, used for all versions of Office unless override provided -->

  <!--IMPORTANT! Id must be unique for your add-in. If you copy this manifest ensure that you change this id to your own GUID. -->
  <Id>e504fb41-a92a-4526-b101-542f357b7acb</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <!-- The display name of your add-in. Used on the store and various placed of the Office UI such as the add-ins dialog -->
  <DisplayName DefaultValue="Add-in Commands Sample" />
  <Description DefaultValue="Sample that illustrates add-in commands basic control types and actions" />
  <!--Icon for your add-in. Used on installation screens and the add-ins dialog -->
  <IconUrl DefaultValue="https://contoso.com/assets/icon-32.png" />
  <HighResolutionIconUrl DefaultValue="https://contoso.com/assets/hi-res-icon.png" />
  <SupportUrl DefaultValue="[Insert the URL of a page that provides support information for the app]" />
  <!--BeginTaskpaneMode integration. Office 2013 and any client that doesn't understand commands will use this section.
    This section will also be used if there are no VersionOverrides -->
  <Hosts>
    <Host Name="Document"/>
  </Hosts>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://commandsimple.azurewebsites.net/Taskpane.html" />
  </DefaultSettings>
  <!--EndTaskpaneMode integration -->

  <Permissions>ReadWriteDocument</Permissions>

  <!--BeginAddinCommandsMode integration-->
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    <Hosts>
      <!--Each host can have a different set of commands. Cool huh!? -->
      <!-- Workbook=Excel Document=Word Presentation=PowerPoint -->
      <!-- Make sure the hosts you override match the hosts declared in the top section of the manifest -->
      <Host xsi:type="Document">
        <!-- Form factor. Currently only DesktopFormFactor is supported. We will add TabletFormFactor and PhoneFormFactor in the future-->
        <DesktopFormFactor>
          <!--Function file is an html page that includes the javascript where functions for ExecuteAction will be called.
            Think of the FunctionFile as the "code behind" ExecuteFunction-->
          <FunctionFile resid="Contoso.FunctionFile.Url" />

          <!--PrimaryCommandSurface==Main Office app ribbon-->
          <ExtensionPoint xsi:type="PrimaryCommandSurface">
            <!--Use OfficeTab to extend an existing Tab. Use CustomTab to create a new tab -->
            <!-- Documentation includes all the IDs currently tested to work -->
            <CustomTab id="Contoso.Tab1">
              <!--Group ID-->
              <Group id="Contoso.Tab1.Group1">
                <!--Label for your group. resid must point to a ShortString resource -->
                <Label resid="Contoso.Tab1.GroupLabel" />
                <Icon>
                  <!-- Sample Todo: Each size needs its own icon resource or it will look distorted when resized -->
                  <!--Icons. Required sizes: 16, 32, 80; optional: 20, 24, 40, 48, 64. You should provide as many sizes as possible for a great user experience. -->
                  <!--Use PNG icons and remember that all URLs on the resources section must use HTTPS -->
                  <bt:Image size="16" resid="Contoso.TaskpaneButton.Icon16" />
                  <bt:Image size="32" resid="Contoso.TaskpaneButton.Icon32" />
                  <bt:Image size="80" resid="Contoso.TaskpaneButton.Icon80" />
                </Icon>

                <!--Control. It can be of type "Button" or "Menu" -->
                <Control xsi:type="Button" id="Contoso.FunctionButton">
                  <!--Label for your button. resid must point to a ShortString resource -->
                  <Label resid="Contoso.FunctionButton.Label" />
                  <Supertip>
                    <!--ToolTip title. resid must point to a ShortString resource -->
                    <Title resid="Contoso.FunctionButton.Label" />
                    <!--ToolTip description. resid must point to a LongString resource -->
                    <Description resid="Contoso.FunctionButton.Tooltip" />
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Contoso.FunctionButton.Icon16" />
                    <bt:Image size="32" resid="Contoso.FunctionButton.Icon32" />
                    <bt:Image size="80" resid="Contoso.FunctionButton.Icon80" />
                  </Icon>
                  <!--This is what happens when the command is triggered (E.g. click on the Ribbon). Supported actions are ExecuteFunction or ShowTaskpane-->
                  <!--Look at the FunctionFile.html page for reference on how to implement the function -->
                  <Action xsi:type="ExecuteFunction">
                    <!--Name of the function to call. This function needs to exist in the global DOM namespace of the function file-->
                    <FunctionName>writeText</FunctionName>
                  </Action>
                </Control>

                <Control xsi:type="Button" id="Contoso.TaskpaneButton">
                  <Label resid="Contoso.TaskpaneButton.Label" />
                  <Supertip>
                    <Title resid="Contoso.TaskpaneButton.Label" />
                    <Description resid="Contoso.TaskpaneButton.Tooltip" />
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Contoso.TaskpaneButton.Icon16" />
                    <bt:Image size="32" resid="Contoso.TaskpaneButton.Icon32" />
                    <bt:Image size="80" resid="Contoso.TaskpaneButton.Icon80" />
                  </Icon>
                  <Action xsi:type="ShowTaskpane">
                    <TaskpaneId>Button2Id1</TaskpaneId>
                    <!--Provide a url resource id for the location that will be displayed on the task pane -->
                    <SourceLocation resid="Contoso.Taskpane1.Url" />
                  </Action>
                </Control>
                <!-- Menu example -->
                <Control xsi:type="Menu" id="Contoso.Menu">
                  <Label resid="Contoso.Dropdown.Label" />
                  <Supertip>
                    <Title resid="Contoso.Dropdown.Label" />
                    <Description resid="Contoso.Dropdown.Tooltip" />
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Contoso.TaskpaneButton.Icon16" />
                    <bt:Image size="32" resid="Contoso.TaskpaneButton.Icon32" />
                    <bt:Image size="80" resid="Contoso.TaskpaneButton.Icon80" />
                  </Icon>
                  <Items>
                    <Item id="Contoso.Menu.Item1">
                      <Label resid="Contoso.Item1.Label"/>
                      <Supertip>
                        <Title resid="Contoso.Item1.Label" />
                        <Description resid="Contoso.Item1.Tooltip" />
                      </Supertip>
                      <Icon>
                        <bt:Image size="16" resid="Contoso.TaskpaneButton.Icon16" />
                        <bt:Image size="32" resid="Contoso.TaskpaneButton.Icon32" />
                        <bt:Image size="80" resid="Contoso.TaskpaneButton.Icon80" />
                      </Icon>
                      <Action xsi:type="ShowTaskpane">
                        <TaskpaneId>MyTaskPaneID1</TaskpaneId>
                        <SourceLocation resid="Contoso.Taskpane1.Url" />
                      </Action>
                    </Item>

                    <Item id="Contoso.Menu.Item2">
                      <Label resid="Contoso.Item2.Label"/>
                      <Supertip>
                        <Title resid="Contoso.Item2.Label" />
                        <Description resid="Contoso.Item2.Tooltip" />
                      </Supertip>
                      <Icon>
                        <bt:Image size="16" resid="Contoso.TaskpaneButton.Icon16" />
                        <bt:Image size="32" resid="Contoso.TaskpaneButton.Icon32" />
                        <bt:Image size="80" resid="Contoso.TaskpaneButton.Icon80" />
                      </Icon>
                      <Action xsi:type="ShowTaskpane">
                        <TaskpaneId>MyTaskPaneID2</TaskpaneId>
                        <SourceLocation resid="Contoso.Taskpane2.Url" />
                      </Action>
                    </Item>

                  </Items>
                </Control>

              </Group>

              <!-- Label of your tab -->
              <!-- If validating with XSD it needs to be at the end -->
              <Label resid="Contoso.Tab1.TabLabel" />
            </CustomTab>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Contoso.TaskpaneButton.Icon16" DefaultValue="https://myCDN/Images/Button16x16.png" />
        <bt:Image id="Contoso.TaskpaneButton.Icon32" DefaultValue="https://myCDN/Images/Button32x32.png" />
        <bt:Image id="Contoso.TaskpaneButton.Icon80" DefaultValue="https://myCDN/Images/Button80x80.png" />
        <bt:Image id="Contoso.FunctionButton.Icon" DefaultValue="https://myCDN/Images/ButtonFunction.png" />
      </bt:Images>
      <bt:Urls>
        <bt:Url id="Contoso.FunctionFile.Url" DefaultValue="https://commandsimple.azurewebsites.net/FunctionFile.html" />
        <bt:Url id="Contoso.Taskpane1.Url" DefaultValue="https://commandsimple.azurewebsites.net/Taskpane.html" />
        <bt:Url id="Contoso.Taskpane2.Url" DefaultValue="https://commandsimple.azurewebsites.net/Taskpane2.html" />
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="Contoso.FunctionButton.Label" DefaultValue="Execute Function" />
        <bt:String id="Contoso.TaskpaneButton.Label" DefaultValue="Show Taskpane" />
        <bt:String id="Contoso.Dropdown.Label" DefaultValue="Dropdown" />
        <bt:String id="Contoso.Item1.Label" DefaultValue="Show Taskpane 1" />
        <bt:String id="Contoso.Item2.Label" DefaultValue="Show Taskpane 2" />
        <bt:String id="Contoso.Tab1.GroupLabel" DefaultValue="Test Group" />
         <bt:String id="Contoso.Tab1.TabLabel" DefaultValue="Test Tab" />
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="Contoso.FunctionButton.Tooltip" DefaultValue="Click to Execute Function" />
        <bt:String id="Contoso.TaskpaneButton.Tooltip" DefaultValue="Click to Show a Taskpane" />
        <bt:String id="Contoso.Dropdown.Tooltip" DefaultValue="Click to Show Options on this Menu" />
        <bt:String id="Contoso.Item1.Tooltip" DefaultValue="Click to Show Taskpane1" />
        <bt:String id="Contoso.Item2.Tooltip" DefaultValue="Click to Show Taskpane2" />
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</OfficeApp>

Проверка манифеста надстройки Office

Сведения о проверке манифеста с помощью определения схемы XML (XSD) см. в статье Проверка манифеста надстройки Office.

См. также