Freigeben über

Erstellen Ihrer ersten Field Customizer-Erweiterung

  • Artikel

Erweiterungen sind clientseitige Komponenten, die im Kontext einer SharePoint-Website ausgeführt werden. Erweiterungen lassen sich auf SharePoint Online bereitstellen und auch mithilfe aktueller JavaScript-Tools und -Bibliotheken erstellen.

Sie können diese Schritte ausführen, indem Sie sich das Video auf dem YouTube-Kanal der Microsoft 365 Platform Communtiy (PnP) ansehen:

Erstellen eines Erweiterungsprojekts

  1. Erstellen Sie an einem Speicherort Ihrer Wahl ein neues Projektverzeichnis:

    md field-extension

  2. Wechseln Sie in das Projektverzeichnis:

    cd field-extension

  3. Führen Sie den Yeoman-SharePoint-Generator aus, um eine neue HelloWorld-Erweiterung 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 ihr Lösungsname?: Felderweiterung
    • 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? HelloWorld
    • Welche Vorlage möchten Sie verwenden?: Kein JavaScript-Framework

    An diesem Punkt installiert Yeoman die erforderlichen Abhängigkeiten und erstellt ein Gerüst für die Lösungsdateien sowie die HelloWorld-Erweiterung. Das kann einige Minuten dauern.

  5. Geben Sie Folgendes in die Konsole ein, um Visual Studio Code zu starten.

    code .

    Hinweis

    Da die clientseitige SharePoint-Lösung auf HTML/TypeScript basiert, können Sie zur Erstellung Ihrer Erweiterung jeden Code-Editor verwenden, der clientseitige Entwicklung unterstützt.

  6. Öffnen Sie die Datei ./src/extensions/helloWorld/HelloWorldFieldCustomizer.manifest.json .

    Diese Datei definiert den Erweiterungstyp und eine eindeutige id für die Erweiterung. Sie benötigen diese eindeutige ID später beim Debuggen und Bereitstellen der Erweiterung in SharePoint.

Codieren des Field Customizers

Öffnen Sie die Datei ./src/extensions/helloWorld/HelloWorldFieldCustomizer.ts .

Beachten Sie, dass die Basisklasse für den Field Customizer aus dem sp-listview-extensibility-Paket importiert wird, das den SharePoint-Frameworkcode enthält, der für den Field Customizer erforderlich ist.

import { Log } from '@microsoft/sp-core-library';
import { override } from '@microsoft/decorators';
import {
  BaseFieldCustomizer,
  IFieldCustomizerCellEventParameters
} from '@microsoft/sp-listview-extensibility';

Die Logik für Den Field Customizer ist in den onInit()Methoden , onRenderCell()und onDisposeCell() enthalten.

  • onInit() ist der Ort, an dem Sie das setup ausführen, das für Ihre Erweiterung erforderlich ist. Dieses Ereignis tritt auf, nachdem this.context und this.properties zugewiesen wurden, jedoch bevor das Seiten-DOM bereit ist. Wie bei Webparts gibt eine Zusage zurück, die Sie für asynchrone Vorgänge verwenden können. onRenderCell() Wird erst aufgerufen, onInit() wenn Ihre Zusage aufgelöst wurde. Wenn Sie dies nicht benötigen, geben Sie einfach Promise.resolve<void>(); zurück.
  • onRenderCell() tritt auf, wenn jede Zelle gerendert wird. Die Methode bietet ein event.domElement-HTML-Element, in das der Code den Inhalt schreiben kann.
  • onDisposeCell() tritt unmittelbar vor dem Löschen von event.cellDiv ein. Die Methode kann zum Freigeben von Ressourcen verwendet werden, die beim Feldrendering zugeordnet wurden. Wenn onRenderCell() ein React-Element bereitgestellt hat, muss onDisposeCell() zum Freigeben verwendet werden; anderenfalls würde ein Ressourcenverlust auftreten.

