Gerador Yeoman para a Estrutura do SharePoint

  • Artigo

O SharePoint Online SPFx Yeoman Generator ajuda-o a criar rapidamente um projeto de solução do lado do cliente SharePoint com a cadeia de ferramentas e a estrutura de projeto certas. Ele é usado junto com Yeoman para solicitar perguntas para criar o scaffolding do projeto (os arquivos de pastas & ).

Importante

Esta página pressupõe que você já instalou todos os pré-requisitos necessários para desenvolver soluções da Estrutura do SharePoint. Verifique as instruções atualizadas descritas na página Conjunto de desenvolvimento da Estrutura do SharePoint.

O Gerador Yeoman do SharePoint Online SPFx (O “gerador SPFx”) usa as respostas às perguntas que o desenvolvedor é solicitado a criar um novo projeto da Estrutura do SharePoint (SPFx). Dependendo de algumas respostas de prompt, outras perguntas são apresentadas.

Por exemplo, se você selecionar o tipo de componente WebPart só verá perguntas sobre o nome da web part e o tipo de modelo. No entanto, se você selecionar o tipo de componente de Extensão, também será solicitado o tipo de extensão, como personalizador de aplicativo, personalizador de campo ou conjunto de comandos ListView.

O exemplo a seguir demonstra a criação de uma nova solução chamada sfpxplay-01 na pasta atual com uma web part chamada HelloWorld que usa o modelo de projeto Mínimo:

yo @microsoft/sharepoint --skip-install

     _-----_     ╭──────────────────────────╮
    |       |    │      Welcome to the      │
    |--(o)--|    │  SharePoint Online SPFx  │
   `---------´   │          Yeoman          │
    ( _´U`_ )    │     Generator@1.14.0     │
    /___A___\   /╰──────────────────────────╯
     |  ~  |
   __'.___.'__
 ´   `  |° ´ Y `

Let's create a new SharePoint solution.
? What is your solution name? spfxplay-01
? Which type of client-side component to create? WebPart
Add new Web part to solution spfxplay-01.
? What is your Web part name? HelloWorld
? Which template would you like to use? Minimal

   create package.json
    force .yo-rc.json
   create config/package-solution.json
   create config/config.json
   create config/serve.json
   create tsconfig.json
   create .vscode/launch.json
   create .vscode/settings.json
   create config/deploy-azure-storage.json
   create config/write-manifests.json
   create src/index.ts
   create README.md
   create .gitignore
   create .npmignore
   create gulpfile.js
   create tslint.json
   create src/webparts/helloWorld/loc/en-us.js
   create src/webparts/helloWorld/loc/mystrings.d.ts
   create src/webparts/helloWorld/HelloWorldWebPart.module.scss
   create src/webparts/helloWorld/HelloWorldWebPart.ts
   create src/webparts/helloWorld/HelloWorldWebPart.manifest.json
   create teams/55564fc2-179d-4bc1-bd63-9ede8183dadc_outline.png
   create teams/55564fc2-179d-4bc1-bd63-9ede8183dadc_color.png

Changes to package.json were detected.
Skipping package manager install.

      _=+#####!
   ###########|       .------------------------------------.
   ###/    (##|(@)    |          Congratulations!          |
   ###  ######|   \   |  Solution spfxplay-01 is created.  |
   ###/   /###|   (@) |   Run gulp serve to play with it!  |
   #######  ##|   /   '------------------------------------'
   ###     /##|(@)
   ###########|
      **=+####!

Dica

Os diferentes tipos de componentes e opções são abordados em toda a documentação deste site. Todas as opções não são abordadas nesta página. Para obter mais informações sobre os detalhes sobre cada tipo de componente, consulte os tópicos relevantes em toda a documentação.

Instale o Gerador Yeoman do SharePoint Online SPFx

O gerador SPFx está disponível como um pacote npm. Instale a versão mais recente do gerador SPFx, executando o seguinte comando em um console:

npm install @microsoft/generator-sharepoint -g

Você também pode instalar uma versão específica do gerador indicando o número da versão no nome do pacote, separado por um @1. Por exemplo, para instalar o gerador SPFx v1.10, execute o seguinte comando:

