2019年七月18日星期四

Office 365开发人员-构建自定义SPFx表单的提示

我最近从事的一个项目涉及构建自定义表单作为SPFx Web部件。–总的来说,我认为这是一个不错的选择“high-end”需要具有特定行为和/或外观的表格。同样,将页面指定为SPFx应用程序页面的功能意味着可以删除一些不必要的页面家具,这很有帮助。在考虑Office 365中的表单时,我看到了一系列的选项,看起来像(按复杂程度/工作量的顺序排列):

  1. 即用型SharePoint列表表单 
  2. PowerAppscustomised SharePoint list form 
  3. Canvas PowerApp,通过PowerApps Web部件嵌入到SharePoint页面中 
  4. 使用SPFx和React定制开发的表单 
所以,我们’在这里谈论最后一个选择。

好消息是,对于具有足够技能的SPFx开发人员,可以很快速地构建其中一种形式-有一些非常强大的构建块可以提供帮助。我认为总体配方如下所示:
通过将这些成分的使用与一些额外的步骤结合起来以帮助用户进入您的表单(请参阅本章后面的部分),您可以以比您想象的更少的精力来获得丰富的解决方案。

与SPFx一起使用的表单控件,并处理数据

考虑上面的成分列表,您会发现通过引入这些控件并将其与数据集成可以走很长一段路。我认为以下安排可能很常见:

需求

资源

标准文本框,按钮等 Office UI Fabric反应
下拉菜单,包括高级格式/行为 Office UI Fabric反应
分类选择器 PnP React分类选择器
人选器 PnP React人员选择器
文件上载控件(存储为列表项附件) PnP React文件上传控件
文件上传控件(以其他方式存储) 其他第三方控制(您可以处理到SharePoint的上载)

您最有可能需要允许使用表单编辑现有项目以及创建新项目。 PnPJS 非常适合简化操作以获取现有项目(通常是从传递到页面的项目ID),并还可以保存回SharePoint。在SPFx Web部件中,您将使用React状态作为前端控件中间与数据层服务代码之间的过渡。

最后,我的表单看起来像这样(此处显示为缩小)。您可能会注意到顶部的一系列按钮-这些表面功能,例如“另存为草稿”,尽管我认为使用的是Office UI Fabric 命令栏 要么 上下文菜单 很好,在这种情况下,客户端会选择简单明了的按钮。否则,仅使用上述控件:


提供编辑项目的经验


假设您的自定义表单将项目存储在SharePoint列表中,则您可能需要采取一些步骤将默认列表体验与表单集成在一起。一个很好的例子是确保用户编辑项目时,将其带到您的表单而不是即用的SharePoint列表编辑表单。这可以通过在您的列表中添加一列并定义一些JSON格式来提供链接来完成。只需获取页面(即您创建并添加了Web部件的页面)的URL,然后在JSON中使用该URL作为链接。您应该以如下形式结束:

我像这样使用JSON:

请注意,我正在将当前列表项ID传递给表单。在我的SPFx Web部件中,我有代码正在寻找要在'itemId'URL参数中传递的值-如果找到了,如上所述,我使用PnPJS来:
  • 提取此项目的数据
  • 使用这些值设置React状态,以便将表单控件设置为这些值
这样可以照顾到编辑经验。

提供“新项目”体验或自定义现代列表中的新/编辑/显示表格


就我而言,可以通过主页上的大型视觉表示来简单地提供新的项目体验。普通最终用户不会使用该列表,也不会按下“新建”按钮。在这种情况下,事情很简单。 与同事聊天(感谢 狮子座 !),*可能会覆盖现代列表的新/编辑/显示形式,但是如果现代页面是目标并且您想要在URL中传递任何参数(例如,用于编辑经验)-显然有些东西完全破裂了,您的表格也不太可能加载。 一种可行的方法是创建一个经典页面,相应地设置列表的新/编辑/显示表单URL,并在经典页面上添加JavaScript以重定向到托管SPFx表单的现代页面。您可能需要对传递的任何ID进行哈希/进一步编码,并考虑添加CSS隐藏一些页面元素,以防用户在重定向过程中短暂看到它们。 这显然与2019年夏季的情况差不多,并且有一个UserVoice条目 允许我们开发具有定制编辑经验的定制现代表单 要求更好的集成-好消息是这种情况的状态最近已更改为“思考”。因此,希望对于那些需要在您的自定义表单和现成的列表UI之间进行紧密集成的用户,这个故事会很快得到改善。

将页面设置为SPFx应用页面


