django-sass-processor

在开发Django项目时，是否烦恼于必须运行Compass、Grunt或Gulp守护进程？

那么，这个应用程序正是为你准备的！无需管理第三方服务或特殊IDE插件，即可动态编译SASS/SCSS文件。

使用此库的其他良好理由

• 直接从源代码引用SASS/SCSS文件，而不是引用编译后的CSS文件，不需要依赖另一个创建它们的工具，该工具隐藏在源代码树中。
• 使用Django的settings.py进行路径、盒子大小等的配置，而不是使用另一个SCSS特定文件（通常是_variables.scss），来保存这些。
• 通过直接调用Django项目中的Python函数来扩展你的SASS函数。
• 直接在Django开发服务器的调试控制台中查看SCSS错误。

django-sass-processor在渲染模板时将*.scss或*.sass文件转换为*.css。出于性能考虑，这仅执行一次，因为预处理器会跟踪时间戳，只有当任何导入的SASS/SCSS文件比相应的生成CSS文件更年轻时，才会重新编译。

简介

此Django应用程序提供了一个模板标签{% sass_src 'path/to/file.scss' %}，可以用它来替代内置的模板标签static。此模板标签也适用于Jinja2模板。

如果SASS/SCSS文件要通过Media类或media属性进行引用，则可以直接使用SASS处理器。

此外，django-sass-processor附带一个管理命令，可以作为一个离线操作将sass_src模板标签中所有出现的内容转换为内容。因此，在生产环境中不需要libsass编译器。

在开发期间，会生成与编译的*.css文件一起的sourcemap。这使得调试样式表错误变得更容易。

使用此工具，你可以安全地从Django项目中移除Ruby安装的"Compass"和"SASS"。你也不需要基于node.js的任何目录"监视"守护进程。

项目的首页

在GitHub上

https://github.com/jrief/django-sass-processor

请使用问题跟踪器报告错误或提出新功能建议。

安装

pip install libsass django-compressor django-sass-processor

仅当使用manage.py compilescss命令进行离线编译时，才需要django-compressor。

如果使用离线编译预编译并部署了SASS/SCSS文件，则生产环境中不需要libsass。

配置

在settings.py中添加到

INSTALLED_APPS = [
    ...
    'sass_processor',
    ...
]

django-sass-processor附带一个特殊的查找器，用于定位位于STORAGES['sass_processor']['ROOT']（对于Django >= 4.2.)或SASS_PROCESSOR_ROOT（对于Django <= 4.1.）的目录中生成的*.css文件，或者如果没有设置，则位于STATIC_ROOT。只需将其添加到您的settings.py。如果您的settings.py中没有STATICFILES_FINDERS，请务必包括Django的默认查找器。

STATICFILES_FINDERS = [
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'sass_processor.finders.CssFinder',
    ...
]

可选地，添加一个额外的搜索路径列表，SASS编译器在SASS/SCSS文件中使用@import "...";语句时可能会检查。

import os

SASS_PROCESSOR_INCLUDE_DIRS = [
    os.path.join(PROJECT_PATH, 'extra-styles/scss'),
    os.path.join(PROJECT_PATH, 'node_modules'),
]

此外，django-sass-processor将遍历所有已安装的Django应用程序（INSTALLED_APPS）并检查它们的静态文件夹。如果其中任何一个包含匹配正则表达式模式^_.+\.(scss|sass)$（意思是：文件名以下划线开头且类型为scss或sass）的文件，则将该应用程序特定的静态文件夹添加到libsass的包含目录中。您可以通过设置来禁用此功能：

SASS_PROCESSOR_AUTO_INCLUDE = False

如果您的SASS/SCSS文件中，您还想要导入（使用@import "path/to/scssfile";）不以下划线开头的文件，则可以在您的设置中配置另一个正则表达式模式，例如

SASS_PROCESSOR_INCLUDE_FILE_PATTERN = r'^.+\.scss$'

将会查找所有类型的 scss 文件。请记住，以下划线开头的 SASS/SCSS 文件是为了被其他 SASS/SCSS 文件导入的，而以字母或数字开头的文件是为了被 HTML 标签 <link href="{% sass_src 'path/to/file.scss' %}" ...> 包含的。

在开发过程中，或者当 SASS_PROCESSOR_ENABLED = True 时，编译后的文件将被放置到由 STORAGES['sass_processor']['ROOT'] （对于 Django >= 4.2）或 SASS_PROCESSOR_ROOT （对于 Django <= 4.1）引用的文件夹中。如果没有设置，则此设置默认为 STATIC_ROOT。将位置放在工作目录之外可以防止自动生成的文件污染您的本地 static/css/... 目录。因此，请确保这个目录可以被 Django runserver 写入。

在 settings.py 中调整 SASS 编译器参数。

整数 SASS_PRECISION 设置输出 CSS 的浮点精度。libsass 的默认值为 5。注意：bootstrap-sass 需要 8，否则将出现各种布局问题。

SASS_PRECISION = 8

SASS_OUTPUT_STYLE 设置编译结果的编码风格，可以是 compact、compressed、expanded 或 nested 之一。默认情况下，在 DEBUG 时为 nested，在生产中为 compressed。

注意：libsass-python 0.8.3 在 Windows 上保存结果时编码存在问题，该问题已修复，并将包含在未来的 pip 包发布中，同时避免使用 compressed 输出风格。

SASS_OUTPUT_STYLE = 'compact'

Jinja2 支持

sass_processor.jinja2.ext.SassSrc 是一个 Jinja2 扩展。将其添加到您的 Jinja2 环境中，以启用 sass_src 标签，不需要 load 标签。以下是向 Django 添加 Jinja2 环境的示例。

