Freigeben über

Migrieren von Ecb-Menüelementen (Edit Control Block) zu SharePoint-Framework Erweiterungen

  • Artikel

In den letzten Jahren nutzten die meisten Unternehmenslösungen, die auf Microsoft 365 und SharePoint Online basieren, die Websitefunktion CustomAction des SharePoint Feature Frameworks, um die Benutzeroberfläche von Seiten zu erweitern. Mit der "modernen" Benutzeroberfläche von SharePoint sind die meisten dieser Anpassungen nicht mehr verfügbar. Mit SharePoint-Framework Erweiterungen können Sie ähnliche Funktionen in der modernen Benutzeroberfläche bereitstellen.

In diesem Tutorial erfahren Sie, wie Sie klassische Legacyanpassungen zum aktuellen Modell migrieren: 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 „Command Set“.

Angenommen, Sie verfügen in SharePoint Online über ein CustomAction benutzerdefiniertes ECB-Menüelement für Dokumente in einer Bibliothek. Die Funktion des ECB-Menüelements besteht darin, eine benutzerdefinierte Seite zu öffnen, auf der die Listen-ID und die Listenelement-ID des aktuell ausgewählten Elements in der Abfragezeichenfolge der Zielseite bereitgestellt wird.

Im folgenden Codeausschnitt sehen Sie den XML-Code, der eine CustomAction mithilfe des SharePoint-Featureframeworks definiert.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction
      Id="OpenDetailsPageWithItemReference"
      Title="Show Details"
      Description="Opens a new page with further details about the currently selected item"
      Sequence="1001"
      RegistrationType="List"
      RegistrationId="101"
      Location="EditControlBlock">
    <UrlAction Url="ShowDetails.aspx?ID={ItemId}&amp;List={ListId}" />
  </CustomAction>
</Elements>

Wie Sie sehen können, definiert die Featureelementdatei ein Element vom Typ CustomAction , um ein neues Element am EditControlBlock Speicherort (d.a. ECB) für jedes Dokument in einer beliebigen Bibliothek hinzuzufügen (RegistrationType ist List und RegistrationId ist 101).

In der folgenden Abbildung sehen Sie die Ausgabe der vorherigen benutzerdefinierten Aktion in der Listenansicht einer Bibliothek.

Die benutzerdefinierte Fußzeile auf einer klassischen Seite

Beachten Sie, dass das benutzerdefinierte ECB-Element des SharePoint-Feature-Framework in einer „modernen“ Liste funktioniert. Tatsächlich funktioniert eine benutzerdefinierte Listenaktion auch in „modernen“ Listen, solange Sie keinen JavaScript-Code verwenden.

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-ecb-extension

  2. Wechseln Sie zum Projektordner:

    cd spfx-ecb-extension

  3. Erstellen Sie ein neues SharePoint-Framework-Lösungswebpart, indem Sie den Yeoman SharePoint-Generator ausführen.

    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-ecb-extension
    • Welche Basislinienpakete möchten Sie für Ihre Komponente(n) als Ziel festlegen? Nur SharePoint Online (neustes)
    • Welchen Typ von clientseitiger Komponente möchten Sie erstellen?: Erweiterung
    • Welchen Typ von clientseitiger Erweiterung möchten Sie erstellen? ListView-Befehlssatz
    • Was ist Ihr Befehlssatzname? CustomECB

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

  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 ECB-Elements

