2017年3月14日,星期二

Creating/provisioning 现代 pages and SPFx web parts

因此,SharePoint Framework(SPFx)现在可在所有Office 365租户中使用,并将SPFx用于Web部件 ’现在重新开发是一个明智的选择。毕竟,我们现在有了“modern”SharePoint网站和要考虑的页面,以及可以在以下位置使用的矩阵:

  • SPFx Web部件– 经典 pages AND 现代 pages
  • 经典网页部分– 经典 pages only

仅此一项就可以告诉您,大多数新开发都应该使用SPFx完成。提醒一下,连接到Office 365组的任何SharePoint网站都是现代网站,并且已经存在很长时间的任何旧SharePoint Online网站现在都具有现代页面(’是创建新页面时的默认值)。在2017年的某个时候,我认为我们也可以期待一个用于发布网站的新框架,因此总体信息是,您使用其开发的任何Web部件“classic”方法将使用的地方越来越少。

但是,SPFx最初在配置方面缺少一些东西:

  1. 能够添加一个 习俗 将SPFx Web部件以编程方式(或在其他某些供应方式下,例如PnP供应XML)连接到页面
  2. 补充能力 微软之一 ’s 将SPFx现成的Web部件以编程方式(或使用PnP供应XML)添加到页面
  3. 能够将应用程序自动添加到站点,以便可以使用任何SPFx Web部件(或其他工件)
  4. Ability to create 现代 pages programmatically
  5. Ability to create 现代 site collections programmatically

因此,许多站点模板方案在新世界中都存在差距。

好消息是微软已经采取了关闭这些措施的第一步。 实际上,现在可以进行项目1、2、4和5的操作。 Yes, there are still things that may get in the way of meeting client requirements for SharePoint team sites, but things are progressing and hopefully these will be closed 不久.

具体来说,坏消息是,据我所知,上面列表中缺少项目编号3意味着它’仍然无法为SharePoint网站提供模板 which has a home page with certain 现代 web parts。那’很可惜,因为’对我们来说是一个共同的要求–我们开发的大多数协作解决方案都包含少量定制的团队站点,但是通常包括调整主页以具有最合适的Web部件集。这里’s总结:

将自定义SPFx Web部件配置到页面
在撰写本文时(2017年3月),您构建的任何* 习俗 * SPFx Web部件仅在将该应用*安装到当前站点*时才可用。我希望情况并非如此,我的理解是"soon"还有其他选项可用于在租户中展开Web部件(以避免安装该应用程序)。至少,对于不提供其他工件(例如支持列表)的Web部件,这应该是可能的。但是现在,一旦将应用程序本身上载到.sppkg文件到应用程序目录中,则必须将应用程序安装到站点上。当前没有可简化应用程序安装的API,并且传统的租户范围部署方法不起作用。
 
此外,PnP当前不支持使用XML模板将SPFx Web部件设置到页面。现在,您必须编写代码。

因此,根据您的要求,您可能需要做一些“post-processing”创建网站后到达您需要的位置。

Getting started with PnP methods for provisioning 现代 pages and web parts

本文中的所有代码均使用Microsoft ’■供应的模式和实践方法。 It’s possible to “code direct”针对SharePoint Online,但您’会发现代码不太简单,这样做几乎没有好处–通常,您想要的是PnP抽象。如果发现需要做更多控制的情况(可能是一个例子“PromotedState=1”创建新闻页面),然后是Microsoft’s 客制化"modern" site pages 文章向您展示了两种代码方法。实际上,在这篇文章中,我想用一些额外的信息和屏幕快照来补充该文章,但我建议您注意这一点。通常,您需要按照以下过程开始:

  1. 准备好一些.NET代码(例如控制台应用程序,Azure Function或其他功能)-我们将使用的PnP核心库基于C#CSOM
  2. 安装 //www.nuget.org/packages/SharePointPnPCoreOnline NuGet软件包, 使用2.13.1703(2017年3月)之后的版本:

     SNAGHTMLd3a2852