开发完Web部件后,您将要确保它在页面上正常工作-通常,您将希望删除一些“页面家具”,以便您的表单成为焦点,并且更少分心。在现代页面上,您可以执行某些操作,例如将标题区域设置为“ Plain”布局-这样会减少标题区域,但是如果您的表单具有某种标题/标题,您仍然会在此标题和页面标题。

页面作者可能会意外地编辑页面并删除Web部件,该怎么办?

通过将页面转换为SPFx应用程序页面,可以解决这两个问题。在其中之一上,只能使用单个Web部件,无法编辑其Web部件的属性并删除标题区域。下面的两张图片比较了我的表单,然后将其转换为应用程序页面(左),然后转换为应用程序页面(右):

如您所见,标题区域已删除。另外,如果我将页面切换到编辑模式,则无法删除Web部件,并且我看到的唯一选项与页面标题有关:

因此,现在您的表单中发生“意外”创作的可能性较小。如果该页面最初不是作为应用程序页面创建的,则可以一次性使用PowerShell或什至通过浏览器控制台中的一些快速JavaScript进行转换。查看更多详细信息- //docs.microsoft.com/en-us/sharepoint/dev/spfx/web-parts/single-part-app-pages。当然,您也可以根据需要删除左侧导航栏。

以这种形式使用PnP分类法选择器控件


我想在这里讨论的一个方面是PnP分类法选择器控件(这些表格的常见控件)中的一个怪癖。与该工具包中的许多其他工具一样,控件本身也非常出色,并且将是一项重大任务’自己写,如果你必须写的话。让’s all buy 埃里奥 下次我们再见他(另一种)啤酒时

分类选择器很容易添加到您的Web部件中,并使用您提供的术语集(按名称或ID)填充术语。典型的声明如下所示:

<TaxonomyPicker allowMultipleSelections = {false} termetNameOrID =“ b2a79b4b-9d64-46d9-8a94-38f8809f8d12”
 panelTitle =“选择地区”
  label=""
 initialValues = {this.state.selectedRegion}
 context = {this.props.context}
 onChange = {this._onRegionTaxPickerChange}
 isTermSetSelectable = {false} />

这样可以在您的页面上提供如下内容:

其他一些注意事项是:
  • 初始值–使用此属性来设置控件的值。因此,如果您的表单用于编辑现有列表项,请从数据中获取值并设置此属性– since I’m使用React,这完全来自我的Web部件状态中的值
  • onChange–选择术语时会发生什么。在React中,您’d通常此时将值存储在状态中,以备日后插入/更新到SharePoint
到目前为止,如此简单。但是,需要注意的是,onChange()方法以IPickerTerm对象的形式提供了该项–PnP代码提供的内容。但是,由于REST API要求使用其他格式,因此无法使用PnPJS或REST将此类对象传递给SharePoint。 IPickerTerm具有以下属性:
  • 名称
  • 路径
  • termSet
  • termSet Name
但是,PnPJS或SharePoint REST API期望具有以下属性的对象(这是针对单值分类法字段):
  • TermGuid
  • 标签
  • WssId
旁注-如果您的字段存储多个值,则情况会有些复杂。 Alex Terentiev对此发表了一篇文章 可能会帮助您。

那么你’如果您需要在两个对象类型之间进行一些映射’从PnP分类控件中将数据重新读/写到SharePoint(包括将控件的选定值设置为存储在SharePoint列表项中的当前值)。

这里要知道一些重要的事情:
  • 值-1可以用于WssId值– you don’无需再做任何其他操作,SharePoint将解决此问题
  • TermGuid 属性映射到IPickerTerm.key属性
  • 标签 属性映射到IPickerTerm.name属性
考虑到这一点,我们只需要一些代码即可在两种对象类型之间进行映射-我发现需要使用以下两种方法(在每个方向上进行转换):

概要


希望这篇文章对构建自定义SPFx表单时的注意事项有所帮助。我认为这种方法对于更复杂的表单非常有用,这里列出的构建基块确实有助于减少所需的代码量。将页面设置为应用程序页面可以消除不必要的页面修饰,这与与SharePoint列表UI集成以获得新的/编辑/显示体验一样有帮助。除了Office UI Fabric,PnP React控件在SPFx表单中都非常有用,TaxonomyPicker也不例外。如果使用该格式,您可能会发现需要像上面的示例一样的代码,以帮助您在控件使用的格式与SharePoint REST API或PnPJS使用的格式之间进行映射,但这并不太复杂。祝您编码愉快!