Usar caixas de diálogo personalizadas com extensões da Estrutura do SharePoint

Artigo
03/21/2023

Você pode usar caixas de diálogo personalizadas, disponíveis no pacote @microsoft/sp-dialog, dentro do contexto das Extensões da Estrutura do SharePoint ou das Web Parts do lado do cliente.

Este artigo descreve como criar uma caixa de diálogo personalizada e usá-la dentro do contexto de uma extensão Conjunto de Comandos ListView.

Você pode acessar a amostra de código em que este artigo se baseia no repositório sp-dev-fx-extensions.

Importante

Esse tutorial pressupõe que você configurou seu ambiente de desenvolvimento conforme o explicado em Configurar seu ambiente de desenvolvimento.

Criar um novo projeto

Crie um novo diretório de projeto para o seu projeto e altere a pasta atual para esse diretório.
Crie um novo projeto executando o Gerador Yeoman do SharePoint a partir do novo diretório que você criou:
```
yo @microsoft/sharepoint
```
Quando solicitado, insira os seguintes valores (selecione a opção padrão para todos os avisos omitidos abaixo):
- Que tipo de componente do cliente será criado? Extensão
- Que tipo de extensão do lado do cliente criar? Conjunto de comandos ListView
- Qual é o nome do seu Conjunto de Comandos? DialogDemo
Neste ponto, o Yeoman instalará as dependências necessárias e manterá a estrutura dos arquivos da solução. Esse processo pode levar alguns minutos.
Quando o scaffolding inicial for concluído, digite o seguinte para instalar o Office UI Fabric em sua solução:
```
npm install office-ui-fabric-react  --save
```
Abra a pasta do projeto no seu editor de código. Este artigo usa o Visual Studio Code nas etapas e capturas de tela, mas você pode usar o editor que preferir. Para abrir a pasta no Visual Studio Code, use o seguinte comando no console:
```
code .
```

Modificar o manifesto da extensão

No manifesto de extensão, configure a extensão para ter apenas um botão. No editor de código, abra o arquivo ./src/extensions/dialogDemo/DialogDemoCommandSet.manifest.json . Substitua a seção de comandos pelo seguinte JSON:

{
  //...
  "items": {
    "COMMAND_1": {
      "title": { "default": "Open Custom Dialog" },
      "iconImageUrl": "icons/request.png",
      "type": "command"
    }
  }
}

Criar uma caixa de diálogo personalizada

Crie um novo arquivo chamado ColorPickerDialog.tsx na pasta ./src/extensions/dialogDemo/.

Adicione as seguintes instruções de importação na parte superior do arquivo que foi criado recentemente. Você está criando uma caixa de diálogo personalizada usando componentes do Office UI Fabric React, portanto, a implementação estará em React.

import * as React from 'react';
import * as ReactDOM from 'react-dom';
import { BaseDialog, IDialogConfiguration } from '@microsoft/sp-dialog';
import { PrimaryButton, DefaultButton } from 'office-ui-fabric-react/lib/Button';
import { ColorPicker } from 'office-ui-fabric-react/lib/ColorPicker';
import { DialogFooter, DialogContent } from 'office-ui-fabric-react/lib/Dialog';
import { IColor } from 'office-ui-fabric-react/lib/Color';

Adicione a definição de interface a seguir logo abaixo das instruções de importação. Ela será usada para passar informações e funções entre a extensão Conjunto de Comandos ListView e a caixa de diálogo personalizada.
```
interface IColorPickerDialogContentProps {
  message: string;
  close: () => void;
  submit: (color: IColor) => void;
  defaultColor?: IColor;
}
```

Adicione a classe a seguir logo abaixo da definição da interface. Esta classe da React é responsável pela renderização das experiências da interface do usuário na caixa de diálogo personalizada. Observe que você usa componentes do Office UI Fabric React na renderização real e apenas passa as propriedades necessárias.

class ColorPickerDialogContent extends React.Component<IColorPickerDialogContentProps, {}> {
  private _pickedColor: IColor;

  constructor(props) {
    super(props);
    // Default Color
    this._pickedColor = props.defaultColor || { hex: 'FFFFFF', str: '', r: null, g: null, b: null, h: null, s: null, v: null };
  }

  public render(): JSX.Element {
    return <DialogContent
    title='Color Picker'
    subText={this.props.message}
    onDismiss={this.props.close}
    showCloseButton={true}
    >
    <ColorPicker color={this._pickedColor} onChange={this._onColorChange} />
    <DialogFooter>
        <DefaultButton text='Cancel' title='Cancel' onClick={this.props.close} />
        <PrimaryButton text='OK' title='OK' onClick={() => { this.props.submit(this._pickedColor); }} />
    </DialogFooter>
    </DialogContent>;
  }

  private _onColorChange = (ev: React.SyntheticEvent<HTMLElement, Event>, color: IColor) => {
    this._pickedColor = color;
  }
}

Adicione a definição da classe a seguir à caixa de diálogo personalizada abaixo da classe ColorPickerDialogContent adicionada. Esta é a caixa de diálogo personalizada real, que será chamada ao clicar no botão Conjunto de Comandos ListView e é herdada de BaseDialog.

export default class ColorPickerDialog extends BaseDialog {
  public message: string;
  public colorCode: IColor;

  public render(): void {
    ReactDOM.render(<ColorPickerDialogContent
    close={ this.close }
    message={ this.message }
    defaultColor={ this.colorCode }
    submit={ this._submit }
    />, this.domElement);
  }

