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

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

Dan Clark
Dan Clark
X GitHub

Com o novo recurso de scripts de módulo CSS, é possível carregar folhas de estilo CSS com instruções import, assim como os módulos JavaScript. As folhas de estilo podem ser aplicadas a documentos ou raízes paralelas da mesma forma que nas folhas de estilo construtáveis. Isso pode ser mais conveniente e com melhor desempenho do que outras formas 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 ao Firefox e ao Safari ainda não está disponível. O progresso da implementação pode ser acompanhado 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 a uma raiz paralela, da seguinte maneira:

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 construível, ela é aplicada a documentos ou raízes paralelas usando adoptedStyleSheets.

Ao contrário de outras formas de aplicar CSS a partir de JavaScript, não é necessário criar elementos <style> ou confundir as strings JavaScript de texto CSS.

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

  • Eliminação de duplicação: se o mesmo arquivo CSS for importado de vários locais em um aplicativo, ele só será buscado, instanciado e analisado uma única vez.
  • Ordem consistente de avaliação: quando o JavaScript de importação está em execução, ele pode confiar que a folha de estilo importada já tenha sido buscada e analisada.
  • Segurança:os módulos são buscados com CORS e usam uma verificação rigorosa do tipo MIME.

Importar declarações (o que inclui "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 vai falhar se o arquivo importado tiver um tipo MIME não 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 são permitidas

Atualmente, as regras @import CSS não funcionam em folhas de estilo construtáveis, incluindo scripts de módulo CSS. Se as regras @import estiverem presentes em uma folha de estilo construível, essas regras 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>

A compatibilidade com @import em scripts de módulo CSS pode ser adicionada à especificação. Acompanhe essa discussão de especificações no problema do GitHub (em inglês).