XML-манифест надстроек OfficeOffice Add-ins XML manifest

XML-файл манифеста надстройки Office описывает способ ее активации, когда пользователь устанавливает и использует эту надстройку для работы с документами и приложениями Office.The XML manifest file of an Office Add-in describes how your add-in should be activated when an end user installs and uses it with Office documents and applications.

С помощью такого XML-файла манифеста надстройка Office может выполнять следующие действия:An XML manifest file based on this schema enables an Office Add-in to do the following:

  • предоставлять идентификатор, версию, описание, отображаемое имя и языковой стандарт по умолчанию.Describe itself by providing an ID, version, description, display name, and default locale.

  • указывать изображения, используемые для фирменного оформления надстройки, и значки, используемые для [команд надстройки][] в ленте Office;Specify the images used for branding the add-in and iconography used for add-in commands in the Office Ribbon.

  • указывать, как надстройка интегрируется с Office, включая создаваемые ею элементы пользовательского интерфейса, например кнопки на ленте;Specify how the add-in integrates with Office, including any custom UI, such as ribbon buttons the add-in creates.

  • определять запрошенные размеры по умолчанию для контентных надстроек, а также запрошенную высоту для надстроек Outlook;Specify the requested default dimensions for content add-ins, and requested height for Outlook add-ins.

  • объявлять разрешения, в которых нуждается надстройка Office, например чтение или запись документа;Declare permissions that the Office Add-in requires, such as reading or writing to the document.

  • в случае надстроек Outlook необходимо определить одно или несколько правил, указывающих контекст, в котором эти надстройки будут активироваться и взаимодействовать с сообщением, сведениями о встрече или приглашением на собрание.For Outlook add-ins, define the rule or rules that specify the context in which they will be activated and interact with a message, appointment, or meeting request item.

Примечание

Если вы планируете опубликовать надстройку в AppSource и сделать ее доступной в интерфейсе Office, убедитесь, что она соответствует политикам проверки AppSource. Например, чтобы пройти проверку, надстройка должна работать на всех платформах, поддерживающих определенные вами методы. Дополнительные сведения см. в разделе 4.12 и на странице со сведениями о доступности и ведущих приложениях для надстроек Office.If you plan to publish your add-in to AppSource and make it available within the Office experience, make sure that you conform to the AppSource validation policies. For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 4.12 and the Office Add-in host and availability page).

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

В приведенной ниже таблице указаны обязательные элементы для трех типов надстроек Office.The following table specifies the elements that are required for the three types of Office Add-ins.

Примечание

Кроме того, есть обязательный порядок размещения элементов в родительском элементе.There is also a mandatory order in which elements must appear within their parent element. Дополнительные сведения см. в статье Как определить правильный порядок элементов манифеста.For more information see How to find the proper order of manifest elements.

Обязательные элементы по типам надстроек OfficeRequired elements by Office Add-in type

| ЭлементElement | КонтентнаяContent | Для области задачTask pane | OutlookOutlook | | :------------------------------------------------------------------------------------------- | :-----: | :-------: | :-----: | | OfficeAppOfficeApp | XX | XX | XX | | IdId | XX | XX | XX | | VersionVersion | XX | XX | XX | | ProviderNameProviderName | XX | XX | XX | | DefaultLocaleDefaultLocale | XX | XX | XX | | DisplayNameDisplayName | XX | XX | XX | | DescriptionDescription | XX | XX | XX | | IconUrlIconUrl | XX | XX | XX | | DefaultSettings (ContentApp)DefaultSettings (ContentApp)
DefaultSettings (TaskPaneApp)DefaultSettings (TaskPaneApp) | XX | XX | | | SourceLocation (ContentApp)SourceLocation (ContentApp)
SourceLocation (TaskPaneApp)SourceLocation (TaskPaneApp) | XX | XX | | | DesktopSettingsDesktopSettings | | | XX | | SourceLocation (MailApp)SourceLocation (MailApp) | | | XX | | Permissions (ContentApp)Permissions (ContentApp)
Permissions (TaskPaneApp)Permissions (TaskPaneApp)
Permissions (MailApp)Permissions (MailApp) | XX | XX | XX | | Rule (RuleCollection)Rule (RuleCollection)
Rule (MailApp)Rule (MailApp) | | | XX | | [Requirements (MailApp)*][][Requirements (MailApp)*][] | | | XX | | [Set*][][Set*][]
[Sets (MailAppRequirements)*][][Sets (MailAppRequirements)*][] | | | XX | | [Form*][][Form*][]
[FormSettings*][][FormSettings*][] | | | XX | | [Sets (Requirements)*][][Sets (Requirements)*][] | XX | XX | | | [Hosts*][][Hosts*][] | XX | XX | |

