创建加载项部件以安装 SharePoint 加载项
使用加载项部件，可以直接在 SharePoint 网站页面中显示加载项用户体验。 外接程序部件在 主机 Web 页中显示您使用 IFrame（也称为框架）指定的网页（通常为交互式表单或数据的动态显示）。
有关外接程序部件的更多背景，请参阅下列文章：
下图是 SharePoint 页中显示的加载项部件内容。
SharePoint 页中显示的外接程序部件内容
加载项部件通过 ClientWebPart 类实现，与所有 Web 部件一样，当用户安装了包含该部件的 SharePoint 加载项后，它便可在 Web 部件库中使用。 用户可以使用所提供的属性进一步自定义加载项部件。 （有关加载项部件中可配置属性的示例，请参阅本文后面的托管基本加载项部件的 SharePoint 页一图。）
本文中的示例使用托管在远程服务器上而不是 SharePoint 上的网页作为内容页面。 请记住，还可以使用 SharePoint 页面托管外接程序部件内容，如本文后面的 其他常见方案外接程序部件 部分中所述。
使用本文中示例的先决条件
若要按照此示例中的步骤操作，您需要：
- Visual Studio
- Visual Studio Microsoft Office 开发人员工具
- SharePoint 开发环境。 如果在设置开发环境方面需要帮助，请参阅两种类型的 SharePoint 加载项：SharePoint 托管的加载项和提供程序托管的加载项。
创建外接程序部件以安装到主机 Web 上
创建外接程序部件并安装到主机 Web 上需要执行以下几个任务：
- 创建 SharePoint 外接程序和远程 Web 项目。
- 添加外接程序部件内容的一个表单。
- 将加载项部件添加到 SharePoint 加载项项目。
完成任务后，当加载项部件处于编辑模式时，加载项部件外观应类似于下图。 此处，我们可以看到 (1) SharePoint 页中显示的加载项内容，和 (2) 加载项部件自定义属性。
SharePoint 页托管基本外接程序部件
添加加载项部件内容的一个表单
按照开始创建提供程序托管的 SharePoint 加载项中的说明，创建一个提供程序托管的 SharePoint 加载项，但将该项目命名为 TestAppPart。
创建 Visual Studio 解决方案后，右键单击 Web 应用程序项目（而不是 SharePoint 加载项项目），并添加一个新的 Web 窗体，方法是选择“添加”>“新项目”>“Web”>“Web 表单”。 将窗体命名为 AppPartContent.aspx。
在 AppPartContent.aspx 文件中，将整个 HTML 元素及其子项替换为以下 HTML 代码。 保留 HTML 元素上的所有标记不变。 HTML 代码包含执行以下任务的 JavaScript：
- 从查询字符串中提取默认属性值
- 显示属性值
请注意，此代码需要查询字符串中的一些参数。 外接程序部件通过查询字符串提供其自定义属性，因此网页可以使用这些属性。 下一项任务解释如何声明自定义属性和如何使其能够用于外接程序网页。
<html> <body> <div id="content"> <!-- Placeholders for properties --> String property: <span id="strProp"></span><br /> Integer property: <span id="intProp"></span><br /> Boolean property: <span id="boolProp"></span><br /> Enumeration property: <span id="enumProp"></span><br /> </div> <!-- Main JavaScript function, controls the rendering logic based on the custom property values --> <script lang="javascript"> "use strict"; var params = document.URL.split("?")[1].split("&"); var strProp; var intProp; var boolProp; var enumProp; // Extracts the property values from the query string. for (var i = 0; i < params.length; i = i + 1) { var param = params[i].split("="); if (param[0] == "strProp") strProp = decodeURIComponent(param[1]); else if (param[0] == "intProp") intProp = parseInt(param[1]); else if (param[0] == "boolProp") boolProp = (param[1] == "true"); else if (param[0] == "enumProp") enumProp = decodeURIComponent(param[1]); } document.getElementById("strProp").innerText = strProp; document.getElementById("intProp").innerText = intProp; document.getElementById("boolProp").innerText = boolProp; document.getElementById("enumProp").innerText = enumProp; </script> </body> </html>保存并关闭该文件。
将加载项部件添加到 SharePoint 加载项项目
右键单击 SharePoint 加载项项目（而不是 Web 应用程序项目），然后选择“添加”>“新项目”>“Office/SharePoint”>“客户端 Web 部件（主机 Web）”。 （“客户端 Web 部件”是“加载项部件”的别名。）
将部件命名为基本加载项部件。
在“指定客户端 Web 部件页”对话框中，选择“选择或输入现有网页的 URL”。 在下拉列表中选择“TestAppWebPart/AppPartContent.aspx”页。 （在做出选择后，页面 URL 可能会显示在框中，并且“TestAppWebPart”会被替换为 ~remoteAppUrl，并添加 {StandardTokens} 用于查询参数。）
选择“完成”。
在“解决方案资源管理器”中右键单击“基本加载项部件”，然后选择“属性”。
在“属性”窗格中，依次选择“自定义属性”和标注（“...”）按钮。
使用“自定义属性”对话框将四个自定义属性添加到外接程序部件。 您必须为每个自定义属性设置五个特性。 特性名称和值如表 1 中所列。 使用以下过程创建属性。
选择“添加”。
在特性列表中，从表 1 中选择第一个特性：“DefaultValue”。
设置值，例如 String default value。
选择下一个特性"Name"并设置其值，例如， strProp。
继续设置“Type”、“WebCategory”和“WebDisplayName”特性。
再次选择“添加”并为表 1 中的所有四行重复此过程。 请勿关闭对话框。
表 1. 外接程序部件的自定义属性的特性
DefaultValue 名称 类型 WebCategory WebDisplayName 字符串默认值 strProp 字符串 基本外接程序部件类别 字符串类型的属性 0 intProp INT 基本外接程序部件类别 整数类型的属性 FALSE boolProp 布尔 基本外接程序部件类别 布尔类型的属性 1st enumProp 枚举 基本外接程序部件类别 枚举类型的属性 此时，该对话框应如下所示：
ClientWebPart 的自定义属性对话框
依次选择“enumProp”属性、“EnumItems”特性和标注（“...”）按钮。
使用“ClientWebPartEnumItem 集合编辑器”添加三个项目。 您必须为每个项目设置两个特性。 特性名称和值如表 1 中所列。 使用以下过程创建属性。
选择“添加”。
在特性列表中，从表 2 中选择第一个特性：“Value”。
设置特性的值，例如 1st。
选择下一个特性“WebDisplayName”并设置其值，例如，First option。
再次选择“添加”并为表 2 中的所有行重复此过程。
表 2. enumProp 属性的枚举项
值 WebDisplayName 1st 第一个选项 2nd 第二个选项 3rd 第三个选项 完成后，该对话框应如下所示：
ClientWebPartEnumItem 集合编辑器
选择“确定”关闭对话框，然后再次选择“确定”关闭“自定义属性”对话框。
Visual Studio 在加载项部件的 elements.xml 文件中生成以下 XML 代码（为清楚起见，添加了换行符）。 请注意，ClientWebPart 元素的“Title”特性设置为“基本加载项部件标题”，“Description”设置为“基本加载项部件说明”。 从第一特性中删除“标题”一词，并将第二个特性替换为“基本加载项部件”。
<?xml version="1.0" encoding="UTF-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<ClientWebPart
Name="Basic add-in part"
Title="Basic add-in part Title"
Description="Basic add-in part Description" >
<!-- The properties are passed through the query string
using the following notation: _propertyName_
in the Src property of the Content element.
-->
<Content
Src="~remoteAppUrl/AppPartContent.aspx?strProp=_strProp_&amp;intProp=_intProp_&amp;boolProp=_boolProp_&amp;enumProp=_enumProp_"
Type="html"/>
<Properties>
<Property
Name="strProp"
Type="string"
RequiresDesignerPermission="true"
DefaultValue="String default value"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type string.">
</Property>
<Property
Name="intProp"
Type="int"
RequiresDesignerPermission="true"
DefaultValue="0"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type integer.">
</Property>
<Property
Name="boolProp"
Type="boolean"
RequiresDesignerPermission="true"
DefaultValue="false"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type boolean.">
</Property>
<Property
Name="enumProp"
Type="enum"
RequiresDesignerPermission="true"
DefaultValue="1st"
WebCategory="Basic add-in part category"
WebDisplayName="A property of type enum.">
<EnumItems>
<EnumItem WebDisplayName="First option" Value="1st"/>
<EnumItem WebDisplayName="Second option" Value="2nd"/>
<EnumItem WebDisplayName="Third option" Value="3rd"/>
</EnumItems>
</Property>
</Properties>
</ClientWebPart>
</Elements>
将加载项起始页设置为主机 Web 主页
接下来的示例 SharePoint 加载项不具有任何加载项 Web，其远程 Web 应用程序的存在只是为了托管表单。 没有此加载项的任何完整页面和沉浸式体验。 因此，加载项的起始页应设置为主机 Web 的主页。
若要开始，请选择 SharePoint 外接程序项目 (而不是解决方案资源管理器中) 的 Web 应用程序项目，并将“网站 URL”属性的值（包括协议 (（例如https://contoso.sharepoint.com) ）复制到剪贴板中。
打开加载项清单，然后将 URL 粘贴到“起始页”框中。
可以选择从 Web 应用程序项目中删除 Default.aspx 页面，因为它没有在 SharePoint 外接程序中使用。
生成和测试解决方案
按 F5 键。
注意
按 F5 键时，Visual Studio 会生成解决方案并安装加载项，同时还会打开加载项的权限页面。
选择“信任它”按钮。
从加载项部件库添加“基本加载项部件”。 For detailed instructions, see Add an Add-in Part to a page.
在主机 Web 上安装加载项后，加载项部件库中就会提供“基本加载项部件”。 它应与下图非常相似。
加载项部件库中的加载项部件
添加加载项部件后，选择标题“基本加载项部件”右侧的向下箭头，然后选择“编辑 Web 部件”。
应该会看到处于编辑模式的加载项部件。
打开“基本加载项部件类别”并更改某些属性值。
选择“确定”保存所做的更改，并确认属性已在加载项部件中更改。
结束调试会话后，如果暂时不会在此项目上再次使用 F5，最好在最后一次撤回 SharePoint 加载项，以确保测试加载项部件从主页中删除。 右键单击 SharePoint 加载项项目并选择“撤回”。
解决方案疑难解答
| 问题 | 解决方案 |
|---|---|
| 外接程序部件没有显示任何内容。 外接程序部件显示以下错误：“已取消到该网页的导航”。 出现此错误是因为浏览器阻止了内容页。 | 启用混合内容。 根据所使用的浏览器，该过程可能会有所不同：Internet Explorer 9 和 10 在页面底部显示以下消息：“只显示安全内容”。 选择“显示所有内容”来显示加载项部件内容。 Internet Explorer 8 显示包含以下消息的对话框： 是否仅查看安全传送的网页内容？ 选择“ 否 ”可显示外接程序部件内容。 您也可以启用正在使用的 Internet 区域中的混合内容。 对于大多数开发者而言，此 Intetrnet 区域是本地 Intranet。 如果这与你的情况不符，请将正在使用的 Internet 区域替换为本地 Intranet。 在 Internet Explorer 中，选择“工具”>“Internet 选项”。 在“Internet 选项”对话框中的“安全”选项卡上，选择“本地 Intranet”，然后选择“自定义级别”按钮。 在“安全设置”对话框中，启用“其他”部分中的“显示混合内容”。 |
其他常见的方案外接程序部件
本文显示如何利用将远程网页用作内容页的自定义属性创建基本外接程序部件。 您还可以探索以下有关外接程序部件的方案和详细信息。
使用 SharePoint 页作为内容页
大多数情况下，如果网页在响应中发送 X-Frame-Options HTTP 头，则该网页将无法在框架中显示。 默认情况下，SharePoint 页包括 X-Frame-Options 头。 如果使用的是托管在加载项 Web 上的 SharePoint 网页，可能会遇到以下错误（如下图所示）：“此内容无法在框架中显示”。
无法在框架中显示内容的外接程序部件
请注意，当网页在框架中显示时，特定方案易受点击劫持攻击。 请仔细评估加载项部件方案，以确保不存在点击劫持攻击风险。
如果加载项 Web 中托管的页面不易受点击劫持攻击，则可以使用 AllowFraming Web 部件抑制来自页面响应的 X-Frame-Options 头。 以下示例代码显示如何在 SharePoint 页面上使用 AllowFraming Web 部件。 将此标记复制到加载项 Web 上托管的页面中。 将此标记放在页面中第一个 asp:content 元素的上方。 它不能为任何其他元素的子级。
<WebPartPages:AllowFraming ID="AllowFraming1" runat="server" />
可以下载加载项部件代码示例使用加载项部件在主机 Web 中显示加载项 Web 内容，以展示如何将 SharePoint 页作为内容页。
调整加载项部件大小
如果您在外接程序部件中使用动态内容，则该内容的宽度和高度可能发生改变。 由于内容的动态特性，它可能不适合框架。 您也可能使用了过多的空间。 若使用动态内容，则可能难以在您的外接程序部件声明中指定固定大小。 不过，您可以调整框架的大小，以便与内容的宽度和高度相符。
您可以使用内容网页中的 POST 消息指定框架的大小。 以下 JavaScript 示例显示了如何发送 POST 消息以调整托管外接程序部件的框架的大小。 通常情况下，在您从页面调用的 JavaScript 文件的 JavaScript 方法中具有此消息。 例如，页面可能有一个控件，用户可在该控件中指定外接程序部件窗口的大小。 然后会从控件的 onchange 处理程序调用自定义方法。
有关动态调整大小的加载项部件的完整示例，请参阅代码示例：在 SharePoint 加载项中动态调整加载项部件大小。
window.parent.postMessage("<message senderId={SenderId}>resize(120, 300)</message>", {hostweburl});
在上述示例中，呈现页面时，加载项部件代码将对页面的查询字符串自动设置 senderId 值。 在请求调整大小时，页面只需从查询字符串中读取 SenderId 值并使用该值即可。 可以通过将 StandardTokens 或 HostUrl 标记追加到加载项部件定义中的 Src 属性来检索查询字符串的主机 Web URL。
在加载项部件内容中使用 SharePoint 样式表
由于加载项部件托管在 SharePoint 页面中，你可能希望让加载项部件内容看起来像是页面的一部分。 一个可以实现外观相似的方法是使用与托管加载项部件的 SharePoint 页面相同的样式类。 可以通过添加对加载项 Web 中的 defaultcss.ashx 文件的引用来使加载项部件可供 SharePoint 网站的样式表使用。
有关如何在 SharePoint 加载项中引用 defaultcss.ashx 文件的说明，请参阅在 SharePoint 加载项中使用 SharePoint 网站样式表。
若要查看引用样式表的加载项部件，请下载代码示例：使用 coffeemaker 加载项部件显示远程网页内容。
当加载项部件处于编辑模式时进行检测
用户可以编辑加载项部件以更改其属性。 例如，用户可能想要更改加载项部件的一个 Appearance 或 Layout 属性。 如果加载项部件处于编辑模式，你可能希望修改呈现逻辑或者阻止某些不必要的处理。 例如，只要重新加载主机页面，外接程序部件就会调用后端数据库。 Changing an add-in part property value in edit mode causes a page reload, but you might not want the network call to be triggered in that case. You can use the editMode token to detect if users are editing your add-in part.
若要使用 editMode 标记，请将查询字符串参数添加到外接程序部件声明中 Content 元素的 Src 属性中。
<Content Src="content_page_url&amp;editmode=_editMode_">
editMode 标记让内容页可以判断外接程序部件是否处于编辑模式。 如果外接程序部件处于编辑模式， editMode 标记将解析为 1；否则解析为 0。