Symfony 的 Sass！

編輯此頁面

此套件讓您能輕鬆地將 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';

假設有一個 assets/images/login-bg.png 檔案，您想要從 base.css 參照它

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() 和相對於目前檔案的路徑。然而，目前這是不可能的。請參閱 此 issue 以取得更多詳細資訊。

設定

若要查看此套件的完整設定，請執行

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 授權條款授權。
目錄
    版本