*Элемент добавлен в схеме манифеста для надстроек Office версии 1.1.*Added in the Office Add-in Manifest Schema version 1.1.

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

Все URI изображений, в частности используемые для [команд надстройки][], должны поддерживать кэширование.All image URIs, such as those used for add-in commands, must support caching. Сервер с изображением не должен возвращать заголовок Cache-Control, содержащий no-cache, no-store или подобные параметры в ответе HTTP.The server hosting the image should not return a Cache-Control header specifying no-cache, no-store, or similar options in the HTTP response.

Все URL-адреса, например адреса исходных файлов, указанные в элементе SourceLocation, должны быть защищены с помощью SSL (HTTPS).All URLs, such as the source file locations specified in the SourceLocation element, should be SSL-secured (HTTPS). Использовать конечную точку HTTPS для надстройки не обязательно, но настоятельно рекомендуется. Надстройки без SSL-защиты (HTTPS) выдают предупреждения о небезопасном контенте и ошибки во время использования. Для запуска в Office Online и публикации в AppSource надстройка должна быть защищена с помощью SSL. Если надстройка получает данные из внешнего источника, она должна использовать SSL-соединение для защиты данных при передаче. Самозаверяющие сертификаты можно использовать для разработки и тестирования, если они добавлены в список доверенных сертификатов на локальном компьютере.While not strictly required in all add-in scenarios, using an HTTPS endpoint for your add-in is strongly recommended. Add-ins that are not SSL-secured (HTTPS) generate unsecure content warnings and errors during use. If you plan to run your add-in in Office Online or publish your add-in to AppSource, it must be SSL-secured. If your add-in accesses external data and services, it should be SSL-secured to protect data in transit. Self-signed certificates can be used for development and testing, so long as the certificate is trusted on the local machine.

Рекомендации по отправке решений в AppSourceBest practices for submitting to AppSource

Убедитесь, что идентификатор надстройки представляет собой допустимый и уникальный GUID. В Интернете доступно множество генераторов, с помощью которых можно создать уникальный GUID.Make sure that the add-in ID is a valid and unique GUID. Various GUID generator tools are available on the web that you can use to create a unique GUID.

Надстройки, отправляемые в AppSource, также должны включать элемент SupportUrl.Add-ins submitted to AppSource must also include the SupportUrl element. Дополнительные сведения см. в статье Политики проверки для приложений и надстроек, отправляемых в AppSource.For more information, see Validation policies for apps and add-ins submitted to AppSource.

Чтобы указать домены, отличные от указанного в элементе SourceLocation для сценариев проверки подлинности, используйте только элемент AppDomains.Only use the AppDomains element to specify domains other than the one specified in the SourceLocation element for authentication scenarios.

Укажите домены, которые необходимо открыть в окне надстройкиSpecify domains you want to open in the add-in window

В Office в Интернете область задач может открывать любой URL-адрес.When running in Office Online, your task pane can be navigated to any URL. Однако, на платформах для настольных компьютеров в области надстроек ведущего приложения Office открываются только URL-адреса в домене, где размещена начальная страница (указанная в элементе SourceLocation файла манифеста).However, in desktop platforms, if your add-in tries to go to a URL in a domain other than the domain that hosts the start page (as specified in the SourceLocation element of the manifest file), that URL opens in a new browser window outside the add-in pane of the Office host application.

Чтобы переопределить это поведение, укажите все домены, которые должны открываться в окне надстройки, в списке доменов в элементе AppDomains файла манифеста.To override this (desktop Office) behavior, specify each domain you want to open in the add-in window in the list of domains specified in the AppDomains element of the manifest file. URL-адреса в доменах из списка будут открываться в области задач как в классическом Office, так и в Office в Интернете.If the add-in tries to go to a URL in a domain that is in the list, then it opens in the task pane in both desktop Office and Office Online. URL-адреса в доменах не из списка будут открываться в новом окне браузера (не в области надстроек) в классическом Office.If it tries to go to a URL that isn't in the list, then, in desktop Office, that URL opens in a new browser window (outside the add-in pane).

Примечание

Из этого правила есть два исключения:There are implications to this behavior:

  • Это относится только к корневой области надстройки.This behavior applies only to the root pane of the add-in. Если в страницу надстройки внедрен iframe, его можно перенаправить на любой URL-адрес, независимо от того, указан ли он в элементе AppDomains, даже в классической версии Office.If there is an iframe embedded in the add-in page, the iframe can be directed to any URL regardless of whether it is listed in AppDomains, even in desktop Office.
  • Если диалоговое окно открыто с помощью API displayDialogAsync, URL-адрес, передаваемый методу, должен находиться в том же домене, что и надстройка. Затем диалоговое окно можно перенаправить на любой URL-адрес, независимо от того, указан ли он в элементе AppDomains, даже в классической версии Office.When a dialog is opened with the displayDialogAsync API, the URL that is passed to the method must be in the same domain as the add-in, but the dialog can then be directed to any URL regardless of whether it is listed in AppDomains, even in desktop Office.

