了解并配置自 2019 年 6 月版本起 (发布页面转换模型)
发布页面始终基于页面布局和母版页。 这两个页面与包含数据的字段相结合，构成了用户在浏览器中看到的页面。 转换发布页面时，必须将使用的页面布局映射到发布页面转换模型。 发布页面转换组件将为所有现成的页面布局提供“默认”页面布局映射，因此，如果门户使用现成的页面布局，则会涵盖这些页面布局。 现实情况是，大多数门户使用自定义页面布局 (和自定义母版页) 因此需要对这些自定义页面布局进行页面布局映射。 可以通过两种方式处理自定义页面布局：
- 首选选项是自行提供自定义页面布局映射文件，这使你可以完全控制哪些字段转换为 Web 部件，以及它们驻留在新式页面上的位置、哪些字段成为元数据等。
- 如果未找到要转换的页面的页面布局映射，我们将动态生成映射并使用该映射。 此方法的缺点是，所有内容最终都将位于新式页面的同一部分和列中。
生成页面布局映射文件
如果使用自定义页面布局，则建议使用自定义页面布局映射文件，以便能够获取更准确的新式页面。 幸运的是，你不必手动制作这些自定义布局文件，有一个 .Net API 和 PnP PowerShell 支持来生成一个。
使用 PowerShell
Export-PnPPageMapping使用 cmdlet 可以：
- 将内置映射文件 (
-BuiltInPageLayoutMapping参数导出) ：此文件将用于现成的页面布局。 如果在自己的映射文件中为现成的页面布局指定自定义映射，则该映射优先于 OOB 映射 - 在连接的门户中分析页面布局，并将其导出为映射文件，
-CustomPageLayoutMapping(参数) ：分析和导出找到的所有自定义页面布局。 如果还想要分析 OOB 页面布局，请使用-AnalyzeOOBPageLayouts参数。
# Connect to your "classic" portal
Connect-PnPOnline -Url https://contoso.sharepoint.com/sites/classicportal -Interactive
# Analyze and export the page layout mapping files
Export-PnPPageMapping -BuiltInPageLayoutMapping -CustomPageLayoutMapping -Folder c:\temp
使用 .Net
在 .Net 中， PageLayoutAnalyser 需要使用 类来分析页面布局。 下面的两个代码片段演示如何分析所有页面布局或某些发布页面使用的页面布局。
string siteUrl = "https://contoso.sharepoint.com/sites/classicportal";
AuthenticationManager am = new AuthenticationManager("<Azure AD client id>", "joe@contoso.onmicrosoft.com", "Pwd as SecureString");
using (var cc = am.GetSharePointOnlineAuthenticatedContextTenant(siteUrl))
{
var analyzer = new PageLayoutAnalyser(cc);
// Analyze all found page layouts
analyzer.AnalyseAll();
analyzer.GenerateMappingFile("c:\\temp", "custompagelayoutmapping.xml");
}
string siteUrl = "https://contoso.sharepoint.com/sites/classicportal";
AuthenticationManager am = new AuthenticationManager("<Azure AD client id>", "joe@contoso.onmicrosoft.com", "Pwd as SecureString");
using (var cc = am.GetSharePointOnlineAuthenticatedContextTenant(siteUrl))
{
var analyzer = new PageLayoutAnalyser(cc);
// Analyze all the unique page layouts for publishing pages starting with an "a"
var pages = cc.Web.GetPagesFromList("Pages", "a");
foreach (var page in pages)
{
analyzer.AnalysePageLayoutFromPublishingPage(page);
}
analyzer.GenerateMappingFile("c:\\temp", "custompagelayoutmapping.xml");
}
页面布局映射模型说明
打开页面布局映射文件时，会出现以下顶级元素：
AddOns：作为页面转换的用户，可能需要应用自定义逻辑来实现你的需求，例如，你需要转换给定属性，使其可与自定义 SPFX Web 部件配合使用。 框架通过允许你添加包含函数的程序集来支持这一点...只需在 AddOn 部分中定义它们，然后稍后通过为自定义函数添加给定名称前缀来引用自定义函数，发布页面转换将使用自定义代码。
PageLayouts：此元素包含计划使用的每个页面布局的信息。 对于每个页面布局，你将找到标头、Web 部件、元数据、Web 部件区域和固定 Web 部件的定义。
接下来的章节将提供更多详细信息。
页面布局模型中的 PageLayout 定义
让我们来分析如何在页面布局映射模型中配置页面布局映射，最好根据示例定义完成此操作：
<PageLayout Name="MyPageLayout" AlsoAppliesTo="MyOtherPageLayout;MyOtherPageLayout2" AssociatedContentType="CustomPage1" PageLayoutTemplate="AutoDetect" IncludeVerticalColumn="true" PageHeader="Custom">
<SectionEmphasis VerticalColumnEmphasis="Soft">
<Section Row="3" Emphasis="Neutral" />
</SectionEmphasis>
<Header Type="FullWidthImage" Alignment="Left" ShowPublishedDate="true">
<Field Name="PublishingRollupImage;PublishingPageImage" HeaderProperty="ImageServerRelativeUrl" Functions="ToImageUrl({@name})" />
<Field Name="ArticleByLine" HeaderProperty="TopicHeader" Functions=""/>
<Field Name="PublishingContact" HeaderProperty="Authors" Functions="ToAuthors({PublishingContact})"/>
</Header>
<MetaData ShowPageProperties="true" PagePropertiesRow="1" PagePropertiesColumn="4" PagePropertiesOrder="1">
<Field Name="PublishingContactName;PublishingContactEmail" TargetFieldName="MyPageContact" Functions="" />
<Field Name="MyCategory" TargetFieldName="Category" Functions="" ShowInPageProperties="true" />
</MetaData>
<WebParts>
<Field Name="PublishingPageImage" TargetWebPart="SharePointPnP.Modernization.WikiImagePart" Row="1" Column="1" Order="1">
<Property Name="ImageUrl" Type="string" Functions="ToImageUrl({PublishingPageImage})"/>
<Property Name="AlternativeText" Type="string" Functions="ToImageAltText({PublishingPageImage})" />
</Field>
<Field Name="PublishingPageContent" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="2" Order="1">
<Property Name="Text" Type="string" Functions="" />
</Field>
</WebParts>
<WebPartZones>
<WebPartZone Row="2" Column="1" Order="1" ZoneId="g_0C7F16935FAC4709915E2D77092A90DE" ZoneIndex="0">
<!-- Optional element, only needed if you want to use custom position of the web parts coming from a web part zone -->
<WebPartZoneLayout>
<WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="2"/>
<WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="1" Order="2"/>
<WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.XsltListViewWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="1" Order="1"/>
</WebPartZoneLayout>
</WebPartZone>
</WebPartZones>
<FixedWebParts>
<WebPart Row="1" Column="2" Order="1" Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">
<Property Name="TITLE" Type="string" Value="Example Embedded Web Content Editor"/>
<Property Name="CONTENT" Type="string" Value="PnP Rocks!"/>
</WebPart>
</FixedWebParts>
</PageLayout>
注意
建议在编辑这些文件时使用 pagelayoutmapping.xsd 架构 。 提供给页面的文件转换将针对该架构进行验证，当提供的页面布局映射文件无效时，转换将失败。
PageLayout 元素
以下属性用于 PageLayout 元素：
- 名称：包含页面布局的名称。
- AlsoAppliesTo：当此映射将用于多个页面布局时，可以在此属性中将这些附加页面布局的名称指定为分号分隔列表。 Name 属性将是第一个页面布局的名称，而 AlsoAppliesTo 只包含其他页面布局。
- AssociatedContentType：要使用的新式网站页面内容类型的名称。 如果要使用默认网站页面内容类型，请将此内容留空。
- PageLayoutTemplate：要使用的布局系统...默认情况下，
AutoDetect在所有情况下都应正常工作，但你也可以选择特定的 Wiki 布局。 - IncludeVerticalColumn：用于指定所创建目标页的可选元素应具有垂直列。 使用垂直列时，会将垂直列作为额外的列，因此，如果在添加垂直列之前有 3 列，现在将有 4 列，因此可以将页面内容的列值设置为 4 以将其放在垂直列中。
- PageHeader：控制将使用的页眉类型。
Custom默认为 ，因为它允许良好的页眉，但你可以将其切换None为无标题或Default默认新式页眉。
SectionEmphasis 元素
以下属性用于可选的 SectionEmphasis 元素：
- VerticalColumnEmphasis：使用此属性将垂直列强调设置为 None、Neutral、Soft 或 Strong
对于每个部分，可以选择性地通过 Section 元素指定节强调：
- 行：指示此节的行号，第一节将具有数字 1
- 强调：将节强调设置为“无”、“中性”、“软”或“强”
Header 元素
标头元素使用以下属性：
- 类型：默认为
FullWidthImage允许标头以全宽显示标头图像。 替代选项包括ColorBlock、CutInShape和NoImage。 请注意，仅当 PageHeader 属性设置为Custom时，此属性才相关。 - 对齐方式：控制页眉内容的对齐方式。 默认值为
Left，备用选项为Center。 - ShowPublishedDate：定义是否显示页面发布日期。 默认为
true。
对于要在新式标头中使用的每个字段，需要添加一个 Field 元素，指定：
- 名称：经典发布页中 () 字段的名称。 例如，将 作为值进行添加
PublishingRollupImage;PublishingPageImage将意味着PublishingRollupImage将采用 （如果已填充），如果未填充 ，PublishingPageImage将尝试 。 可以根据需要添加任意数量的替代 - HeaderProperty：要设置的标头属性的名称
- 函数：如果设置为空，则经典发布页中的字段值将按原样执行，但如果在此处指定函数，则使用该函数的输出。 如果 (指定了多个字段，因此使用字段替代选项) ，则需要将函数中使用的字段指定为
{@name}
构造新式页眉时，可以使用来自发布页的数据填充 4 个页眉属性：
- ImageServerRelativeUrl：如果标头需要显示图像，则此字段需要为与页面位于同一网站集中的图像定义服务器相对图像路径。 默认情况下，使用经典发布页
PublishingRollupImage字段，但由于该字段包含 Img 标记，因此通过ToImageUrl函数清理字段内容。 - TopicHeader：默认情况下，经典发布页面
ArticleByLine字段用作新式页面标题的主题标题 - 作者：通过设置作者，可以在页眉中显示此页面的主要联系人。 默认情况下，使用经典发布页
PublishingContact字段，但由于这是用户字段，字段内容通过ToAuthors函数进行转换。 - AlternativeText：默认情况下不映射，但可以添加自定义映射以填充新式标头替代文本属性（如果需要）
例如，如果不想设置主题标题，只需删除或注释相应的 Field 元素。
页眉图像选项
默认映射采用字段中定义的 PublishingRollupImage 图像作为页眉，但可以选择选择另一个发布图像字段，或指定位于源站点或目标网站中的图像的硬编码值。 以下示例显示了包含静态图像的标头：
<Header Type="FullWidthImage" Alignment="Left" ShowPublishedDate="true">
<!-- Note that static values do require specifying them between '' -->
<Field Name="PublishingRollupImage" HeaderProperty="ImageServerRelativeUrl" Functions="StaticString('/sites/classicportal/images/myimage.jpg')" />
<Field Name="ArticleByLine" HeaderProperty="TopicHeader" Functions=""/>
<Field Name="PublishingContact" HeaderProperty="Authors" Functions="ToAuthors({PublishingContact})"/>
</Header>
MetaData 元素
metadata 元素定义需要接管哪个经典发布页面字段作为新式页面的元数据。 有时，你希望也使用 OOB 页面属性 Web 部件来表示元数据，你通过以下可选属性指示：
- ShowPageProperties：页面属性 Web 部件将添加到生成的新式页面上
- PagePropertiesRow：将保存页面属性 Web 部件的行
- PagePropertiesColumn：将保存页面属性 Web 部件的列
- PagePropertiesOrder：页面属性 Web 部件在定义的行/列中的顺序
对于要接管的每个字段，需要添加一个 Field 元素，指定：
- 名称：经典发布页中 () 字段的名称。 例如，将 作为值进行添加
PublishingContactName;PublishingContactEmail将意味着PublishingContactName将采用 （如果已填充），如果未填充 ，PublishingContactEmail将尝试 。 可以根据需要添加任意数量的替代 - TargetFieldName：目标新式页中字段的名称
- 函数：如果设置为空，则经典发布页中的字段值将按原样执行，但如果在此处指定函数，则使用该函数的输出。 如果 (指定了多个字段，因此使用字段替代选项) ，则需要将函数中使用的字段指定为
{@name} - ShowInPageProperties：如果设置为 true，并且如果显示页面属性 Web 部件已打开，则此字段显示在页面属性 Web 部件
注意
- 函数支持不适用于分类字段
WebParts 元素
经典发布页中需要成为目标页面上视觉元素的每个字段 (如 Web 部件或文本) 必须在 Web 部件部分中定义：
- 名称：经典发布页中字段的名称。
- TargetWebPart：将在新式页面上可视化此字段的目标 Web 部件的类型。 支持的目标 Web 部件是
SharePointPnP.Modernization.WikiTextPart、SharePointPnP.Modernization.WikiImagePart和Microsoft.SharePoint.Publishing.WebControls.SummaryLinkWebPart, Microsoft.SharePoint.Publishing, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c。 - 行：要放入目标 Web 部件的行。 需要为 1 或更大。
- 列：要放入目标 Web 部件的列。 需要为 1、2 或 3。
- 顺序：目标 Web 部件在定义的行/列中的顺序。
根据所选的 TargetWebPart，需要提供包含转换期间所需数据的 Web 部件属性。 每个属性具有以下属性：
- 名称：属性的名称。 这些属性名称需要与 页面转换模型中使用的属性匹配。
- 类型：属性的类型。 这些属性类型需要与 页面转换模型中使用的属性匹配。
- 函数：如果设置为空，则属性值将是源经典发布页中字段的值。 可以使用函数首先转换字段内容，或使用经典发布页面另一个字段中的数据
WebPartZones 元素
如果页面布局包含 Web 部件区域，则必须在此处定义这些区域。 若要在新式页面上正确定位已转换的 Web 部件，必须执行此操作。 使用以下属性：
- ZoneId：区域的名称
- ZoneIndex：区域索引 (整数)
- 行：要在其中放置托管的 Web 部件的行。 需要为 1 或更大。
- 列：要在其中放置托管的 Web 部件的列。 需要为 1、2 或 3。
- 顺序：在此区域中托管的 Web 部件的已定义行/列中的顺序
有时，发布页面在一个 Web 部件区域中有多个 Web 部件，并且你确实希望在目标页面上以不同的方式放置每个 Web 部件。 可以使用可选的 WebPartZoneLayout 元素执行此操作：
<WebPartZoneLayout>
<WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="2"/>
<WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.ContentEditorWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="1" Order="2"/>
<WebPartOccurrence Type="Microsoft.SharePoint.WebPartPages.XsltListViewWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="3" Column="1" Order="1"/>
</WebPartZoneLayout>
上述定义的结果是，第一个 ContentEditorWebPart 将转到第 3 行第 2 列。 第二个 ContentEditorWebPart 将放在第 3 行，第 1 列，顺序为 2，第一个 XSLTListView Web 部件最终将位于第 3 行，第 1 列 1 次。 可以根据需要定义任意数量的 WebPartOccurrence 元素，如果 Web 部件区域中没有相应的 Web 部件，则将忽略 WebPartOccurrence 元素。 如果 Web 部件区域中有未列为 WebPartOccurrence 元素的 Web 部件，则该 Web 部件将从 WebPartZone 元素获取其行、列和顺序信息。
FixedWebParts 元素
有时页面布局包含“固定”Web 部件，这是在页面布局内硬编码的 Web 部件，因此这些部件存在于使用页面布局的所有页面上。 由于没有 API 来检测这些“固定”Web 部件，因此需要将其定义为页面布局映射模型的一部分。
可以在“固定”Web 部件上设置以下属性：
- 类型：固定 Web 部件的类型。 有关可能类型的列表，请参阅 此处 。
- 行：要放入“固定”Web 部件的行。 需要为 1 或更大。
- 列：要在其中放置“固定”Web 部件的列。 需要为 1、2 或 3。
- 顺序：如果在同一行和列中放置了多个 Web 部件，则顺序相关。
对于每个“固定”Web 部件，需要定义相关属性。 通常，你会接管这些属性，因为它们是在经典页面布局中定义的。 对于每个属性，可以设置以下属性：
页面布局模型中的 AddOns 定义
通过加载项，可以按照以下 2 个步骤将自定义逻辑插入页面布局映射模型中：
- 创建托管自定义函数的自定义程序集
- 在 AddOns 元素中声明此自定义程序集
创建自定义函数/选择器程序集
若要创建自己的函数，将需要在项目中引用 SharePoint.Modernization.Framework 程序集，然后创建继承 SharePointPnP.Modernization.Framework.Functions.FunctionsBase 类的类：
using Microsoft.SharePoint.Client;
using SharePointPnP.Modernization.Framework.Functions;
using System;
namespace Contoso.Modernization
{
public class MyCustomFunctions: FunctionsBase
{
public MyCustomFunctions(ClientContext clientContext) : base(clientContext)
{
}
public string MyListAddServerRelativeUrl(Guid listId)
{
if (listId == Guid.Empty)
{
return "";
}
else
{
var list = this.clientContext.Web.GetListById(listId);
list.EnsureProperties(p => p.RootFolder.ServerRelativeUrl);
return list.RootFolder.ServerRelativeUrl;
}
}
}
}
声明自定义程序集
在可以使用自定义函数之前，需要在模型中声明它们，方法是将每个库/类的一个引用添加到 AddOns 元素中：
<AddOn Name="Custom" Type="Contoso.Modernization.MyCustomFunctions" Assembly="Contoso.Modernization.dll" />
或（注意完全限定的路径）
<AddOn Name="Custom" Type="Contoso.Modernization.MyCustomFunctions" Assembly="c:\transform\Contoso.Modernization.dll" />
请注意，每个声明都具有一个名称，在上述示例中，都拥有名称“Custom”。
使用自定义函数/选择器
现在已经定义了程序集，可以使用函数和选择器按照名称来引用它们，如下面示例中所示的“Custom”前缀：
<Property Name="ListId" Type="guid" Functions="{ListServerRelativeUrl} = Custom.MyListAddServerRelativeUrl({ListId})"/>
页面布局映射常见问题解答
我想保留源页面创建信息
使用 PnP PowerShell 方法 时， -KeepPageCreationModificationInformation 请在 cmdlet 中使用 ConvertTo-PnPPage cmdlet。 使用 .Net 方法 时，请将 KeepPageCreationModificationInformation 参数设置为 true。 使用此选项将为目标页面提供源页面中的“创建”、“修改”、“作者”和“编辑器”字段值。
注意
在页面转换过程中，将页面提升为新闻或发布页面时，编辑器字段将设置为运行页面转换的帐户
我想将创建的页面推广为新闻
在使用 ) PnP PowerShell 方法时，可以使用 cmdlet (上的 -KeepPageCreationModificationInformation 参数，或者通过使用 .Net 方法) 时将PostAsNews参数设置为 true (，从而将从页面布局创建的页面提升为-PostAsNews新闻页面。
将 PostAsNews 选项与 选项FirstPublishedDateField结合使用时，KeepPageCreationModificationInformation字段将设置为源页修改日期。 字段 FirstPublishedDateField 是在新闻汇总期间显示的日期值。
我想在创建的页面上插入硬编码文本
有时页面布局包含文本代码段，由于它们不是实际页面中的内容，因此不会进行转换。 如果是这种情况，则可以定义要映射的“fake”字段，如下所示：
<WebParts>
...
<Field Name="ID" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="3">
<Property Name="Text" Type="string" Functions="StaticString('<H1>This is some extra text</H1>')" />
</Field>
...
</WebParts>
注意
StaticString 函数中提供的 HTML 必须经过 XML 编码，并且格式必须与源页面 HTML 类似，因为此 HTML 仍将转换为符合新式文本编辑器的 HTML
我想为字段中的内容添加前缀或后缀
上一章中使用的方法允许你在页面上添加额外的文本，但缺点是，额外的文本将添加到它自己的文本部分。 如果希望将额外文本与要转换的实际文本集成，则可以使用以下方法执行此操作。 可以为现有字段内容添加前缀和/或后缀，还可以选择仅在字段包含内容时完成前缀/后缀。 和 PrefixAndSuffix 函数中的 PrefixSuffix bool 参数定义当字段内容为空时是否需要进行前缀/后缀：“true”表示即使字段为空，也要应用操作。
有关以下函数的更多详细信息，请参阅 页面转换函数和选择器 。
<WebParts>
...
<Field Name="PublishingPageContent" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="2">
<Property Name="Text" Type="string" Functions="PrefixAndSuffix('<H1>Prefix some extra text</H1>','<H1>Suffix some extra text</H1>',{PublishingPageContent},'false')" />
</Field>
...
<Field Name="PublishingPageContent" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="2">
<Property Name="Text" Type="string" Functions="Prefix('<H1>Prefix some extra text</H1>',{PublishingPageContent},'true')" />
</Field>
...
<Field Name="PublishingPageContent" TargetWebPart="SharePointPnP.Modernization.WikiTextPart" Row="1" Column="2">
<Property Name="Text" Type="string" Functions="Suffix('<H1>Suffix some extra text</H1>',{PublishingPageContent},'false')" />
</Field>
...
</WebParts>
我想使用一个或多个术语填充托管元数据字段
如果源页元数据中具有托管元数据字段，则可能希望为目标页面使用类似的托管元数据字段。 给定的页面转换当前确实具有托管元数据映射功能，这会带来一个问题。 一种可能的解决方法是使用所选术语或多值托管元数据字段的一组术语填充目标托管元数据字段。 可以使用 函数完成此操作， DefaultTaxonomyFieldValue 如以下示例所示：
<MetaData ShowPageProperties="true" PagePropertiesRow="1" PagePropertiesColumn="4" PagePropertiesOrder="1">
...
<Field Name="TaxField2" TargetFieldName="Metadata2" Functions="DefaultTaxonomyFieldValue({TaxField2},'a65537e8-aa27-4b3a-bad6-f0f61f84b9f7|69524923-a5a0-44d1-b5ec-7f7c6d0ec160','true')" ShowInPageProperties="true"/>
...
</MetaData>
有关函数的更多详细信息DefaultTaxonomyFieldValue，请参阅页面转换函数和选择器。
我想在创建的页面上添加额外的 Web 部件
将经典发布页转换为新式页面时，有时需要在创建的页面上添加 其他 新式 Web 部件，而经典发布页上没有该 Web 部件的经典版本。 这可以通过调整webpartmapping.xml和页面布局映射文件来完成，如下所示。
首先在webpartmapping.xml文件中添加WebParts 元素，在 webpartmapping.xml 文件中定义自定义 Web 部件，如以下标准 SPFX Hello World Web 部件所示：
<WebParts>
...
<!-- Custom Hello world web part-->
<WebPart Type="SharePointPnP.Demo.HelloWorld" CrossSiteTransformationSupported="true">
<Properties>
<Property Name="HelloWorld" Type="string" />
</Properties>
<Mappings>
<Mapping Default="true" Name="default">
<ClientSideWebPart Type="Custom" ControlId="157b22d0-8006-4ec7-bf4b-ed62383fea76" Order="10" JsonControlData="{"serverProcessedContent":{"htmlStrings":{},"searchablePlainTexts":{},"imageSources":{},"links":{}},"dataVersion":"1.0","properties":{"description":"{HelloWorld}","test":"Multi-line text field","test1":true,"test2":"2","test3":true}}"/>
</Mapping>
</Mappings>
</WebPart>
...
</WebParts>
如果不了解如何在上述 ClientSideWebPart 元素中正确定义自定义 Web 部件，请执行以下步骤：
- 导航到站点 (SharePoint 框架 Workbench，例如 https://contoso.sharepoint.com/sites/myportalsite/_layouts/workbench.aspx)
- 将自定义 Web 部件添加到工作台，并在需要时对其进行配置
- 单击工具栏中的“Web 部件数据”按钮，然后单击“新式页面”按钮
- 复制 WebPartData json 结构并使用它来完成后续步骤：
- ControlId guid 值是 id json 属性的值
- 从复制的代码片段中删除以下 json 属性：id、instanceIf、title 和 description。 此时，左侧有以下内容：
{"serverProcessedContent":{"htmlStrings":{},"searchablePlainTexts":{},"imageSources":{},"links":{}},"dataVersion":"1.0","properties":{"description":"HelloWorld from Bert","test":"Multi-line text field","test1":true,"test2":"2","test3":true}} - XML 对此字符串进行编码，这会提供以下代码：
{"serverProcessedContent":{"htmlStrings":{},"searchablePlainTexts":{},"imageSources":{},"links":{}},"dataVersion":"1.0","properties":{"description":"HelloWorld from Bert","test":"Multi-line text field","test1":true,"test2":"2","test3":true}} - 如果需要，请在此字符串中插入 Web 部件参数， (例如上面的示例) 中的 {HelloWorld}：
{"serverProcessedContent":{"htmlStrings":{},"searchablePlainTexts":{},"imageSources":{},"links":{}},"dataVersion":"1.0","properties":{"description":"{HelloWorld}","test":"Multi-line text field","test1":true,"test2":"2","test3":true}} - 将生成的字符串粘贴到 JsonControlData 属性中
完成此操作后，需要通过在 “Web 部件” 部分中添加一个字段来更新页面布局映射，该字段将转换为此自定义 Web 部件：
<WebParts>
...
<!-- Add an extra web part on the page -->
<Field Name="ID" TargetWebPart="SharePointPnP.Demo.HelloWorld" Row="4" Column="1" Order="1">
<Property Name="HelloWorld" Type="string" Functions="StaticString('PnP Rocks!')"/>
</Field>
...
</WebParts>
使用 .Net) 时，请确保将自定义webpartmapping.xml文件指定为转换 (-WebPartMappingFile PowerShell cmdlet 参数（ PublishingPageTransformator 构造函数）的一部分。
我正在使用大量Add-In部件，并希望将这些部件转换为自定义 SPFX Web 部件
页面转换的默认行为只是接管新式页面上的加载项部件，因为外接程序在新式页面上工作。 但是，如果要有选择地将某些外接程序部件转换为基于自定义 SPFX 的 Web 部件，请删除一些加载项部件并保留剩余的外接程序部件，则默认映射将不够。 在下面的示例中，你看到函数 StaticString 用于将外接程序标题作为映射选择器值馈送。 因此，将根据 Web 部件的标题选择映射。 第一个加载项将作为新式页面上的加载项接管，第二个加载项将转换为基于自定义 SPFX 的替代项，最后一个加载项将直接删除。
映射到基于 SPFX 的自定义 Web 部件时，可以使用任何加载项部件属性来配置基于 SPFX 的替代 (例如以下示例中的 {HelloWorld}) ，即使映射文件中的“属性”节点中未列出这些属性也是如此。 若要详细了解如何创建自定义映射文件，请参阅上一章。
<WebPart Type="Microsoft.SharePoint.WebPartPages.ClientWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" CrossSiteTransformationSupported="true">
<!-- Note: the add-in can depend on assets that live in the source site, which is not something we can detect -->
<Properties>
<Property Name="FeatureId" Type="guid"/>
<Property Name="ProductWebId" Type="guid"/>
<Property Name="ProductId" Type="guid"/>
</Properties>
<Mappings Selector="StaticString({Title})">
<Mapping Name="My Custom Report" Default="true">
<!-- We keep this web part -->
<ClientSideWebPart Type="ClientWebPart" Order="10" JsonControlData="{}"/>
</Mapping>
<Mapping Name="News Ticker" Default="false">
<!--This web part will be transformed to a custom SPFX based web part -->
<ClientSideWebPart Type="Custom" ControlId="157b22d0-8006-4ec7-bf4b-ed62383fea76" Order="10" JsonControlData="{"serverProcessedContent":{"htmlStrings":{},"searchablePlainTexts":{},"imageSources":{},"links":{}},"dataVersion":"1.0","properties":{"description":"{HelloWorld}","test":"Multi-line text field","test1":true,"test2":"2","test3":true}}"/>
</Mapping>
<Mapping Name="Some other add-in" Default="false">
<!-- This add-in will not be taken over -->
</Mapping>
</Mappings>
</WebPart>
甚至可以通过将外接程序部件属性组合在一起以生成选择器字符串来考虑帐户外接程序部件属性，使映射更加精确。
<WebPart Type="Microsoft.SharePoint.WebPartPages.ClientWebPart, Microsoft.SharePoint, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" CrossSiteTransformationSupported="true">
<!-- Note: the add-in can depend on assets that live in the source site, which is not something we can detect -->
<Properties>
<Property Name="FeatureId" Type="guid"/>
<Property Name="ProductWebId" Type="guid"/>
<Property Name="ProductId" Type="guid"/>
</Properties>
<Mappings Selector="ConcatenateWithPipeDelimiter({Title},{effect})">
<Mapping Name="News Ticker|Slide" Default="true">
<ClientSideText Text="***TEST.{Title} web part - Slide mapping chosen! Slider theme = {theme}***" Order="10" />
</Mapping>
<Mapping Name="News Ticker|Scroll" Default="false">
<ClientSideText Text="***TEST.{Title} web part - Scroll mapping chosen! Slider theme = {theme}***" Order="10" />
</Mapping>
</Mappings>
</WebPart>
是否可以控制页面预览图像
当页面具有页眉图像时，该图像也将用作页面预览图像。 但是，如果想要控制页面预览图像，则可以使用 ToPreviewImageUrl 函数或通过指定硬编码值来填充BannerImageUrl字段，如以下示例所示。
<!-- When you do have a publishing image field that will need to be set as preview image -->
<Field Name="PreviewImage" TargetFieldName="BannerImageUrl" Functions="ToPreviewImageUrl({PreviewImage})" />
<!-- When you do have a hard coded preview image already available on the target site. Note that the source field name (PublishingContactEmail in below sample) must exist, although it's not used here -->
<Field Name="PublishingContactEmail" TargetFieldName="BannerImageUrl" Functions="StaticString('https://contoso.sharepoint.com/_layouts/15/getpreview.ashx?guidSite=88eebac1710b464cb6816639340fac55&guidWeb=277fe40db9d24da5bbc6827714184958&guidFile=91bf17fd54e849149a3ad6b4f006304e&ext=jpg')" />
<!-- When you want to refer a static image living in the source site -->
<Field Name="PreviewImage" TargetFieldName="BannerImageUrl" Functions="ToPreviewImageUrl('/sites/classicportal/images/myimage.jpg')" />
我想对 QuickLinks Web 部件使用不同的默认值
当转换导致新式 QuickLinks Web 部件 (例如用于转换 SummaryLinkWebPart) 则页面转换框架将使用 QuickLinks Web 部件的默认基本配置。 但是，如果想要其他配置，可以通过指定 QuickLinksJsonProperties 属性来执行此操作。 将编码的 JSON 属性包装在 StaticString 函数中，如以下示例所示：
<WebParts>
...
<Field Name="SummaryLinks" TargetWebPart="Microsoft.SharePoint.Publishing.WebControls.SummaryLinkWebPart, Microsoft.SharePoint.Publishing, Version=16.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" Row="1" Column="2">
<!-- No function specified, means the content of the PublishingPageContent field will be assigned to the value of the first listed web part property -->
<Property Name="SummaryLinkStore" Type="string" />
<Property Name="Title" Type="string" Functions="EmptyString()"/>
<Property Name="QuickLinksJsonProperties" Type="string" Functions="StaticString('{"isMigrated": false, "layoutId": "Button", "shouldShowThumbnail": true, "buttonLayoutOptions": { "showDescription": false, "buttonTreatment": 1, "iconPositionType": 2, "textAlignmentVertical": 1, "textAlignmentHorizontal": 2, "linesOfText": 2}, "listLayoutOptions": { "showDescription": false, "showIcon": true}, "waffleLayoutOptions": { "iconSize": 1, "onlyShowThumbnail": false}, "hideWebPartWhenEmpty": true}')" />
</Field>
...
</WebParts>
示例中的 JSON 显示了所有可以设置的配置选项，但也可以仅定义所需的选项。 只要 JSON 有效且结构保持，就会选取自定义 QuickLinks 配置。