Compartilhar via

Como usar o Office UI Fabric Core e o Fabric React na Estrutura do SharePoint

  • Artigo

O Office UI Fabric é a estrutura de front-end oficial para criar experiências no Office 365 e no SharePoint. O SharePoint fornece uma integração contínua com o Fabric que permite que a Microsoft forneça uma linguagem de design robusta e consistente em várias experiências do SharePoint, como sites de equipe modernos, páginas modernas e listas modernas. Além disso, o Office UI Fabric está disponível para desenvolvedores no Estrutura do SharePoint ao criar soluções personalizadas do SharePoint.

A Microsoft usa o Fabric Core e o Fabric React no SharePoint. A Microsoft regularmente envia atualizações para o SharePoint Online que também podem atualizar as versões do Fabric Core e do Fabric React. Essas atualizações podem entrar em conflito com soluções de terceiros compiladas com versões anteriores do Fabric Core e do Fabric React e isso pode causar exceções nas personalizações. A principal razão desses tipos de quebras é o uso dos estilos do Global CSS nas duas bibliotecas do Fabric. Esses conflitos precisam ser realmente evitados.

O desafio com estilos do Global CSS é bem explicado na apresentação a seguir no contexto do React e JavaScript: React CSS em JS.

Para alcançar a confiabilidade, um dos principais problemas que precisamos resolver é o dos estilos do Global CSS. Isso explica a não usar nomes de classe globais na marcação HTML e, sim, usar variáveis e misturas do Fabric Core no arquivo da declaração Sass. Isso envolve a importação de declarações Sass do Fabric Core no seu arquivo Sass e, em seguida, o consumo adequado de variáveis e misturas.

Metas

O objetivo da Estrutura do SharePoint é permitir que a Microsoft e os clientes criem experiências do usuário avançadas, bonitas e consistentes no SharePoint.

De acordo com esses objetivos, veja a seguir os principais princípios de design:

  • Os clientes devem poder consumir o Fabric Core e o Fabric React de forma tranquila e confiável em suas soluções.
  • A Microsoft implementará experiências atualizadas que consomem versões atualizadas do Fabric Core e do Fabric React no SharePoint sem entrar em conflito com as soluções do cliente.
  • Os clientes podem personalizar e substituir os estilos, designs e componentes padrão de acordo com as necessidades de suas soluções.

Há duas partes do Office UI Fabric que podem ser usadas por desenvolvedores:

  • Office UI Fabric Core. Um conjunto dos principais estilos, tipografia, grade responsiva, animações, ícones e outros blocos de construção fundamentais da linguagem geral do design.

  • Office UI Fabric React. Um conjunto de componentes do React criados na linguagem de design do Fabric para ser usado em projetos do React.

Pacote do Office UI Fabric Core

O pacote npm do Fabric Core da Estrutura do SharePoint (@microsoft/sp-office-ui-fabric-core) contém um subconjunto de estilos compatíveis do Fabric Core que podem ser consumidos com segurança em um componente da Estrutura do SharePoint.

Os principais estilos a seguir têm suporte no pacote:

  • Tipografia
  • Layouts
  • Cores
  • Temas
  • Localização

Os itens a seguir não têm suporte no pacote:

  • Animações
  • Ícones

Começando com o gerador Yeoman da Estrutura do SharePoint 1.3.4, os modelos do projeto padrão (Web Parts e extensões) são configurados com o novo pacote @microsoft/sp-office-ui-fabric-core e consomem estilos principais do pacote em vez de usar estilos CSS globais.

Atualizar projetos atuais

Para usar o pacote do Fabric Core em seu projeto atual, instale-o como uma dependência:

npm install @microsoft/sp-office-ui-fabric-core --save

Após a instalação, você pode importar as declarações Sass do Fabric Core no arquivo de definição Sass e usar as variáveis e misturas conforme descrito na seção a seguir.

Use estilos do Fabric Core

Para usar os estilos do Fabric Core, você precisa importar declarações SPFabricCore no seu arquivo Sass.

Observação

Verifique se você tem o pacote npm @microsoft/sp-office-ui-fabric-core instalado.

@import '~@microsoft/sp-office-ui-fabric-core/dist/sass/SPFabricCore.scss';

Agora, você pode usar os estilos principais como misturas e variáveis.