Um das gleiche Verhalten des ECB-Menüelements zu reproduzieren, das mit dem SharePoint-Feature-Framework erstellt wurde, müssen Sie die gleiche 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/customEcb/CustomEcbCommandSet.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. Bearbeiten Sie innerhalb derselben Datei das Array von items im unteren Teil der Datei, um einen einzelnen Befehl für den Befehlssatz zu definieren. Rufen Sie den Befehl ShowDetails auf, und geben Sie dann einen Titel sowie einen Befehlstyp ein. Im folgenden Screenshot sehen Sie, wie die Manifestdatei aussehen soll.

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx/command-set-extension-manifest.schema.json",

  "id": "5d3bac4c-e040-44ed-ab43-464490d22762",
  "alias": "CustomEcbCommandSet",
  "componentType": "Extension",
  "extensionType": "ListViewCommandSet",

  "version": "*",
  "manifestVersion": 2,

  "requiresCustomScript": false,

  "items": {
    "ShowDetails": {
      "title": {
        "default": "Show Details"
      },
      "type": "command"
    }
  }
}

  3. Öffnen Sie die Datei ./src/extensions/customEcb/CustomEcbCommandSet.ts , und bearbeiten Sie den Inhalt gemäß dem folgenden Codeausschnitt:

    import { Guid } from '@microsoft/sp-core-library';
import { override } from '@microsoft/decorators';
import {
  BaseListViewCommandSet,
  Command,
  IListViewCommandSetListViewUpdatedParameters,
  IListViewCommandSetExecuteEventParameters
} from '@microsoft/sp-listview-extensibility';
import { Dialog } from '@microsoft/sp-dialog';

import * as strings from 'CustomEcbCommandSetStrings';

export interface ICustomEcbCommandSetProperties {
  targetUrl: string;
}

export default class CustomEcbCommandSet extends BaseListViewCommandSet<ICustomEcbCommandSetProperties> {

  @override
  public onInit(): Promise<void> {
    return Promise.resolve();
  }

  @override
  public onListViewUpdated(event: IListViewCommandSetListViewUpdatedParameters): void {
    const compareOneCommand: Command = this.tryGetCommand('ShowDetails');
    if (compareOneCommand) {
      // This command should be hidden unless exactly one row is selected.
      compareOneCommand.visible = event.selectedRows.length === 1;
    }
  }

  @override
  public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
    switch (event.itemId) {
      case 'ShowDetails':

        const itemId: number = event.selectedRows[0].getValueByName("ID");
        const listId: Guid = this.context.pageContext.list.id;

        window.location.replace(`${this.properties.targetUrl}?ID=${itemId}&List=${listId}`);

        break;
      default:
        throw new Error('Unknown command');
    }
  }
}

    Beachten Sie die import-Anweisung am Anfang der Datei, die auf den Typ Guid verweist, der die ID der aktuellen Liste enthalten soll.

    Die Schnittstelle ICustomEcbCommandSetProperties deklariert eine einzelne Eigenschaft namens targetUrl , die verwendet werden kann, um die URL der Zielseite anzugeben, die beim Auswählen des ECB-Menüelements geöffnet werden soll.

    Darüber hinaus behandelt die Überschreibung der onExecute()-Methode die Ausführung der benutzerdefinierten Aktion. Beachten Sie den Codeauszug, der die ID des aktuell ausgewählten Elements aus dem event-Argument sowie die ID der Quellliste aus dem pageContext-Objekt abruft.

    Beachten Sie schließlich auch die Überschreibung der onListViewUpdated()-Methode, die standardmäßig den Befehl ShowDetails nur dann aktivierte, wenn ein einzelnes Element ausgewählt wird.

    Die Umleitung an die Ziel-URL erfolgt durch die Verwendung von klassischem JavaScript-Code und der Funktion window.location.replace(). Sie können jeden beliebigen TypeScript-Code in der onExecute() -Methode schreiben. Um hier nur ein Beispiel zu nennen, können Sie das Dialog-Framework des SharePoint-Frameworks verwenden, um ein neues Dialogfeld zu öffnen und mit Benutzern zu interagieren.

    Hinweis

    Weitere Informationen zum SharePoint-Framework Dialog Framework finden Sie unter Verwenden von benutzerdefinierten Dialogfeldern mit SharePoint-Framework Erweiterungen.

    In der folgenden Abbildung ist die resultierende Ausgabe enthalten.

    Das Command Set von ECB, gerendert in einer „modernen“ Liste

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“ Bibliothek einer beliebigen „modernen“ Teamwebsite. Hängen Sie die folgenden Abfragezeichenfolgeparameter an die AllItems.aspx-Seiten-URL an.

    ?loadSpfx=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"6c5b8ee9-43ba-4cdf-a106-04857c8307be":{"location":"ClientSideExtension.ListViewCommandSet.ContextMenu","properties":{"targetUrl":"ShowDetail.aspx"}}}

    Ersetzen Sie in der vorherigen Abfragezeichenfolge die GUID durch den id-Wert aus der Datei CustomEcbCommandSet.manifest.json ersetzen, den Sie gespeichert und aufbewahrt haben.

    Darüber hinaus gibt es eine location Eigenschaft, die den Wert von ClientSideExtension.ListViewCommandSet.ContextMenu annimmt, die SPFx anweist, den Befehlssatz als ECB-Menüelement zu rendern. Nachfolgend finden Sie alle Optionen für die location-Eigenschaft:

    • ClientSideExtension.ListViewCommandSet.ContextMenu: Das Kontextmenü der Elemente.
    • ClientSideExtension.ListViewCommandSet.CommandBar: im oberen Befehlssatzmenü in einer Liste oder Bibliothek.
    • ClientSideExtension.ListViewCommandSet: Sowohl das Kontextmenü als auch die Befehlsleiste (entspricht SPUserCustomAction.Location="CommandUI.Ribbon").

    Weiterhin in der Abfragezeichenfolge gibt es eine Eigenschaft namens properties , die die JSON-Serialisierung eines Objekts vom Typ ICustomEcbCommandSetProperties darstellt, der dem Typ der benutzerdefinierten Eigenschaften entspricht, die vom benutzerdefinierten Befehlssatz für das Rendering angefordert werden.

    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

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 den Unterordner /sharepoint/assets des Projektmappenordners, und bearbeiten Sie die dateielements.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/">
    <CustomAction
        Title="CustomEcb"
        RegistrationId="101"
        RegistrationType="List"
        Location="ClientSideExtension.ListViewCommandSet.ContextMenu"
        ClientSideComponentId="6c5b8ee9-43ba-4cdf-a106-04857c8307be"
        ClientSideComponentProperties="{&quot;targetUrl&quot;:&quot;ShowDetails.aspx&quot;}">
    </CustomAction>