Im Folgenden sind die Inhalte von onRenderCell() und onDisposeCell() in der Standardlösung aufgeführt:

@override
public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
  // Use this method to perform your custom cell rendering.
  const text: string = `${this.properties.sampleText}: ${event.fieldValue}`;

  event.domElement.innerText = text;

  event.domElement.classList.add(styles.cell);
}

@override
public onDisposeCell(event: IFieldCustomizerCellEventParameters): void {
  super.onDisposeCell(event);
}

Debuggen des Field Customizers

SharePoint-Framework-Erweiterungen können nicht mit der lokalen Workbench getestet werden. Sie müssen sie direkt mit einer SharePoint Online-Live-Website testen und bereitstellen. Hierzu ist es nicht erforderlich, die Anpassung im App-Katalog bereitzustellen, was das Debugging vereinfacht und beschleunigt.

  1. Um Ihre Erweiterung zu testen, müssen Sie zuerst das Feld erstellen, in dem der Customizer getestet wird. Navigieren Sie zu der Seite in Ihrem SharePoint Online-Mandanten, in dem Sie das Feld Customizer testen möchten.

  2. Navigieren Sie zur Seite Websiteinhalte.

  3. Wählen Sie auf der Symbolleiste Neu, und wählen Sie dann Liste.

    Erstellen einer neuen Liste

  4. Erstellen Sie eine neue Liste mit dem Namen Bestellungen, und klicken Sie auf Erstellen.

    Erstellen einer neuen Liste mit dem Namen „Bestellungen“

  5. Wählen Sie das + Zeichen und dann Zahl aus, um ein neues Zahlenfeld für die Liste zu erstellen.

    Erstellen eines neuen Zahlenfelds

  6. Legen Sie den Namen des Felds auf Prozent fest, und wählen Sie dann Speichern.

    Erstellen eines neuen Felds mit der Bezeichnung „Prozent“

  7. Fügen Sie im Prozentfeld einige Elemente mit unterschiedlichen Zahlen hinzu. Wir ändern das Rendering später in diesem Tutorial, sodass die verschiedenen Zahlen basierend auf Ihrer benutzerdefinierten Implementierung unterschiedlich dargestellt werden.

    Erstellen von Elementen in der neuen Liste mit verschiedenen Werten im Feld „Prozent“

  8. Öffnen Sie in Visual Studio Code die Datei ./config/serve.json .

    Legen Sie das InternalFieldName Attribut für den Feldnamen, den wir erstellt haben, auf Percent fest. Aktualisieren Sie die pageUrl Attribute so, dass sie mit einer URL der Liste übereinstimmen, die wir in den Vorschauschritten erstellt haben. Nach den Änderungen sollte Ihre "serve.json"- Datei wie der folgende Code aussehen:

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/spfx-serve.schema.json",
  "port": 4321,
  "https": true,
  "serveConfigurations": {
    "default": {
      "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx",
      "fieldCustomizers": {
        "Percent": {
          "id": "b909e395-f714-421f-94e0-d638dafeb210",
            "properties": {
            "sampleText": "Value"
          }
        }
      }
    },
    "helloWorld": {
      "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx",
      "fieldCustomizers": {
        "Percent": {
          "id": "b909e395-f714-421f-94e0-d638dafeb210",
          "properties": {
            "sampleText": "Value"
          }
        }
      }
    }
  }
}

    Hinweis

    Die GUID im obigen JSON-Auszug ist die eindeutige ID der SPFx-Erweiterungskomponente. Dies ist im Manifest der Komponente definiert. Die GUID in Ihrer Lösung unterscheidet sich von einer eindeutigen Komponenten-ID.

  9. Zunächst führen Sie den folgenden Befehl aus, um den Code zu kompilieren und die Dateien auf Ihrem lokalen Computer zu hosten:

    gulp serve

    Wenn der Code ohne Fehler kompiliert wurde, verarbeitet er das resultierende Manifest von https://localhost:4321.

    gulp serve

    Dadurch wird Ihr Standardbrowser gestartet und die in der Datei serve.json definierte Seite geladen.

  10. Klicken Sie bei Aufforderung auf Debugskripts laden, um das Laden der Debugmanifeste zu akzeptieren.

    Akzeptieren des Ladens der Debugskripte

    Beachten Sie, dass die Prozentspaltenwerte jetzt mit einer zusätzlichen Präfixzeichenfolge als Value:angezeigt werden, die als Eigenschaft für den Field Customizer bereitgestellt wird.

    Listenansicht mit für das Prozentfeld gerendertem Field Customizer