npm install @microsoft/generator-sharepoint@1.10 -g

Opções de modelo de projeto

Antes do SPFx v1.14, o gerador forneceu aos desenvolvedores dois modelos de projeto:

  • Sem estruturas de JavaScript:
  • React

Observação

Uma terceira opção Knockout, estava disponível em todas as versões SPFx por meio do SPFx v1.10. Knockout foi desativado como uma opção no SPFx v1.11.

Esses modelos incluíam o código mínimo que um projeto precisava para começar a criar soluções. O modelo No JavaScript Framework usou HTML e CSS para estilizar um componente básico enquanto o modelo React usou HTML, React e CSS para fazer a mesma coisa.

Modelos de projeto atualizados no SPFx v1.14 com suporte a tema

Na versão SPFx v1.14, o gerador SPFx introduziu novos & modelos de projeto atualizados. O objetivo desses modelos é incluir o código necessário para dar suporte ao tema no ambiente atual em que o componente está em execução (SharePoint ou Microsoft Teams).

O código incluído nesses modelos simplifica o trabalho inicial que os desenvolvedores devem fazer para adicionar suporte a temas a seus componentes. Por exemplo, usando esses modelos, todo o código necessário para determinar as cores e a fonte usadas no site atual do SharePoint estão disponíveis na web part e a web part será notificada quando o tema for alterado para selecionar as novas configurações de tema.

Para componentes SPFx usados no contexto do Microsoft Teams, eles receberão os detalhes do tema para o cliente atual do Microsoft Teams, como padrão (claro), escuro e alto contraste.

Além disso, esses modelos incluem o código para determinar se o componente está em execução no momento em um contexto do SharePoint ou em um contexto do Microsoft Teams.

Por exemplo, os métodos a seguir são incluídos em ambos os modelos. O método _getEnvironmentMessage() retorna uma cadeia de caracteres que indica se o componente está sendo executado atualmente no SharePoint ou no Microsoft Teams e se ele está implantado em produção ou em desenvolvimento (servido do localhost). O onThemeChanged() determina se o tema atual está no modo escuro e aplica algumas alterações às propriedades com base nas cores do tema atual:

private _getEnvironmentMessage(): string {
  if (!!this.context.sdks.microsoftTeams) { // running in Teams
    return this.context.isServedFromLocalhost
        ? strings.AppLocalEnvironmentTeams
        : strings.AppTeamsTabEnvironment;
  }

  return this.context.isServedFromLocalhost
        ? strings.AppLocalEnvironmentSharePoint
        : strings.AppSharePointEnvironment;
}

protected onThemeChanged(currentTheme: IReadonlyTheme | undefined): void {
  if (!currentTheme) {
    return;
  }

  this._isDarkTheme = !!currentTheme.isInverted;
  const {
    semanticColors
  } = currentTheme;
  this.domElement.style.setProperty('--bodyText', semanticColors.bodyText);
  this.domElement.style.setProperty('--link', semanticColors.link);
  this.domElement.style.setProperty('--linkHovered', semanticColors.linkHovered);

}

Modelo de projeto mínimo

Uma nova opção de modelo de projeto, Mínimo, foi adicionada ao gerador SPFx no SPFx v1.14. Essa opção de modelo de projeto não inclui nenhum tema ou código de ambiente de host em novos projetos.

Por exemplo, um novo projeto de web part começa com o código a seguir, representando o código mínimo necessário para executar a web part:

export default class HelloWorldMinimalWebPart
          extends BaseClientSideWebPart<IHelloWorldMinimalWebPartProps> {

  protected onInit(): Promise<void> {
    return super.onInit();
  }

  public render(): void {
    this.domElement.innerHTML = `<div class="${ styles.helloWorldMinimal }"></div>`;
  }

  protected get dataVersion(): Version {
    return Version.parse('1.0');
  }
}

Prompts de gerador desativados

A cada versão da Estrutura do SharePoint, os prompts podem ser adicionados ou removidos no gerador Yeoman. Os prompts foram removidos para simplificar a experiência de criação do projeto.

Na seção a seguir, você encontrará os prompts desativados com as diretrizes aplicáveis.

