dart sass
1.81.0
Une implémentation Dart de Sass. Sass rend le CSS amusant .
Utiliser Dart Sass
Paquet sass_api
Dart Sass dans le navigateur
Ancienne API JavaScript
Utiliser Sass avec Jest
Depuis Chocolatey ou Scoop (Windows)
Depuis Homebrew (macOS)
Autonome
De npm
Du pub
De la source
Dans Docker
Pourquoi Dart?
Politique de compatibilité
Compatibilité du navigateur
Compatibilité Node.js
CSS invalide
Dart Sass intégré
Usage
Différences comportementales par rapport à Ruby Sass
Il existe différentes manières d'installer et d'exécuter Dart Sass, en fonction de votre environnement et de vos besoins.
Si vous utilisez le gestionnaire de packages Chocolatey ou le gestionnaire de packages Scoop pour Windows, vous pouvez installer Dart Sass en exécutant
choco installer sass
ou
scoop installer sass
Cela vous donnera un exécutable sass sur votre ligne de commande qui exécutera Dart Sass. Consultez la documentation CLI pour plus de détails.
Si vous utilisez le gestionnaire de packages Homebrew, vous pouvez installer Dart Sass en exécutant
infuser installer sass/sass/sass
Cela vous donnera un exécutable sass sur votre ligne de commande qui exécutera Dart Sass.
Vous pouvez télécharger l'archive Dart Sass autonome pour votre système d'exploitation (contenant la machine virtuelle Dart et l'instantané de l'exécutable) à partir de la page de version de GitHub. Extrayez-le, ajoutez le répertoire à votre chemin, redémarrez votre terminal et l'exécutable sass est prêt à s'exécuter !
Dart Sass est disponible, compilé en JavaScript, sous forme de package npm. Vous pouvez l'installer globalement en utilisant npm install -g sass qui donnera accès à l'exécutable sass . Vous pouvez également l'ajouter à votre projet en utilisant npm install --save-dev sass . Celui-ci fournit l'exécutable ainsi qu'une bibliothèque :
const sass = require('sass');const result = sass.compile(scssFilename);// OR// Notez que `compileAsync()` est sensiblement plus lent que `compile()`.const result = wait sass.compileAsync( scssFilename);Consultez le site Web Sass pour la documentation complète de l'API.
Le package sass npm peut également être exécuté directement dans le navigateur. Il est compatible avec tous les principaux bundles Web tant que vous désactivez le changement de nom (comme --keep-names dans esbuild). Vous pouvez également l'importer directement depuis un navigateur en tant que module ECMAScript sans aucun regroupement (en supposant que node_modules soit également servi) :
<script type="importmap">
{"imports": { "immutable": "./node_modules/immutable/dist/immutable.es.js", "sass": "./node_modules/sass/sass.default.js"}
}</script><!-- Prise en charge des navigateurs comme Safari 16.3 sans prise en charge de l'importation de cartes. --><script async src="https://unpkg.com/es-module-shims@^1.7.0" crossorigin="anonymous"></script><script type="module">
importer * assass depuis 'sass' ;
console.log(sass.compileString(` .box { width: 10px + 15px; } `));</script>Ou depuis un CDN :
<script type="importmap">
{"imports": { "immuable": "https://unpkg.com/immutable@^4.0.0", "sass": "https://unpkg.com/sass@^1.63.0/sass.default .js"}
}</script><!-- Prise en charge des navigateurs comme Safari 16.3 sans prise en charge de l'importation de cartes. --><script async src="https://unpkg.com/es-module-shims@^1.7.0" crossorigin="anonymous"></script><script type="module">
importer * assass depuis 'sass' ;
console.log(sass.compileString(` .box { width: 10px + 15px; } `));</script>Ou même bundle avec toutes ses dépendances :
<type de script="module">
importer * en tant que sass depuis 'https://jspm.dev/sass' ;
console.log(sass.compileString(` .box { width: 10px + 15px; } `));</script> Étant donné que le navigateur n'a pas accès au système de fichiers, les fonctions compile() et compileAsync() ne sont pas disponibles pour celui-ci. Si vous souhaitez charger d'autres fichiers, vous devrez transmettre un importateur personnalisé à compileString() ou compileStringAsync() . L'API héritée n'est pas non plus prise en charge dans le navigateur.
Dart Sass prend également en charge une ancienne API JavaScript entièrement compatible avec Node Sass (à quelques exceptions près répertoriées ci-dessous), avec prise en charge des fonctions render() et renderSync() . Cette API est considérée comme obsolète et sera supprimée dans Dart Sass 2.0.0, elle doit donc être évitée dans les nouveaux projets.
La prise en charge par Sass de l'ancienne API JavaScript présente les limitations suivantes :
Seules les valeurs "expanded" et "compressed" de outputStyle sont prises en charge.
Dart Sass ne prend pas en charge l'option precision . Dart Sass utilise par défaut une précision suffisamment élevée pour tous les navigateurs existants, et rendre cette configuration personnalisable rendrait le code considérablement moins efficace.
Dart Sass ne prend pas en charge l'option sourceComments . Les cartes sources sont la méthode recommandée pour localiser l’origine des sélecteurs générés.
Si vous utilisez Jest pour exécuter vos tests, sachez qu'il présente un bug de longue date dans lequel son environnement de test par défaut interrompt l'opérateur instanceof intégré de JavaScript. Le package JS de Dart Sass utilise assez largement instanceof , donc pour éviter de casser Sass, vous devrez installer jest-environment-node-single-context et ajouter testEnvironment: 'jest-environment-node-single-context' à votre configuration Jest. .
Si vous êtes un utilisateur de Dart, vous pouvez installer Dart Sass globalement en utilisant pub global activate sass , qui fournira un exécutable sass . Vous pouvez également l'ajouter à votre pubspec et l'utiliser comme bibliothèque. Nous recommandons fortement de l'importer avec le préfixe sass :
importer 'package:sass/sass.dart' en tant que sass;void main(List<String> args) { print(sass.compile(args.first));
}Consultez la documentation de l'API Dart pour plus de détails.
sass_api Les utilisateurs de Dart ont également accès à des API plus approfondies via le package sass_api . Cela donne accès au Sass AST et aux API pour résoudre les charges Sass sans exécuter une compilation complète. Il est séparé dans son propre package afin qu'il puisse augmenter son numéro de version indépendamment du package sass principal.
En supposant que vous ayez déjà extrait ce référentiel :
Installez Dart. Si vous téléchargez une archive manuellement plutôt que d'utiliser un programme d'installation, assurez-vous que le répertoire bin du SDK se trouve sur votre PATH .
Installez Buf. Ceci est utilisé pour créer les tampons de protocole pour le compilateur intégré.
Dans ce référentiel, exécutez dart pub get . Cela installera les dépendances de Dart Sass.
Exécutez dart run grinder protobuf . Cela téléchargera et créera la définition du protocole intégré.
Exécutez dart bin/sass.dart path/to/file.scss .
C'est ça!
Vous pouvez installer et exécuter Dart Sass dans Docker à l'aide des commandes Dockerfile suivantes :
# Dart stageFROM bufbuild/buf AS bufFROM dart:stable AS dart# Ajoutez vos fichiers scssCOPY --from=another_stage /app /app# Inclure le tampon de protocole binaireCOPY --from=buf /usr/local/bin/buf /usr/local/ bin/WORKDIR /dart-sassRUN git clone https://github.com/sass/dart-sass.git . && pub de fléchettes obtenir && dart run grinder protobuf# C'est ici que vous exécutez sass.dart sur votre (vos) fichier(s) scssRUN dart ./bin/sass.dart /app/sass/example.scss /app/public/css/example.css
Dart Sass a remplacé Ruby Sass comme implémentation canonique du langage Sass. Nous avons choisi Dart car il présentait de nombreux avantages :
C'est rapide. La machine virtuelle Dart est hautement optimisée et devient de plus en plus rapide (pour les derniers chiffres de performances, voir perf.md ). C'est beaucoup plus rapide que Ruby et proche du C++.
C'est portatif. La VM Dart n'a pas de dépendances externes et peut compiler des applications dans des fichiers d'instantanés autonomes, nous pouvons donc distribuer Dart Sass sous forme de seulement trois fichiers (la VM, l'instantané et un script wrapper). Dart peut également être compilé en JavaScript, ce qui facilite la distribution de Sass via npm, que la majorité de nos utilisateurs utilisent déjà.
C'est facile à écrire. Dart est un langage de niveau supérieur à C++, ce qui signifie qu'il ne nécessite pas beaucoup de problèmes de gestion de la mémoire et de systèmes de construction. Il est également typé statiquement, ce qui facilite la création de grands refactors en toute confiance qu'avec Ruby.
C'est plus convivial pour les contributeurs. Dart est nettement plus facile à apprendre que Ruby, et de nombreux utilisateurs de Sass, chez Google en particulier, le connaissent déjà. Plus de contributeurs se traduit par un développement plus rapide et plus cohérent.
Pour l’essentiel, Dart Sass suit le versioning sémantique. Nous considérons que tous les éléments suivants font partie de l'API versionnée :
La sémantique du langage Sass implémentée par Dart Sass.
L'API Dart.
L'API JavaScript.
L'interface de ligne de commande.
Étant donné que Dart Sass a une version unique partagée entre les distributions Dart, JavaScript et autonomes, cela peut signifier que nous incrémentons le numéro de version majeure alors qu'il n'y a en fait aucune modification majeure pour une ou plusieurs distributions. Cependant, nous tenterons de limiter le nombre de modifications majeures que nous apportons et de les regrouper dans le moins de versions possible afin de minimiser le taux de désabonnement. Nous encourageons fortement les utilisateurs à utiliser le journal des modifications pour une compréhension complète de toutes les modifications apportées à chaque version.
Il existe une exception où des modifications avec rupture peuvent être apportées en dehors d’une révision de version majeure. Il arrive parfois que CSS ajoute une fonctionnalité incompatible d'une manière ou d'une autre avec la syntaxe Sass existante. Étant donné que Sass s'engage à assurer une compatibilité CSS totale, nous devons parfois rompre la compatibilité avec l'ancien code Sass afin de rester compatible avec CSS.
Dans ces cas, nous publierons d'abord une version de Sass qui émet des avertissements de dépréciation pour toutes les feuilles de style dont le comportement va changer. Ensuite, au moins trois mois après la publication d'une version avec ces avertissements de dépréciation, nous publierons une version mineure avec la modification radicale de la sémantique du langage Sass.
En général, nous considérons toute modification apportée à la sortie CSS de Dart Sass qui empêcherait ce CSS de fonctionner dans un vrai navigateur comme un changement radical. Cependant, dans certains cas, un tel changement aurait des avantages substantiels et n’aurait qu’un impact négatif sur une petite minorité de navigateurs rarement utilisés. Nous ne voulons pas avoir à bloquer un tel changement sur une version majeure.
En tant que tel, si un changement devait rompre la compatibilité avec moins de 2 % de la part de marché mondiale des navigateurs selon StatCounter GlobalStats, nous pourrions publier une version mineure de Dart Sass avec ce changement.
Nous considérons que l'abandon de la prise en charge d'une version donnée de Node.js constitue un changement radical tant que cette version est toujours prise en charge par Node.js. Cela signifie que les versions sont répertoriées comme Current, Active LTS ou Maintenance LTS selon la page des versions de Node.js. Une fois qu'une version de Node.js est sortie de LTS, Dart Sass se considère libre de rompre le support si nécessaire.
Les modifications apportées au comportement des feuilles de style Sass qui produisent une sortie CSS non valide ne sont pas considérées comme des modifications avec rupture. De tels changements sont presque toujours nécessaires lors de l'ajout de la prise en charge de nouvelles fonctionnalités CSS, et retarder toutes ces fonctionnalités jusqu'à une nouvelle version majeure serait indûment fastidieux pour la plupart des utilisateurs.
Par exemple, lorsque Sass a commencé à analyser les expressions calc() , l'expression non valide calc(1 +) est devenue une erreur Sass alors qu'elle était auparavant transmise telle quelle. Cela n'a pas été considéré comme un changement radical, car calc(1 +) n'a jamais été un CSS valide pour commencer.
Dart Sass inclut une implémentation du côté compilateur du protocole Embedded Sass. Il est conçu pour être intégré dans un langage hôte, qui expose ensuite une API permettant aux utilisateurs d'invoquer Sass et de définir des fonctions et des importateurs personnalisés.
sass --embedded démarre le compilateur intégré et écoute sur stdin.
sass --embedded --version imprime versionResponse avec id = 0 en JSON et quitte.
L'indicateur de ligne de commande --embedded n'est pas disponible lorsque vous installez Dart Sass en tant que package npm. Aucun autre indicateur de ligne de commande n'est pris en charge avec --embedded .
Il existe quelques différences comportementales intentionnelles entre Dart Sass et Ruby Sass. Ce sont généralement des endroits où Ruby Sass a un comportement indésirable, et il est beaucoup plus facile d'implémenter le comportement correct que d'implémenter un comportement compatible. Ceux-ci devraient tous avoir des bogues de suivi contre Ruby Sass pour mettre à jour le comportement de référence.
@extend n'accepte que les sélecteurs simples, tout comme le deuxième argument de selector-extend() . Voir le numéro 1599.
Les sélecteurs de sujets ne sont pas pris en charge. Voir le numéro 1126.
Les arguments du pseudo-sélecteur sont analysés comme des <declaration-value> plutôt que d'avoir une analyse personnalisée plus limitée. Voir le numéro 2120.
La précision numérique est définie sur 10. Voir le numéro 1122.
L'analyseur de syntaxe indentée est plus flexible : il ne nécessite pas d'indentation cohérente dans l'ensemble du document. Voir le numéro 2176.
Les couleurs ne prennent pas en charge l'arithmétique couche par couche. Voir le numéro 2144.
Les nombres sans unité ne sont pas == aux nombres d'unités ayant la même valeur. De plus, les clés de mappage suivent la même logique que == -equality. Voir le numéro 1496.
Les valeurs alpha rgba() et hsla() avec des unités de pourcentage sont interprétées comme des pourcentages. Les autres unités sont interdites. Voir le numéro 1525.
Trop d’arguments variables passés à une fonction sont une erreur. Voir le numéro 1408.
Autorisez @extend à atteindre l'extérieur d'une requête multimédia s'il existe un @extend identique défini en dehors de cette requête. Ceci n'est pas suivi explicitement, car cela ne sera plus pertinent une fois le problème 1050 résolu.
Certains pseudos de sélecteur contenant des sélecteurs d'espace réservé seront compilés là où ils ne le seraient pas dans Ruby Sass. Cela correspond mieux à la sémantique des sélecteurs en question et est plus efficace. Voir le numéro 2228.
L’ancienne syntaxe :property value n’est pas prise en charge dans la syntaxe indentée. Voir le numéro 2245.
Le combinateur de référence n'est pas pris en charge. Voir le numéro 303.
L'unification universelle du sélecteur est symétrique. Voir le numéro 2247.
@extend ne produit pas d'erreur s'il correspond mais ne parvient pas à s'unifier. Voir le numéro 2250.
Dart Sass ne prend actuellement en charge que les documents UTF-8. Nous aimerions en prendre davantage en charge, mais Dart ne les prend actuellement pas en charge. Voir dart-lang/sdk#11744, par exemple.
Avertissement : il ne s'agit pas d'un produit Google officiel.
