Usar componentes do Office UI Fabric React na sua Web Part do lado do cliente do SharePoint

2023-03-21

O Office UI Fabric React é a estrutura de front-end para criar experiências para o Office e para o Office 365. Ele inclui um conjunto robusto de componentes dinâmicos e voltados para a mobilidade para facilitar a criação de experiências da Web usando o Office Design Language.

Este artigo descreve como compilar uma Web Part simples, como na imagem a seguir, que usa o componente DocumentCard do Office UI Fabric React.

Imagem de um componente DocumentCard Fabric no SharePoint Workbench

Você também pode seguir estas etapas assistindo a este vídeo no Canal do YouTube da Comunidade (PnP) da Plataforma Microsoft 365:

React de interface do usuário fluente do Office UI Fabric React &

Observação

A Microsoft renomeou o Office UI Fabric para Fluent UI no início de 2020.

A transição do Office UI Fabric para a IU do Fluent e os respectivos componentes do React está atualmente em estado de transição. Para saber mais sobre o estado atual e seu roteiro, consulte as perguntas frequentes fornecidas pela equipe do Fluent UI: Perguntas frequentes sobre o Fabric e Stardust para o Fluent UI.

Atualmente, os pacotes da Estrutura do SharePoint (SPFx) referenciam os Pacotes NPM originais do Office UI Fabric. No momento, esses pacotes com & suporte continuarão funcionando.

O pacote de React de interface do usuário fluente primário, @fluentui/react, simplesmente exporta componentes do pacote office-ui-fabric-react usado em projetos Estrutura do SharePoint. Neste momento, você deve continuar a usar o office-ui-fabric-react em seus projetos da Estrutura do SharePoint.

Esta página continuará direcionando aos pacotes do Office UI Fabric até que a Microsoft recomende alternar para os pacotes do Fluent UI. Os links de documentação nesta página podem apontar para a documentação do Fluent UI, mas também se aplicam ao Office UI Fabric.

Site do Fluent UI: documentação detalhada da API juntamente com exemplos de código de implementação para cada controle.
Referência da API: documentação detalhada da API.
Office UI Fabric React / Fluent UI React: repositório de código-fonte no github.

Criar um projeto de web part

Crie um novo diretório de projeto em seu local favorito:
```
md documentcardexample-webpart
```
Vá para o diretório do projeto:
```
cd documentcardexample-webpart
```
Crie um novo projeto executando o Gerador Yeoman do SharePoint a partir do novo diretório que você criou:
```
yo @microsoft/sharepoint
```
O Gerador Yeoman do Microsoft Office SharePoint Online solicitará uma série de perguntas. Para todas as perguntas, aceite as opções padrão, exceto para as seguintes perguntas:
- Que tipo de componente para o cliente você deseja criar?: Web Part
- Qual modelo você gostaria de usar?: React
Neste ponto, o Yeoman instalará as dependências necessárias e manterá a estrutura dos arquivos da solução.

Começando com a versão SPFx v1.8.2, o Yeoman incluirá a versão recomendada do pacote @microsoft/sp-office-ui-fabric-core para sua solução quando você selecionar o React como a estrutura web desejada.
Observação

A partir do SPFx v1.8, você pode usar o Office UI Fabric React v5 ou v6. Cada versão do SPFx atualiza a versão do Office UI Fabric React em novos projetos. Por exemplo:
- Projetos do SPFx v1.8 usam o Office UI Fabric React v5.132.0 por padrão
- Os projetos SPFx v1.9 & v1.10 usam o Office UI Fabric React v6.189.2 por padrão
Versões diferentes do Office UI Fabric React têm dependências diferentes em versões do TypeScript. Se você quiser atualizar um projeto SPFx existente para uma versão mais recente do Office UI Fabric React, consulte a seção a seguir: Apêndice: Atualizando as versões do Office UI Fabric React

Esta página pressupõe que você está usando a versão mais recente da Estrutura do SharePoint.
Em seguida, execute o seguinte comando para abrir o projeto de Web part no Visual Studio Code:
```
code .
```
Agora você tem um projeto de Web part com a estrutura da Web do React.

Abra DocumentCardExampleWebPart.ts na pasta src\webparts\documentCardExample.

Como você pode ver, o método render() cria um elemento react e renderiza-o no DOM da Web Part.

public render(): void {
  const element: React.ReactElement<IDocumentCardExampleProps> = React.createElement(
    DocumentCardExample,
    {
      description: this.properties.description
    }
  );

  ReactDom.render(element, this.domElement);
}

Abra DocumentCardExample.tsx na pasta src\webparts\documentCardExample\components.

Este é o principal componente do react que o Yeoman adicionou ao projeto que renderiza no DOM da Web Part.

