Erweiterungen für Befehlssätze

Abgeschlossen

In dieser Lektion lernen Sie einen anderen Typ von SharePoint Framework-Erweiterung kennen, mit dessen Hilfe Schaltflächen zu Listensymbolleisten und Kontextmenüs hinzugefügt werden können: Befehlszeilen.

Übersicht

Mit einer SharePoint-Framework-Befehlssatzerweiterung können Entwickler Schaltflächen zu modernen Listen und Bibliothekssymbolleisten sowie zu Kontextmenüs hinzufügen.

Der Sichtbarkeitsstatus jeder Schaltfläche wird mit einer einzigen booleschen Eigenschaft eingestellt, die Entwickler festlegen können. Mit dieser Eigenschaft können Entwickler Schaltflächen in der Symbolleiste oder in den Kontextmenüs eines Elements bedingt ein- oder ausblenden. Diese Befehlssatzerweiterungen ähneln den Anpassungsmöglichkeiten für benutzerdefinierte Aktionen im klassischen SharePoint-Modus. Die Anpassungsmöglichkeiten für benutzerdefinierte Aktion im klassischen Modus funktionieren nicht in der modernen Benutzeroberfläche, während Befehlssätze nur in der modernen Benutzeroberfläche funktionieren.

Die folgenden Szenarien sind einige mögliche Anwendungsfälle für Befehlssätze:

• Starten eines externen Prozesses
• Ausführen benutzerdefinierter Skripts bei Auswahl der Schaltfläche

Das SharePoint-Framework löst ein Ereignis aus, sobald sich der Status der Anzeige ändert, die der benutzerdefinierte Code abonnieren kann. Wenn ein Benutzer beispielsweise ein Element auswählt bzw. dessen Auswahl aufhebt oder einen Filter innerhalb der Anzeige ändert, können Sie abhängig von der Anzahl der Elemente, die aktuell in der Liste ausgewählt sind, den Status der visible-Eigenschaft der Schaltfläche mit bestimmten Bedingungen anpassen.

Registrieren von Befehlssätzen

Im Gegensatz zu den anderen Erweiterungstypen müssen Sie zuerst die Schaltflächen für den Befehlssatz registrieren, bevor Sie den Code ausführen. Die Registrierung des Befehlssatzes erfolgt in der Manifestdatei der Komponente. Jede Schaltfläche muss der items-Sammlung hinzugefügt werden:

{
  "id": "93c624a4-13df-4e43-a1c8-fa8da95eb949",
  "alias": "CommandSetDemoCommandSet",
  "componentType": "Extension",
  "extensionType": "ListViewCommandSet",
  ...
  "items": {
    "ONE_ITEM_SELECTED": {
      "title": { "default": "One Item Selected" },
      "type": "command"
    },
    "TWO_ITEM_SELECTED": {
      "title": { "default": "Two Items Selected" },
      "type": "command"
    },
    "ALWAYS_ON": {
      "title": { "default": "Always On" },
      "type": "command"
    }
  }
}

Dieser JSON-Ausschnitt aus dem Komponentenmanifest registriert drei Schaltflächen. Der Name der Schaltflächen darf ausschließlich aus Großbuchstaben und Unterstrichen bestehen.

Jede Schaltflächenreferenz verfügt über eine auf command eingestellte type-Eigenschaft sowie über eine title-Eigenschaft, die gemäß eines der von SharePoint-Framework unterstützten Gebietsschemas lokalisiert werden kann. Sie können auch eine iconUrl-Eigenschaft für das Schaltflächenobjekt festlegen, die auf die vollständig qualifizierte URL des Symbols verweist, das mit der Schaltfläche dargestellt werden soll.

Befehlssatz-Klasse

Nachdem Sie die Schaltflächen registriert haben, müssen Sie eine Klasse erstellen, die auf ähnliche Weise implementiert wird wie Erweiterungsoptionen für SharePoint-Framework.

Eine Schnittstelle wird verwendet, um die öffentlichen Eigenschaften zu definieren, die als Eingaben an der Erweiterung festgelegt werden können.

export interface ICommandSetDemoCommandSetProperties {
  messagePrefix: string;
}

Implementieren Sie als Nächstes eine Klasse zur Erweiterung der BaseListViewCommandSet-Basisklasse und überschreiben Sie die Implementierung der folgenden drei Methoden:

export default class CommandSetDemoCommandSet extends BaseListViewCommandSet<ICommandSetDemoCommandSetProperties> {

  @override
  public onInit(): Promise<void> { }

  @override
  public onListViewUpdated(event: IListViewCommandSetListViewUpdatedParameters): void { }

  @override
  public onExecute(event: IListViewCommandSetExecuteEventParameters): void { }
}

Die onInit()-Methode gibt ein Promise-Objekt zurück und kann dazu verwendet werden, einen Initialisierungscode auszuführen, der abgeschlossen werden muss, bevor der Befehlssatz gerendert wird.

Implementieren Sie als Nächstes das onListViewUpdated()-Ereignis. Diese Methode wird aufgerufen, wenn die Befehlssatzschaltfläche zum ersten Mal auf der Seite angezeigt wird und sich die Listenansicht ändert. Jede Schaltfläche auf der Seite ruft diese Methode auf. Wenn Sie über drei Schaltflächen verfügen, wird diese Methode dreimal aufgerufen, wenn sich die Listenansicht ändert.

