Adicionar suporte para ações principais

Cuidado

Essa versão está disponível atualmente como uma versão beta pública disponibilizada para teste.

Para ambientes de produção, recomendamos o uso da versão SPFx referenciada em Configurar seu ambiente de desenvolvimento da Estrutura do SharePoint.

Hoje, os usuários precisam estar cientes dos painéis de propriedades da Web Part para descobrir as opções adicionais que cada Web Part fornece. Esta é uma parte comum de comentários em que os usuários querem ações surgindo no contexto de onde estão sem precisar confiar em abrir algo para chegar a essas opções. Portanto, agora estamos permitindo a apresentação das configurações mais comuns do painel de propriedades de uma Web Part diretamente na barra de ferramentas da Web Part. Essas configurações comuns são chamadas de Ações Principais da Web Part.

Importante

Esse recurso ainda é status de visualização como parte da versão 1.16 e não deve ser usado na produção. Estamos procurando liberá-los oficialmente como parte da próxima versão 1.17. No momento da gravação deste artigo, o Top Actions dá suporte apenas à renderização de um comando suspenso e de botão.

Introdução

Dica

Essas instruções supõem que você sabe como criar uma Web Part do Hello World.

Definir suas configurações de Ação Superior

No exemplo abaixo, estamos definindo a função de retorno de chamada que será usada para puxar as configurações para nossos comandos top action.

Observação

getTopActionsConfiguration deve ser definido como público na classe da web part.

import { ITopActions } from '@microsoft/sp-top-actions';

public getTopActionsConfiguration(): ITopActions | undefined {
  return {
    topActions: [],
    onExecute: (actionName: string, newValue: any) => {}
  };
}

Definir a interface do usuário da barra de ferramentas

A topActions matriz é uma lista ordenada de controles a serem renderizados na barra de ferramentas da Web Part. No exemplo abaixo, estamos definindo uma ação superior como uma interface de botão.

import { PropertyPaneFieldType } from '@microsoft/sp-property-pane';

return {
  topActions: [
    {
      targetProperty: 'reset',
      properties: {
        icon: 'Reset'
      },
      type: PropertyPaneFieldType.Button
    }
  ]
  ...
}

Execute o comando quando o usuário interage

A etapa anterior demonstrou como obter um botão para ser exibido na barra de ferramentas da Web Part. Agora, executaremos uma ação quando o usuário selecionar o botão. Observe que actionName foi definido como na última etapa e, como targetProperty este é um botão, podemos ignorar o newValue que entra.

return {
  ...
  onExecute: (actionName: string, newValue: any) => {
    if (actionName === 'reset') {
      // user defined logic to reset the web part
      this.reset();
    }
  }
}

Dica

A armadilha comum ao implementar o onExecute comando não é sincronizar o novo estado com as propriedades da Web Part e/ou não atualizar ou renderizar novamente a Web Part.

Snippets de código

Comando button

A interacessão de tipo para um botão é semelhante ao botão do painel de propriedades (IPropertyPaneButtonProps).

import { ITopActions } from '@microsoft/sp-top-actions';
import { PropertyPaneFieldType } from '@microsoft/sp-property-pane';
...
public getTopActionsConfiguration(): ITopActions | undefined {
  return {
    topActions: [
      {
        targetProperty: 'reset',
        type: PropertyPaneFieldType.Button,
        properties: {
          icon: 'Reset'
        }
      }
    ],
    onExecute: (actionName: string, newValue: any) => {
      if (actionName === 'reset') {
        // user defined logic to reset the web part
        this.reset();
      }
    }
  };
}

Comando suspenso

A interface de tipo para uma lista suspensa é semelhante ao grupo de opções do painel de propriedades (IPropertyPaneChoiceGroupOption).

import { ITopActions } from '@microsoft/sp-top-actions';
import { PropertyPaneFieldType } from '@microsoft/sp-property-pane';
...
public getTopActionsConfiguration(): ITopActions | undefined {
  return {
    topActions: [{
      targetProperty: 'layout',
      type: PropertyPaneFieldType.ChoiceGroup,
      properties: {
        options: [
          {
            // key maps to newValue in onExecute
            key: 'card',
            text: 'Card Layout',
            imageSize: { width: 32, height: 32 },
            iconProps: { officeFabricIconFontName: 'ArticlesIcon' },
            checked: this.state.layout === 'card'
          },
          {
            key: 'list',
            text: 'List Layout',
            imageSize: { width: 32, height: 32 },
            // you can use iconProps, icon to define icons
            icon: 'List',
            checked: this.state.alignment === 'list'
          }
        ]
      }
    }],
    // for ChoiceGroup drop-down, the newValue tells us which option's key was selected
    onExecute: (actionName: string, newValue: any) => {
      if (actionName === 'layout') {
        this.setLayout(newValue);
        this.render();
      }
    }
  };
}

Configurações avançadas

Para configurações avançadas de seus principais comandos de ação, verifique as definições de tipo de @microsoft/sp-property-pane e @microsoft/sp-top-actions. Atualmente, os dois comandos de ação superior com suporte, botão e suspenso, podem ser definidos usando um subconjunto dos tipos IPropertyPaneChoiceGroupOption e IPropertyPaneButtonProps.

• Para IPropertyPaneButtonProps, as propriedades com suporte atualmente são icon, text, , ariaLabel, disabled
• Para IPropertyPaneChoiceGroupOption, o porperty com suporte no momento é options e dessa matriz oferecemos suporte keya , text, , iconProps.officeFabricIconFontName, imageSize, checkedtitle

import { IPropertyPaneButtonProps, IPropertyPaneChoiceGroupOption } from '@microsoft/sp-property-pane'
import { ITopActions } from '@microsoft/sp-top-actions';

Veja mais

IPropertyPaneButtonPropsIPropertyPaneChoiceGroupOption