Migrieren von JSLink zu SharePoint-Framework-Erweiterungen
Seit Microsoft SharePoint 2013 nutzen die meisten Unternehmenslösungen, die auf Microsoft 365 und SharePoint Online aufbauen, die JSLink
-Eigenschaft von Feldern und Listenansichten, um das Rendern von Feldern anzupassen.
Innerhalb der „modernen“ Benutzeroberfläche von SharePoint Online und SharePoint Server 2019 stehen die meisten dieser Anpassungen nicht mehr zur Verfügung. Mit den SharePoint-Framework-Erweiterungen können Sie jedoch fast die gleichen Funktionen auch in der „modernen“ Benutzeroberfläche bereitstellen.
In diesem Lernprogramm erfahren Sie, wie Sie die alten, klassischen Anpassungen zu dem neuen Modell basierend auf SharePoint-Framework-Erweiterungen migrieren können.
Hinweis
Weitere Informationen zum Erstellen von SharePoint-Framework-Erweiterungen finden Sie unter Übersicht über SharePoint-Framework-Erweiterungen.
Bei der Entwicklung von SharePoint-Framework-Erweiterungen sind folgende Optionen verfügbar:
- Application Customizer: Erweitert die native „moderne“ Benutzeroberfläche von SharePoint, indem benutzerdefinierte HTML-Elemente und clientseitiger Code den vordefinierten Platzhaltern der „modernen“ Seiten hinzugefügt werden. Weitere Informationen zu Anwendungsanpassungen finden Sie unter Erstellen Ihrer ersten SharePoint-Framework-Erweiterung (Hello World, Teil 1).
- Command Set: Fügt benutzerdefinierte ECB-Menüelemente (Edit Control Block) oder benutzerdefinierte Schaltflächen zur Befehlsleiste einer Listenansicht für eine Liste oder Bibliothek hinzu. Sie können diesen Befehlen eine beliebige clientseitige Aktion zuordnen. Weitere Informationen zu Befehlssätzen finden Sie unter Erstellen Ihrer ersten Erweiterung des Typs „ListView Command Set“.
- Field Customizer: Passt das Rendering eines Felds in einer Listenansicht mit benutzerdefinierten HTML-Elementen und clientseitigem Code an. Weitere Informationen zu Feldanpassungen finden Sie unter Erstellen Ihrer ersten Field Customizer-Erweiterung.
Die nützlichste Option in diesem Kontext ist die Erweiterung „Field Customizer“.
Angenommen, Sie befinden sich in SharePoint Online und verfügen über eine benutzerdefinierte Liste mit einem benutzerdefinierten Feld namens "Color", das vom Typ Choice ist und die folgenden Werte annehmen kann: Rot, Grün, Blau, Gelb. Angenommen, Sie verfügen über einen benutzerdefinierten Wert für die JSLink
Eigenschaft des Listenansichts-Rendering-Webparts der benutzerdefinierten Liste.
Im folgenden Codeausschnitt sehen Sie den JavaScript-Code, der von der JSLink
-Eigenschaft (customColorRendering.js) referenziert wird.
// Define a namespace for the custom rendering code
var customJSLinkRendering = customJSLinkRendering || {};
// Define a function that declare the custom rendering rules for the target list view
customJSLinkRendering.CustomizeFieldRendering = function () {
// Define a custom object to configure the rendering template overrides
var customRenderingOverride = {};
customRenderingOverride.Templates = {};
customRenderingOverride.Templates.Fields =
{
// Declare the custom rendering function for the 'View' of field 'Color'
'Color':
{
'View': customJSLinkRendering.RenderColorField
}
};
// Register the custom rendering template
SPClientTemplates.TemplateManager.RegisterTemplateOverrides(customRenderingOverride);
};
// Declare the custom rendering function for the 'View' of field 'Color'
customJSLinkRendering.RenderColorField = function (context)
{
var colorField = context.CurrentItem.Color;
// Declare a local variable to hold the output color
var color = '';
// Evaluate the values of the 'Color' field and render it accordingly
switch (colorField)
{
case 'Red':
color = 'red';
break;
case 'Green':
color = 'green';
break;
case 'Blue':
color = 'blue';
break;
case 'Yellow':
color = 'yellow';
break;
default:
color = 'white';
break;
}
// Render the output for the 'Color' field
return "<div style='float: left; width: 20px; height: 20px; margin: 5px; border: 1px solid rgba(0,0,0,.2);background:" + color + "' />";
};
// Invoke the custom rendering function
customJSLinkRendering.CustomizeFieldRendering();
Im folgenden Screenshot sehen Sie, wie die JSLink
-Eigenschaft im Listenansicht-Webpart konfiguriert ist.
Wenn Sie die JavaScript-Datei in die Bibliothek Site Assets hochgeladen haben, kann der Wert für die JSLink
-Eigenschaft "~site/SiteAssets/customColorRendering.js"
lauten.
Sie können erkennen, wie das benutzerdefinierte Rendern der Liste funktioniert.
Wie Sie sehen können, rendern Color-Felder ein farbiges Feld mit der ausgewählten Farbe auf der Elementebene.
Hinweis
Um diese Art von Lösung für eine „klassische“ Website bereitstellen zu können, können Sie letztendlich eine PnP-Bereitstellungsvorlage verwenden, die sowohl die Liste mit dem benutzerdefinierten Feld als auch gleichzeitig die JSLink
-Eigenschaft bereitstellen kann.
Zum Migrieren der vorherigen Lösung zum SharePoint-Framework führen Sie die folgenden Schritte aus.
Erstellen einer neuen SharePoint-Framework-Lösung
Erstellen Sie in der Konsole einen neuen Ordnern für Ihr Projekt:
md spfx-custom-field-extension
Wechseln Sie zum Projektordner:
cd spfx-custom-field-extension
Führen Sie im Projektordner den SharePoint Framework-Yeoman-Generator aus, um ein Gerüst für ein neues SharePoint Framework-Projekt zu erstellen:
yo @microsoft/sharepoint
Wenn Sie dazu aufgefordert werden, geben Sie die folgenden Werte ein (wählen Sie für alle unten nicht aufgeführten Eingabeaufforderungen die Standardoption aus):
- Wie lautet der Name Ihrer Lösung?: spfx-custom-field-extension
- Welchen Typ von clientseitiger Komponente möchten Sie erstellen?: Erweiterung
- Welchen Typ von clientseitiger Erweiterung möchten Sie erstellen? Field Customizer
- Wie heißt Ihr Field Customizer? CustomColorField
- Welche Vorlage möchten Sie verwenden?: Kein JavaScript-Framework
Starten Sie Visual Studio Code (oder den Code-Editor Ihrer Wahl), und beginnen Sie, die Lösung zu entwickeln. Zum Starten von Visual Studio Code können Sie die folgende Anweisung ausführen.
code .
Definieren des neuen Field Customizer mit JavaScript
Um das gleiche Verhalten des JSLink
benutzerdefinierten Feldrenderings zu reproduzieren, müssen Sie dieselbe Logik mithilfe von clientseitigem Code innerhalb der neuen SharePoint-Framework-Lösung implementieren. Gehen Sie hierzu wie folgt vor:
Öffnen Sie die Datei ./src/extensions/customColorField/CustomColorFieldFieldCustomizer.manifest.json. Kopieren Sie den Wert der Eigenschaft
id
, und bewahren Sie ihn an einem sicheren Ort auf, da Sie ihn später benötigen.Öffnen Sie die Datei ./src/extensions/customColorField/CustomColorFieldFieldCustomizer.ts, und bearbeiten Sie den Inhalt entsprechend dem folgenden Codeausschnitt:
import { Log } from '@microsoft/sp-core-library'; import { override } from '@microsoft/decorators'; import { BaseFieldCustomizer, IFieldCustomizerCellEventParameters } from '@microsoft/sp-listview-extensibility'; import * as strings from 'CustomColorFieldFieldCustomizerStrings'; import styles from './CustomColorFieldFieldCustomizer.module.scss'; /** * If your field customizer uses the ClientSideComponentProperties JSON input, * it will be deserialized into the BaseExtension.properties object. * You can define an interface to describe it. */ export interface ICustomColorFieldFieldCustomizerProperties { // This is an example; replace with your own property sampleText?: string; } const LOG_SOURCE: string = 'CustomColorFieldFieldCustomizer'; export default class CustomColorFieldFieldCustomizer extends BaseFieldCustomizer<ICustomColorFieldFieldCustomizerProperties> { @override public onInit(): Promise<void> { // Add your custom initialization to this method. The framework will wait // for the returned promise to resolve before firing any BaseFieldCustomizer events. Log.info(LOG_SOURCE, 'Activated CustomColorFieldFieldCustomizer with properties:'); Log.info(LOG_SOURCE, JSON.stringify(this.properties, undefined, 2)); Log.info(LOG_SOURCE, `The following string should be equal: "CustomColorFieldFieldCustomizer" and "${strings.Title}"`); return Promise.resolve(); } @override public onRenderCell(event: IFieldCustomizerCellEventParameters): void { var colorField = event.fieldValue; // Declare a local variable to hold the output color var color = ''; // Evaluate the values of the 'Color' field and render it accordingly switch (colorField) { case 'Red': color = 'red'; break; case 'Green': color = 'green'; break; case 'Blue': color = 'blue'; break; case 'Yellow': color = 'yellow'; break; default: color = 'white'; break; } // Render the output for the 'Color' field event.domElement.innerHTML = "<div style='float: left; width: 20px; height: 20px; margin: 5px; border: 1px solid rgba(0,0,0,.2);background:" + color + "' />"; } @override public onDisposeCell(event: IFieldCustomizerCellEventParameters): void { // This method should be used to free any resources that were allocated during rendering. // For example, if your onRenderCell() called ReactDOM.render(), then you should // call ReactDOM.unmountComponentAtNode() here. super.onDisposeCell(event); } }
Wie Sie sehen können, ist der Inhalt der Methode
onRenderCell()
fast identisch mit der vorherigenRenderColorField()
Methode in derJSLink
Implementierung. Die einzigen Unterschiede sind:- Um den aktuellen Feldwert abzurufen, müssen Sie die
event.fieldValue
-Eigenschaft des Eingabearguments deronRenderCell()
-Methode lesen. - Um den benutzerdefinierten HTML-Code zum Rendern des Felds zurückzugeben, müssen Sie der
innerHTML
-Eigenschaft desevent.domElement
-Objekts einen Wert zuweisen, der den Ausgabe-HTML-Container des Feldrenderings darstellt.
Abgesehen von diesen geringfügigen Änderungen können Sie fast den gesamten JavaScript-Code wie zuvor verwenden.
In der folgenden Abbildung ist die resultierende Ausgabe enthalten.
- Um den aktuellen Feldwert abzurufen, müssen Sie die
Testen der Lösung im Debugmodus
Kehren Sie zum Konsolenfenster zurück, und führen Sie den folgenden Befehl aus, um die Lösung zu erstellen und den lokalen Node.js-Server zum Hosten der Lösung auszuführen.
gulp serve --nobrowser
Öffnen Sie Ihren bevorzugten Browser, und wechseln Sie zu einer "modernen" Liste mit einem benutzerdefinierten Feld mit dem Namen Farbe und dem Typ Auswahl mit den gleichen Wertoptionen wie zuvor (Rot, Grün, Blau, Gelb). Sie können schließlich die Liste verwenden, die Sie auf der "klassischen" Website erstellt haben, und sie nur mit der neuen "modernen" Benutzeroberfläche anzeigen. Fügen Sie nun die folgenden Abfragezeichenfolgenparameter an die Url der Seite "AllItems.aspx " an.
?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={"Color":{"id":"c3070978-d85e-4298-8758-70b5b5933076"}}
In dieser Abfragezeichenfolge müssen Sie die GUID durch den
id
-Wert aus der Datei CustomColorFieldFieldCustomizer.manifest.json ersetzen, den Sie zuvor gespeichert oder notiert haben. Der Color-Eigenschaftenname bezieht sich auf das anzupassende Feld. Wenn Sie möchten, können Sie auch ein benutzerdefiniertes Konfigurationsobjekt, das im JSON-Format serialisiert ist, als einen zusätzlichen Parameter für die Field Customizer-Konstruktion bereitstellen.Beachten Sie, dass Beim Ausführen der Seitenanforderung ein Warnmeldungsfeld mit dem Titel "Debugskripts zulassen?" angezeigt wird, in dem Sie aus Sicherheitsgründen Ihre Zustimmung zum Ausführen von Code von localhost anfordern. Wenn Sie die Projektmappe lokal debuggen und testen möchten, müssen Sie ihr das Laden von Debugskripts erlauben.
Hinweis
Alternativ können Sie Serverkonfigurationseinträge in der Datei config/serve.json in Ihrem Projekt erstellen, um das Erstellen der Abfragezeichenfolgenparameter zum Debuggen zu automatisieren, wie in diesem Dokument beschrieben: Debuggen von SharePoint-Framework-Lösungen auf modernen SharePoint-Seiten
Definieren des neuen Field Customizer mit TypeScript
Sie können nun den JavaScript-Code durch TypeScript ersetzen, um den vollständig typisierten Ansatz von TypeScript nutzen zu können.
Öffnen Sie die Datei ./src/extensions/customColorField/CustomColorFieldFieldCustomizer.module.scss. Diese Datei, eine Sass CSS, stellt die Formatvorlage der Benutzeroberfläche für den Field Customizer dar. Ersetzen Sie den Inhalt der SCSS-Datei durch den folgenden.
.CustomColorField { .cell { float: left; width: 20px; height: 20px; margin: 5px; border: 1px solid rgba(0,0,0,.2); } .cellRed { background: red; } .cellGreen { background: green; } .cellBlue { background: blue; } .cellYellow { background: yellow; } .cellWhite { background: white; } }
Ersetzen Sie die Implementierung der
onRenderCell()
-Methode durch den folgenden Codeauszug.@override public onRenderCell(event: IFieldCustomizerCellEventParameters): void { // Read the current field value let colorField: String = event.fieldValue; // Add the main style to the field container element event.domElement.classList.add(styles.CustomColorField); // Get a reference to the output HTML let fieldHtml: HTMLDivElement = event.domElement.firstChild as HTMLDivElement; // Add the standard style fieldHtml.classList.add(styles.cell); // Add the colored style switch(colorField) { case "Red": fieldHtml.classList.add(styles.cellRed); break; case "Green": fieldHtml.classList.add(styles.cellGreen); break; case "Blue": fieldHtml.classList.add(styles.cellBlue); break; case "Yellow": fieldHtml.classList.add(styles.cellYellow); break; default: fieldHtml.classList.add(styles.cellWhite); break; } }
Beachten Sie, dass die neue Methodenimplementierung einen vollständig typisierten Ansatz verwendet und die CSS-Klasse
cell
dem untergeordnetenDIV
-Element des aktuellen Feldelements zusammen mit einer anderen CSS-Klasse zuweist, um die Zielfarbe vonDIV
basierend auf dem derzeit ausgewählten Feldwert zu definieren.Führen Sie den Field Customizer noch einmal im Debugmodus aus, und sehen Sie sich die Ergebnisse an.
Packen und Hosten der Lösung
Wenn Sie mit dem Ergebnis zufrieden sind, können Sie die Lösung nun packen und in der eigentlichen Hostinginfrastruktur hosten. Bevor Sie das Bundle und das Paket erstellen, müssen Sie eine XML-Feature-Framework-Datei deklarieren, um die Erweiterung bereitzustellen.
Überprüfen von Feature-Framework-Elementen
Öffnen Sie im Code-Editor die Datei ./sharepoint/assets/elements.xml. Der folgende Codeauszug gibt an, wie die Datei aussehen sollte.
<?xml version="1.0" encoding="utf-8"?> <Elements xmlns="http://schemas.microsoft.com/sharepoint/"> <Field ID="{40475661-efaf-447a-a220-c992b20ec1c3}" Name="SPFxColor" DisplayName="Color" Title="Color" Type="Choice" Required="FALSE" Group="SPFx Columns" ClientSideComponentId="c3070978-d85e-4298-8758-70b5b5933076"> </Field> </Elements>
Wie Sie sehen, ähnelt sie der SharePoint-Feature-Framework-Datei. Sie definiert jedoch ein benutzerdefiniertes
Field
-Element mit dem FeldtypChoice
, der dasClientSideComponentId
-Attribut zum Verweisen auf dieid
des Field Customizer verwendet. Es könnte auch einClientSideComponentProperties
-Attribut vorhanden sein, um die für die Erweiterung erforderlichen benutzerdefinierten Konfigurationseigenschaften zu konfigurieren.Öffnen Sie die Datei ./config/package-solution.json. In der Datei können Sie sehen, dass ein Verweis auf die Datei elements.xml im Abschnitt
assets
vorhanden ist.{ "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json", "solution": { "name": "spfx-custom-field-extension-client-side-solution", "id": "ab0fbbf8-01ba-4633-8498-46cfd5652619", "version": "1.0.0.0", "features": [{ "title": "Application Extension - Deployment of custom action.", "description": "Deploys a custom action with ClientSideComponentId association", "id": "090dc976-878d-44fe-8f8e-ac603d094aa1", "version": "1.0.0.0", "assets": { "elementManifests": [ "elements.xml" ] } }] }, "paths": { "zippedPackage": "solution/spfx-custom-field-extension.sppkg" } }
Bündeln, Packen und Bereitstellen der Lösung
Als Nächstes müssen Sie das Lösungsbundle im App-Katalog bündeln und packen. Um diese Aufgabe auszuführen, gehen Sie folgendermaßen vor.
Vorbereiten und Bereitstellen der Lösung für den SharePoint Online-Mandanten:
Führen Sie die folgende Aufgabe aus, um Ihre Lösung in einem Bundle zu packen. Dadurch wird ein Releasebuild Ihres Projekts erstellt:
gulp bundle --ship
Führen Sie die folgende Aufgaben aus, um Ihre Lösung zu packen. Dieser Befehl erstellt ein *.sppkg-Paket im Ordner sharepoint/solution .
gulp package-solution --ship
Laden Sie das neu erstellte Paket mit ihrer clientseitigen Lösung in den App-Katalog in Ihrem Mandanten hoch. Alternativ können Sie es auch per Drag-and-Drop verschieben. Klicken Sie dann auf die Schaltfläche Bereitstellen.
Installieren und Ausführen der Lösung
Öffnen Sie den Browser, und navigieren Sie zu der gewünschten modernen Zielwebsite.
Navigieren Sie zur Seite Websiteinhalte, und wählen Sie App, um eine neue App hinzuzufügen.
Wählen Sie zum Installieren einer neuen App Von Ihrer Organisation aus, um die im App-Katalog verfügbaren Lösungen zu durchsuchen.
Wählen Sie die Lösung mit dem Namen spfx-custom-field-extension-client-side-solution, und installieren Sie sie auf der Zielwebsite.
Nachdem die Anwendung installiert wurde, erstellen Sie eine neue benutzerdefinierte Liste, bearbeiten Sie die Listeneinstellungen, und fügen Sie eine neue Spalte aus den bereits vorhandenen Websitespalten hinzu. Wählen Sie die Spaltengruppe SPFx Columns, und fügen Sie das Feld Color hinzu.
Bearbeiten Sie das hinzugefügte Feld, und konfigurieren Sie einige Farbwerte (z. B. Red, Green, Blue, Yellow). Speichern Sie die Feldeinstellungen anschließend.
Fügen Sie der Liste einige Elemente hinzu, und sehen Sie sich die Ausgabe in der Listenansicht an. Sie sollte in etwa wie im folgenden Screenshot aussehen.
Sie können nun den Field Customizer nutzen, den Sie mit den SharePoint-Framework-Erweiterungen erstellt haben.