dart sass
1.81.0
Uma implementação Dart do Sass. Sass torna o CSS divertido .
Usando Dart Sass
Pacote sass_api
Dart Sass no navegador
API JavaScript legada
Usando Sass com Jest
De Chocolatey ou Scoop (Windows)
Do Homebrew (macOS)
Autônomo
De npm
Do bar
Da fonte
No Docker
Por que Dardo?
Política de Compatibilidade
Compatibilidade do navegador
Compatibilidade com Node.js.
CSS inválido
Dardo Sass incorporado
Uso
Diferenças comportamentais de Ruby Sass
Existem algumas maneiras diferentes de instalar e executar o Dart Sass, dependendo do seu ambiente e das suas necessidades.
Se você usar o gerenciador de pacotes Chocolatey ou o gerenciador de pacotes Scoop para Windows, poderá instalar o Dart Sass executando
choco instalar atrevimento
ou
colher instalar atrevimento
Isso lhe dará um executável sass em sua linha de comando que executará o Dart Sass. Consulte a documentação da CLI para obter detalhes.
Se você usa o gerenciador de pacotes Homebrew, você pode instalar o Dart Sass executando
preparar instalar sass/sass/sass
Isso lhe dará um executável sass em sua linha de comando que executará o Dart Sass.
Você pode baixar o arquivo Dart Sass independente para o seu sistema operacional – contendo o Dart VM e o instantâneo do executável – na página de lançamento do GitHub. Extraia-o, adicione o diretório ao seu caminho, reinicie o seu terminal e o executável sass estará pronto para ser executado!
Dart Sass está disponível, compilado em JavaScript, como um pacote npm. Você pode instalá-lo globalmente usando npm install -g sass que fornecerá acesso ao executável sass . Você também pode adicioná-lo ao seu projeto usando npm install --save-dev sass . Isso fornece o executável e também uma biblioteca:
const sass = require('sass');const result = sass.compile(scssFilename);// OU// Observe que `compileAsync()` é substancialmente mais lento que `compile()`.const result = await sass.compileAsync( scssNomeArquivo);Consulte o site do Sass para obter a documentação completa da API.
O pacote sass npm também pode ser executado diretamente no navegador. É compatível com todos os principais empacotadores da web, desde que você desative a renomeação (como --keep-names no esbuild). Você também pode importá-lo diretamente de um navegador como um módulo ECMAScript sem qualquer pacote (assumindo que node_modules também seja servido):
<script type="importmap">
{"importações": { "immutável": "./node_modules/immutable/dist/immutable.es.js", "sass": "./node_modules/sass/sass.default.js"}
}</script><!-- Suporta navegadores como Safari 16.3 sem suporte para importação de mapas. --><script async src="https://unpkg.com/es-module-shims@^1.7.0" crossorigin="anonymous"></script><script type="module">
importar * como atrevimento de 'atrevimento';
console.log(sass.compileString(` .box {largura: 10px + 15px; } `));</script>Ou de um CDN:
<script type="importmap">
{"importações": { "immutável": "https://unpkg.com/immutable@^4.0.0", "atrevimento": "https://unpkg.com/sass@^1.63.0/sass.default .js"}
}</script><!-- Suporta navegadores como Safari 16.3 sem suporte para importação de mapas. --><script async src="https://unpkg.com/es-module-shims@^1.7.0" crossorigin="anonymous"></script><script type="module">
importar * como atrevimento de 'atrevimento';
console.log(sass.compileString(` .box {largura: 10px + 15px; } `));</script>Ou mesmo empacotado com todas as suas dependências:
<script type="módulo">
importar * como sass de 'https://jspm.dev/sass';
console.log(sass.compileString(` .box {largura: 10px + 15px; } `));</script> Como o navegador não tem acesso ao sistema de arquivos, as funções compile() e compileAsync() não estão disponíveis para ele. Se quiser carregar outros arquivos, você precisará passar um importador personalizado para compileString() ou compileStringAsync() . A API legada também não é compatível com o navegador.
Dart Sass também suporta uma API JavaScript mais antiga que é totalmente compatível com Node Sass (com algumas exceções listadas abaixo), com suporte para as funções render() e renderSync() . Esta API é considerada obsoleta e será removida no Dart Sass 2.0.0, portanto deve ser evitada em novos projetos.
O suporte do Sass para a API JavaScript legada tem as seguintes limitações:
Somente os valores "expanded" e "compressed" de outputStyle são suportados.
Dart Sass não oferece suporte à opção precision . O padrão do Dart Sass é uma precisão suficientemente alta para todos os navegadores existentes, e tornar isso personalizável tornaria o código substancialmente menos eficiente.
Dart Sass não oferece suporte à opção sourceComments . Os mapas de origem são a forma recomendada de localizar a origem dos seletores gerados.
Se você estiver usando Jest para executar seus testes, esteja ciente de que ele tem um bug antigo em que seu ambiente de teste padrão quebra o operador instanceof integrado do JavaScript. O pacote JS do Dart Sass usa instanceof bastante, então, para evitar quebrar o Sass, você precisará instalar jest-environment-node-single-context e adicionar testEnvironment: 'jest-environment-node-single-context' à sua configuração do Jest .
Se você for um usuário do Dart, poderá instalar o Dart Sass globalmente usando pub global activate sass , que fornecerá um executável sass . Você também pode adicioná-lo ao seu pubspec e usá-lo como uma biblioteca. Recomendamos fortemente importá-lo com o prefixo sass :
import 'pacote:sass/sass.dart' as sass;void main(List<String> args) { print(sass.compile(args.first));
}Consulte a documentação da API Dart para obter detalhes.
sass_api Os usuários do Dart também têm acesso a APIs mais detalhadas por meio do pacote sass_api . Isso fornece acesso ao Sass AST e APIs para resolver cargas Sass sem executar uma compilação completa. Ele é separado em seu próprio pacote para que possa aumentar seu número de versão independentemente do pacote sass principal.
Supondo que você já tenha verificado este repositório:
Instale o Dardo. Se você baixar um arquivo manualmente em vez de usar um instalador, certifique-se de que o diretório bin do SDK esteja em seu PATH .
Instale o Buff. Isso é usado para construir os buffers de protocolo para o compilador incorporado.
Neste repositório, execute dart pub get . Isso instalará as dependências do Dart Sass.
Execute dart run grinder protobuf . Isso fará o download e criará a definição do protocolo incorporado.
Execute dart bin/sass.dart path/to/file.scss .
É isso!
Você pode instalar e executar o Dart Sass no Docker usando os seguintes comandos do Dockerfile:
# Dart stageFROM bufbuild/buf AS bufFROM dart:stable AS dart# Adicione seus arquivos scssCOPY --from=another_stage /app /app# Incluir buffer de protocolo binárioCOPY --from=buf /usr/local/bin/buf /usr/local/ bin/WORKDIR /dart-sassRUN git clone https://github.com/sass/dart-sass.git . && dardo pub obter && dart run grinder protobuf# É aqui que você executa sass.dart em seu(s) arquivo(s) scssRUN dart ./bin/sass.dart /app/sass/example.scss /app/public/css/example.css
Dart Sass substituiu Ruby Sass como implementação canônica da linguagem Sass. Escolhemos o Dart porque apresentava uma série de vantagens:
É rápido. A VM Dart é altamente otimizada e está cada vez mais rápida (para obter os números de desempenho mais recentes, consulte perf.md ). É muito mais rápido que Ruby e próximo do C++.
É portátil. O Dart VM não tem dependências externas e pode compilar aplicativos em arquivos de instantâneo independentes, portanto, podemos distribuir o Dart Sass como apenas três arquivos (o VM, o instantâneo e um script wrapper). O Dart também pode ser compilado para JavaScript, o que facilita a distribuição do Sass através do npm, que a maioria dos nossos usuários já usa.
É fácil escrever. Dart é uma linguagem de nível superior ao C++, o que significa que não requer muitos problemas com gerenciamento de memória e construção de sistemas. Ele também é digitado estaticamente, o que torna mais fácil fazer grandes refatoradores com segurança do que com Ruby.
É mais amigável para os contribuidores. Dart é substancialmente mais fácil de aprender do que Ruby, e muitos usuários de Sass no Google em particular já estão familiarizados com ele. Mais colaboradores se traduzem em um desenvolvimento mais rápido e consistente.
Na maior parte, Dart Sass segue versionamento semântico. Consideramos todos os itens a seguir como parte da API versionada:
A semântica da linguagem Sass implementada por Dart Sass.
A API Dart.
A API JavaScript.
A interface da linha de comandos.
Como o Dart Sass tem uma única versão que é compartilhada entre Dart, JavaScript e distribuições autônomas, isso pode significar que incrementamos o número da versão principal quando na verdade não há alterações significativas para uma ou mais distribuições. No entanto, tentaremos limitar o número de alterações significativas que faremos e agrupá-las no menor número possível de versões para minimizar a rotatividade. Encorajamos fortemente os usuários a usar o changelog para uma compreensão completa de todas as mudanças em cada versão.
Há uma exceção em que alterações significativas podem ser feitas fora de uma revisão de versão principal. Ocasionalmente, o CSS adiciona um recurso que é incompatível de alguma forma com a sintaxe Sass existente. Como o Sass está comprometido com a compatibilidade total do CSS, ocasionalmente precisamos quebrar a compatibilidade com o código Sass antigo para permanecermos compatíveis com o CSS.
Nestes casos, primeiro lançaremos uma versão do Sass que emite avisos de descontinuação para quaisquer folhas de estilo cujo comportamento irá mudar. Então, pelo menos três meses após o lançamento de uma versão com esses avisos de descontinuação, lançaremos uma versão secundária com a alteração significativa na semântica da linguagem Sass.
Em geral, consideramos qualquer alteração na saída CSS do Dart Sass que faça com que o CSS pare de funcionar em um navegador real como uma alteração significativa. No entanto, existem alguns casos em que tal alteração traria benefícios substanciais e afetaria apenas negativamente uma pequena minoria de navegadores raramente utilizados. Não queremos ter que bloquear tal mudança no lançamento de uma versão principal.
Dessa forma, se uma alteração quebrar a compatibilidade com menos de 2% da participação no mercado global de navegadores, de acordo com a StatCounter GlobalStats, poderemos lançar uma versão secundária do Dart Sass com essa alteração.
Consideramos que abandonar o suporte para uma determinada versão do Node.js é uma alteração significativa , desde que essa versão ainda seja suportada pelo Node.js. Isso significa que as versões são listadas como Atual, LTS ativo ou LTS de manutenção de acordo com a página de lançamento do Node.js. Depois que uma versão do Node.js sai do LTS, o Dart Sass se considera livre para interromper o suporte, se necessário.
Alterações no comportamento das folhas de estilo Sass que produzem saída CSS inválida não são consideradas alterações significativas. Tais mudanças são quase sempre necessárias ao adicionar suporte para novos recursos CSS, e atrasar todos esses recursos até que uma nova versão principal seria excessivamente oneroso para a maioria dos usuários.
Por exemplo, quando o Sass começou a analisar as expressões calc() , a expressão inválida calc(1 +) tornou-se um erro do Sass onde antes era passada como está. Isso não foi considerado uma alteração significativa, porque calc(1 +) nunca foi CSS válido para começar.
Dart Sass inclui uma implementação do lado do compilador do protocolo Embedded Sass. Ele foi projetado para ser incorporado em uma linguagem host, que então expõe uma API para os usuários invocarem Sass e definirem funções e importadores personalizados.
sass --embedded inicia o compilador incorporado e escuta no stdin.
sass --embedded --version imprime versionResponse com id = 0 em JSON e sai.
O sinalizador de linha de comando --embedded não está disponível quando você instala o Dart Sass como um pacote npm. Nenhum outro sinalizador de linha de comando é suportado com --embedded .
Existem algumas diferenças comportamentais intencionais entre Dart Sass e Ruby Sass. Geralmente, esses são locais onde Ruby Sass tem um comportamento indesejado e é substancialmente mais fácil implementar o comportamento correto do que implementar um comportamento compatível. Todos eles devem ter bugs de rastreamento no Ruby Sass para atualizar o comportamento de referência.
@extend aceita apenas seletores simples, assim como o segundo argumento de selector-extend() . Veja a edição 1599.
Os seletores de assunto não são suportados. Veja a edição 1126.
Os argumentos do pseudoseletor são analisados como <declaration-value> s em vez de ter uma análise personalizada mais limitada. Consulte a edição 2120.
A precisão numérica é definida como 10. Consulte a edição 1122.
O analisador de sintaxe recuado é mais flexível: não requer recuo consistente em todo o documento. Consulte a edição 2176.
As cores não suportam aritmética canal por canal. Consulte a edição 2144.
Números sem unidade não são == para números unitários com o mesmo valor. Além disso, as chaves do mapa seguem a mesma lógica que == -equality. Veja a edição 1496.
Os valores alfa rgba() e hsla() com unidades percentuais são interpretados como porcentagens. Outras unidades são proibidas. Veja a edição 1525.
Muitos argumentos variáveis passados para uma função são um erro. Veja a edição 1408.
Permitir que @extend alcance fora de uma consulta de mídia se houver um @extend idêntico definido fora dessa consulta. Isso não é rastreado explicitamente porque será irrelevante quando o problema 1050 for corrigido.
Alguns pseudos de seletores contendo seletores de espaço reservado serão compilados onde não seriam no Ruby Sass. Isto corresponde melhor à semântica dos seletores em questão e é mais eficiente. Consulte a edição 2228.
A sintaxe antiga :property value não é suportada na sintaxe recuada. Consulte a edição 2245.
O combinador de referência não é compatível. Veja a edição 303.
A unificação do seletor universal é simétrica. Consulte a edição 2247.
@extend não produz um erro se corresponder, mas não consegue unificar. Consulte a edição 2250.
Atualmente, o Dart Sass oferece suporte apenas a documentos UTF-8. Gostaríamos de oferecer mais suporte, mas o Dart atualmente não oferece suporte. Consulte dart-lang/sdk#11744, por exemplo.
Isenção de responsabilidade: este não é um produto oficial do Google.
