Compartilhar via

Recomendações para trabalhar com CSS em soluções de Estrutura do SharePoint

Ao criar soluções de Estrutura do SharePoint, você pode usar o CSS para definir como devem ser a aparência e comportamento de sua personalização. Este artigo descreve como tirar o máximo proveito dos recursos que acompanham a Estrutura do SharePoint e como criar seus estilos CSS de uma maneira eficiente.

As personalizações da Estrutura do SharePoint fazem parte da página

Ao criar as personalizações do SharePoint usando o modelo de suplementos, a solução é isolada de outros elementos na página. Seu código pode ser executado em um iframe como uma parte do suplemento ou como um aplicativo avançado que assume o controle de toda a página. Em ambos os casos, seu código não é afetado por outros elementos e estilos definidos na página.

As soluções de Estrutura do SharePoint fazem parte da página e se integram totalmente com o DOM da página. Embora isso remova algumas restrições que vêm com o modelo de suplementos, sua solução fica exposta a riscos. Como essas soluções são uma parte da página, a menos que isoladas explicitamente, todos os estilos CSS presentes na página se aplicam a elas, resultando potencialmente em uma experiência diferente daquela pretendida. Para evitar esses riscos, você deve definir seus estilos CSS de forma que eles não afetem nada mais na página a não ser sua personalização.

Organizar arquivos CSS em sua solução

A interface do usuário de suas soluções geralmente consiste em vários blocos de construção. Em muitas bibliotecas do JavaScript, esses blocos de construção são chamados de componentes. Um componente pode ser simples e definir apenas a apresentação ou pode ser mais complexo e incluir estado e outros componentes. Dividir sua solução em vários componentes permite simplificar o processo de desenvolvimento e facilitar o teste e reuso dos componentes em sua solução.

Como os componentes têm apresentação, eles geralmente precisam de estilos CSS. O ideal é que os componentes possam ser isolados e usados por conta própria. Tendo isso em mente, faz todo o sentido você armazenar os estilos CSS para o componente específico juntamente com todos os outros arquivos de ativos ao lado do componente. A seguir temos um exemplo de estrutura de um aplicativo React com vários componentes, cada um com o seu próprio arquivo CSS.

todoWebPart\components
                      \todoList
                               \todoList.tsx
                               \todoList.module.scss
                      \todoItem
                               \todoItem.tsx
                               \todoItem.module.scss

Usar Sass

Na Estrutura do SharePoint, você pode usar CSS e Sass. Sass é um subconjunto de CSS e oferece inúmeros recursos como usar variáveis, aninhar seletores ou mesclagens; todos eles simplificam o trabalho e o gerenciamento dos estilos CSS em longo prazo.

Confira o conjunto completo de recursos no site Sass. Todos os CSS válidos também são Sass válidos e isso será muito útil se você não tiver trabalhado com Sass antes e quiser aprender seus recursos gradualmente.

Evitar o uso de IDs em marcação

Ao usar a Estrutura do SharePoint, você cria personalizações que os usuários finais adicionam ao SharePoint. Não é possível saber antecipadamente se a personalização específica é usada somente uma vez em uma página ou se há várias instâncias dela.

Para evitar problemas, você deve sempre supor que existem várias instâncias de suas personalizações na mesma página. Tendo isso em mente, evite usar qualquer ID em sua marcação. As IDs devem ser exclusivas em uma página e se um usuário adiciona sua Web Part à página duas vezes, e isso viola essa premissa, levando possivelmente a erros.

Prática ruim

// ...

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {

  public render(): void {
    this.domElement.innerHTML = `
      <div id="helloWorld">
        Hello world
      </div>`;
  }

  // ...
}

Prática boa

// ...

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {

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

  // ...
}

Usar módulos de CSS para evitar conflitos de estilo

Estrutura do SharePoint soluções fazem parte da página. Para garantir que os estilos CSS para um componente não afetem outros elementos na página, você deve definir seus seletores CSS de forma que eles se apliquem apenas ao DOM da sua solução. É tedioso e propenso a erros fazer isso manualmente, mas Estrutura do SharePoint pode fazer isso automaticamente por você.

