浏览应用部件清单 (manifest) 结构和 SharePoint 加载项包Explore the app manifest structure and the package of a SharePoint Add-in

SharePoint 加载项包结构Add-in for SharePoint package structure

SharePoint 加载项包是扩展名为“.app”且符合开放打包约定 (OPC) 的文件。A SharePoint Add-in package is a file that has an ".app" extension and that complies with the Open Packaging Conventions (OPC). 此包包含以下各项:The package contains the following items:

  • 加载项清单:这是名为 appmanifest.xml 的必需的文件。Add-in manifest: This is a required file that is named appmanifest.xml. 它会告诉 SharePoint 有关加载项的一些重要属性,例如其标题和运行所需的权限。It tells SharePoint about some important properties of the add-in, such as its title and the permissions it needs to run. 有关此文件内容的详细信息,请参阅 SharePoint 加载项清单文件For more information about the contents of this file, see Add-in for SharePoint manifest file.

  • SharePoint 解决方案包:加载项可能视情况包含一个 SharePoint 解决方案包(.wsp 文件),其中包含加载项 Web 的组件。SharePoint solution packages: Optionally, the add-in may include a SharePoint solution package (.wsp file) that contains the components of the add-in web. 这些组件可能包含页、列表实例、视图、文档、Web 范围的功能和其他 SharePoint 组件。These components may include pages, list instances, views, documents, web-scoped features, and other SharePoint components. (有关 SharePoint 加载项中可包含的 SharePoint 组件的详细信息,请参阅可包含在 SharePoint 加载项中的 SharePoint 组件的类型。).wsp 文件还可能包含 Office 加载项。.wsp 文件中的组件会部署到加载项 Web 中。(For more information about what SharePoint components can be included in a SharePoint Add-in, see Types of SharePoint components that can be in a SharePoint Add-in.) The .wsp file may also contain Office Add-ins. The components in the .wsp file are deployed to the add-in web. 有关包含 SharePoint 解决方案包的加载项包的示例,请参阅创建包括自定义 SharePoint 列表和内容类型的提供程序托管的加载项For an example of an add-in package that includes a SharePoint solution package, see Create a provider-hosted add-in that includes a custom SharePoint list and content type.

  • 包含自定义操作或加载项部件的主机 Web 功能:除了部署到加载项 Web 的 SharePoint 组件之外,SharePoint 加载项还可将一个或多个自定义操作(快捷菜单项或功能区扩展)部署到主机 Web。Host web features with Custom Actions or add-in parts: In addition to the SharePoint components that are deployed to the add-in web, a SharePoint Add-in can also deploy one or more custom actions (shortcut menu items or ribbon extensions) to the host web. 这通过以下方式实现:将位于包的 .wsp 文件之外和部署将转到主机 Web 的组件的功能包含在加载项包中。This is accomplished by including in the add-in package a feature that is not inside the package's .wsp file and that deploys the components that go to the host web. 此“稀疏”功能称为主机 Web 功能。This "loose" feature is called a host web feature.

    将通过同一方式将加载项部件部署到主机 Web 中。主机 Web 功能包含标准 SharePoint feature.xml 文件和一个或多个关联的 elements.xml 文件。例如,自定义操作的 elements.xml 文件包含此自定义操作的 CustomAction 标记。它还可包含加载项部件的标记。只有这两种组件可位于主机 Web 功能中。这些主机 Web 功能未在加载项清单中详细记录。但是,它们是 OPC 感知中的"部件",并且加载项清单和其中每个文件之间存在显式 OPC 关系。有关包含主机 Web 功能的加载项包的示例,请参阅创建自定义操作以部署 SharePoint 加载项Add-in parts are deployed to the host web in the same way. The host web feature consists of a standard SharePoint feature.xml file and one or more associated elements.xml files. An elements.xml file for a custom action, for example, contains the CustomAction markup for the custom action. It can also include markup for add-in parts. Only these two kinds of components can be in the host web feature. These host web features are not itemized in the add-in manifest. However, they are "parts" in the OPC sense, and there is an explicit OPC relationship between the add-in manifest and each of these files. For an example of an add-in package that includes a host web feature, see Create custom actions to deploy with SharePoint Add-ins.

    备注

    租户管理员可选择将 SharePoint 加载项批安装到多个网站。Tenant administrators have the option to batch-install a SharePoint Add-in to multiple websites. 已通过此方式安装的加载项的范围可能为租户An add-in that has been installed in this way is said to have Tenant scope. 如果未批量安装此加载项,而是安装到各个单独的网站,则加载项可能为 Web 范围。If the add-in has not been batch-installed, and is instead installed to each website separately, it has Web scope. 如果主机 Web 功能包含功能区扩展或加载项部件,则不会在批量安装加载项时将其部署到主机 Web,以便仅为快捷菜单项部署租户范围的加载项。If the host web feature includes ribbon extensions or add-in parts, they are not deployed to the host webs if the add-in is batch-installed, so only shortcut menu items are deployed with Tenant-scoped add-ins.

    不得混淆加载项范围和功能范围。Add-in scope should not be confused with feature scope. 功能范围决定了功能元素的部署位置。Feature scope determines where the elements in a feature are deployed. 可能的位置包括Web 应用程序网站(即网站集)和 WebThe possibilities are Farm, WebApplication, Site (that is, site collection), and Web. 对于 SharePoint 加载项中的功能(主机 Web 功能和加载项包中 .wsp 内的功能),只能使用 Web 选项。Only the Web option is permitted for features in SharePoint Add-ins (both host web features and features inside a .wsp in an add-in package).

    加载项范围是指在其中安装加载项的范围。Add-in scope refers to the scope at which an add-in is installed. 可能的位置为 Web(其中已将加载项点对点安装到一个或多个网站)和租户(其中已将加载项批量安装到客户租赁的网站的所有或部分子集)。The possibilities are Web, in which case the add-in has been installed to one or more websites site-by-site, and Tenant, in which case the add-in has been batch installed to all or some subset of the websites in a customer's tenancy.

    有关租户Web 范围的详细信息,请参阅 SharePoint 加载项的租赁和部署范围For more information about Tenant and Web scope, see Tenancies and deployment scopes for SharePoint Add-ins.

  • 本地化资源文件 (.resx):这些文件适用于本地化包含加载项标题的加载项清单的各个方面和加载项包中的主机 Web 功能的各个方面。Localization resource files (.resx): These are for localizing aspects of the add-in manifest that include the add-in title and aspects of host web features in the add-in package. (位于其自己的包内的加载项包的各个部分,如 .wsp 文件、Azure 网站包和加载项清单,其中每个都有自己的本地化过程,这些过程将在相关项不是 SharePoint 加载项的一部分时完全应用。)有关包含 .resx 文件的主机 Web 功能的加载项包的示例,请参阅本地化 SharePoint 加载项(Individual parts of the add-in package that are inside their own package, such as .wsp files, Azure websites packages, and add-in manifests, each have their own localization processes that are applied exactly as they would be if the items in question were not part of a SharePoint Add-in.) For an example of an add-in package that includes .resx files for a host web feature, see Localize SharePoint Add-ins.

  • Office 加载项清单:可能视情况存在一个或多个 Office 加载项清单,其中每个包对应一个 Office 加载项。Office Add-ins manifests: Optionally, there may be one or more Office Add-ins manifests that each package an Office Add-in. 只有在加载项将被上传到 SharePoint 企业加载项目录(而不是公共市场)时,才会将此部分包含在加载项包中。This part can be included in the add-in package only if the add-in is going to be uploaded to a SharePoint corporate add-in catalog, not the public marketplace. 有关详细信息,请参阅发布 SharePoint 加载项For more information, see Publish SharePoint Add-ins.