Verbessern der Darstellung des Field Customizer

Nachdem wir nun erfolgreich den sofort einsatzbereiten Startpunkt des Field Customizers getestet haben, ändern wir die Logik geringfügig, um eine ansprechendere Darstellung des Feldwerts zu erhalten.

  1. Öffnen Sie die Datei ./src/extensions/helloWorld/HelloWorldFieldCustomizer.module.scss , und aktualisieren Sie die Formatdefinition wie folgt.

    .HelloWorld {
  .cell {
    display: inline-block;
  }
  .full {
    background-color: #e5e5e5;
    width: 100px;
  }
}

  2. Öffnen Sie die Datei ./src/extensions/helloWorld/HelloWorldFieldCustomizer.ts , und aktualisieren Sie die onRenderCell() -Methode wie folgt.

    @override
public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
  event.domElement.classList.add(styles.cell);
  event.domElement.innerHTML = `
    <div class='${styles.HelloWorld}'>
        <div class='${styles.full}'>
        <div style='width: ${event.fieldValue}px; background:#0094ff; color:#c0c0c0'>
            &nbsp; ${event.fieldValue}
        </div>
        </div>
    </div>`;
}

  3. Stellen Sie im Konsolenfenster sicher, dass keine Fehler auftreten. Wenn die Lösung nicht ausgeführt wird, führen Sie die folgende Aufgabe aus:

    gulp serve

  4. Aktualisieren Sie in Ihrer zuvor erstellten Liste das Browserfenster mit den Debugabfrageparametern, oder starten Sie den Browser mit gulp serve neu.

  5. Klicken Sie bei Aufforderung auf Debugskripts laden, um das Laden der Debugmanifeste zu akzeptieren.

    Akzeptieren des Ladens der Debugskripte

    Beachten Sie, dass sich die Felddarstellung komplett geändert hat. Der Feldwert wird grafisch dargestellt.

    Grafische Darstellung der Prozentwerte

Hinzufügen der Felddefinition zum Lösungspaket für die Bereitstellung

Nachdem wir unsere Lösung nun ordnungsgemäß im Debugmodus getestet haben, können wir dies so packen, dass es automatisch als Teil des Lösungspakets bereitgestellt wird, das auf den Standorten bereitgestellt wird.

  1. Installieren Sie das Lösungspaket an dem Standort, an dem es installiert werden soll, damit das Erweiterungsmanifest für die Ausführung eingeschlossen wird.

  2. Ordnen Sie den Field Customizer einem vorhandenen Feld in der Website zu. Sie können dies programmgesteuert mithilfe der SharePoint-REST- oder CSOM-API oder mithilfe des Featureframeworks im SharePoint-Framework Lösungspakets tun. In diesem Tutorial verwenden wir die XML-Dateien des Feature Frameworks. Sie müssen die folgenden Eigenschaften im SPField-Objekt auf der Website- oder Listenebene zuweisen.

    • ClientSideComponentId: Dies ist der Bezeichner (GUID) des Field Customizer, der im App-Katalog installiert wurde.
    • ClientSideComponentProperties: Dies ist ein optionaler Parameter, der verwendet werden kann, um Eigenschaften für die Field Customizer-Instanz bereitzustellen.

    Sie können die Anforderung zum Hinzufügen einer Lösung, die Ihre Erweiterung enthält, mit der -Eigenschaft in der skipFeatureDeployment Datei ./config/package-solution.json steuern. Auch wenn Die Lösung nicht auf der Website installiert sein muss, müssen Sie bestimmte Objekte zuordnen ClientSideComponentId , damit die Erweiterung sichtbar ist.

    Sie können beispielsweise das Cmdlet Set-PnPField aus PnP PowerShell-Cmdlets verwenden, um vorhandene Felder in Ihren Websites programmgesteuert eine Erweiterung zuzuordnen.

    Hinweis

    PnP PowerShell ist eine Open Source-Lösung mit aktiver Community, die Support dafür bietet. Es gibt keine SLA für den Support des Open-Source-Tools durch Microsoft.