.row {
  @include ms-Grid-row;
  @include ms-fontColor-white;
  background-color: $ms-color-themeDark;
  padding: 20px;
}

Office UI Fabric React

Recomendamos usar as versões do pacote Office UI Fabric React incluídas no projeto do gerador Yeoman da Estrutura do SharePoint. Por exemplo, a Estrutura do SharePoint v1.7.0 usa o Fabric React v5.131.0

Observação

O Fabric React versões 2.x ou mais antigas não são compatíveis com a Estrutura do SharePoint.

Após o pacote do Fabric React ser instalado, você poderá importar os componentes necessários do pacote do Fabric React.

//import Button component from Fabric React Button bundle
import { Button } from 'office-ui-fabric-react/lib/Button';

//use it in your component
render() {
  ...
  <div>
    <Button>click me</Button>
  </div>
  ...
}

O pacote do Fabric React inclui estilos compatíveis do Fabric Core usados nos componentes do Fabric React. Recomendamos que você importe os estilos do Fabric Core do pacote do Fabric React em vez do pacote @microsoft/sp-office-ui-fabric-core para garantir que os estilos corretos sejam usados em seu componente.

Como o pacote @microsoft/sp-office-ui-fabric-core já é instalado pela solução pelo gerador Yeoman, é recomendável desinstalar esse pacote se você decidir usar componentes do Fabric e reduzir o tamanho do pacote de componentes.

npm uninstall @microsoft/sp-office-ui-fabric-core --save

Você pode então importar estilos do core a partir das declarações SASS disponíveis no pacote do Fabric React.

@import '~office-ui-fabric-react/dist/sass/_References.scss';

Noções básicas sobre essa abordagem e suas deficiências

Os componentes do Fabric na solução estão bloqueados para uma versão específica do Fabric React que você instalou. Você precisa atualizar o pacote do Fabric React para obter os novos componentes se eles estiverem disponíveis em uma versão mais recente do pacote. Como os componentes do Fabric estão incluídos no pacote do componente, ele pode aumentar o tamanho do seu pacote de componentes. No entanto, essa abordagem é a única abordagem oficialmente suportada quando o Office UI Fabric React está sendo usado nas soluções da Estrutura do SharePoint.

O desafio CSS com o Office UI Fabric

Os conceitos e as referências a seguir oferecem ideias sobre o desafio do uso do Office UI Fabric no contexto de Web Parts do lado do cliente.

Estilos CSS globais

Como realmente evitar estilos CSS globais é um grande problema. Hoje, tanto o Fabric Core como o Fabric React têm estilos globais. A falta de uma solução nativa do navegador para gerenciar o escopo de estilos agrava esse problema.

  • O escopo CSS está nos estágios iniciais da discussão.
  • Os iframes não são uma boa opção para isolar estilos.
  • Componentes da Web é outro padrão que fala sobre estilos com escopo, mas ainda encontra-se no estágio de discussão.
  • A discussão O React: CSS no JS também explica o problema.

Há muitas outras documentações na Web sobre as soluções para a ameaça do namespace global.

Especificidade de CSS

