# { } scss-to-css
### 将所有 SCSS 文件递归编译为缩小的 CSS。
## ⚡ 如何安装
作为**全局实用程序**：
```
$ npm install -g @adamlui/scss-to-css
```
作为**开发人员依赖**（例如，对于构建脚本），从项目根目录：
```
$ npm install -D @adamlui/scss-to-css
```
作为**运行时依赖**（例如，用于动态编译），从项目根目录：
```
$ npm install @adamlui/scss-to-css
```
## 💻 命令行使用
基本的**全局命令**是：
```
$ scss-to-css
```
示例输出：
**📝 笔记：**默认情况下也会生成源映射，除非传递 `-S` 或 `--no-source-maps`。
#
指定**输入/输出**路径：
```
$ scss-to-css [input_path] [output_path]
```
- `[input_path]`: SCSS 文件或包含要编译的 SCSS 文件的目录的路径，相对于当前工作目录。
- `[output_path]`: 存储 CSS 和源映射文件的文件或目录路径，相对于输入根目录（如果未提供，则使用 `css/`）。
**📝 注意:** 如果传递文件夹，文件将被递归处理，除非传递 `-R` 或 `--no-recursion`。
#
要用作 **包脚本**，请在项目的 `package.json` 中：
```json
"scripts": {
"build:css": ""
},
```
将 `` 替换为 `scss-to-css` + 可选参数。 然后，可以使用 `npm run build:css` 来运行该命令。
#
### 命令示例
编译 **当前目录** 中的所有 SCSS 文件（输出到 `css/`）：
```
$ scss-to-css
```
编译 **特定目录** 中的所有 SCSS 文件（输出到 `css/path/to/your/directory/`）：
```
$ scss-to-css path/to/your/directory
```
编译一个**特定文件**（输出到 `css/path/to/your/file.min.css`）：
```
$ scss-to-css path/to/your/file.scss
```
指定 **输入和输出** 目录（输出到 `output_folder/`）：
```
$ scss-to-css input_folder output_folder
```
**📝 注意:** 除非传递 `-M` 或 `--no-minify` ，否则输出 CSS 会被缩小。
#
### 命令行选项
```
布尔选项：
-n, --dry-run 实际上并不缩小文件，只是显示它们是否会被处理。
-d, --include-dotfolders 在文件搜索中包括点文件夹。
-S, --no-source-maps 防止生成源映射。
-M, --no-minify 禁用输出 CSS 的缩小。
-R, --no-recursion 禁用递归文件搜索。
-r, --relative-output 输出文件相对于每个源文件而非输入根目录。
-c, --copy 如果处理单个源文件，则将编译后的 CSS 复制到剪贴板，而不是写入文件。
-q, --quiet 禁止除错误之外的所有日志记录。
参数选项：
--ignores="dir/,file1.scss,file2.sass" 要从编译中排除的文件/目录。
--comment="comment" 将标头注释添加到已编译的 CSS 中。使用 '\n' 按行分隔。
--ui-lang="code" 用于显示用户界面的语言的 ISO 639-1 代码。
--config="path/to/file" 加载自定义配置文件。
命令：
-i, --init 创建配置文件（位于项目根目录）。
-h, --help 显示帮助屏幕。
-v, --version 显示版本号。
--stats 显示 npm 统计信息。
--debug [targetKey] 显示调试日志。
```
#
### 配置文件
您可以通过在项目根目录放置 `scss-to-css.config.mjs` 或 `scss-to-css.config.js` 文件来自定义 **scss-to-css** 的配置。
默认配置示例：
```js
export default {
dryRun: false, // 不实际压缩文件，仅显示哪些文件将被处理
includeDotFolders: false, // 在文件搜索中包含隐藏文件夹（以点开头的文件夹）
noSourceMaps: false, // 阻止生成源映射文件
noMinify: false, // 禁用输出 CSS 的压缩
noRecursion: false, // 禁用递归文件搜索
relativeOutput: false, // 输出文件相对于每个源文件，而不是相对于输入根目录
copy: false, // 如果只处理单个文件，则将编译后的 CSS 复制到剪贴板，而不是写入文件
quietMode: false, // 除了错误信息外，抑制所有日志输出
ignores: '', // 要从压缩中排除的文件/目录
comment: '' // 要添加到压缩代码开头的注释
}
```
💡 运行 `scss-to-css init` 即可在项目根目录生成一个 `scss-to-css.config.mjs` 模板文件。
## 🔌 API 使用
您还可以将 **scss-to-css** 导入您的应用程序以使用其 API 方法，无论是作为 ECMAScript 模块还是 CommonJS 模块。
#### ECMAScript*:
```js
import scssToCSS from '@adamlui/scss-to-css'
```
#### CJS:
```js
const scssToCSS = require('@adamlui/scss-to-css')
```
###### _*需要 Node.js 版本 14 或更高版本_
#
### `compile(input[, options])`
💡 根据提供的字符串输入编译 SCSS。
如果传入**源代码**，则直接编译，然后返回一个包含 `srcPath` + `code` + `srcMap` + `error` 的对象：
```js
const srcCode = 'h1 { font-size: 40px ; code { font-face: Roboto Mono }}',
compileResult = scssToCSS.compile(srcCode)
console.log(compileResult.error) // 输出运行时错误，如果没有错误则输出 `undefined`
console.log(compileResult.code) // 输出缩小的 CSS：'h1{font-size:40px}h1 code{font-face:Roboto Mono}'
```
如果传递了 **文件路径**，则文件的代码将被加载，然后编译为 CSS，返回一个像上面一样的对象。
如果传递 **目录路径**，则搜索 SCSS 文件（默认情况下递归），加载每个文件的代码并编译，然后返回包含 `srcPath` + `code` + `srcMap` + `error` 的对象数组：
```js
// 输出工作目录 + 所有嵌套目录中 SCSS 文件的路径
const compileResults = scssToCSS.compile('.')
compileResults.forEach(result => console.log(result.srcPath))
// 如果找到，则输出从第二个 SCSS 文件编译的 CSCS，如果未找到，则输出 `undefined`
console.log(compileResults[1].code)
```
选项是布尔值，作为对象属性传递。 例如：
```js
// 返回数据对象数组，其中 `.code` 包含未缩小的 CSS
scssToCSS.compile(inputDir, { minify: false })
```
可用参数（及其默认设置）有：
姓名 | 类型 | 描述 | 默认值
-----------------|--------|---------------------------------------------------|--------
`recursive` | 布尔值 | 如果传递目录路径，则递归搜索嵌套文件。 | `true`
`verbose` | 布尔值 | 在控制台/终端中显示日志记录。 | `true`
`dotFolders` | 布尔值 | 在文件搜索中包括点文件夹。 | `false`
`minify` | 布尔值 | 缩小输出 CSS。 | `true`
`sourceMaps` | 布尔值 | 生成 CSS 源映射。 | `true`
`relativeOutput` | 布尔值 | 输出文件相对于每个源文件而非输入根目录。 | `false`
`ignores` | 大批 | 要从编译中排除的文件/目录。 | `[]`
`comment` | 字符串 | 添加到已编译 CSS 前面的标头注释。使用 '\n' 按行分隔。 | `''`
#
### `findSCSS(searchDir[, options])`
💡 搜索传递的 `searchDir` 字符串中的所有 SCSS 文件（对于发现 [`compile()`](#compileinput-options) 将处理哪些文件很有用）并返回包含其文件路径的数组。
选项是布尔值，作为对象属性传递。 例如：
```js
// 在 assets/scss 中搜索 SCSS 文件
const searchResults = scssToCSS.findSCSS('assets/scss', { recursive: false })
console.log(searchResults)
/* 示例输出：
findSCSS() » Searching for SCSS files...
findSCSS() » Search complete! 2 files found.
findSCSS() » Check returned array.
[
'E:\\js\\utils\\scss-to-css\assets\\scss\\foo.scss',
'E:\\js\\utils\\scss-to-css\assets\\scss\\bar.sass'
]
*/
```
可用参数（及其默认设置）有：
姓名 | 类型 | 描述 | 默认值
--------------|--------|---------------------------------------|--------
`recursive` | 布尔值 | 递归搜索传递的 searchDir 中的嵌套文件。 | `true`
`verbose` | 布尔值 | 在控制台/终端中显示日志记录。 | `true`
`dotFolders` | 布尔值 | 在文件搜索中包括点文件夹。 | `false`
`ignores` | 大批 | 要从搜索结果中排除的文件/目录。 | `[]`
## 🏛️ MIT 许可证
**版权所有 © 2024 [刘展鹏 (Adam Lui)](https://github.com/adamlui) 和贡献者**
特此免费向任何获得副本的人授予许可本软件和相关文档文件（『软件』），处理在软件中不受限制，包括但不限于权利使用、复制、修改、合并、发布、分发、再许可和/或出售该软件的副本，并允许该软件是提供这样做，但须满足以下条件：
上述版权声明和本许可声明应包含在所有软件的副本或重要部分。
本软件『按原样』提供，不提供任何形式的明示或保证暗示的，包括但不限于适销性保证，适用于特定目的和非侵权。 在任何情况下都不得作者或版权持有人对任何索赔、损害或其他责任，无论是在合同、侵权或其他方面的行为中，由以下原因引起，出于或与软件或使用或其他交易有关软件。
## 🛠️ 相关实用程序
### [ minify.js](https://github.com/adamlui/minify.js/#readme) 
> 递归地缩小所有 JavaScript 文件。
[安装](https://github.com/adamlui/minify.js/tree/main/node.js/docs/zh-cn#-%E5%A6%82%E4%BD%95%E5%AE%89%E8%A3%85) /
[自述文件](https://github.com/adamlui/minify.js/tree/main/node.js/docs/zh-cn/#readme) /
[CLI 用法](https://github.com/adamlui/minify.js/tree/main/node.js/docs/zh-cn#-%E5%91%BD%E4%BB%A4%E8%A1%8C%E4%BD%BF%E7%94%A8) /
[API 使用](https://github.com/adamlui/minify.js/tree/main/node.js/docs/zh-cn#-api-%E4%BD%BF%E7%94%A8) /
[讨论](https://github.com/adamlui/minify.js/discussions)
**更多 JavaScript 实用程序** /
讨论 /
报告错误 /
报告漏洞 /
回到顶部 ↑