Para ajudar a evitar conflitos de estilos, a Estrutura do SharePoint usa módulos de CSS. Ao criar o projeto, a cadeia de ferramentas da Estrutura do SharePoint processa todos os arquivos com a extensão .module.scss. Para cada arquivo, ela lê todos os seletores de classe e acrescenta um valor de hash exclusivo para eles. Quando tiver terminado, ela grava os seletores atualizados em arquivos CSS intermediários que estão incluídos no pacote de Web Part gerado.

Seguindo o exemplo anterior, vamos supor que você tenha os seguintes dois arquivos Sass:

todoList.module.scss

.todoList {
  margin: 1em 0;

  .text {
    font-weight: bold;
    font-size: 1.5em;
  }
}

todoItem.module.scss

.todoItem {
  padding: 0.5em 1em;

  .text {
    font-size: 0.9em;
  }
}

Depois de criar o projeto, na pasta lib, você verá os dois seguintes arquivos CSS gerados (quebras de linha e recuo adicionados para facilitar a leitura):

todoList.module.css

.todoList_3e9d35f0 {
  margin:1em 0
}

.todoList_3e9d35f0 .text_3e9d35f0 {
  font-weight:700;
  font-size:1.5em
}

todoItem.module.css

.todoItem_f7081cc4 {
  padding:.5em 1em
}

.todoItem_f7081cc4 .text_f7081cc4 {
  font-size:.9em
}

Mesmo que tenha havido uma classe .text definida em ambos os arquivos Sass, observe como, nos arquivos CSS gerados, ela tem dois hashes diferentes anexados a ela, tornando-se um nome de classe exclusivo específico para cada componente.

Os nomes de classe CSS em módulos CSS são gerados dinamicamente, o que torna impossível para você se referir diretamente a eles em seu código. Em vez disso, ao processar módulos CSS, o Estrutura do SharePoint toolchain gera um arquivo JavaScript com referências aos nomes de classe gerados.

todoList.module.scss.js

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
/* tslint:disable */
require('./todoList.module.css');
var styles = {
    todoList: 'todoList_3e9d35f0',
    text: 'text_3e9d35f0',
};
exports.default = styles;
/* tslint:enable */

//# sourceMappingURL=todoList.module.scss.js.map

Para usar os nomes de classe gerados no seu código, você primeiro importa os estilos do seu componente e, em seguida, usa a propriedade apontando para a classe específica:

import styles from './todoList.module.scss';
// ...

export default class TodoList extends React.Component<ITodoListProps, void> {
  public render(): React.ReactElement<ITodoListProps> {
    return (
      <div className={styles.todoList}>
        <div className={styles.text}>Hello world</div>
      </div>
    );
  }
}

Para que os módulos de CSS funcionem corretamente, você terá que atender às seguintes condições:

  • Seus arquivos Sass devem ter a extensão .module.scss. Se você usar a extensão .scss sem .module, um aviso no processo de criação será exibido. O arquivo Sass será transcompilado para um arquivo CSS intermediário, mas os nomes de classe não serão exclusivos. Em alguns casos, quando você precisar substituir os estilos CSS de terceiros, isso poderá servir.

  • Os nomes de classe CSS devem ser nomes de variável JavaScript válidos. Por exemplo, eles não podem conter hifens: todoList está correto, mas todo-list não.

  • O uso da nomenclatura camelCase para classes é recomendada, mas não é obrigatória.

Encapsule seus estilos CSS em uma classe com o mesmo nome do componente

Ao combinar os módulos CSS com o suporte a Sass para conjuntos de regras de aninhamento, você pode simplificar seus estilos CSS e garantir que eles não afetem outros elementos na página.

Ao criar estilos CSS para um componente, encapsule-os em uma classe com o mesmo nome do componente. Em seguida, no componente, atribua essa classe ao elemento raiz do componente.

todoList.module.scss

.todoList {
  a {
    display: block;
  }
}

TodoList.tsx

// ...

