Office 加载项 XML 清单Office Add-ins XML manifest

Office 外接程序的 XML 清单文件描述,当最终用户安装外接程序并将其与 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:

  • 通过提供 ID、版本、说明、显示名称和默认区域设置进行自我描述。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 app ribbon.

  • 指定外接程序如何与 Office 集成,包括任何自定义 UI,如外接程序创建的功能区按钮。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 体验中可用,请确保你遵守商业市场认证政策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 Commercial marketplace certification policies.例如,加载项必须适用于支持你定义的方法的所有平台,才能通过验证(有关详细信息,请参阅第 1120.3 部分以及 Office 加载项应用程序和可用性页)。 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 1120.3 and the Office Add-in application and availability page).

提示

如果要在多个环境中测试外接程序(例如,在开发、暂存、演示等)中,我们建议您为每个环境维护一个不同的 XML 清单文件。If you'll be testing your add-in across multiple environments (for example, in development, staging, demo, etc.), we recommend that you maintain a different XML manifest file for each environment. 在每个清单文件中,可以执行以下操作:In each manifest file, you can:

  • 指定与环境对应的 Url。Specify the URLs that correspond to the environment.
  • 在中自定义元数据值(如 DisplayName 和标签 Resources )以指明环境,以便最终用户能够识别旁加载外接程序的相应环境。Customize metadata values like DisplayName and labels within Resources to indicate the environment, so that end users will be able to identify a sideloaded add-in's corresponding environment.
  • namespace如果外接程序定义了自定义函数,则自定义用于指示环境的自定义函数。Customize the custom functions namespace to indicate the environment, if your add-in defines custom functions.

通过遵循本指南,您将简化测试过程,并避免在外接程序同时旁加载多个环境时出现的问题。By following this guidance, you'll streamline the testing process and avoid issues that would otherwise occur when an add-in is simultaneously sideloaded for multiple environments.

必需元素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.

Office 加载项类型的必需元素Required 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
SupportUrl**SupportUrl** 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.

** 仅通过 AppSource 分发的加载项才需要 SupportUrl。** SupportUrl is only required for add-ins that are distributed through AppSource.

托管要求Hosting requirements

所有图像 URI(如用于[外接程序命令][]的 URI)都必须支持缓存。All image URIs, such as those used for add-in commands, must support caching. 托管图像的服务器不得在 HTTP 响应中返回指定 no-cacheno-store 或类似选项的 Cache-Control 标头。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)在使用过程中生成不安全的内容警告和错误。如果您计划在 web 上的 Office 中运行外接程序或将外接程序发布到 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 on the web 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.

关于提交到 AppSource 的最佳做法Best practices for submitting to AppSource

确保外接程序 ID 有效且具有唯一 GUID。Web 上提供可用于创建唯一 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.

仅使用 AppDomain 元素指定域(除了在 SourceLocation 元素中指定的用于身份验证方案的域)。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 on the web, your task pane can be navigated to any URL. 但在桌面平台中,如果加载项尝试转到托管起始页(如清单文件的 SourceLocation 元素中所指定的)的域之外的域中的 URL,则该 URL 将在 Office 应用程序的加载项窗格外的新浏览器窗口中打开。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 application.

若要重写此(桌面版 Office)操作,请在清单文件的 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 网页版和桌面版中的任务窗口中打开。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 Office on the web and desktop. 如果它尝试转至列表之外的域中的 URL,则在桌面版 Office 中,该 URL 将在新的浏览器窗口中(外接程序窗格之外)打开。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 two exceptions to this behavior:

  • 它仅适用于外接程序的根窗格。It applies only to the root pane of the add-in. 如果外接程序页面中嵌入有 iframe,则可以将该 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.
  • 使用 displayDialogAsync API 打开对话框时,传递到方法的 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 清单示例在 SourceLocation 元素中指定的 https://www.contoso.com 域中托管其外接程序页面。The following XML manifest example hosts its main add-in page in the https://www.contoso.com domain as specified in the SourceLocation element. 它还指定 AppDomains 元素列表内 AppDomain 元素中的 https://www.northwindtraders.com 域。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="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>

指定从中执行 Office .js API 调用的域Specify domains from which Office.js API calls are made

你的加载项可以从清单文件的 SourceLocation 元素中引用的域执行 Office.js API 调用。Your add-in can make Office.js API calls from the domain referenced in the SourceLocation element of the manifest file. 如果加载项中有需要访问 Office.js API 的其他 IFrame,请将该源 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. 如果有一个未包含在 AppDomains 列表中且具有源的 IFrame 尝试执行 Office.js API 调用,则加载项将收到“权限被拒绝”错误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.

清单 v1.1 XML 文件示例和架构Manifest v1.1 XML file examples and schemas

下面各部分展示了内容加载项、任务窗格加载项和 Outlook 加载项的清单 v1.1 XML 文件示例。The following sections show examples of manifest v1.1 XML files for content, task pane, and Outlook add-ins.

加载项清单架构Add-in manifest schemas

<?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 加载项的清单Validate an Office Add-in's manifest

有关根据 XML 架构定义 (XSD) 验证清单的信息,请参阅验证 Office 加载项的清单For information about validating a manifest against the XML Schema Definition (XSD), see Validate an Office Add-in's manifest.

另请参阅See also