  public getConfig(): IDialogConfiguration {
    return { isBlocking: false };
  }

  protected onAfterClose(): void {
    super.onAfterClose();

    // Clean up the element for the next dialog
    ReactDOM.unmountComponentAtNode(this.domElement);
  }

  private _submit = (color: IColor) => {
    this.colorCode = color;
    this.close();
  }
}

Associar a caixa de diálogo ao clique no botão Conjunto de Comandos ListView

Para associar a caixa de diálogo personalizada ao Conjunto de Comandos ListView personalizado, adicione o código para iniciar a caixa de diálogo à operação de clique de botão.

No editor de códigos, abra o arquivo DialogDemoCommandSet.ts da pasta ./src/extensions/dialogDemo/.
Adicione as seguintes instruções de importação na importação de cadeia de caracteres existente. Elas servem para usar a caixa de diálogo personalizada no contexto do seu Conjunto de Comandos ListView e usar o tipo IColor para passar cores para a nossa caixa de diálogo e a partir da mesma.
```
import ColorPickerDialog from './ColorPickerDialog';
import { IColor } from 'office-ui-fabric-react/lib/Color';
```
Adicione a definição de variável a seguir _colorCode acima da onInit função na DialogDemoCommandSet classe. Isso é usado para armazenar o resultado da caixa de diálogo seletor de cores.
```
private _colorCode: IColor;
```

Atualize a função da onExecute seguinte maneira. Esse código faz o seguinte:

Inicia a caixa de diálogo personalizada.
Passa uma mensagem para a caixa de diálogo, que é usada para o título.
Passa um código de cor para a caixa de diálogo com um valor padrão, se ainda não estiver definido.
Mostra a caixa de diálogo personalizada.
Recebe e armazena o valor de retorno da caixa de diálogo.
Mostra o valor recebido em uma caixa de diálogo padrão usando a função Dialog.alert().

@override
public onExecute(event: IListViewCommandSetExecuteEventParameters): void {
  switch (event.itemId) {
    case 'COMMAND_1':
      Dialog.alert(`${this.properties.sampleTextOne}`);
      const dialog: ColorPickerDialog = new ColorPickerDialog();
      dialog.message = 'Pick a color:';
      // Use 'FFFFFF' as the default color for first usage
      let defaultColor : IColor = { hex: 'FFFFFF', str: '', r: null, g: null, b: null, h: null, s: null, v: null };
      dialog.colorCode = this._colorCode|| defaultColor;
      dialog.show().then(() => {
        this._colorCode = dialog.colorCode;
        Dialog.alert(`Picked color: ${dialog.colorCode.hex}`);
      });
      break;
    default:
      throw new Error('Unknown command');
  }
}

Testar a caixa de diálogo em seu locatário

Abra o arquivo serve.json na pasta ./config/ e atualize as configurações atuais no arquivo. Esse arquivo é usado para facilitar a depuração das Extensões da Estrutura do SharePoint. Você pode atualizar o conteúdo do arquivo para combinar os próprios detalhes do locatário e do site onde deseja testar a extensão. O valor-chave para atualização é a propriedade pageUrl na definição do json para coincidir com seu próprio locatário.

Atualize pageUrl para apontar para uma URL de lista onde você deseja testar a funcionalidade do diálogo.

  "serveConfigurations": {
    "default": {
      "pageUrl": "https://yourtenantname.sharepoint.com/Shared%20Documents/Forms/AllItems.aspx",
      "customActions": {
        "9b98b919-fe5e-4758-ac91-6d62e582c4fe": {
          "location": "ClientSideExtension.ListViewCommandSet.CommandBar",
          "properties": {
            "sampleTextOne": "One item is selected in the list",
            "sampleTextTwo": "This command is always visible."
          }
        }
      }
    },

Observação

O identificador exclusivo da extensão é atualizado automaticamente para esse arquivo durante a estruturação inicial. Se você atualizar as propriedades que sua extensão usará, atualize serve.json antes de iniciar a depuração.

Retorne ao console e execute o seguinte comando:
```
gulp serve
```

Isso iniciará o agrupamento da solução e atenderá o manifesto resultante do endereço localhost. Devido à configuração no arquivo serve.json, ele também abre um navegador na URL específica configurando automaticamente os parâmetros de consulta com base na configuração da solução.

Aceite o carregamento de manifestos de depuração clicando em Carregar scripts de depuração quando solicitado.

Observe que o novo botão não está visível na barra de ferramentas por padrão já que a solução padrão requer que você escolha um item na lista. Se você não tiver itens na lista ou na biblioteca, crie um item ou carregue um documento.
Escolha um item na lista ou na biblioteca e observe como o botão Abrir Caixa de Diálogo Personalizada fica visível na barra de ferramentas.
Clique no botão Abrir Caixa de Diálogo Personalizada para ver a caixa de diálogo personalizada renderizada dentro da exibição de lista.
Escolha uma cor no Seletor de Cores e marque OK para testar como o código está retornando o valor escolhido ao chamador. Em seguida, a seleção é exibida usando a caixa de diálogo de alerta padrão.

Observação

Se você encontrar um problema na documentação ou na Estrutura do SharePoint, informe a engenharia do SharePoint usando a lista de problemas no repositório sp-dev-docs. Agradecemos antecipadamente pela informação.

Confira também

Visão geral das extensões da Estrutura do SharePoint

Compartilhar via