</Elements>

    Wie Sie sehen, ähnelt sie der SharePoint-Feature-Framework-Datei des „klassischen“ Modells. Sie verwendet jedoch das Attribut ClientSideComponentId, um die id der benutzerdefinierten Erweiterung zu referenzieren, sowie das Attribut ClientSideComponentProperties, um die benutzerdefinierten Konfigurationseigenschaften zu konfigurieren, die für die Erweiterung erforderlich sind.

  2. Öffnen Sie die Datei ./config/package-solution.json in der Projektmappe. In der Datei sehen Sie, dass im Abschnitt ein Verweis auf die elements.xml Datei vorhanden assets ist.

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-ecb-extension-client-side-solution",
    "id": "b8ff6fdf-16e9-4434-9fdb-eac6c5f948ee",
    "version": "1.0.2.0",
    "features": [
      {
        "title": "Custom ECB Menu Item.",
        "description": "Deploys a custom ECB menu item sample extension",
        "id": "f30a744c-6f30-4ccc-a428-125a290b5233",
        "version": "1.0.0.0",
        "assets": {
          "elementManifests": [
            "elements.xml"
          ]
        }
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/spfx-ecb-extension.sppkg"
  }
}

Bündeln, Packen und Bereitstellen der SharePoint-Framework-Komponente

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-ecb-extension-client-side-solution aus, 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 Installation der Anwendung abgeschlossen ist, öffnen Sie die Documents-Bibliothek der Website, und sehen Sie sich das funktionsfähige ECB-Menüelement an, indem Sie ein einzelnes Dokument auswählen.

Genießen Sie Ihr neues benutzerdefiniertes ECB-Menüelement, das mithilfe der SharePoint-Framework-Erweiterungen erstellt wurde!

Siehe auch