SharePoint 加载项清单文件Add-in for SharePoint manifest file

每个 SharePoint 外接程序都包含一个 appmanifest.xml 文件。appmanifest.xml 告知 SharePoint 其必须知道的有关外接程序的内容并且定义外接程序最重要的属性。以下是在清单中指定的一些项:Every SharePoint Add-in includes an appmanifest.xml file. The appmanifest.xml tells SharePoint what it must know about the add-in and defines the add-in's most important properties. The following are some of the items that are specified in the manifest:

  • 外接程序的内部名称、产品 ID 和版本。The internal name, product ID, and version of the add-in.

  • 起始页的 URL,该页是在启动外接程序时打开的页。这可以是外接程序 Web 中的页、基于云的页或 ISV 的 Web 服务器上的页。The URL of the start page, which is the page that opens when the add-in is started. This can be a page in the add-in web, a cloud-based page, or a page on a web server of the ISV.

    备注

    在某些情况下,可能会限制可在 StartPage 元素中指定的文件类型。In certain circumstances, there may be restrictions on what type of file can be specified in the StartPage element. 有关详细信息,请参阅 StartPage 元素 (PropertiesDefinition complexType)(SharePoint 加载项清单)For details, see StartPage element (PropertiesDefinition complexType) (SharePoint Add-in Manifest). 将多个查询参数组合到 StartPage 值中时,必须使用编码的与号“&”而不是“&”或分号将其追加在一起。When you are combining more than one query parameter in the StartPage value, you must use the encoded ampersand & rather than & or a semi-colon to append them together.

  • 外接程序的其他属性。这些属性包括标题和外接程序支持的区域设置(这二者是必需的)、处理安装后、升级后和卸载前事件的服务的 URL 以及创建外接程序 Web 时要使用的 Web 模板。Other properties of the add-in. These include title and the locales supported by the add-in (both are required), the URLs of services that handle the post-install, post-upgrade, and pre-uninstall events, and the web template to use when the add-in web is created.

  • 外接程序对外接程序 Web 之外的 SharePoint 资源所需权限的请求。Requests for permissions the add-in needs to SharePoint resources outside the add-in web.

  • 标识,供外接程序主体的身份验证和授权之用。它是被授予权限的主体。Sharepoint 托管的外接程序无需此标识。An identification, for authentication and authorization purposes, of the add-in principal. It is this principal that is granted permissions. This is not required for a SharePoint-hosted add-in.

  • 必须可供加载项使用才能安装加载项的必备项(如果有)的列表。A list of the prerequisites, if any, that must be available to the add-in in order for the add-in to be installed. 例如,可能需要安装并激活某些功能,并且可能需要许可并安装某些服务。For example, certain features may need to be installed and activated, and certain services may need to be licensed and installed.