Prüfen der Datei „elements.xml“

In den folgenden Schritten prüfen wir die Standardfelddefinition, die automatisch erstellt und mit den erforderlichen Konfigurationen bereitgestellt wird, sobald das Lösungspaket auf einer Website installiert wird.

  1. Wechseln Sie wieder zu Ihrer Lösung in Visual Studio Code (oder Ihrem bevorzugten Editor).

  2. Öffnen Sie die Datei ./sharepoint/assets/elements.xml.

    Ordner „assets“ in der Lösungsstruktur

Sehen Sie sich den XML-Code in dieser Datei an. Die ClientSideComponentId Eigenschaft wurde automatisch auf die eindeutige ID Ihres Field Customizers aktualisiert, die in der Datei ./src/extensions/helloWorld/HelloWorldFieldCustomizer.manifest.json verfügbar ist. Sie müssen diesen Dateiabgleich für Ihren Feldtyp und die Details anpassen.

Hinweis

Weitere Informationen zum XML-Schema des FeatureFrameworks finden Sie unter SharePoint-Schemareferenz.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Field ID="{060E50AC-E9C1-3D3C-B1F9-DE0BCAC200F6}"
          Name="SPFxPercentage"
          DisplayName="Percentage"
          Type="Number"
          Min="0"
          Required="FALSE"
          Group="SPFx Columns"
          ClientSideComponentId="7e7a4262-d02b-49bf-bfcb-e6ef1716aaef">
  </Field>
</Elements>

Gewährleisten der Berücksichtigung von Definitionen in der Buildpipeline

Öffnen Sie die Datei ./config/package-solution.json.

Die Datei package-solution.json definiert die Paketmetadaten, wie im folgenden Code dargestellt. Um sicherzustellen, dass die elements.xml-Datei berücksichtigt wird, während das Lösungspaket erstellt wird, wird das Standardgerüst dieser Datei aktualisiert, um zusätzliche Details für eine Featuredefinition einzuschließen. Diese Featuredefinition wird verwendet, um die elements.xml-Datei bereitzustellen und auszuführen.

Beachten Sie außerdem, dass das includeClientSideAssets -Attribut auf truefestgelegt ist. Dies bedeutet, dass die JavaScript-Ressourcen in der Datei *.sppkg enthalten sind:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "field-extension-client-side-solution",
    "id": "80c04d1b-dca7-4d0a-86c0-9aedf904704f",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "isDomainIsolated": false,
    "features": [
      {
        "title": "Application Extension - Deployment of custom action.",
        "description": "Deploys a custom action with ClientSideComponentId association",
        "id": "b27507b9-7c2a-4398-8946-7438571f16f6",
        "version": "1.0.0.0",
        "assets": {
          "elementManifests": [
            "elements.xml"
          ]
        }
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/field-extension.sppkg"
  }
}

Bereitstellen des Felds in SharePoint Online und Hosten von JavaScript über den lokalen Host

