turf 🌱

警告 | 仓库可能反映当前的开发状态，可能与官方发布的版本不同。虽然仓库提供了对持续开发和潜在即将推出的功能的洞察，但它可能并不一定代表通过 crates.io 或其他分发渠道提供的版本。

turf 允许您在编译时将 SCSS 构建到 CSS 并将这些样式注入到您的二进制文件中。

turf 将

• 🌿 在编译时使用 grass 将您的 SCSS 文件转换为 CSS
• 🪴 在编译时为您的 CSS 生成唯一且动态的类名
• 🔬 使用 lightningcss 压缩和优化您的 CSS，确保与各种浏览器目标的兼容性
• 🎨 将生成的 CSS 注入到您的二进制文件中，确保您需要时可以快速访问这些样式

用法

对于完整的可运行示例项目，您可以查看以下示例之一

1. 为您的应用程序创建 SCSS 样式

// file at scss/file/path.scss

.TopLevelClass {
    color: red;

    .SomeClass {
        color: blue;
    }
}

2. 使用 style_sheet 宏将生成的 CSS 包含到您的代码中

turf::style_sheet!("scss/file/path.scss");

上述示例中的宏将扩展到以下代码

static STYLE_SHEET: &'static str = "<style_sheet>";
struct ClassName;
impl ClassName {
    pub const TOP_LEVEL_CLASS: &'static str = "<unique_class_name>";
    pub const SOME_CLASS: &'static str = "<another_unique_class_name>";
}

3. 使用 ClassName 结构及其相关常量来访问生成的类名

let top_level_class_name = ClassName::TOP_LEVEL_CLASS;
let some_class_name = ClassName::SOME_CLASS;

配置

turf 的配置可以在 Cargo.toml 文件中使用 [package.metadata.turf] 和 [package.metadata.turf-dev] 键进行指定。这允许您在项目清单中方便地管理开发和生产构建的 SCSS 编译设置。

这两个配置文件提供完全相同的配置选项。然而，如果您没有指定一个 [package.metadata.turf-dev] 配置文件，[package.metadata.turf] 的设置也将应用于调试构建。这确保了在不同构建类型之间编译过程的一致性，除非您明确为开发配置定义了单独的配置。

示例配置

[package.metadata.turf]
minify = true
load_paths = ["path/to/scss/files", "path/to/other/scss/files"]

[package.metadata.turf.class_names]
template = "custom-<id>-<original_name>"
excludes = ["exclude-this-class-please", "^abc-[123]{4}"]

[package.metadata.turf.browser_targets]
chrome = [80, 1, 2]
firefox = 65
safari = [12, 3]

[package.metadata.turf.file_output]
global_css_file_path = "path/to/global.css"
separate_css_files_path = "dir/for/separate/css/"

以下配置选项可用

• minify（默认：true）：指定生成的CSS是否应进行压缩。如果设置为true，CSS输出将被压缩并优化以减小文件大小。如果设置为false，CSS输出将带有缩进和换行符以增强可读性。

• load_paths：指定在编译期间搜索要包含的SCSS文件的额外路径。它接受一个字符串值列表，每个值代表要包含的目录路径。此选项允许您从多个目录导入SCSS文件。

• browser_targets：定义生成CSS时兼容性所需的浏览器版本。它期望一个包含不同浏览器特定版本的架构。每个浏览器都可以指定其自己的版本。

• class_names：允许配置CSS类名生成。它期望一个包含用于生成CSS类名和从唯一化过程中排除类名的两个值的架构。

• debug（默认：false）：当设置为true时，此选项将启用读取配置和生成的CSS类名的调试输出。这有助于故障排除和理解CSS是如何生成的。

• file_output：启用编译CSS的输出。它期望一个包含单个全局CSS文件或为每个编译的SCSS文件生成单独CSS文件的架构。

class_names 键

• template（默认："class-<id>"）：指定生成随机CSS类名的模板。模板可以包含占位符以自定义输出。<id> 将被替换为每个CSS类名的唯一标识符，而 <original_name> 将被替换为SCSS文件中的原始类名。

• excludes：一个正则表达式模式数组，用于排除SCSS文件中的类名从唯一化过程中。

file_output 键

• global_css_file_path：指定全局CSS文件的文件路径。如果设置，将在提供的路径创建一个CSS文件，并将所有编译的样式写入此文件。这允许您有一个包含所有编译样式的单个CSS文件。

• separate_css_files_path：指定单独CSS文件的目录路径。如果设置，所有编译的CSS文件都将保存在指定的目录中。每个编译的SCSS文件都将在该目录中对应一个CSS文件，允许进行模块化CSS管理。内联SCSS样式定义的文件名将是从原始SCSS样式计算出的64位哈希。

浏览器版本

支持的浏览器如下

• android
• chrome
• edge
• firefox
• ie
• ios_saf
• opera
• safari
• samsung

浏览器版本格式

支持三种格式

附加宏

turf 为其他用例提供了一些附加宏。

style_sheet_values 宏

在某些情况下，可能需要有一个结构体的实例来访问类名（例如，当在 askama 模板中使用 turf 时）。turf::style_sheet_values 宏提供了一个直接包含生成的 CSS 并获取相关类名的替代方法。它返回一个包含 (style_sheet: &'static str, class_names: struct) 的元组。

用法

let (style_sheet, class_names) = turf::style_sheet_values!("path/to/style.scss");
let some_class_name = class_names.some_class;

inline_style_sheet 宏

如果您不想将样式表放在另一个文件中，可以使用 turf::inline_style_sheet 宏。它允许您编写内联 SCSS，然后将其编译为 CSS。

用法

turf::inline_style_sheet! {
    .TopLevelClass {
        color: red;

        .SomeClass {
            color: blue;
        }
    }
}

// ...

let some_class_name = ClassName::SOME_CLASS;

inline_style_sheet_values 宏

此宏结合了 style_sheet_values 和 inline_style_sheet 宏的功能。它允许您编写内联 SCSS，并返回一个包含 (style_sheet: &'static str, class_names: struct) 的元组。

用法

let (style_sheet, class_names) = turf::inline_style_sheet_values! {
    .TopLevelClass {
        color: red;

        .SomeClass {
            color: blue;
        }
    }
};
let some_class_name = class_names.some_class;

贡献

对 turf 的贡献总是受欢迎！无论您是否有新功能或改进的想法，请不要犹豫，提出一个问题或提交一个 pull request。 🤝

许可

turf 在 MIT 许可下发布。有关更多详细信息，请参阅 LICENSE 文件。 📄