在加载项 Web 的网页中添加 Web 部件Include a web part on a webpage in the add-in web

可以在 SharePoint 加载项的加载项 Web 页面中添加现成可用的 Web 部件,但请务必注意,如果你需要更新加载项,执行此操作不能导致任何问题。You can include an out-of-the-box web part on a page in the add-in web of a SharePoint Add-in, but it is important that you do this in a way that won't cause problems if you ever need to update the add-in.

有关说明本主题指南的代码示例,请参阅 OfficeDev/Core.WebPartOnAppWebPageFor a code sample that illustrates the guidance of this topic, see OfficeDev/Core.WebPartOnAppWebPage.

向页面添加 Web 部件Add a web part to a page

  1. 在 Visual Studio 中创建 SharePoint 托管的 SharePoint 加载项项目。Create a SharePoint-hosted SharePoint Add-in project in Visual Studio. 有关详细信息,请参阅开始创建 SharePoint 托管的 SharePoint 加载项For details, see Get started creating SharePoint-hosted SharePoint Add-ins.

  2. 打开要在其中添加 Web 部件的 .aspx 文件。Open the .aspx file to which you want to add a web part. 本主题使用 Default.aspx 作为示例。This topic uses Default.aspx as an example.

  3. 在你想让 Web 部件包含标记的 <asp:Content> 元素中添加 WebPartZoneAdd a WebPartZone to the <asp:Content> element where you want the web part with markup. 通常情况下,应将其添加到 <asp:Content> 中,其中,ContentPlaceHolderIdPlaceHolderMainTypically, you want to add it to the <asp:Content> whose ContentPlaceHolderId is PlaceHolderMain. 示例如下。The following is an example.

      <asp:Content ContentPlaceHolderId="PlaceHolderMain" runat="server">
        <WebPartPages:WebPartZone runat="server" FrameType="TitleBarOnly" 
          ID="HomePage1" Title="loc:full" />
      </asp:Content>
    

    警告

    可以添加一个 Web 部件元素(例如 WebPartPages:XsltListViewWebPart)作为 WebPartZone 的子元素。It is possible to add a web part element, such as WebPartPages:XsltListViewWebPart as a child of the WebPartZone. 但这通常是 SharePoint 加载项中的不建议做法。But this is generally a bad practice in a SharePoint Add-in. 如果需要更新加载项,.aspx 文件中插入的 Web 部件元素可能会导致更新在某些场景中失败,并显示“具有此 ID 的 Web 部件已经添加到此页面中”消息。If the add-in ever needs to be updated, a web part element inserted in the .aspx file can cause the update to fail in some scenarios with the message "A web part with this ID has already been added to this page." 建议将 Web 部件添加到页面的元素清单中,如本过程后面的部分所述。We recommend that you add web parts to the elements manifest for the page as described later in this procedure.

  4. 打开页面的元素清单文件。Open the element manifest file for the page. 通常名为 elements.xml,并位于与 aspx 文件相同的项目文件夹中。This is usually called elements.xml and is located in the same project folder as the .aspx file.

  5. 在页面的 File 元素中,添加一个子 AllUsersWebPart 元素,并将其 WebPartZoneID 设置为你在页面上创建的 Web 部件区域的值,如此示例中所示。In the File element for the page, add a child AllUsersWebPart element, and set its WebPartZoneID to the value of the web part zone that you created on the page, as this example shows.

      <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
        <Module Name="Pages">
          <File Path="Pages\Default.aspx" Url="Pages/Default.aspx" ReplaceContent="TRUE" >
            <AllUsersWebPart WebPartZoneID="HomePage1" WebPartOrder="1">
    
            </AllUsersWebPart>
          </File>
        </Module>
      </Elements>
    
  6. 添加 CDATA 元素作为 AllUsersWebPart 的子元素,然后添加 webParts 元素作为 CDATA 的子元素,如此示例中所示。Add a CDATA element as a child of the AllUsersWebPart, and then add a webParts element as a child of the CDATA, as shown in this example.

      <AllUsersWebPart WebPartZoneID="HomePage1" WebPartOrder="1">
        <![CDATA[
          <webParts>
    
          </webParts>
        ]]>
      </AllUsersWebPart>
    
  7. 添加 webPart 标记作为 webParts 元素的子元素。Add webPart markup as a child of the webParts element. 以下是添加 XsltListViewWebPart 的示例。The following is an example that adds an XsltListViewWebPart. 它假定名为“测试列表”的自定义列表是同一加载项项目的一部分。It assumes that a custom list called "Test List" is part of the same add-in project. 有关如何将自定义列表添加到加载项 Web 的信息,请参阅创建包含自定义 SharePoint 列表和内容类型的提供程序托管的加载项For information about how to add a custom list to an add-in web, see Create a provider-hosted add-in that includes a custom SharePoint list and content type.

    备注

    请注意,Web 部件没有 ID 属性。Note that the web part does not have an ID property. 最佳做法是,仅在两种真正需要的情况下添加 Web 部件的显示 ID:Web 部件要添加到 SharePoint Wiki 网页中。It is a best practice to include an explicit ID for the web part only in the two cases where it is really required: The web part is being added to a SharePoint wiki page. Web 部件是已连接的两个或更多个 Web 部件之一。The web part is one of two or more web parts that are connected.

      <webParts>
      <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
        <metaData>
          <type name="Microsoft.SharePoint.WebPartPages.XsltListViewWebPart, 
                      Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, 
                      PublicKeyToken=71e9bce111e9429c" />
        </metaData>
        <data>
          <properties>
            <property name="ListUrl">Lists/{TestList}</property>
            <property name="IsIncluded">True</property>
            <property name="NoDefaultStyle">True</property>
            <property name="Title">{Test List}</property>
            <property name="PageType">PAGE_NORMALVIEW</property>
            <property name="Default">False</property>
            <property name="ViewContentTypeId">0x</property>
          </properties>
        </data>
      </webPart>
    </webParts>
    
  8. 按 F5 调试加载项。Select F5 to debug the add-in. 应该会在页面上看到 Web 部件。You should see the web part on the page.

另请参阅See also