В приведенном ниже примере XML-манифеста главная страница надстройки размещена в домене https://www.contoso.com, указанном в элементе SourceLocation.The following XML manifest example hosts its main add-in page in the https://www.contoso.com domain as specified in the SourceLocation element. В нем также указан домен https://www.northwindtraders.com с помощью элемента AppDomain из списка AppDomains.It also specifies the https://www.northwindtraders.com domain in an AppDomain element within the AppDomains element list. Страница в домене www.northwindtraders.com будет открываться в области надстроек даже в классической версии Office.If the add-in goes to a page in the www.northwindtraders.com domain, that page opens in the add-in pane, even in Office desktop.

<?xml version="1.0" encoding="UTF-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:type="TaskPaneApp">
  <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"/>
  <AppDomains>
    <AppDomain>https://www.northwindtraders.com</AppDomain>
  </AppDomains>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://www.contoso.com/search_app/Default.aspx" />
  </DefaultSettings>
  <Permissions>ReadWriteDocument</Permissions>
</OfficeApp>

Указание доменов, из которых выполняются вызовы API Office.jsSpecify domains from which Office.js API calls are made

Ваша надстройка может выполнять вызовы API Office.js из домена, указанного в элементе SourceLocation файла манифеста.Your add-in can make Office.js API calls from the domain referenced in the SourceLocation element of the manifest file. Если в вашей надстройке есть другие блоки IFrame, которым требуется доступ к API Office.js, добавьте домен этого исходного URL-адреса в список, указанный в элементе AppDomains файла манифеста.If you have other IFrames within your add-in that need to access Office.js APIs, add the domain of that source URL to the list specified in the AppDomains element of the manifest file. Если блок IFrame с источником, не содержащимся в списке AppDomains, попытается выполнить вызов API Office.js, надстройка получит ошибку об отказе в разрешении.If an IFrame with a source not contained in the AppDomains list attempts to make an Office.js API call, then the add-in will receive a permission denied error.

XML-файлы манифеста версии 1.1: примеры и схемыManifest v1.1 XML file examples and schemas

Ниже показаны примеры XML-файлов манифеста версии 1.1 для надстроек области задач, контентных надстроек и надстроек Outlook.The following sections show examples of manifest v1.1 XML files for content, task pane, and Outlook add-ins.

Схема манифеста приложения области задачTask pane app manifest schema

<?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 clone 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 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.Icon" />
                  <bt:Image size="32" resid="Contoso.TaskpaneButton.Icon" />
                  <bt:Image size="80" resid="Contoso.TaskpaneButton.Icon" />
                </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.Icon" />
                    <bt:Image size="32" resid="Contoso.FunctionButton.Icon" />
                    <bt:Image size="80" resid="Contoso.FunctionButton.Icon" />
                  </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.Icon" />
                    <bt:Image size="32" resid="Contoso.TaskpaneButton.Icon" />
                    <bt:Image size="80" resid="Contoso.TaskpaneButton.Icon" />
                  </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.Icon" />
                    <bt:Image size="32" resid="Contoso.TaskpaneButton.Icon" />
                    <bt:Image size="80" resid="Contoso.TaskpaneButton.Icon" />
                  </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.Icon" />
                        <bt:Image size="32" resid="Contoso.TaskpaneButton.Icon" />
                        <bt:Image size="80" resid="Contoso.TaskpaneButton.Icon" />
                      </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.Icon" />
                        <bt:Image size="32" resid="Contoso.TaskpaneButton.Icon" />
                        <bt:Image size="80" resid="Contoso.TaskpaneButton.Icon" />
                      </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, we might change this before release -->
              <Label resid="Contoso.Tab1.TabLabel" />
            </CustomTab>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Contoso.TaskpaneButton.Icon" DefaultValue="https://i.imgur.com/FkSShX9.png" />
        <bt:Image id="Contoso.FunctionButton.Icon" DefaultValue="https://i.imgur.com/qDujiX0.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>

Проверка манифеста и устранение связанных с ним неполадокValidate and troubleshoot issues with your manifest

Сведения об устранении проблем, связанных с манифестом надстройки, см. в статье Проверка манифеста и устранение связанных с ним неполадок. Там указано, как проверить манифест согласно XSD, а также как отладить манифест с помощью ведения журнала в среде выполнения.For troubleshooting issues with your manifest, see Validate and troubleshoot issues with your manifest. There, you will find information on how to validate the manifest against the XML Schema Definition (XSD), and also how to use runtime logging to debug the manifest.

См. такжеSee also