Torne configurável a Web Part do SharePoint do lado do cliente

O painel de propriedades permite que os usuários finais configurem a Web Part com várias propriedades. O artigo Criar a primeira Web Part descreve como o painel de propriedades é definido na classe HelloWorldWebPart. As propriedades do painel de propriedades são definidas em propertyPaneSettings.

Um painel de propriedades contém três metadados: uma página, um cabeçalho opcional e pelo menos um grupo.

• As páginas fornecem a flexibilidade de separar interações complexas e colocá-las em uma ou mais páginas. As páginas contêm um cabeçalho e grupos.
• Cabeçalhos permitem que você defina o título do painel de propriedade.
• Grupos permitem que você defina várias seções ou campos para o painel de propriedade pelos quais você deseja agrupar seus conjuntos de campo.

A figura a seguir mostra um exemplo de um painel de propriedades no SharePoint.

Configurar o painel de propriedades

O exemplo a seguir inicializa e configura o painel de propriedades na Web Part. Você substitui o método getPropertyPaneConfiguration() e retorna uma coleção de páginas do painel de propriedades.

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

Campos do painel de propriedades

Há suporte para os seguintes tipos de campos:

• Botão
• Caixa de seleção
• Grupo de escolha
• Lista suspensa
• Régua horizontal
• Rótulo
• Link
• Controle Deslizante
• Caixa de texto
• Caixa de texto de várias linhas
• Alternância
• Personalizado

Os tipos de campo estão disponíveis como módulos no @microsoft/sp-property-pane. Você precisa importar os objetos para um módulo antes de usá-los em suas Web Parts:

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

Observação

Os objetos do painel de propriedades foram divididos em seu próprio módulo, @microsoft/sp-property-pane, na versão Estrutura do SharePoint v1.9. Antes disso, eles foram incluídos no módulo @microsoft/sp-webpart-base .

Cada método de tipo de campo é definido da seguinte maneira, tomando PropertyPaneTextField como exemplo:

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

O targetProperty define o objeto associado para esse tipo de campo e também é definido na interface de propriedades na Web Part.

Para atribuir tipos a essas propriedades, defina uma interface na classe da Web Part que inclua um ou mais propriedades de destino.

export interface IHelloWorldWebPartProps {
  targetProperty: string
}

Isso está disponível em sua Web Part usando this.properties.targetProperty.

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

Quando as propriedades são definidas, você pode acessá-las na web part usando o this.properties.[property-name]. Para obter mais informações, consulte Compilar uma web part HelloWorld: método de renderização() de Web Part.

Lidar com alterações de campo

O painel de propriedades tem dois modos de interação:

• Reativo
• Não reativo

No modo reativo, em cada alteração em um controle de campo no painel de propriedades dispara o evento de alteração. O comportamento reativo atualiza automaticamente a Web Part com os novos valores. O modo reativo é o modo padrão para Web Parts.

Embora o modo reativo seja suficiente para muitos cenários, às vezes você precisará do comportamento não reativo. O não reativo não atualiza a Web Part automaticamente, a menos que o usuário confirme as alterações.

Para ativar o modo não reativo, adicione o seguinte código em sua Web Part:

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

Controles de painel de propriedades personalizadas

A Estrutura do SharePoint contém um conjunto de controles padrão para o painel de propriedades. No entanto, às vezes, você precisa de funcionalidade adicional além dos controles básicos. A Estrutura do SharePoint permite criar controles personalizados para fornecer os recursos necessários. Para saber mais, leia o guia Criar controles personalizados para o painel de propriedades.

Confira também

• Visão geral da Estrutura do SharePoint