备注

外接程序清单文件是外接程序包中唯一必需的项,但之前列表中的项并不都是文件的必需部分。The add-in manifest file is the only required item in the add-in package, but not all of the items in the previous list are required parts of the file.

有关加载项清单标记的详细信息,请参阅 SharePoint 加载项清单的架构参考。本主题不是该节点中信息的替代信息,该节点包括有关必需元素和属性的信息。For detailed information about the add-in manifest markup, see Schema reference for manifests of SharePoint Add-ins. This topic is not a substitute for the information in that node, including information about required elements and attributes. 另请注意,SharePoint 加载项清单具有不同于 Office 加载项清单的架构。Also, note that SharePoint add-in manifests have a different schema from Office Add-in manifests. 可以在 Office 加载项清单的架构参考 (v1.1) 中查找有关后者的信息。You can find information about the latter at Schema reference for Office Add-ins manifests (v1.1).

以下是 appmanifest.xml 文件的示例。The following is an example of an appmanifest.xml file. 请注意,在本示例中,加载项的起始页是位于远程服务器上的 ASP.NET 页,而不是 SharePoint 网站上的页。Note that in this example, the start page for the add-in is an ASP.NET page that is on a remote server, not a page on the SharePoint site. 此页的 URL 包含一个查询字符串,它将主机 Web 的 URL 传递到远程 Web 应用程序。The URL for the page includes a query string that passes to the remote web application the URL of the host web. 该字符串的 {HostUrl} 部分是启动加载项时解析的标记。The {HostUrl} part of the string is a token that is resolved when the add-in is launched. 加载项将请求对主机 Web 中所有列表的写入权限。The add-in is requesting Write permission to all the lists in the host web. 必须为其授予此权限的加载项主体是远程 Web 应用程序。The add-in principal that must be granted this permission is the remote web application.

