Sass For Symfony!

编辑此页

此程序包使您可以轻松地将 Sass 与 Symfony 的 AssetMapper 组件一起使用（无需 Node！）。

自动检测系统中安装的 Sass 二进制文件
如果在系统中未检测到 Sass 二进制文件，则自动下载正确的 Sass 二进制文件
添加一个 sass:build 命令来构建和监视您的 Sass 更改

提示

虽然此程序包很棒，但您可能不需要使用 Sass！原生 CSS 现在支持变量和嵌套。请参阅是时候放弃 Sass 了吗？文章以了解更多详情。

安装

安装程序包

        1
        $ composer require symfonycasts/sass-bundle
    

用法

首先编写您的第一个 Sass 文件 assets/styles/app.scss，让我们添加一些基本样式

        1
2
3
4
5
6
7
        /* assets/styles/app.scss */

$red: #fc030b;

body {
  background: $red;
}
    

然后在您的模板中指向您的样式

        1
2
3
4
5
        {# templates/base.html.twig #}

{% block stylesheets %}
    <link rel="stylesheet" href="{{ asset('styles/app.scss') }}">
{% endblock %}
    

没错！您直接指向 .scss 文件。但不用担心，最终构建的 .css 文件将被返回！

然后运行命令

        1
        $ php bin/console sass:build --watch
    

就是这样！

Symfony CLI

如果使用 Symfony CLI，您可以将构建命令添加为 worker，以便在您运行 symfony server:start 时启动

        1
2
3
4
5
        # .symfony.local.yaml
workers:
    # ...
    sass:
        cmd: ['symfony', 'console', 'sass:build', '--watch']
    

提示

如果以守护程序身份运行 symfony server:start，您可以运行 symfony server:log 来跟踪 worker 的输出。

它是如何工作的？

首次运行 Sass 命令之一时，该程序包将自动尝试检测系统中安装的正确 Sass 二进制文件并使用它。如果找不到二进制文件，该程序包将自动为您的系统下载正确的二进制文件，并将其放入 bin/dart-sass 目录中。

当您运行 sass:build 时，该二进制文件用于将 Sass 文件编译为 var/sass/app.built.css 文件。最后，当请求 assets/styles/app.scss 的内容时，程序包会将该文件的内容与 var/sass/app.built.css 的内容交换。真棒！

从 AssetMapper 中排除 Sass 文件

由于您的 assets/ 目录中有 .scss 文件，因此在部署时，这些源文件将被复制到 public/assets/ 目录中。为了防止这种情况发生，您可以从 AssetMapper 中排除它们

        1
2
3
4
5
6
7
8
        # config/packages/asset_mapper.yaml
framework:
    asset_mapper:
        paths:
            - assets/
        excluded_patterns:
            - '*/assets/styles/_*.scss'
            - '*/assets/styles/**/_*.scss'
    

注意

请务必不要排除您的主 SCSS 文件（例如 assets/styles/app.scss）：这是在 AssetMapper 中使用的，并且其内容会与最终构建的 CSS 交换。

如何获取第三方库的源 Sass 文件

获取第三方 Sass 文件的最简单方法是通过 Composer。例如，请参阅以下部分，了解如何获取 Bootstrap 的源 Sass 文件。

但是，如果您使用的库无法通过 Composer 获得，则需要手动将其下载到您的应用程序或通过 NPM 获取它。

使用 Bootstrap Sass

Bootstrap 以 Sass 的形式提供，允许您自定义应用程序的外观和感觉。获取源 Sass 文件的简单方法是通过 Composer 程序包

        1
        $ composer require twbs/bootstrap
    

现在，从您的 app.scss 文件中导入核心 bootstrap.scss

        1
2
3
4
        /* Override some Bootstrap variables */
$red: #FB4040;

@import '../../vendor/twbs/bootstrap/scss/bootstrap';
    

使用 Bootswatch Sass

Bootswatch 也以 Sass 的形式提供，并为 Bootstrap 提供免费主题。获取源 Bootswatch Sass 文件的简单方法是通过 Composer 程序包

        1
        $ composer require thomaspark/bootswatch
    

现在，从您的 app.scss 文件中导入核心 Sass 主题文件以及 bootstrap.scss

        1
2
3
        @import '../../vendor/thomaspark/bootswatch/dist/[theme]/variables';
@import '../../vendor/twbs/bootstrap/scss/bootstrap';
@import '../../vendor/thomaspark/bootswatch/dist/[theme]/bootswatch';
    

不要忘记也安装主要的 twbs/bootstrap 程序包，因为 Bootswatch 需要它。有关更多详细信息，请参见上一节。

部署

部署时，在 asset-map:compile 命令之前运行 sass:build 命令，以便构建的文件可用

        1
2
        $ php bin/console sass:build
$ php bin/console asset-map:compile
    

限制：`url()` 相对路径

当在 Sass 文件中使用 url() 时，目前，路径必须相对于根 .scss 文件。例如，假设根 .scss 文件是

        1
2
        /* assets/styles/app.scss */
import 'tools/base';
    

假设有一个您想要从 base.css 引用的 assets/images/login-bg.png 文件

        1
2
3
4
5
6
7
8
        /* assets/styles/tools/base.scss */
.splash {
    /* This SHOULD work, but doesn't */
    background-image: url('../../images/login-bg.png');

    /* This DOES work: it's relative to app.scss */
    background-image: url('../images/login-bg.png');
}
    

应该可以使用 url() 和相对于当前文件的路径。但是，目前这是不可能的。有关更多详细信息，请参见此问题。

配置

要查看此程序包的完整配置，请运行

        1
        $ php bin/console config:dump symfonycasts_sass
    

源 Sass 文件

主要选项是 root_sass 选项，默认为 assets/styles/app.scss。这表示源 Sass 文件

        1
2
3
        # config/packages/symfonycasts_sass.yaml
symfonycasts_sass:
    root_sass: 'assets/styles/app.scss'
    

注意

root_sass 选项还支持表示不同源 Sass 文件路径的数组

        1
2
3
        symfonycasts_sass:
    root_sass:
        - '%kernel.project_dir%/assets/scss/app.scss'
    

Sass CLI 选项

您可以配置大多数 Dart Sass CLI 选项

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
        # config/packages/symfonycasts_sass.yaml
symfonycasts_sass:
    sass_options:
        # The output style for the compiled CSS files: expanded or compressed. Defaults to expanded.
        # style: expanded

        # Emit a @charset or BOM for CSS with non-ASCII characters. Defaults to true in Dart Sass.
        # charset: true

        # Register additional load paths. Defaults to empty array.
        # load_path: []

        # Whether to generate source maps. Defaults to true when "kernel.debug" is true.
        # source_map: true

        # Embed source file contents in source maps. Defaults to false.
        # embed_sources:

        # Embed source map contents in CSS. Defaults to false.
        # embed_source_map:

        # Don't print warnings. Defaults to false.
        # quiet:

        # Don't print deprecated warnings for dependencies. Defaults to false.
        # quiet_deps:

        # Don't compile more files once an error is encountered. Defaults to false.
        # stop_on_error:

        # Print full Dart stack traces for exceptions. Defaults to false.
        # trace:
    

使用不同的二进制文件

此程序包已经为您检测或安装了正确的二进制文件。但是，如果您已经在您的机器上安装了二进制文件，但程序包无法自动找到它 - 您可以指示程序包使用该二进制文件，设置 binary 选项

        1
2
        symfonycasts_sass:
    binary: 'node_modules/.bin/sass'
    

提示

如果在 binary 选项中显式指定了路径 - 程序包将仅使用它，这意味着它不会尝试搜索二进制文件本身或为您的系统自动下载它。要让程序包自动处理它 - 请勿指定 binary 选项。

注册额外的加载路径

您可以提供额外的加载路径，以使用 load_path 选项解析模块。

例如，使用 Bootstrap 的另一种方法是注册 vendor 路径

        1
2
3
4
5
        # config/packages/symfonycasts_sass.yaml
symfonycasts_sass:
    sass_options:
        load_path:
            - '%kernel.project_dir%/vendor/twbs/bootstrap/scss'
    

然后使用以下命令从 app.scss 导入 bootstrap

        1
        @import 'bootstrap';
    

这项工作，包括代码示例，均在 Creative Commons BY-SA 3.0 许可下获得许可。

版本