Machen Sie Ihr clientseitiges SharePoint-Webpart konfigurierbarMake your SharePoint client-side web part configurable

Im Eigenschaftenbereich können Endbenutzer das Webpart mit einer Reihe von Eigenschaften konfigurieren.The property pane allows end users to configure the web part with several properties. Im Artikel Erstellen Ihres ersten Webparts wird beschrieben, wie der Eigenschaftenbereich in der HelloWorldWebPart-Klasse definiert ist.The article Build your first web part describes how the property pane is defined in the HelloWorldWebPart class. Die Eigenschaften des Eigenschaftenbereichs sind in propertyPaneSettings definiert.The property pane properties are defined in propertyPaneSettings.

Ein Eigenschaftenbereich weist drei wichtige Metadaten auf: eine Seite, einen optionalen Header und mindestens eine Gruppe.A property pane has three key metadata: a page, an optional header, and at least one group.

  • Über Seiten haben Sie die Flexibilität, komplexe Interaktionen zu trennen und diese auf einer oder mehreren Seiten zu platzieren.Pages provide you the flexibility to separate complex interactions and put them into one or more pages. Seiten enthalten dann eine Kopfzeile und Gruppen.Pages contain a header and groups.
  • Kopfzeilen ermöglichen es Ihnen, den Titel des im Eigenschaftenbereich zu definieren.Headers allow you to define the title of the property pane.
  • Gruppen ermöglichen es Ihnen, die verschiedenen Abschnitte oder Felder für die Eigenschaftenbereiche zu definieren, über die Sie Ihre Feldsätze gruppieren können.Groups allow you to define the various sections or fields for the property pane through which you want to group your field sets.

Die folgende Abbildung zeigt ein Beispiel für einen Eigenschaftenbereich in SharePoint.The following figure shows an example of a property pane in SharePoint.

Beispiel für Eigenschaftenbereich

Konfigurieren des EigenschaftenbereichsConfigure the property pane

Im folgenden Codebeispiel wird der Eigenschaftenbereich in Ihrem Webpart initialisiert und konfiguriert. Sie setzen die Methode getPropertyPaneConfiguration außer Kraft und geben eine Auflistung der Eigenschaftbereichsseite(n) zurück.The following code example initializes and configures the property pane in your web part. You override the getPropertyPaneConfiguration method and return a collection of property pane page(s).

protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
  return {
    pages: [
      {
        header: {
          description: strings.PropertyPaneDescription
        },
        groups: [
          {
            groupName: strings.BasicGroupName,
            groupFields: [
              PropertyPaneTextField('description', {
                label: strings.DescriptionFieldLabel
              })
            ]
          }
        ]
      }
    ]
  };
}

Felder des EigenschaftenbereichsProperty pane fields

Die folgenden Feldtypen werden unterstützt:The following field types are supported:

  • SchaltflächeButton
  • KontrollkästchenCheckbox
  • AuswahlgruppeChoice group
  • DropdownDropdown
  • Horizontales LinealHorizontal rule
  • BeschriftungLabel
  • LinkLink
  • SchiebereglerSlider
  • TextfeldTextbox
  • Mehrzeiliges TextfeldMulti-line Textbox
  • UmschaltflächeToggle
  • BenutzerdefiniertCustom

Die Feldtypen sind in sp-client-platform als Module verfügbar. Bevor sie im Code verwendet werden können, müssen sie importiert werden:The field types are available as modules in sp-client-platform. They require an import before you can use them in your code:

import {
  PropertyPaneTextField,
  PropertyPaneCheckbox,
  PropertyPaneLabel,
  PropertyPaneLink,
  PropertyPaneSlider,
  PropertyPaneToggle,
  PropertyPaneDropdown
} from '@microsoft/sp-webpart-base';

Jede Feldtypmethode ist wie folgt definiert, wobei PropertyPaneTextField als Beispiel verwendet wird:Every field type method is defined as follows, taking PropertyPaneTextField as an example:

PropertyPaneTextField('targetProperty',{
  //field properties are defined here
})

targetProperty definiert das zugeordnete Objekt für diesen Feldtyp und ist auch in der Eigenschaftenschnittstelle Ihres Webparts definiert.The targetProperty defines the associated object for that field type and is also defined in the props interface in your web part.

Um diesen Eigenschaften Typen zuzuordnen, definieren Sie eine Schnittstelle in Ihrer Webpartklasse, die eine oder mehrere Zieleigenschaften umfasst.To assign types to these properties, define an interface in your web part class that includes one or more target properties.

export interface IHelloWorldWebPartProps {
    targetProperty: string
}

Diese steht dann in Ihrem Webpart über die this.properties.targetProperty zur Verfügung.This is then available in your web part by using this.properties.targetProperty.

<p class="ms-font-l ms-fontColor-white">${escape(this.properties.targetProperty)}</p>

Wenn die Eigenschaften definiert sind, können Sie in Ihrem Webpart mit der this.properties.[Eigenschaftsname] darauf zugreifen.When the properties are defined, you can access them in your web part by using the this.properties.[property-name]. Weitere Informationen finden Sie unter Render-Methode von HelloWorldWebPart.For more information, see render method of the HelloWorldWebPart.

Behandeln von FeldänderungenHandle field changes

Der Eigenschaftenbereich besteht aus zwei Interaktionsmodi:The property pane has two interaction modes:

  • ReaktivReactive
  • Nicht reaktivNon-reactive

Im reaktiven Modus wird bei jeder Änderung ein Änderungsereignis ausgelöst. Durch das reaktive Verhalten wird das Webpart automatisch mit den neuen Werten aktualisiert.In reactive mode, on every change, a change event is triggered. Reactive behavior automatically updates the web part with the new values.

Der reaktive Modus ist zwar für viele Szenarios ausreichend, manchmal benötigen Sie aber das nicht reaktive Verhalten.While reactive mode is sufficient for many scenarios, at times you need non-reactive behavior. Beim nicht reaktiven Verhalten wird das Webpart nicht automatisch aktualisiert, es sei denn, der Benutzer bestätigt die Änderungen.Non-reactive does not update the web part automatically unless the user confirms the changes.

Fügen Sie den folgenden Code zu Ihrem Webpart hinzu, um den nicht reaktiven Modus zu aktivieren:To turn on the non-reactive mode, add the following code in your web part:

protected get disableReactivePropertyChanges(): boolean { 
  return true; 
}

Benutzerdefinierte Eigenschaftenbereich-SteuerelementeCustom property pane controls

Das SharePoint Framework enthält eine Reihe von Standardsteuerelementen für den Eigenschaftenbereich.SharePoint Framework contains a set of standard controls for the property pane. Doch manchmal benötigen Sie zusätzliche Funktionen, die über die grundlegenden Steuerelemente hinausgehen.But sometimes you need additional functionality beyond the basic controls. Mit SharePoint Framework können Sie benutzerdefinierte Steuerelemente erstellen, um die erforderliche Funktionalität bereitzustellen.SharePoint Framework allows you to build custom controls to deliver the required functionality. Weitere Informationen finden Sie im Leitfaden Erstellen benutzerdefinierter Steuerelemente für den Eigenschaftenbereich.To learn more, read the Build custom controls for the property pane guide.

Siehe auchSee also