使用解决方案包预配 SharePoint 资产
有时，可能需要在你的客户端解决方案包中预配 SharePoint 列表或文档库，以便列表或库对客户端组件（如 Web 部件）可用。SharePoint 框架工具链允许通过客户端解决方案包打包和部署 SharePoint 项。然后，在网站上安装客户端解决方案时可以预配这些项。
还可以在 Microsoft 365 平台社区 (PnP) YouTube 频道上的此 SharePoint PnP 网络广播中找到有关预配选项的详细信息：
使用 JavaScript 代码预配项
虽然可以在组件（如 Web 部件）中使用 JavaScript 代码创建 SharePoint 项，但其受限于使用该部件的当前用户的情况。如果该用户没有足够的权限创建或修改 SharePoint 项，则 JavaScript 代码将不会预配这些项。在这些情况下，如果想要在升级的情况下预配 SharePoint 项，则需要将该项与解决方案包一起打包和部署。
在解决方案中预配 SharePoint 项
以下 SharePoint 资产可在客户端解决方案包中提供：
- 字段
- 内容类型
- 列表实例
- 包含自定义架构的列表实例
字段
字段或网站列表示一个属性或一段元数据，用户想要将其用于管理列表中的项或其将列添加到的内容类型）。它是可重用的列定义或可以跨多个 SharePoint 站点分配到多个列表的模板。网站列减少了修改工作，并帮助你确保跨站点和列表的元数据的一致性。
例如，假设定义一个名为“客户”的网站列。用户可将该列添加到他们的列表中，并在内容类型中引用它。这将确保出现的列至少一开始都具有同一属性。
可以参考 Field 元素 (Field) 文档中的架构和属性，在解决方案中定义新的字段。
以下是新 DateTime 字段的示例：
<Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
Name="DateOpened"
DisplayName="Date Opened"
Type="DateTime"
Format="DateOnly"
Required="FALSE"
Group="Financial Columns">
<Default>[today]</Default>
</Field>
内容类型
内容类型是元数据（列）、行为和 SharePoint 列表或文档库中的项或文档类别的其他设置的可重用集合。内容类型使你能够以集中式、可重用的方式管理信息类别的设置。
例如，假定这样一种业务情形：你有三种不同类型的文档，分别为费用报表、采购订单和发票。所有这三种类型的文档都具有一些共同的特征；首先它们都是财务文档，并且包含的数据值都以货币表示。但是，每种类型的文档都具有各自的数据要求、各自的文档模板和各自的工作流。
此业务问题的一种解决方案是创建四种内容类型。第一种内容类型“财务文档”可以封装组织中所有财务文档共有的数据要求。其余三种内容类型（“费用报表”、“采购订单”和“发票”）可以从“财务文档”继承共有元素。此外，它们还可以定义每种类型所独有的特征，如特定元数据集、用于创建新项目的文档模板和用于处理项目的特定工作流。
可以参考 ContentType 元素 (ContentType) 文档中的架构和属性来定义解决方案中的新内容类型。
以下是内容类型的示例：
<ContentType ID="0x010042D0C1C200A14B6887742B6344675C8B"
Name="Cost Center"
Group="Financial Content Types"
Description="Financial Content Type">
<FieldRefs>
<FieldRef ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}" />
<FieldRef ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}" />
</FieldRefs>
</ContentType>
列表实例
列表是 SharePoint 网站的关键、基础功能。它们使团队能够收集、跟踪和共享信息。许多应用程序依赖于网站中创建的列表，以供数据存储实现其行为。列表实例是预定义的 SharePoint 列表，它具有已知的标识符。可以自定义项目并将其添加到这些列表，从已可用的列表模板中创建其他列表，并仅创建具有所选的设置和列的自定义列表。
SharePoint 提供几个列表模板，如联系人列表、日历和任务列表等。可以使用这些模板为你的 Web 部件或其他组件创建新的列表实例。例如，可以基于“文档库”模板定义列表实例“财务文档”，以在你的 Web 部件中存储相关联的文档。
可以参考 ListInstance 元素 (List Instance) 文档中的架构和属性来定义解决方案中的列表实例。
以下是列表实例定义的示例：
<ListInstance
FeatureId="00bfea71-e717-4e80-aa17-d0c71b360101"
Title="Finance Records"
Description="Finance documents"
TemplateType="101"
Url="Lists/FinanceRecords">
</ListInstance>
包含自定义架构的列表实例
可以使用自定义列表架构定义来定义列表实例中的字段、内容类型和视图。 将使用 ListInstance 元素中的 CustomSchema 属性为列表实例引用自定义架构。
例如，可以使用可封装对组织中所有财务文档通用的数据要求的内容类型 财务文档 定义列表实例 财务文档。
以下是使用自定义架构的列表实例定义的示例：
<ListInstance
CustomSchema="schema.xml"
FeatureId="00bfea71-de22-43b2-a848-c05709900100"
Title="Cost Centers"
Description="Cost Centers"
TemplateType="100"
Url="Lists/CostCenters">
</ListInstance>
这是为之前定义的列表实例定义内容类型的自定义架构定义：
<List xmlns:ows="Microsoft SharePoint" Title="Basic List" EnableContentTypes="TRUE" FolderCreation="FALSE" Direction="$Resources:Direction;" Url="Lists/Basic List" BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
<MetaData>
<ContentTypes>
<ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
</ContentTypes>
<Fields></Fields>
<Views>
<View BaseViewID="1" Type="HTML" WebPartZoneID="Main" DisplayName="$Resources:core,objectiv_schema_mwsidcamlidC24;" DefaultView="TRUE" MobileView="TRUE" MobileDefaultView="TRUE" SetupPath="pages\viewpage.aspx" ImageUrl="/_layouts/images/generic.png" Url="AllItems.aspx">
<XslLink Default="TRUE">main.xsl</XslLink>
<JSLink>clienttemplates.js</JSLink>
<RowLimit Paged="TRUE">30</RowLimit>
<Toolbar Type="Standard" />
<ViewFields>
<FieldRef Name="LinkTitle"></FieldRef>
<FieldRef Name="SPFxAmount"></FieldRef>
<FieldRef Name="SPFxCostCenter"></FieldRef>
</ViewFields>
<Query>
<OrderBy>
<FieldRef Name="ID" />
</OrderBy>
</Query>
</View>
</Views>
<Forms>
<Form Type="DisplayForm" Url="DispForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
<Form Type="EditForm" Url="EditForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
<Form Type="NewForm" Url="NewForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
</Forms>
</MetaData>
</List>
在解决方案中创建 SharePoint 项
解决方案包使用 SharePoint 功能来打包和预配 SharePoint 项。“功能”是包含要预配的一个或多个 SharePoint 项的容器。“功能”包含一个 Feature.xml 文件以及一个或多个元素清单文件。这些 XML 文件也称为功能定义。
通常情况下，客户端解决方案包包含一个功能。在网站中安装解决方案时将激活该功能。请务必注意，网站管理员安装的是解决方案包而非功能。
主要使用以下 XML 文件构造功能。
元素清单文件
元素清单文件包含 SharePoint 项定义并将在功能激活时执行。例如，创建新字段、内容类型或列表实例的 XML 定义将包含在元素清单中。
以下是定义新 DateTime 字段的元素清单文件的示例。
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
Name="DateOpened"
DisplayName="Date Opened"
Type="DateTime"
Format="DateOnly"
Required="FALSE"
Group="Financial Columns">
<Default>[today]</Default>
</Field>
</Elements>
元素文件
元素清单随附的任何受支持的文件都是元素文件。例如：列表实例架构是一个元素文件，它与元素清单中定义的列表实例相关联。
以下是自定义列表实例架构的示例：
<List xmlns:ows="Microsoft SharePoint" Title="Basic List" EnableContentTypes="TRUE" FolderCreation="FALSE"
Direction="$Resources:Direction;" Url="Lists/Basic List" BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
<MetaData>
<ContentTypes>
<ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
</ContentTypes>
</MetaData>
</List>
升级操作文件
正如其名称所示，更新网站中的解决方案时，该文件将包含所有升级操作。作为升级操作的一部分，此操作也可指定包含一个或多个元素清单。例如：如果升级需要添加一个新字段，则字段定义将作为元素清单提供，并在升级操作文件中进行关联。
以下是升级操作文件在升级时应用元素清单文件的示例：
<ApplyElementManifests>
<ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>
配置 SharePoint 功能
要包含 XML 文件，首先必须在项目中 config 文件夹下的 package-solution.json 配置文件中定义功能配置。 package-solution.json 包含有关客户端解决方案包的键元数据信息，并在运行将解决方案打包到 .sppkg 文件的 package-solution gulp 任务时被引用。
{
"solution": {
"name": "hello-world-client-side-solution",
"id": "26364618-3056-4b45-98c1-39450adc5723",
"version": "1.1.0.0",
"features": [{
"title": "hello-world-client-side-solution",
"description": "hello-world-client-side-solution",
"id": "d46cd9d6-87fc-473b-a4c0-db9ad9162b64",
"version": "1.1.0.0",
"assets": {
"elementManifests": [
"elements.xml"
],
"elementFiles":[
"schema.xml"
],
"upgradeActions":[
"upgrade-actions-v1.xml"
]
}
}]
},
"paths": {
"zippedPackage": "solution/hello-world.sppkg"
}
}
features JSON 对象包含有关功能的元数据，如下表中所示。
| 属性 | 说明 |
|---|---|
| id | 功能的唯一标识符 (GUID) |
| title | 功能标题 |
| description | 功能说明 |
| assets | 功能中所使用的一组 XML 文件 |
| elementManifests | 在 assets 属性内定义，一系列元素清单文件 |
| elementFiles | 在 assets 属性内定义，一系列元素文件 |
| upgradeActions | 在 assets 属性内定义，一系列升级操作文件 |
创建功能 XML 文件
工具链查找在客户端解决方案项目中的一个特殊文件夹 sharepoint\assets 下的配置中所定义的 XML 文件。
package-solution.json 中定义的配置是执行 package-solution gulp 任务时将此处的 XML 文件映射到其相应的功能 XML 文件的配置。
打包 SharePoint 项
在 package-solution.json 中定义了功能并创建了各自的功能 XML 文件后，可以使用以下 gulp 任务在 .sppkg 包中打包 SharePoint 项。
gulp package-solution
此命令会打包一个或多个客户端组件清单，如 Web 部件，以及 package-solution.json 配置文件中引用的功能 XML 文件。
备注
可以使用 --ship 标志打包组件的缩减版本。
升级 SharePoint 项
可以在升级客户端解决方案时加入新的 SharePoint 项或更新现有 SharePoint 项。 由于预配 SharePoint 项的操作需使用功能，将使用功能 UpgradeActions XML 文件定义升级操作的列表。
package-solution.json 中的 upgradeActions JSON 对象数组引用与你的功能的升级操作相关联的功能 XML 文件。 升级操作文件至少会定义在升级功能时执行的元素清单 XML 文件。
升级 SharePoint 框架解决方案时，还需要更新解决方案和功能的版本属性，其中包括了升级操作。解决方案版本增加将告知 SharePoint 最终用户有可用的新版本程序包。功能元素版本增加将确保升级操作中定义的任务将作为解决方案升级的一部分进行处理。
以下是升级操作文件在升级时应用元素清单文件的示例：
<ApplyElementManifests>
<ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>
这是定义在升级过程中要预配的新的“货币”字段的相应 element-v2.xml：
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Field ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}"
Name="Amount"
DisplayName="Amount"
Type="Currency"
Decimals="2"
Min="0"
Required="FALSE"
Group="Financial Columns" />
</Elements>
子元素
客户端解决方案中的升级操作支持以下子元素。
AddContentTypeField
向已设置的现有内容类型添加新字段：将来自网站内容类型的更改传播到网站内的所有子列表和内容类型。例如：
<AddContentTypeField
ContentTypeId="0x010100A6F9CE1AFE2A48f0A3E6CB5BB770B0F7"
FieldId="{B250DCFD-9310-4e2d-85F2-BE2DA37A57D2}"
PushDown="TRUE" />
ApplyElementManifests
向现有功能添加新元素。升级功能时，对指定元素清单中引用的所有非声明性元素进行预配。
VersionRange
指定应用所指定的升级操作的版本范围。