export default class DocumentCardExample extends React.Component<IDocumentCardExampleProps, {}> {
  public render(): React.ReactElement<IDocumentCardExampleProps> {
    return (
      <div className={ styles.documentCardExample }>
        <div className={ styles.container }>
          <div className={ styles.row }>
            <div className={ styles.column }>
              <span className={ styles.title }>Welcome to SharePoint!</span>
              <p className={ styles.subTitle }>Customize SharePoint experiences using web parts.</p>
              <p className={ styles.description }>{escape(this.props.description)}</p>
              <a href="https://aka.ms/spfx" className={ styles.button }>
                <span className={ styles.label }>Learn more</span>
              </a>
            </div>
          </div>
        </div>
      </div>
    );
  }
}

Adicionar um componente do Office UI Fabric

As novas experiências modernas no SharePoint usam o Office UI Fabric e Office UI Fabric React como estrutura front-end padrão para criar novas experiências. Como resultado, a Estrutura do SharePoint vem com uma versão padrão do Office UI Fabric e Fabric React que corresponde à versão disponível no SharePoint. Isso garante que a web part que você está compilando usa a versão correta dos componentes e estilos do Fabric quando implantada no SharePoint.

Como escolhemos React como a estrutura ao criar a solução, o gerador também instalou a versão correta do Office UI Fabric React. É possível importar diretamente os componentes do Fabric nos componentes react sem trabalho adicional.

Para adicionar um componente do Office UI Fabric

Abra DocumentCardExample.tsx na pasta src\webparts\documentCardExample\components.

Adicione a seguinte instrução import sobre o arquivo para importar os componentes Fabric React que desejamos usar.

import {
  DocumentCard,
  DocumentCardPreview,
  DocumentCardTitle,
  DocumentCardActivity,
  IDocumentCardPreviewProps
} from 'office-ui-fabric-react/lib/DocumentCard';

Substitua o método render() existente pelo seguinte:

public render(): JSX.Element {
  const previewProps: IDocumentCardPreviewProps = {
    previewImages: [
      {
        previewImageSrc: String(require('./document-preview.png')),
        iconSrc: String(require('./icon-ppt.png')),
        width: 318,
        height: 196,
        accentColor: '#ce4b1f'
      }
    ],
  };

  return (
    <DocumentCard onClickHref='http://bing.com'>
      <DocumentCardPreview { ...previewProps } />
      <DocumentCardTitle title='Revenue stream proposal fiscal year 2016 version02.pptx' />
      <DocumentCardActivity
        activity='Created Feb 23, 2016'
        people={
          [
            { name: 'Kat Larrson', profileImageSrc: String(require('./avatar-kat.png')) }
          ]
        }
      />
    </DocumentCard>
  );
}

Salve o arquivo.

Neste código, o componente DocumentCard inclui algumas seções extras:
- DocumentCardPreview
- DocumentCardTitle
- DocumentCardActivity
A propriedade previewProps inclui algumas propriedades do componente DocumentCardPreview.

Copiar os ativos de imagem

Copie as seguintes imagens para a pasta src\webparts\documentCardExample\components:

Observação

No código, estávamos referenciando essas imagens usando o caminho relativo do local raiz. Como referência as imagens no código, elas serão incluídas no pacote de solução *.sppkg desde que você tenha o includeClientSideAssets conjunto como true no arquivo package-solution.json .

Visualizar a Web Part no workbench hospedado

No console, insira o seguinte para visualizar sua Web Part no workbench hospedado do SharePoint:
```
gulp serve --nobrowser
```
Abra um navegador e vá até o workbench hospedado do site do SharePoint: https://enter-your-SharePoint-site/_layouts/workbench.aspx.
Na caixa de ferramentas, escolha a Web Part DocumentCardExample para adicionar:

Apêndice: Atualizando as versões do Office UI Fabric React

A partir do SPFx v1.8, você pode usar o Office UI Fabric React v5 ou v6. Cada versão do SPFx atualiza a versão do Office UI Fabric React em novos projetos. Por exemplo:

SPFx v1.8 e projetos de versões anteriores usam o Office UI Fabric React v5.x por padrão
Os projetos do SPFx v1.9 & v1.10 usam o Office UI Fabric React v6.x por padrão

Versões diferentes do Office UI Fabric React dão suporte a diferentes versões mínimas do TypeScript.

O Office UI Fabric React v5 depende do TypeScript v2.x. O SPFx v1.8 e os projetos anteriores também dependem do TypeScript v2.x.

O Office UI Fabric React v6 requer TypeScript v3.x. Todos os projetos SPFx v1.9 e posteriores são configurados para usar o TypeScript v3 ou superior que corresponda à mesma dependência do Office UI Fabric React v6.

No caso em que você deseja atualizar um projeto SPFx v1.8 para o Office UI Fabric React v6, você também precisará atualizar a versão do TypeScript no projeto. Consulte as notas de versão do SPFx v1.8 para obter detalhes: notas de versão do SharePoint Framework v1.8: suporte para TypeScript 2.7, 2.9 e 3.x.

Compartilhar via