export default class TodoList extends React.Component<ITodoListProps, void> {
  public render(): React.ReactElement<ITodoListProps> {
    return (
      <div className={styles.todoList}>
        ...
      </div>
    );
  }
}

Após a transcompilação, o arquivo CSS gerado será semelhante ao seguinte:

.todoList_3e9d35f0 a {
  display: block;
}

Como o seletor começa com o nome da classe exclusivo, específico para seu componente, a apresentação alternativa se aplica somente aos hiperlinks dentro de seu componente.

Manipulação do prefixo do fornecedor CSS

Na Estrutura do SharePoint, não são exigidas propriedades do estilo prefixado do fornecedor em arquivos CSS ou Sass de um projeto. Se alguns dos navegadores com suporte para a Estrutura do SharePoint exigirem prefixos, eles serão adicionados automaticamente após a compilação do Sass para CSS. Este método também é conhecido como prefixação automática e é uma parte fundamental da cadeia de compilação do CSS na Estrutura do SharePoint.

Caso uma Web Part precise usar o novo modelo flexível de caixa definido pela instrução display: flex, algumas versões anteriores do Internet Explorer e baseadas no WebKit exigem um determinado prefixo de fornecedor definido no CSS.

.container{
  display: flex;
}

No código Sass da Estrutura do SharePoint, o artefato não precisa ter prefixos de fornecedor incluídos. Após a compilação de Sass para CSS, esses prefixos são adicionados automaticamente resultando na seguinte declaração CSS.

.container_7e976ae1 {
  display: -webkit-box; // older Safari on MacOS and iOS
  display: -ms-flexbox; // IE 10 - 11
  display: flex;
}

Remover prefixos já aplicados não só torna o código do artefato mais limpo, como também facilita a leitura e deixa-o preparado para o futuro. Esse processo também está configurado para ser utilizado somente em navegadores com suporte para a Estrutura do SharePoint, o que o torna menos propenso a erros.

No caso de uma Web Part já ter prefixos de fornecedor incluídos nos arquivos Sass que não são mais necessários, o mesmo processo remove automaticamente essas declarações.

O exemplo a seguir usa a propriedade border-radius, que não exige prefixos de fornecedor nos sistemas compatíveis.

.container {
  /* Safari 3-4, iOS 1-3.2, Android 1.6- */
  -webkit-border-radius: 7px;
  /* Firefox 1-3.6 */
  -moz-border-radius: 7px;
  /* Opera 10.5, IE 9, Safari 5, Chrome, Firefox 4, iOS 4, Android 2.1+ */
  border-radius: 7px;
}

O CSS resultante no pacote é convertido para o código a seguir.

.container_9e54c0b0 {
  border-radius: 7px
}

Para obter mais informações sobre a prefixação automática, confira o repositório do GitHub autoprefixer. O banco de dados para esse processo está disponível em Posso usar__?.

Integrar o Office UI Fabric

Ao fazer suas personalizações se comportarem e se parecerem com a funcionalidade padrão do SharePoint e do Office 365, você facilita a forma como os usuários finais trabalham com elas. O Office UI Fabric oferece a você um conjunto de controles e de estilos para uso em suas personalizações para integrar-se com perfeição à experiência de usuário existente.

Para obter mais informações sobre como usar o Office UI Fabric na Estrutura do SharePoint , confira Usando o Office UI Fabric Core e o Fabric React na Estrutura do SharePoint.

Usar cores de tema

O SharePoint permite que os usuários escolham a cor de tema para seus sites. Em suas personalizações da Estrutura do SharePoint, você deverá seguir o tema selecionado pelos usuários para melhorar a aparência de suas personalizações, como parte integral do site em vez de se destacarem desnecessariamente.

Como o tema é definido por usuários em seu site, você não poderá dizer antecipadamente quais cores suas personalizações devem usar, mas a Estrutura do SharePoint pode carregar dinamicamente o esquema de cores ativo no momento de maneira automática para você.

Para ver mais informações sobre esse recurso, confira Use cores de tema em suas personalizações da Estrutura do SharePoint.