Direcionar diferentes Ambientes do SharePoint

No lançamento do SPFx v1.13, o seguinte prompt foi retirado:

Quais pacotes de linha de base deseja direcionar para seus componentes?

Este prompt apresentou ao desenvolvedor a opção de criar um projeto direcionado a implantações específicas do SharePoint, incluindo:

  • Somente SharePoint Online (mais recente)
  • SharePoint 2016 em diante, incluindo 2019 e SharePoint Online
  • SharePoint 2019 em diante, incluindo o SharePoint Online

A partir do SPFx v1.13, o gerador só pode criar projetos para o SharePoint Online.

Pular ferramenta de desenvolvimento - skipFeatureDeployment

No lançamento do SPFx v1.14, o seguinte prompt foi retirado:

Você deseja permitir que o administrador de locatários possa implantar a solução para todos os sites imediatamente sem executar qualquer implantação de recurso ou adicionar aplicativos aos sites?

Esta pergunta é se a solução deve ser instalada automaticamente para todos os locais do inquilino, ou deve ser instalada manualmente em cada local? A opção padrão era [N]o.

Observação

Saiba mais sobre este prompt: Implantação de solução com escopo de locatário para soluções da Estrutura do SharePoint.

O resultado desta pergunta foi fixado na skipFeatureDeploymentpropriedade do projeto ./config/package-solution.json arquivo.

A partir do SPFx v1.14, a propriedade skipFeatureDeployment usa como padrão true. Você pode alterar o valor dessa propriedade depois de criar o projeto, se necessário.

Web Parts de domínio isolado - isDomainIsolated

No lançamento do SPFx v1.14, o seguinte prompt foi retirado:

Os componentes da solução exigem permissões para acessar as APIs da Web que são exclusivas e não são compartilhadas com outros componentes no locatário?

Essa pergunta está perguntando se as web parts dentro da solução devem ser renderizadas em um IFRAME em um domínio exclusivo ou em um DIV como a página atual. A opção padrão era [N]o.

Observação

Saiba mais sobre esse prompt: Web parts isoladas

O resultado desta pergunta foi fixado na isDomainIsolatedpropriedade do projeto ./config/package-solution.json arquivo.

A partir do SPFx v1.14, a propriedade isDomainIsolated usa como padrão false. Você pode alterar o valor dessa propriedade depois de criar o projeto, se necessário.

Qual estrutura você deseja usar?

No lançamento do SPFx v1.14, o seguinte prompt foi alterado:

Qual estrutura você deseja usar?

Esse prompt foi exibido para tipos de projeto específicos, como tipos de web parts & de extensões SPFx. Ele permite que os desenvolvedores selecionem de diferentes modelos de projeto: Sem estrutura JavaScript ou Reagir.

O scaffolding de projeto padrão criado pelo gerador Yeoman foi determinado usando a opção selecionada.

No SPFx v1.14, esse prompt foi alterado para o seguinte e apresentou ao usuário três opções: Mínima, Nenhuma estrutura, ou Reagir:

Qual modelo você deseja usar?

Descrições do componente

No Lançamento do SPFx v1.14, nos seguintes prompts foram retirados:

Qual é a descrição da Web Part?

Qual é a sua descrição do Personalizador de Aplicativo?

Qual é a sua descrição do Personalizador de Campos?

Qual é a descrição do Conjunto de Comandos ListView?

Qual é a descrição da Biblioteca?

Qual é a descrição da Extensão de Cartão Adaptável?

Os valores desses prompts foram definidos nas preConfiguredEntries[0].description.default&preConfiguredEntries[0].properties.description propriedades no arquivo *.manifest.json do componente.

A partir do SPFx v1.14, essas propriedades são definidas como cadeias de caracteres vazias. Você pode alterar o valor dessas propriedades depois de criar o projeto, se necessário.

Opções de linha de comando do gerador SPFx

Você pode usar as opções de linha de comando do gerador SPFx para criar projetos em um só comando, em vez de ter que passar por cada um dos prompts. Execute o seguinte comando para ver a lista de opções de linha de comando disponíveis para o gerador do SharePoint:

yo @microsoft/sharepoint --help