Erstellen Ihrer ersten Erweiterung des Typs „ListView Command Set“
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
Erstellen Sie an einem Speicherort Ihrer Wahl ein neues Projektverzeichnis:
md command-extensionWechseln Sie in das Projektverzeichnis:
cd command-extensionFühren Sie den Yeoman-SharePoint-Generator aus, um eine neue HelloWorld-Erweiterung zu erstellen:
yo @microsoft/sharepointWenn 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?: command-extension
- 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? HelloWorld
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 je nach Internetverbindung 1 bis 3 Minuten dauern.
Geben Sie als Nächstes Folgendes in die Konsole ein, um Visual Studio Code zu starten.
code .Öffnen Sie die Datei ./src/extensions/helloWorld/HelloWorldCommandSet.manifest.json .
Diese Datei definiert den Erweiterungstyp und eine eindeutige
idfür die Erweiterung. Sie benötigen diese eindeutige ID später beim Debuggen und Bereitstellen der Erweiterung in SharePoint.{ "$schema": "https://developer.microsoft.com/json-schemas/spfx/command-set-extension-manifest.schema.json", "id": "95688e19-faea-4ef1-8394-489bed1de2b4", "alias": "HelloWorldCommandSet", "componentType": "Extension", "extensionType": "ListViewCommandSet", "version": "*", "manifestVersion": 2, "requiresCustomScript": false, "items": { "COMMAND_1": { "title": { "default": "Command One" }, "iconImageUrl": "icons/request.png", "type": "command" }, "COMMAND_2": { "title": { "default": "Command Two" }, "iconImageUrl": "icons/cancel.png", "type": "command" } } }Beachten Sie die aktuellen Befehlsdefinitionen in der Manifestdatei. Es handelt sich hierbei um Schaltflächen, die auf Grundlage des Registrierungsziels verfügbar gemacht werden. In der Standardvorlage finden Sie zwei verschiedene Schaltflächen: Command One und Command Two.
Hinweis
Auf Bilder wird nicht ordnungsgemäß verwiesen, es sei denn, Sie beziehen sich auf sie von absoluten Speicherorten in einem CDN in Ihrem Manifest.
Programmieren Ihrer Erweiterung des Typs „ListView Command Set“
Öffnen Sie die Datei ./src/extensions/helloWorld/HelloWorldCommandSet.ts.
Beachten Sie, dass die Basisklasse für den ListView-Befehlssatz aus dem Paket @microsoft/sp-listview-extensibility importiert wird, das SharePoint-Framework (SPFx)-Code enthält, der für den ListView-Befehlssatz erforderlich ist.
import { override } from '@microsoft/decorators';
import { Log } from '@microsoft/sp-core-library';
import {
BaseListViewCommandSet,
Command,
IListViewCommandSetListViewUpdatedParameters,
IListViewCommandSetExecuteEventParameters
} from '@microsoft/sp-listview-extensibility';
import { Dialog } from '@microsoft/sp-dialog';
Das Verhalten für ihre benutzerdefinierten Schaltflächen ist in den onListViewUpdated() Methoden und OnExecute() enthalten.
Das onListViewUpdated() Ereignis tritt für jeden Befehl (z. B. ein Menüelement) separat auf, wenn eine Änderung in der ListView erfolgt und die Benutzeroberfläche erneut gerendert werden muss. Der event-Funktionsparameter gibt Informationen über den angezeigten Befehl an. Der Handler kann mithilfe dieser Informationen den Titel oder die Sichtbarkeit anpassen, beispielsweise wenn ein Befehl nur angezeigt werden soll, wenn eine bestimmte Anzahl von Elementen in der Listenansicht ausgewählt ist. Dies ist die Standardimplementierung.
Wenn Sie die tryGetCommand()-Methode verwenden, erhalten Sie ein Command-Objekt, das den auf der Benutzeroberfläche angezeigten Befehl angibt. Sie können die zugehörigen Werte wie title oder visible ändern, um das Benutzeroberflächenelement zu ändern. SPFx verwendet diese Informationen, wenn die Befehle neu gerendert werden müssen. Diese Objekte speichern den Status des letzten Renderings. Wenn ein Befehl zum Beispiel auf visible = false festgelegt wurde, wird er erst eingeblendet, wenn er wieder auf visible = true festgelegt wurde.
@override
public onListViewUpdated(event: IListViewCommandSetListViewUpdatedParameters): void {
const compareOneCommand: Command = this.tryGetCommand('COMMAND_1');
if (compareOneCommand) {
// This command should be hidden unless exactly one row is selected.
compareOneCommand.visible = event.selectedRows.length === 1;
}
}
Die onExecute() -Methode definiert, was geschieht, wenn ein Befehl ausgeführt wird (z. B. wird das Menüelement ausgewählt). In der Standardimplementierung werden je nach ausgewählter Schaltfläche unterschiedliche Meldungen angezeigt.
@override
public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
switch (event.itemId) {
case 'COMMAND_1':
Dialog.alert(`${this.properties.sampleTextOne}`);
break;
case 'COMMAND_2':
Dialog.alert(`${this.properties.sampleTextTwo}`);
break;
default:
throw new Error('Unknown command');
}
}
Debuggen Ihrer Erweiterung des Typs „ListView Command Set“
SharePoint-Framework-Erweiterungen können derzeit 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.
Navigieren Sie auf Ihrer SharePoint Online-Website zu einer beliebigen SharePoint-Liste, indem Sie die moderne Oberfläche verwenden. Kopieren Sie die URL der Liste in die Zwischenablage, da wir diese im folgenden Schritt benötigen.
Da unsere Erweiterung des Typs „ListView Command Set“ auf Localhost gehostet wird und aktuell ausgeführt wird, können wir den Code mithilfe spezifischer Debugabfrageparameter in der Listenansicht ausführen.
Öffnen Sie die Datei ./config/serve.json . Aktualisieren Sie die
pageUrlAttribute so, dass sie mit einer URL der Liste übereinstimmen, in der Sie die Lösung testen möchten. Nach der Bearbeitung sollte ihre serve.json in etwa wie folgt aussehen:{ "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json", "port": 4321, "https": true, "serveConfigurations": { "default": { "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx", "customActions": { "bf232d1d-279c-465e-a6e4-359cb4957377": { "location": "ClientSideExtension.ListViewCommandSet.CommandBar", "properties": { "sampleTextOne": "One item is selected in the list", "sampleTextTwo": "This command is always visible." } } } }, "helloWorld": { "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx", "customActions": { "bf232d1d-279c-465e-a6e4-359cb4957377": { "location": "ClientSideExtension.ListViewCommandSet.CommandBar", "properties": { "sampleTextOne": "One item is selected in the list", "sampleTextTwo": "This command is always visible." } } } } } }Zunächst führen Sie den folgenden Befehl aus, um den Code zu kompilieren und die Dateien auf Ihrem lokalen Computer zu hosten:
gulp serveWenn der Code ohne Fehler kompiliert wurde, verarbeitet er das resultierende Manifest von https://localhost:4321.
Dadurch wird auch Ihr Standardbrowser innerhalb der URL gestartet, die in der Datei ./config/serve.json definiert ist. Beachten Sie, dass Sie, zumindest in Windows, steuern können, welches Browserfenster verwendet wird, indem Sie das bevorzugte Fenster aktivieren, bevor Sie diesen Befehl ausführen.
Klicken Sie bei Aufforderung auf Debugskripts laden, um das Laden der Debugmanifeste zu akzeptieren.
Beachten Sie die neue Schaltfläche Command Two, die auf der Symbolleiste zur Verfügung steht. Wählen Sie diese Schaltfläche, um den als Eigenschaft für die
sampleTextTwo-Eigenschaft bereitgestellten Text anzuzeigen.
Die Schaltfläche Command One wird basierend auf dem Code erst dann angezeigt, wenn eine Ziele in der Dokumentbibliothek ausgewählt ist. Erstellen Sie ein Dokument oder laden Sie es in die Bibliothek hoch, und stellen Sie sicher, dass die zweite Schaltfläche angezeigt wird.
Wählen Sie Command Two aus, um zu sehen, wie die Dialogfeldsteuerung funktioniert, die in der Standardausgabe aus dem Lösungsgerüst verwendet wird, wenn „ListView Command Set“ als Erweiterungstyp ausgewählt ist.
Weitere Details zu serve.json-Optionen
customActions: simuliert eine benutzerdefinierte Aktion. Sie können zahlreiche Eigenschaften für diesesCustomAction-Objekt festlegen, die sich auf die Darstellung und den Ort der Schaltfläche auswirken. Diese werden zu einem späteren Zeitpunkt erläutert.GUID: GUID der Erweiterung.Location: Hier werden die Befehle angezeigt. Die folgenden Werte sind möglich:ClientSideExtension.ListViewCommandSet.ContextMenu: Das Kontextmenü der Elemente.ClientSideExtension.ListViewCommandSet.CommandBar: Das obere Befehlssatzmenü in einer Liste oder Bibliothek.ClientSideExtension.ListViewCommandSet: Sowohl das Kontextmenü als auch die Befehlsleiste (entspricht SPUserCustomAction.Location="CommandUI.Ribbon").
Properties: Ein optionales JSON-Objekt mit Eigenschaften, die über denthis.propertiesMember verfügbar sind.
Erweitern der Darstellung von Erweiterungen des Typs „ListView Command Set“
Für die Standardlösung nutzen wir eine neue Dialogfeld-API, mit der Sie über Ihren Code ganz einfach modale Dialogfelder anzeigen lassen können. In den folgenden Schritten wird nun die Standardoberfläche leicht geändert, um Anwendungsfälle der Dialogfeld-API zu demonstrieren.
Kehren Sie zu Visual Studio Code (oder Ihrem bevorzugten Editor) zurück.
Öffnen Sie die Datei ./src/extensions/helloWorld/HelloWorldCommandSet.ts .
Aktualisieren Sie die
onExecute()-Methode wie folgt:@override public onExecute(event: IListViewCommandSetExecuteEventParameters): void { switch (event.itemId) { case 'COMMAND_1': Dialog.alert(`Clicked ${strings.Command1}`); break; case 'COMMAND_2': Dialog.prompt(`Clicked ${strings.Command2}. Enter something to alert:`).then((value: string) => { Dialog.alert(value); }); break; default: throw new Error('Unknown command'); } }Stellen Sie in dem Konsolenfenster sicher, dass keine Ausnahmen vorhanden sind. Wenn die Lösung nicht in localhost ausgeführt wird, führen Sie den folgenden Befehl aus:
gulp serveKlicken Sie bei Aufforderung auf Debugskripts laden, um das Laden der Debugmanifeste zu akzeptieren.
Auf der Symbolleiste werden weiterhin dieselben Schaltflächen angezeigt, sie verhalten sich nun jedoch anders, wenn sie einzeln ausgewählt werden. Wir verwenden jetzt die neue Dialogfeld-API, die sogar für komplexe Szenarien problemlos verwendet werden kann.
Hinzufügen einer Erweiterung des Typs „ListView Command Set“ zu einem Lösungspaket zwecks Bereitstellung
- Wechseln Sie wieder zu Ihrer Lösung in Visual Studio Code (oder Ihrem bevorzugten Editor).
- Öffnen Sie die Datei ./sharepoint/assets/elements.xml.
Beachte Sie die folgende XML-Struktur in elements.xml. Die ClientSideComponentId Eigenschaft wurde auf die eindeutige ID Ihres ListView-Befehlssatzes aktualisiert, der in der Datei ./src/extensions/helloWorld/HelloWorldCommandSet.manifest.json verfügbar ist.
Beachten Sie, dass wir einen bestimmten Location-Wert von ClientSideExtension.ListViewCommandSet.CommandBar verwenden, um die Erweiterung als „ListView Command Set“ zu definieren und anzugeben, dass sie in der Befehlsleiste angezeigt werden soll. Wir definieren auch die RegistrationId bis 100 und die RegistrationType , List um diese benutzerdefinierte Aktion automatisch generischen Listen zuzuordnen. ClientSideComponentProperties kann verwendet werden, um instanzspezifische Konfigurationen bereitzustellen. In diesem Fall verwenden wir die Standardeigenschaften sampleTextOne und sampleTextTwo.
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<CustomAction
Title="SPFxListViewCommandSet"
RegistrationId="100"
RegistrationType="List"
Location="ClientSideExtension.ListViewCommandSet.CommandBar"
ClientSideComponentId="5fc73e12-8085-4a4b-8743-f6d02ffe1240"
ClientSideComponentProperties="{"sampleTextOne":"One item is selected in the list.", "sampleTextTwo":"This command is always visible."}">
</CustomAction>
</Elements>
Hinweis
Während der Ausführung von localhost funktioniert die benutzerdefinierte Aktion sowohl für Listen als auch für Dokumentbibliotheken, wird jedoch nicht einmal bereitgestellt, es sei denn, die elements.xml wird aktualisiert. RegistrationId=100 verknüpft die benutzerdefinierte Aktion nur mit Listen und NICHT mit Dokumentbibliotheken.
Um die benutzerdefinierte Aktion Dokumentbibliotheken zuzuordnen, muss auf RegistrationId101festgelegt werden. Wenn die Aktion sowohl für Listen als auch für Dokumentbibliotheken verwendet werden soll, muss der elements.xml Datei eine weitere CustomAction hinzugefügt werden.
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<CustomAction
Title="SPFxListViewCommandSet"
RegistrationId="100"
RegistrationType="List"
Location="ClientSideExtension.ListViewCommandSet.CommandBar"
ClientSideComponentId="5fc73e12-8085-4a4b-8743-f6d02ffe1240"
ClientSideComponentProperties="{"sampleTextOne":"One item is selected in the list.", "sampleTextTwo":"This command is always visible."}">
</CustomAction>
<CustomAction
Title="SPFxListViewCommandSet"
RegistrationId="101"
RegistrationType="List"
Location="ClientSideExtension.ListViewCommandSet.CommandBar"
ClientSideComponentId="5fc73e12-8085-4a4b-8743-f6d02ffe1240"
ClientSideComponentProperties="{"sampleTextOne":"One item is selected in the list.", "sampleTextTwo":"This command is always visible."}">
</CustomAction>
</Elements>
Für eine Erweiterung des Typs „ListView Command Set“ können Sie folgende Positionswerte angeben:
ClientSideExtension.ListViewCommandSet.CommandBar: Symbolleiste der Liste oder BibliothekClientSideExtension.ListViewCommandSet.ContextMenu: Kontextmenü für Listen- oder BibliothekselementeClientSideExtension.ListViewCommandSet: Registrieren von Befehlen sowohl für die Symbolleiste als auch für das Kontextmenü
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 element.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.
Hinweis
Sie können ClientSideInstance.xml verwenden, um Ihre Erweiterungen über alle Websites in Ihrem Mandanten hinweg automatisch bereitzustellen. Weitere Informationen zu dieser Option finden Sie im Artikel Mandantenweite Bereitstellung von SharePoint Framework-Erweiterungen. Da diese Lösung so konfiguriert ist, dass die mandantenweite Option nicht verwendet wird, wird diese XML-Datei ignoriert, wenn die Lösung im App-Katalog aktiviert wird.
{
"$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
"solution": {
"name": "command-extension-client-side-solution",
"id": "0abe5c73-1655-49d3-922b-7a47dd70e151",
"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": "25f8df47-61f2-4d75-bfe2-8d614f775219",
"version": "1.0.0.0",
"assets": {
"elementManifests": [
"elements.xml",
"clientsideinstance.xml"
]
}
}
]
},
"paths": {
"zippedPackage": "solution/command-extension.sppkg"
}
}
Bereitstellen der Erweiterung in SharePoint Online
Nun können Sie die Lösung auf einer SharePoint-Website bereitstellen und das Objekt CustomAction automatisch auf Website-Ebene verknüpfen.
Da Lösungen standardmäßig die Funktion Verpacken von Objekten verwenden, werden Ihre JavaScript-Dateien und andere Objekte automatisch in der sppkg-Datei verpackt und dann automatisch vom Office 365-CDN oder von der Websitesammlung des App-Katalogs gehostet.
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 --shipFühren Sie den folgenden Befehl aus, um das Lösungspaket zu erstellen:
gulp package-solution --shipDer Befehl erstellt das folgende Paket: Ordner ./sharepoint/solution/command-extension.sppkg :
Stellen Sie das Paket, das generiert wurde, im App-Katalog bereit. Wechseln Sie dazu zum App-Katalog Ihres Mandanten, und öffnen Sie die Bibliothek Apps für SharePoint.
Laden Sie den Ordner ./sharepoint/solution/command-extension.sppkg in den App-Katalog hoch. In SharePoint wird ein Dialogfeld angezeigt, und Sie werden aufgefordert, der clientseitigen Lösung zu vertrauen.
Klicken Sie auf die Schaltfläche Bereitstellen.
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.
Wählen Sie das Zahnradsymbol in der oberen Navigationsleiste auf der rechten Seite und dann App hinzufügen aus, um zur Seite Apps zu wechseln.
Geben Sie in das Suchfeld die Zeichenfolge extension ein, und drücken Sie die EINGABETASTE, um Ihre Apps zu filtern.
Wählen Sie die App command-extension-client-side-solution, um die Lösung auf der Website zu installieren. Wenn die Installation abgeschlossen ist.
Klicken Sie nach der Installation der Anwendung auf der Symbolleiste auf der Seite Websiteinhalte auf Neu, und wählen Sie die Option Liste aus.
Geben Sie als Namen Sample ein, und klicken Sie auf Erstellen.
Command One und Command Two werden nun gemäß den Anpassungen in der Erweiterung des Typs „ListView Command Set“ auf der Symbolleiste gerendert. Beachten Sie, dass die Erweiterung auch automatisch für alle vorhandenen Listen gerendert wird, nicht nur für neue.
