Folhas de estilo construíveis

Estilos reutilizáveis e integrados.

Jason Miller

As folhas de estilo construtíveis são uma maneira de criar e distribuir estilos reutilizáveis ao usar o Shadow DOM.

Browser Support

• 73
• 79
• 101
• 16.4

Source

Sempre foi possível criar folhas de estilo usando JavaScript. No entanto, o processo sempre foi criar um elemento <style> usando document.createElement('style') e, em seguida, acessar a propriedade da planilha para receber uma referência à instância CSSStyleSheet subjacente. Esse método pode produzir código CSS duplicado e o inchaço associado, e o ato de anexar leva a um flash de conteúdo sem estilo, haja inchaço ou não. A interface CSSStyleSheet é a raiz de uma coleção de interfaces de representação de CSS, conhecida como CSSOM, que oferece uma maneira programática de manipular folhas de estilo e elimina os problemas associados ao método antigo.

As folhas de estilo construtíveis permitem definir e preparar estilos CSS compartilhados e, em seguida, aplicá-los a várias raízes de sombra ou ao documento com facilidade e sem duplicação. As atualizações de uma CSSStyleSheet compartilhada são aplicadas a todas as raízes em que ela foi adotada, e a adoção de uma folha de estilo é rápida e síncrona depois que a folha é carregada.

A associação configurada pelas folhas de estilo construtíveis se adapta bem a vários aplicativos diferentes. Ele pode ser usado para fornecer um tema centralizado usado por muitos componentes: o tema pode ser uma instância CSSStyleSheet transmitida para componentes, com atualizações do tema se propagando para os componentes automaticamente. Ele pode ser usado para distribuir valores de propriedades personalizadas de CSS para subárvores DOM específicas sem depender da cascata. Ele pode até ser usado como uma interface direta para o analisador de CSS do navegador, facilitando o pré-carregamento de folhas de estilo sem injetá-las no DOM.

Como criar uma folha de estilo

Em vez de introduzir uma nova API para fazer isso, a especificação de folhas de estilo construtíveis permite criar folhas de estilo de forma imperativa invocando o construtor CSSStyleSheet(). O objeto CSSStyleSheet resultante tem dois novos métodos que tornam mais seguro adicionar e atualizar regras de folha de estilo sem acionar o Flash of Unstyled Content (FOUC). Os métodos replace() e replaceSync() substituem a folha de estilo por uma string de CSS, e replace() retorna uma promessa. Em ambos os casos, as referências de folhas de estilo externas não são compatíveis. Todas as regras @import são ignoradas e produzem um aviso.

const sheet = new CSSStyleSheet();

// replace all styles synchronously:
sheet.replaceSync('a { color: red; }');

// replace all styles:
sheet.replace('a { color: blue; }')
  .then(() => {
    console.log('Styles replaced');
  })
  .catch(err => {
    console.error('Failed to replace styles:', err);
  });

// Any @import rules are ignored.
// Both of these still apply the a{} style:
sheet.replaceSync('@import url("styles.css"); a { color: red; }');
sheet.replace('@import url("styles.css"); a { color: red; }');
// Console warning: "@import rules are not allowed here..."

Em versões anteriores da especificação, replace() permitia regras @import e retornava uma promessa que era resolvida quando o carregamento era concluído. No Chrome 84, esse recurso foi removido da especificação, e as regras @import são ignoradas com um aviso.

Como usar folhas de estilo construídas

O segundo novo recurso introduzido pelas folhas de estilo construtíveis é uma propriedade adoptedStyleSheets disponível em Shadow Roots e Documents. Isso permite aplicar explicitamente os estilos definidos por um CSSStyleSheet a uma determinada subárvore do DOM. Para isso, definimos a propriedade como uma matriz de uma ou mais folhas de estilo a serem aplicadas a esse elemento.

// Create our shared stylesheet:
const sheet = new CSSStyleSheet();
sheet.replaceSync('a { color: red; }');

// Apply the stylesheet to a document:
document.adoptedStyleSheets.push(sheet);

// Apply the stylesheet to a Shadow Root:
const node = document.createElement('div');
const shadow = node.attachShadow({ mode: 'open' });
shadow.adoptedStyleSheets.push(sheet);

Em versões anteriores da especificação, adoptedStyleSheets era implementado como uma matriz congelada, o que significa que mutações no local, como push(), geravam uma exceção. Para adicionar uma nova folha de estilo, era necessário redefinir a matriz: `document.adoptedStyleSheets = [...document.adoptedStyleSheets, newSheet] Isso não é mais necessário, porque a especificação foi atualizada para permitir mutações de matriz.

Como tudo funciona em conjunto

Com as folhas de estilo construtíveis, os desenvolvedores web agora têm uma solução explícita para criar folhas de estilo CSS e aplicá-las a árvores do DOM. Temos uma nova API baseada em promessas para carregar folhas de estilo de uma string de origem CSS que usa o analisador integrado do navegador e a semântica de carregamento. Por fim, temos um mecanismo para aplicar atualizações de folha de estilo a todos os usos de um StyleSheet, simplificando coisas como mudanças de tema e preferências de cor.

Ver demonstração

No futuro

A versão inicial das folhas de estilo construtíveis foi enviada com a API descrita aqui, mas há um trabalho em andamento para facilitar o uso. Há uma proposta para estender o adoptedStyleSheets FrozenArray com métodos dedicados para inserir e remover folhas de estilo, o que eliminaria a necessidade de clonagem de matrizes e evitaria possíveis referências duplicadas de folhas de estilo.

Mais informações

• Status da plataforma Chrome
• Exemplo
• API
• Explicativa
• Intenção de implementar
• Intent de envio
• Discourse