Como a especificidade de CSS se aplica à interface do usuário da Web. Os estilos de especificidade mais altos substituem os estilos de especificidade inferiores, porém o mais importante é compreender como as regras de especificidade são aplicadas. Em geral, a ordem de precedência, da maior para a menor, é a seguinte:

  • O atributo do estilo (por exemplo, style="background:red;")
  • Seletores de identificação (#myDiv { })
  • Seletores de classe (.myCssClass{}), seletores de atributo ([type="radio"]) e pseudoclasses (:hover)
  • Seletores de tipo (h1)

Ordem de carregamento. Se duas classes forem aplicadas a um elemento e tiverem a mesma especificidade, a classe carregada posteriormente tem precedência. Como mostrado no código a seguir, o botão aparece vermelho. Se a ordem das marcas de estilo for alterada, o botão fica verde. Este é um conceito importante e, se não for usado corretamente, a experiência do usuário poderá se tornar dependente da ordem de carregamento (ou seja, inconsistente).

<style>
  .greenButton { color: green; }
</style>
<style>
  .redButton { color: red; }
</style>
<body>
  <button class="greenButton redButton"></button>
</body>

Outras abordagens consideradas e descartadas

A seguir mais algumas ideias sobre outras abordagens que foram consideradas, mas descartadas, por não terem atingido os principais objetivos para permitir que desenvolvedores terceirizados usem os estilos do Office UI Fabric com segurança.

Office UI Fabric Core

O desenvolvedor da Web Part não é obrigado a fazer nada de forma explícita para que o escopo funcione. Pretendemos resolver esse problema usando a especificidade CSS e o seletor descendente. A equipe do Fabric Core enviaria várias cópias css do Fabric Core (por exemplo, fabric-6.css, fabric-6-scoped.css, fabric-6.0.0.css e fabric-6.0.0-scoped.css).

Todos os estilos nos arquivos CSS com escopo estariam dentro de um seletor descendente, por exemplo .ms-Fabric--v6-0-0 .ms-Icon--List. No tempo de compilação, as ferramentas coletariam a versão do Office UI Fabric Core com a qual a Web Part foi criada. Esta versão poderia ser aquela que acompanha a Estrutura do SharePoint. Como alternativa, os desenvolvedores de Web Parts poderiam especificar uma dependência explícita em uma versão específica do Office UI Fabric Core em seu arquivo de package.json.

A div da Web Part receberia esse escopo, ou seja, <div data-sp-webpart class="ms-Fabric--v6-0-0">. A Estrutura carregaria a versão principal específica do arquivo CSS com escopo do Fabric Core. Se a Web Part tiver sido criada com a versão 6.0.0 do CSS do Fabric Core, a Estrutura baixaria fabric-6-scoped.css quando a Web Part fosse carregada.

O restante da página conteria os estilos do Office UI Fabric Core sem escopo. Dessa forma, de acordo com as regras de especificidade de CSS, o CSS supervisionado teria precedência dentro da divisão da Web Part. A Web Part e seu conteúdo se alinhariam à versão específica do Office UI Fabric Core que o desenvolvedor escolheu.

Não há suporte para a substituição dos estilos do Fabric Core.

// Sample of how the scoping would work.
import { SPComponentLoader } from '@microsoft/sp-loader';

export default class MyWebPart {
    constructor() {
        super();

        SPComponentLoader.loadCss('https://static2.sharepointonline.com/files/fabric/office-ui-fabric-core/6.0.0/css/fabric-6.0.0.scoped.css');
    }
}

protected render(): void {
  <div className="ms-Fabric--v6-0-0">
    { // Rest of the web part UI }
  </div>
}

Limitações dessa estratégia

Após analisar um pouco a situação, decidimos que a abordagem do seletor descendente apresenta duas deficiências sérias, razão pela qual é impossível criar uma Web Part que nunca será interrompida.

Falta de suporte de aninhamento confiável

Essa abordagem só funciona se a experiência de usuário da Microsoft (ou seja, Web Parts internas e da página) usar uma versão sem escopo do Office UI Fabric Core, como ms-Icon--List, enquanto as Web Parts de terceiros usam apenas o CSS do Office UI Fabric Core com escopo, conforme explicado anteriormente.

O motivo é que a especificidade do CSS com escopo aplicado à Web Part substitui o CSS sem escopo na página. Tenha em mente, conforme explicado anteriormente, que se a especificidade do CSS das duas classes for a mesma, a ordem de carregamento dessas classes desempenha um papel na forma como as classes CSS são aplicadas. A classe que carrega mais tarde tem precedência. Portanto, para uma experiência uniforme, é importante ter uma especificidade mais alta do CSS com escopo.

Além disso, várias extensões, uma contida em outra, não podem usar versões diferentes do Fabric Core. No exemplo a seguir, apenas ms-Fabric--v6-0-0 seria aplicada:

<div className="ms-Fabric--v6-0-0">
  { // Rest of the web part UI }
    { // inside of this SPExtension trying to use different Fabric core version does not work }
    <div className="ms-Fabric--v8-0-0">
    </div>
</div>

Veja um exemplo mais simples que demonstra o desafio:

<html>
<head>
  <title>CSS specifity test</title>
  <style>
  .myButton {
      background-color: brown;
      color: brown;
      height: 20px;
      width: 40px;
  }
  </style>
  <style>
  .scope2 .myButton {
      background-color: green;
      color: green;
  }
  </style>
  <style>
  .scope3 .myButton {
      background-color: yellow;
      color: yellow;
  }
  </style>
  <style>
  .scope1 .myButton {
      background-color: red;
      color: red;
  }
  </style>
</head>
<body>
  <div>
    <span>These tests demonstrate descendant selectors, nesting and load order problems.</span>

    <div>
      <br/>
      <span>This test depicts that a descendant selector with the same specificity does not allow nesting.
      All buttons below do not take the innermost scope (i.e. they should be different colors), but they are all red.
      Further, if you change the ordering of the style tags, the colors will change. (i.e. the UI is load order dependant.)</span>
      <div class='scope1'>
        <button class='myButton'</button>
        <div class='scope2'>
          <button class='myButton'></button>
          <div class='scope3'>
            <button class='myButton'></button>
          </div>
        </div>
      </div>
    </div>
  </div>
</body>
</html>

Vazamento de classes sem escopo

Há outro problema com seletores descendentes. No exemplo anterior, os estilos de altura e largura da classe myButton sem escopo são aplicados a todos os botões. Isso significa que uma alteração nesse estilo poderia inadvertidamente interromper o HTML usando marcação com escopo.

Por exemplo, vamos supor que, por algum motivo, no nível do aplicativo, decidimos usar 0px como a altura na classe myButton. Isso resulta em todas as Web Parts de terceiros que usam a classe myButton para ter uma altura 0 (ou seja, uma regressão séria na experiência do usuário).

Use estilos herdados do Office UI Fabric com segurança (após SPFx v1.8.2)

Importante

As diretrizes a seguir se aplicam a Estrutura do SharePoint >= 1,8,2

Certifique-se de que o manifesto da webpart exige que os estilos do Fabric Core estejam carregados na página. Isso é feito especificando loadLegacyFabricCss: true no manifesto de solução.

Antes do lançamento do SPFx v1.8.2, um bug da página host estava presente no qual os estilos herdados do Fabric Core eram carregados sem delimitação. Portanto, se outra solução exigisse os estilos, todas as outras soluções na página poderiam usá-los. Isso levou a soluções que funcionavam "por acaso", quando não processadas isoladamente.

Para resolver esse bug, os estilos foram delimitados para a classe .ms-SPLegacyFabricBlock e aplicados às soluções SPFx que exigem que a folha de estilo do Fabric Core esteja carregada. Para fornecer um caminho de migração para as soluções que dependem do efeito colateral acima, a classe .ms-SPLegacyFabricBlock é aplicada a todos os <div> expostos a soluções de terceiros. Durante esse tempo, modifique a(s) solução(ões) afetada(s) para declarar a dependência nos estilos herdados do Fabric Core.

Importante

Eventualmente, a referência explícita a .ms-SPLegacyFabricBlockserá removida do DOM para soluções que não declaram sua dependência. Esta mudança será amplamente comunicada por meio dos canais existentes antes da remoção desta classe.

No caso de uma solução que está sendo executada em elementos DOM que não são fornecidos pela SPFx ( que geralmente não é compatível), você mesmo precisará aplicar a .ms-SPLegacyFabricBlock classe.

Uso dos ícones Office UI Fabric em componentes da SPFx

Há alterações em como usar os ícones do Office UI Fabric na renderização das soluções da Estrutura do SharePoint a partir da Estrutura do SharePoint v. 1.8.2.

Forma herdada de usar ícones (antes da SPFx 1.8.2)

<i className={css('ms-Icon', 'ms-Icon--RecurringEvent')}></i>

Forma atualizada de usar ícones (depois da SPFx 1.8.2)

Soluções criadas com a opção sem estrutura JavaScript.

  1. Adicionar pacote @uifabric/styling ao seu package.json
  2. Faça alterações de código semelhantes ao código abaixo para inserir o ícone necessário em seu código:
import { getIconClassName } from '@uifabric/styling';

return `<i class="${getIconClassName('Mail')}" />`;

Soluções criadas com a opção React ou usando o React em geral.

  1. Adicione o pacote office-ui-fabric-react ao seu package.json, se ainda não estiver adicionado.
  2. Faça alterações de código semelhantes ao código abaixo para inserir o ícone necessário em seu código:
import { Icon } from 'office-ui-fabric-react/lib/Icon';

<Icon iconName='Mail' />

Confira também