Migrieren von JSLink zu SharePoint-Framework-Erweiterungen

  • Artikel

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.

Konfiguration der JSLink-Eigenschaft im Listenansicht-Webpart

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.

Benutzerdefiniertes Rendern des Felds „Color“ in der benutzerdefinierten Liste

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

  1. Erstellen Sie in der Konsole einen neuen Ordnern für Ihr Projekt:

    md spfx-custom-field-extension

  2. Wechseln Sie zum Projektordner:

    cd spfx-custom-field-extension

  3. 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

  4. 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

  5. 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:

  1. Ö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.

  2. Ö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 vorherigen RenderColorField() Methode in der JSLink Implementierung. Die einzigen Unterschiede sind:

    • Um den aktuellen Feldwert abzurufen, müssen Sie die event.fieldValue-Eigenschaft des Eingabearguments der onRenderCell()-Methode lesen.
    • Um den benutzerdefinierten HTML-Code zum Rendern des Felds zurückzugeben, müssen Sie der innerHTML-Eigenschaft des event.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.

    Der in einer modernen Liste gerenderte Field Customizer

Testen der Lösung im Debugmodus

  1. 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

  2. Ö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.

  1. Ö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;
  }
}

  2. 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 untergeordneten DIV-Element des aktuellen Feldelements zusammen mit einer anderen CSS-Klasse zuweist, um die Zielfarbe von DIV basierend auf dem derzeit ausgewählten Feldwert zu definieren.

  3. 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

  1. Ö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 Feldtyp Choice, der das ClientSideComponentId-Attribut zum Verweisen auf die id des Field Customizer verwendet. Es könnte auch ein ClientSideComponentProperties-Attribut vorhanden sein, um die für die Erweiterung erforderlichen benutzerdefinierten Konfigurationseigenschaften zu konfigurieren.

  2. Ö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:

  1. 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

  2. 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

  3. 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

  1. Öffnen Sie den Browser, und navigieren Sie zu der gewünschten modernen Zielwebsite.

  2. Navigieren Sie zur Seite Websiteinhalte, und wählen Sie App, um eine neue App hinzuzufügen.

  3. Wählen Sie zum Installieren einer neuen App Von Ihrer Organisation aus, um die im App-Katalog verfügbaren Lösungen zu durchsuchen.

  4. Wählen Sie die Lösung mit dem Namen spfx-custom-field-extension-client-side-solution, und installieren Sie sie auf der Zielwebsite.

    Hinzufügen einer App-Benutzeroberfläche zum Hinzufügen der Lösung zu einer Website

  5. 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.

    Hinzufügen des Felds zur Liste

  6. Bearbeiten Sie das hinzugefügte Feld, und konfigurieren Sie einige Farbwerte (z. B. Red, Green, Blue, Yellow). Speichern Sie die Feldeinstellungen anschließend.

  7. 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.

    Der Field Customizer in Aktion

Sie können nun den Field Customizer nutzen, den Sie mit den SharePoint-Framework-Erweiterungen erstellt haben.

Siehe auch