在 settings.py

TEMPLATES = [{
    'BACKEND': 'django.template.backends.jinja2.Jinja2',
    'DIRS': [],
    'APP_DIRS': True,
    'OPTIONS': {
        'environment': 'yourapp.jinja2.environment'
    },
    ...
}]

如果您仍在其他地方使用 Django 模板，请确保添加默认模板后端。这已在 升级模板文档 中说明。

在 yourapp/jinja2.py

# Include this for Python 2.
from __future__ import absolute_import

from jinja2 import Environment


def environment(**kwargs):
    extensions = [] if 'extensions' not in kwargs else kwargs['extensions']
    extensions.append('sass_processor.jinja2.ext.SassSrc')
    kwargs['extensions'] = extensions

    return Environment(**kwargs)

如果您想使用 compilescss 命令，则还必须在您的设置中添加以下内容。

from yourapp.jinja2 import environment

COMPRESS_JINJA2_GET_ENVIRONMENT = environment

用法

在您的 Django 模板中

{% load sass_tags %}

<link href="{% sass_src 'myapp/css/mystyle.scss' %}" rel="stylesheet" type="text/css" />

上面的模板代码将被渲染为 HTML

<link href="/static/myapp/css/mystyle.css" rel="stylesheet" type="text/css" />

您可以在 Sekizai 的 {% addtoblock "css" %} 语句中安全地使用此模板标签。

在媒体类或属性中

在 Python 代码中，您可以直接访问 SASS 处理器的 API。这在 Django 的 admin 或表单框架中非常有用。

from sass_processor.processor import sass_processor

class SomeAdminOrFormClass(...):
    ...
    class Media:
        css = {
            'all': [sass_processor('myapp/css/mystyle.scss')],
        }

使用来自 https://caniuse.cn/ 的值添加 CSS 规则的供应商前缀

编写 SCSS 应该快速简单，您不需要关心是否要在 CSS 指令中添加供应商特定的前缀。不幸的是，没有纯 Python 包可以解决这个问题，但使用一些 node 模块，我们可以将其添加到我们的处理流程中。

以超级用户身份安装

npm install -g npx

并在您的项目根目录中安装

npm install postcss-cli autoprefixer

确保 node_modules 的路径与设置指令 STATICFILES_DIRS 中的条目相对应（见下文）。

如果您的系统路径中找不到 npx，请使用设置指令 NODE_NPX_PATH = /path/to/npx 指向该可执行文件。

如果一切设置正确，django-sass-processor 将将所有必需的供应商前缀添加到编译后的 CSS 文件中。有关更多信息，请参阅 Autoprefixer 包。

要禁用自动前缀，请设置 NODE_NPX_PATH = None。

重要提示：如果已安装 npx，但本地 node_modules 中缺少 postcss 和/或 autoprefixer，则必须将 NODE_NPX_PATH 设置为 None，否则 django-sass-processor 将不知道如何后处理生成的 CSS 文件。

离线编译

如果您想预编译整个项目中所有SASS/SCSS文件的实例，请在命令行中调用

./manage.py compilescss

这对于准备生产环境很有用，因为在生产环境中SASS/SCSS文件不能即时编译。

为了简化部署，编译后的*.css文件与其对应的SASS/SCSS文件存储在相邻位置。编译完文件后运行

./manage.py collectstatic

就像在正常部署中一样。

如果您不想在生产环境中暴露SASS/SCSS文件，请使用以下命令部署

./manage.py collectstatic --ignore=*.scss

要删除本地静态目录中的编译后的*.css文件，只需反转上述命令

./manage.py compilescss --delete-files

这将删除所有之前生成的*.css文件的实例。

或者您可以将编译结果直接编译到STORAGES['sass_processor']['ROOT'] [Django >= 4.2.](Django >= 4.2.) 或 SASS_PROCESSOR_ROOT [Django <= 4.1.](Django <= 4.1.) 目录（如果未指定，则为STATIC_ROOT）

./manage.py compilescss --use-storage

SASS_TEMPLATE_EXTS = ['.html','.jade']

npm install bootstrap-sass

STATICFILES_DIRS = [
    ...
    ('node_modules', '/path/to/your/project/node_modules/'),
    ...
]

NODE_MODULES_URL = STATIC_URL + 'node_modules/'

$icon-font-path: unquote(get-setting(NODE_MODULES_URL) + "bootstrap-sass/assets/fonts/bootstrap/");

SASS_PROCESSOR_CUSTOM_FUNCTIONS = {
    'get-color': 'myproject.utils.get_color',
}

$color: get-color(250, 10, 120);

# For Django >= 4.2.*
STORAGES['sass_processor'] = {
    'BACKEND': 'django.core.files.storage.FileSystemStorage',
    'OPTIONS': {
        'location': '/srv/media/generated',
        'base_url': 'https://media.myapp.example.com/generated'
    }
}

# For Django <= 4.1.*
SASS_PROCESSOR_STORAGE = 'django.core.files.storage.FileSystemStorage'
SASS_PROCESSOR_STORAGE_OPTIONS = {
    'location': '/srv/media/generated',
    'base_url': 'https://media.myapp.example.com/generated'
}

# For Django >= 4.2.*
STORAGES['sass_processor'] = {
    'BACKEND': 'storages.backends.s3boto3.S3Boto3Storage'
}

# For Django <= 4.1.*
SASS_PROCESSOR_STORAGE = 'storages.backends.s3boto3.S3Boto3Storage'

python -m pip install --upgrade pip
pip install Django
pip install -r tests/requirements.txt
python -m pytest tests