Der letzte Schritt besteht darin, das onExecute()-Ereignis zu implementieren, das aufgerufen wird, wenn eine Schaltfläche vom Benutzer ausgewählt wird. Ähnlich wie im onListViewUpdated()-Ereignis wird diese Methode von allen Schaltflächen geteilt, die im Manifest Ihrer Komponente registriert sind. Sie können die itemId-Eigenschaft für das IListViewCommandSetExecuteEventParameters-Objekt verwenden, das an den onExecute()-Befehl übergeben wird, um zu bestimmen, welche Schaltfläche das Click-Ereignis ausgelöst hat.

Debuggen und Testen von Erweiterungen

Sehen wir uns nun an, wie Sie SharePoint-Framework-Befehlssatzerweiterungen testen und bei Bedarf Fehler beheben können. Die SharePoint Workbench unterstützt keine Testerweiterungen. Sie können jedoch Erweiterungsprojekte lokal erstellen und hosten, während Sie auf einer entfernten SharePoint-Website debuggen und testen.

Zum Testen von Befehlssatzerweiterungen müssen Sie spezielle Abfragezeichenfolgen-Parameter in die URL einer modernen SharePoint-Seite, -Liste oder -Bibliothek einfügen. Mit diesen Parametern weisen Sie SharePoint an, folgende Aktionen auszuführen:

• Laden des SharePoint-Frameworks auf die Seite, sofern es nicht bereits vorhanden ist
• Speicherort der Datei manifest.js vom lokalen Webserver, die SharePoint mitteilt, welche benutzerdefinierten Komponenten auf die Seite gestellt werden können
• Welche Komponente das SharePoint-Framework laden und auf die Seite stellen soll
• zusätzliche Eigenschaften, die für jede Komponente spezifisch sind

Der Yeoman-Generator für das SharePoint-Framework vereinfacht diesen Prozess für Sie, indem er eine Konfiguration erstellt, die von der Aufgabe gulp serve zur Erstellung der Debugging-URL verwendet wird. Diese Einstellungen sind in der Datei ./config/serve.jsondefiniert.

Wenn SharePoint die Anforderung mit diesen Abfragezeichenfolgenparametern empfängt, fordert es den Benutzer zunächst auf, zu bestätigen, dass er Debugging-Skripts laden möchte. SharePoint kann die gleiche Methode auch bei einem Phishing-Angriff verwenden. Sie sollten also die Debugging-Skripte nur laden, wenn Sie sicher sind, dass Sie die Anfrage gestartet haben.

Bereitstellung

Die Bereitstellung von Befehlssatzerweiterungen ähnelt der Bereitstellung anderer Typen von SharePoint-Framework-Erweiterungen.

SharePoint-Framework-Befehlssatzerweiterungen wie Application Customizers unterstützen die mandantenweite Bereitstellung. Wenn die mandantenweite Bereitstellung für das bereitgestellte Paket aktiviert ist, verwendet der Bereitstellungsprozess die ClientSideInstance.xml-Datei in Ihrem SharePoint-Paket, um der Liste Mandantenweite Erweiterungen auf der App-Katalogwebsite des Mandanten einen Eintrag hinzuzufügen. Die ClientSideInstance.xml-Datei befindet sich im ./sharepoint/assets-Ordner in Ihrem Projekt.

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <ClientSideComponentInstance
        Title="CommandSetDemo"
        Location="ClientSideExtension.ListViewCommandSet.CommandBar"
        ListTemplateId="100"
        Properties="{&quot;sampleTextOne&quot;:&quot;One item is selected in the list.&quot;, &quot;sampleTextTwo&quot;:&quot;This command is always visible.&quot;}"
        ComponentId="3be2fc87-25c0-4ab1-a66c-10667d5912f6" />
</Elements>

Wenn die mandantenweite Bereitstellung nicht aktiviert ist, fügt das SharePoint-Featureframework Befehlssatzschaltflächen mithilfe einer benutzerdefinierten Aktion hinzu. Die benutzerdefinierte Aktion wird in der ./sharepoint/assets/elements.xml-Datei definiert.

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction
    Title="CommandSetDemo"
    RegistrationId="100"
    RegistrationType="List"
    Location="ClientSideExtension.ListViewCommandSet.CommandBar"
    ClientSideComponentId="93c624a4-13df-4e43-a1c8-fa8da95eb949"
    ClientSideComponentProperties="{&quot;messagePrefix&quot;:&quot;[command_set_prefix]&quot;}">
  </CustomAction>
</Elements>

Die dateien, auf die zuvor verwiesen wird, sind Elemente eines Features. Die Definition des Features ist Teil des solution-Objekts in der ./config/package-solution.json-Datei.

"features": [
  {
    "title": "Application Extension - Deployment of custom action",
    "description": "Deploys a custom action with ClientSideComponentId association",
    "id": "3e349cf8-f870-404e-bfa7-431ae3e8b1dc",
    "version": "1.0.0.0",
    "assets": {
      "elementManifests": [
        "elements.xml",
        "ClientSideInstance.xml"
      ]
    }
  }
]

Zusammenfassung

In dieser Lektion haben Sie einen anderen Typ von SharePoint Framework-Erweiterung kennengelernt, mit dessen Hilfe Schaltflächen zu Listensymbolleisten und Kontextmenüs hinzugefügt werden können: Befehlszeilen.