Jetzt können Sie die Lösung auf einer SharePoint-Website bereitstellen und die Feldzuordnung automatisch in ein Feld einbeziehen. Wir verwenden die Option --ship mit dieser Verpackung, damit alle Ressourcen automatisch im Lösungspaket verpackt werden.

  1. Geben Sie im Konsolenfenster den folgenden Befehl ein, um die clientseitige Lösung, die die Erweiterung enthält, zu verpacken und so die Grundstruktur für die Paketerstellung zu erstellen:

    gulp bundle --ship

  2. Führen Sie den folgenden Befehl aus, um das Lösungspaket zu erstellen:

    gulp package-solution --ship

    Der Befehl erstellt das Paket ./sharepoint/solution/field-extension.sppkg:

  3. Als Nächstes müssen Sie das Paket, das generiert wurde, im App-Katalog bereitstellen. Wechseln Sie dazu zum App-Katalog Ihres Mandanten, und öffnen Sie die Bibliothek Apps für SharePoint.

  4. Laden Sie die Datei ./sharepoint/solution/field-extension.sppkg in den App-Katalog hoch.

    Beachten Sie, dass SharePoint das Vertrauensdialogfeld anzeigt und Sie auffordern, der clientseitigen Lösung mit SharePoint Online als Domäne zu vertrauen. Ihre Ressourcen werden je nach Mandanteneinstellungen automatisch entweder über die App-Katalog-URL oder über Microsoft 365 öffentlichen CDN gehostet.

  5. Klicken Sie auf die Schaltfläche Bereitstellen.

    Bereitstellungsdialogfeld

  6. Wechseln Sie zu der Website, auf der Sie die Bereitstellung der SharePoint-Ressource testen möchten. Dies könnte eine Websitesammlung im Mandanten sein, auf dem Sie dieses Lösungspaket bereitgestellt haben.

  7. Wählen Sie das Zahnradsymbol in der oberen Navigationsleiste auf der rechten Seite und dann App hinzufügen aus.

  8. Geben Sie im Suchfelddas Feld ein, und drücken Sie dann die EINGABETASTE , um Ihre Apps zu filtern.

    Installieren des Field Customizers am Standort

  9. Wählen Sie die App field-extension-client-side-solution, um die Lösung auf der Website zu installieren. Aktualisieren Sie nach Abschluss der Installation die Seite.

  10. Klicken Sie nach dem Installieren der Lösung auf Neu in der Symbolleiste auf der Seite Websiteinhalte, und wählen Sie Liste.

    Erstellen einer neuen Liste

  11. Erstellen Sie eine Liste mit dem Namen Rechnungen.

  12. Wählen Sie, nachdem die neue Liste erstellt wurde, im Menü der neu erstellten Liste auf der Seite Websiteinhalte die Option Einstellungen aus.

    Einstellungen für die neue Liste

  13. Wählen Sie Spalten>Aus vorhandenen Websitespalten hinzufügen aus.

  14. Wählen Sie das Feld SPFx Columns>Percentage aus, das aus dem Lösungspaket bereitgestellt wurde, und wählen Sie dann OK aus.

    Hinzufügen des Prozentfelds zur Liste

  15. Wechseln Sie zu der neu erstellten Liste Rechnungen. Fügen Sie der Liste einige neue Einträge mit verschiedenen Werten in der Prozentspalte hinzu, um zu sehen, wie das Feld ohne die Debugging-Abfrageparameter dargestellt wird.

Felddarstellung ohne Debugging-Abfrageparameter

Die Vorgehensweise für die Veröffentlichung Ihrer App ist für alle Erweiterungstypen identisch.

Hinweis

Dies war ein relativ einfacher Field Customizer mit Funktionen, die auch mit Verwenden von Spaltenformatierung zum Anpassen von SharePoint erreicht werden können. Die Spaltenformatierung unterstützt jedoch keinen tatsächlichen benutzerdefinierten Code. Beachten Sie, dass Feldanpassungen nicht von Endbenutzern über die Benutzeroberfläche geändert werden können, was zusätzliche Anwendungsfälle ermöglicht.

Siehe auch