編輯

共用方式為

Modernize customizations

  • 發行項

Important

Modernization tooling and all other PnP components are open-source tools backed by an active community providing support for them. There is no SLA for open-source tool support from official Microsoft support channels.

An important aspect when modernizing a site is understanding the customizations used on that site because not all existing customizations continue to work after the site is modernized. A classic example that occurs frequently is a site banner that shows some type of company information (such as a legal notice).

This typically is realized via a user custom action that embeds JavaScript on the page, which in turn is responsible for showing the banner. This banner is visible on all classic pages, but will not be visible on modern pages. To work around this problem, you can implement the banner as a SharePoint Framework Application Customizer extension and deploy that to the tenant/site.

This article gives an overview of the customizations that are not compatible with the modern user interface and guidelines on how to remediate them.

Customizations in lists and libraries

This section focuses on customizations that you might have implemented in your lists and libraries. SharePoint automatically falls back to the classic list and library user interface when it detects an incompatible customization. Therefore, it's important to address these customizations if you want to get a 100% modern experience.

To get an understanding of the modern user interface compatibility of your lists and libraries, use the SharePoint Modernization scanner.

A very common model to control how a field is represented in the SharePoint user interface is by using JSLink. Essentially, JSLink allows you to plug in JavaScript, which then takes over the rendering of the field. In the modern user interface, similar customization capabilities are available for the list view pages, although customizing the list edit pane currently is not possible.

If you're replacing JSLink, you can consider two alternative approaches; which one works best depends on the complexity of the existing solution:

  • If it's merely about how to display the data, using column formatting is often the best choice.
  • If more behavior is needed, using a SharePoint Framework Field Customizer extension is often the best choice.

Use column formatting

You can use column formatting to customize how fields in SharePoint lists and libraries are displayed. To do this, you construct a JSON object that describes the elements that are displayed when a field is included in a list view, and the styles to be applied to those elements. The column formatting does not change the data in the list item or file; it only changes how it’s displayed to users who browse the list. Anyone who can create and manage views in a list can use column formatting to configure how view fields are displayed.

For example, a list with the fields Title, Effort, Assigned To, and Status with no customizations applied might look like this:


Before column formatter


A list with the appearance of the Effort, Assigned To, and Status fields customized via column formatting might look like this:


After column formatter


To learn more about column formatting, see:

Use SharePoint Framework Field Customizer extension

SharePoint Framework Extensions enable you to extend the SharePoint user experience within modern pages and document libraries, while using the familiar SharePoint Framework tools and libraries for development. Specifically, Field Customizers allow you to fully control how field data is presented in your list or library views.

Following is an example of a percent column.

Field customizer

To learn more about SharePoint Framework Field Customizer extensions, see:

List-scoped user custom actions that add custom menu options or embed JavaScript

Using a list-scoped user custom action that adds custom menu options in the list ribbon or context menu or embeds JavaScript is, next to JSLink, a very common customization pattern that does not work anymore for the modern list and library experience. Fortunately, by using SharePoint Framework Extensions, you can realize similar customizations, in particular via command set extensions that allow you to add custom Edit Control Block (ECB) menu items or custom buttons to the command bar of a list or library. You can associate any JavaScript (TypeScript) action to these commands.


List view command set

To learn more about SharePoint Framework ListView Command Set extensions, see:

Customizations on pages

SharePoint has multiple flavors of classic site pages such as wiki pages, web part pages, and publishing pages. Each of these pages allow the user to customize them by adding web parts and (formatted) text or by embedding JavaScript via user custom actions. This section gives an overview of the existing customization models and how these can be replaced by modern compatible options.

Out-of-the-box classic web parts

SharePoint has many out-of-the-box web parts (including the script editor web part) that work on classic pages but not on modern pages (that is, there's no out-of-the-box modern equivalent). There's also a set of modern, first-party, modern web parts available that offer similar functionality for some of the classic web parts; however, there's no feature parity.

If you need the functionality of a classic web part as a modern equivalent, you must either roll your own version based on the SharePoint Framework or alternatively consume a web part from the large list of open source SharePoint Framework web parts, which you can find in the sp-dev-fx-webparts GitHub repository.

Following is a diagram showing a sample web part.

SPFX web part sample

To learn more about SharePoint Framework web parts, see:

Site or web-scoped user custom actions that embed JavaScript

In the introduction, we mentioned the common pattern of adding a site banner by embedding JavaScript via a site/web-scoped user custom action. Because this pattern is not compatible with the modern user interface, you must rework this type of customization based upon the SharePoint Framework Application Customizer extensions. By using application customizers, you can insert custom script that can be used to embed HTML into the SharePoint modern user interface at predefined extension points at the top or bottom of the page.


SPFX Application Customizer sample


To learn more about SharePoint Framework Application Customizer extensions, see:

Custom menu items in the site actions menu

Currently it's not possible to add your own custom menu items to the site actions menu (the gear icon) on modern pages. Alternative strategies you can follow are adding the needed links into the site's navigation or by adding the needed links on the site's home page.

See also