Como utilizar o SharePoint Framework (SPFx)

O SharePoint Framework (SPFx) é um modelo de desenvolvimento baseado em cliente que permite criar soluções modernas e personalizadas para o SharePoint Online e o Microsoft Teams. Baseado em tecnologias como TypeScript, React e Node.js, o SPFx oferece uma abordagem flexível e compatível com o ecossistema Microsoft 365.

Este guia tem como objetivo apresentar, de forma objetiva e técnica, os passos para iniciar o desenvolvimento de componentes utilizando o SPFx.

Pré-requisitos

Antes de iniciar o desenvolvimento com SPFx, é necessário garantir que o ambiente de desenvolvimento esteja devidamente configurado. Os seguintes softwares devem ser instalados:

1. Node.js (versão LTS 18.x)
   Disponível em: https://nodejs.org/

Atenção: o SPFx possui dependência direta com a versão do Node.js. Verifique a compatibilidade na documentação oficial.

2. Yeoman e gerador do SharePoint
   Utilizados para gerar a estrutura básica do projeto:
3. npm install -g yo @microsoft/generator-sharepoint
4. Gulp (executor de tarefas)
   Necessário para executar tarefas de build e empacotamento:
5. npm install -g gulp
6. Editor de código-fonte
   O Visual Studio Code é recomendado: https://code.visualstudio.com/

Etapas para criar um web part com SPFx

1. Criação do diretório do projeto

Abra o terminal e crie um diretório para o projeto:

mkdir spfx-helloworld

cd spfx-helloworld

2. Execução do gerador Yeoman

Inicie a criação da solução SPFx com o comando:

yo @microsoft/sharepoint

Durante a execução, serão solicitadas as seguintes informações:

• Nome da solução: spfx-helloworld
• Ambiente de destino: SharePoint Online Only (mais recente)
• Diretório do projeto: usar pasta atual
• Tipo de componente: WebPart
• Nome do web part: exemplo: HelloWorld
• Framework: React (ou outra opção, conforme preferido)

Após a conclusão, a estrutura do projeto será gerada automaticamente.

3. Execução em ambiente de desenvolvimento local

Utilize o seguinte comando para iniciar o servidor de desenvolvimento e acessar a Workbench local:

gulp serve

Acesse no navegador:
https://localhost:4321/temp/workbench.html

Neste ambiente é possível adicionar e testar o web part localmente, sem a necessidade de publicação no SharePoint.

4. Personalização do componente

Abra o projeto no Visual Studio Code:

code .

Altere o conteúdo do componente localizado em:

/src/webparts/helloWorld/components/

O desenvolvimento pode ser feito em React, conforme a estrutura padrão gerada pelo template.

5. Empacotamento para produção

Após a finalização do desenvolvimento e testes locais, execute os comandos abaixo para gerar o pacote de produção:

gulp bundle –ship

gulp package-solution –ship

O pacote .sppkg será gerado no diretório:
sharepoint/solution/

6. Publicação no SharePoint Online

1. Acesse o Catálogo de Aplicativos no centro de administração do SharePoint.
2. Faça upload do arquivo .sppkg.
3. Confirme a aceitação do pacote e a concessão de permissões (se aplicável).
4. O componente estará disponível para ser adicionado às páginas do SharePoint Online.

Recursos adicionais e extensões

Além de web parts, o SPFx também permite o desenvolvimento dos seguintes componentes:

• Extensões: Application Customizers, Field Customizers e Command Sets.
• Integração com APIs: suporte nativo à Microsoft Graph via MSGraphClient ou bibliotecas como PnPjs.
• Uso de bibliotecas externas: como Fluent UI, Chart.js, entre outras.

Boas práticas

• Mantenha o ambiente atualizado e compatível com as versões suportadas.
• Utilize o Workbench online (/sites/seusite/_layouts/15/workbench.aspx) para testes com dados reais.
• Implemente tratamento de erros e lógica de fallback para garantir robustez.
• Armazene as configurações do web part no arquivo manifest.json e nas interfaces de propriedades (IWebPartProps).

Veja também nosso artigo sobre Por que atualizar para o SharePoint Framework (SPFx) é essencial.