在安装NuGet软件包时,您还将获得正确版本的SharePoint CSOM库作为依赖项。一旦安装了这些,就可以开始使用PnP方法进行编码了。它’s now easy to create a 现代 site programatically (see //msdn.microsoft.com/en-us/pnp_articles/modern-experience-customizations-provisioning-sites)或操作网站中的页面,这就是我’m focusing on here.

创建新页面与修改现有页面

首先,请注意创建新页面与获取对现有页面的引用并进行修改之间的区别–下面的代码示例同时显示了两者。还要注意,现代页面只是设置为特定内容类型并具有某些特定属性的页面– it’这使它变得现代。 PnP方法使您从这些细节中抽象出来,但是请参阅上一个链接的MSDN页面以获取该信息。使用PnP,创建或修改现有的现代页面非常简单:

供应一个 page with an out-of-the-box 现代 web part

多亏了PnP,’s nothing complex about getting your web part onto the page. A nice method is provided which knows about the out-of-the-box 现代 web parts –ClientSidePage.InstantiateDefaultWebPart():

这样一来,您便可以将Web部件添加到具有默认属性的页面上:

 SNAGHTML137b5e9a

顺便说一句,该方法允许您使用枚举在所有当前可用的现成的Web部件之间进行选择:

 SNAGHTML137dca4a

万一您需要了解底层Web部件ID是什么,可以在这里进行以下操作:

Web部件ID Web部件名称
daf0b71c-6de8-4ef7-b511-faae7c388708 ContentRollupWebPart
e377ea37-9047-43b9-8cdb-a761be2f8e09 BingMapWebPart
490d7c76-1824-45b2-9de3-676421c997fa ContentEmbedWebPart
b7dd04e1-19ce-4b24-9132-b60a1c2b910d DocumentEmbedWebPart
d1d91016-032f-456d-98a4-721247c305e8 ImageWebPart
af8be689-990e-492a-81f7-ba3e4cd3ed9c ImageGalleryWebPart
6410b3b6-d440-4663-8744-378976dc041e LinkPreviewWebPart
0ef418ba-5d19-4ade-9db0-b339873291d0 NewsfeedWebPart
a5df8fdf-b508-4b66-98a6-d83bc2597f63 NewsreelWebPart
c70391ea-0b10-4ee9-b2b4-006d3fcad0cd PinnedItemsWebPart
58fcd18b-e1af-4b0a-b23b-422c2c52d5a2 PowerBIReportEmbedWebPart
91a50c94-865f-4f5c-8b4e-e49659e69772 QuickChartWebPart
eb95c819-ab8f-4689-bd03-0c2d65d47b1f SiteActivityWebPart
275c0095-a77e-4f6d-a2a0-6a7626911518 EmbeddedVideoWebPart
31e9537e-f9dc-40a4-8834-0e3b7df418bc YammerEmbedWebPart

 

在Web部件上设置属性值

在设置属性时,事情变得有些棘手,但这仅是因为发现当前每个Web部件的实际属性名称都需要进行一些挖掘。这是使用视频嵌入Web部件和Yammer嵌入Web部件的几个示例:

现在,我将Web部件正确地配置到了页面上:

 SNAGHTML13864eb6

现在,它’发现每个Web部件的属性名称有些棘手–但是PnP人士提到,将来SPFx工作台页面将对此有所帮助(即,将Web部件添加到页面,然后在工作台中的某处使用see属性结构),那将是很好的。现在,我找到了两个选择-您可以浏览从返回的集合 ClientSidePage.AvailableClientSideComponents() 在调试器中(有关此方法的更多信息):

 SNAGHTML1389c697

..或更简单的方法是先使用PnP方法实例化Web部件,然后在调试器中查看该部件:

 SNAGHTML138befa1

另一种选择是分析“CanvasContent1”页面上的页面属性’的列表项(例如,在SharePoint Online客户端浏览器或类似工具中)。无论如何,一旦有了属性名称,就可以进行相应设置。

设置自定义SPFx Web部件

供应一个 习俗 Web部件在PnP堆栈中使用了不同的方法– ClientSidePage.AvailableClientSideComponents()。 该过程稍有不同之处在于:

  • 如前所述,该应用程序需要安装到当前站点(至少目前如此)
  • 您需要从清单中获取Web部件的ID /名称,或者通过分析页面上的可用Web部件集合(一旦安装了应用程序并且Web部件确实可用)来获取ID /名称。

这里’将命名的自定义Web部件添加到页面的方法可能看起来像什么– it’确定标识代表您的自定义Web部件的集合中的项目:

可以在Web部件中找到ID和名称’的原始清单文件,如下所示:

 SNAGHTML1256879f

这些值只需要与您所需要的相匹配’用来在代码中标识Web部件,例如:

var webPartToAdd = components.Where(wp =>wp.​​ComponentType == 1&& wp. 名称 == wpName ).FirstOrDefault();

 SNAGHTML12a2fda8

..无论如何,现在我的自定义Web部件已配置到页面上(在这种情况下,具有我真正美丽的色彩主题!):

 SNAGHTML13aa72e8  

其他注意事项

  • ClientSidePage.AvailableClientSideComponents() 方法是对 [site] / _ api / web / GetClientSideWebParts 端点。它’值得一看。
  • 如果查看这些方法返回的完整集合,则您’会发现我还有很多其他物品’我没有在上表中列出。这些是非Web部件组件,例如“SPFilepicker”, “SPHtmlEmbed” and “SPPageContext” –这些是在框架中注册的SPFx代码的其他位,以便允许它们运行。我认为我们可以期望以这种方式注册我们实现的其他形式的任意JavaScript(例如JSLink替换)。
  • 如果需要,您可以使用以下方法添加现成的Web部件: ClientSidePage.AvailableClientSideComponents() (因为它既包含自定义Web部件又包含库存Web部件)。请注意,对于现成的Microsoft Web部件,名称始终与ID相同,这有点令人困惑,这意味着您可以’不要轻易在代码中按名称引用零件。我检查了,这不是’是PnP错误,但它们是怎么来的 [site] / _ api / web / GetClientSideWebParts:

     SNAGHTML129f4543

    将该屏幕截图与上述用于自定义Web部件(ID和名称不同)的屏幕截图进行对比-只是要注意的一个。

概要

Adding a 现代/SPFx web part to a page is simple with the PnP methods, so long as you're happy to write your own code rather than depend on a PnP provisioning template - but hopefully XML support is coming 不久 too. Similarly, it’使用这些方法还可以轻松创建新页面或将其添加到现有页面。我在这里经历了一些场景,但是有关MSDN的文章 客制化"modern" site pages 有一些“很棒”的信息,我强烈建议您注意这一点(以及从那里链接的伴随文章)。好的PnP团队:)祝您编程愉快!