必须在加载项清单中使用 SupportedLocalesSupportedLanguages 元素。You must use either the SupportedLocales or the SupportedLanguages element in your add-in manifest. 将弃用 SupportedLanguages 并使用 SupportedLocalesSupportedLanguages is being deprecated in favor of SupportedLocales. 在发布后,SupportedLanguages 元素可能仍继续可用,但请勿使用它。The SupportedLanguages element will continue to work even after release, but you should refrain from using it. 有关这些元素的详细信息,请参阅 SupportedLocales 元素 (PropertiesDefinition complexType)(SharePoint 加载项清单)SupportedLanguages 元素 (PropertiesDefinition complexType)(SharePoint 加载项清单)For more information about these elements, see SupportedLocales element (PropertiesDefinition complexType) (SharePoint Add-in Manifest) and SupportedLanguages element (PropertiesDefinition complexType) (SharePoint Add-in Manifest).

备注

AppPermissionRequest 元素的 Scope 属性的值的结构类似 URI,但它们实际上是文本字符串。The values of the Scope attribute of the AppPermissionRequest element are structured like URIs, but they are actually literal strings. 以下示例中的示例 Scope 值中没有任何部分是占位符。No part of the example Scope value in the following example is a placeholder. 有关权限的详细信息,请参阅 SharePoint 中的加载项权限For more information about permissions, see Add-in permissions in SharePoint.

<?xml version="1.0" encoding="utf-8" ?>
<App xmlns="http://schemas.microsoft.com/sharepoint/2012/app/manifest"
     ProductID="{4a07f3bd-803d-45f2-a710-b9e944c3396e}"
     Version="1.0.0.0"
     SharePointMinVersion="15.0.0.0"
     Name="MySampleApp"
>
  <Properties>
    <Title>My Sample App</Title>
    <StartPage>http://MyRemoteWebApplicationServer/default.aspx/?SPHostUrl={HostUrl}</StartPage>
    <SupportedLocales>
      <SupportedLocale CultureName="en-US" />
    </SupportedLocales>        
  </Properties>

  <AppPermissionRequests>
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web/list" Right="Write"/>
  </AppPermissionRequests>

  <AppPrincipal>
    <RemoteWebApplication ClientId="1ee82b34-7c1b-471b-b27e-ff272accd564" />
  </AppPrincipal>
</App>


加载项清单中的 URL 标记URL tokens in the add-in manifest

SharePoint 提供了若干可在加载项的 StartPage 元素和其他位置以及加载项的组件中使用的标记,用于表示加载项运行前未知的信息。SharePoint provides several tokens that can be used in the StartPage element and other places in add-ins and components of add-ins to represent information that is not known until the add-in is run. SharePoint 基础结构将解析这些标记。The SharePoint infrastructure resolves these tokens. 部分标记用于 URL 的开头,其他标记可在 URL 中使用,如查询参数的值。Some are used at the beginning of the URL and others can be used within a URL such as the value of a query parameter. 这些标记和若干其他标记还可在各种 SharePoint 开发上下文中使用。These tokens and several others can also be used in a variety of SharePoint development contexts.

有关所有标记以及可使用它们的位置的详细信息,请参阅 SharePoint 加载项中的 URL 字符串和标记。有关 SharePoint 中的其他标记和 URL 的常规信息,请参阅 SharePoint 中的 URL 和标记For detailed information about all the tokens and where they can be used, see URL strings and tokens in SharePoint Add-ins. For general information about other tokens and URLs in SharePoint, see URLs and tokens in SharePoint.

备注

这些标记不会在 AppPermissionRequest 元素的 Scope 属性中使用。These tokens are not used in the Scope attribute of an AppPermissionRequest element.

另请参阅See also