Como usar scripts de módulo CSS para importar folhas de estilo

Aprenda a usar scripts de módulo CSS para importar folhas de estilo CSS usando a mesma sintaxe dos módulos JavaScript.

Dan Clark

Com o novo recurso de scripts de módulo CSS, é possível carregar folhas de estilo CSS com instruções import, assim como módulos JavaScript. As folhas de estilo podem ser aplicadas a documentos ou raízes de sombra da mesma maneira que folhas de estilo computáveis. Isso pode ser mais conveniente e mais eficiente do que outras maneiras de importar e aplicar CSS.

Compatibilidade com navegadores

Os scripts de módulo CSS estão disponíveis por padrão no Chrome e no Edge na versão 93.

O suporte no Firefox e no Safari ainda não está disponível. O progresso da implementação pode ser rastreado no bug do Gecko e no bug do WebKit, respectivamente.

Pré-requisitos

Como usar scripts de módulo CSS

Importe um script de módulo CSS e aplique-o a um documento ou uma raiz de sombra assim:

import sheet from './styles.css' assert { type: 'css' };
document.adoptedStyleSheets = [sheet];
shadowRoot.adoptedStyleSheets = [sheet];

A exportação padrão de um script de módulo CSS é uma folha de estilo construível com conteúdo do arquivo importado. Como qualquer outra folha de estilo que pode ser construída, ela é aplicada a documentos ou raízes de sombra usando adoptedStyleSheets.

Ao contrário de outras maneiras de aplicar CSS do JavaScript, não é necessário criar elementos <style> ou mensagens com strings JavaScript de texto CSS.

Os módulos CSS também têm alguns dos mesmos benefícios dos módulos JavaScript.

  • Deduplificação: se o mesmo arquivo CSS for importado de vários lugares em um aplicativo, ele ainda será buscado, instanciado e analisado apenas uma vez.
  • Ordem consistente de avaliação: quando o JavaScript de importação está em execução, ele pode confiar na folha de estilos importada, que já foi buscada e analisada.
  • Segurança: os módulos são buscados com CORS e usam a verificação rigorosa de tipo MIME.

Importar declarações (o que é o "assert"?)

A parte assert { type: 'css' } da instrução import é uma declaração de importação. Isso é necessário. Sem ele, o import é tratado como uma importação normal de módulo JavaScript e falhará se o arquivo importado tiver um tipo MIME que não seja JavaScript.

import sheet from './styles.css'; // Failed to load module script:
                                  // Expected a JavaScript module
                                  // script but the server responded
                                  // with a MIME type of "text/css".

Folhas de estilo importadas dinamicamente

Você também pode importar um módulo CSS usando a importação dinâmica, com um novo segundo parâmetro para a declaração de importação type: 'css':

const cssModule = await import('./style.css', {
  assert: { type: 'css' }
});
document.adoptedStyleSheets = [cssModule.default];

@import regras ainda não permitidas

No momento, as regras @import do CSS não funcionam em folhas de estilo construíveis, incluindo scripts de módulo CSS. Se as regras @import estiverem presentes em uma folha de estilo construível, elas serão ignoradas.

/* atImported.css */
div {
    background-color: blue;
}

/* styles.css */
@import url('./atImported.css'); /* Ignored in CSS module */
div {
    border: 1em solid green;
}

<!-- index.html -->
<script type="module">
    import styles from './styles.css' assert { type: "css" };
    document.adoptedStyleSheets = [styles];
</script>
<div>This div will have a green border but no background color.</div>

O suporte a @import em scripts de módulo CSS pode ser adicionado à especificação. Acompanhe essa discussão de especificação no problema do GitHub.