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/taskpaneappversionoverrideshttp://schemas.microsoft.com/office/contentappversionoverrideshttp://schemas.microsoft.com/office/mailappversionoverrides
Сам элемент VersionOverrides также должен иметь атрибут xmlns, определяющий схему. Возможные значения: три, приведенные выше, а также следующие:
http://schemas.microsoft.com/office/mailappversionoverrides/1.1
Элемент VersionOverrides также должен иметь атрибут xsi:type, который определяет версию схемы. Возможные значения:
VersionOverridesV1_0VersionOverridesV1_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.
См. также
- Определение правильного порядка элементов манифеста
- Создание команд надстройки в манифесте
- Указание приложений Office и обязательных элементов API
- Локализация надстроек для Office
- Справочная схема по манифестам надстроек для Office
- Обновление API и версии манифеста
- Определение аналогичной надстройки COM
- Запрос разрешений на использование API в надстройках
- Проверка манифеста надстройки Office