# { } 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" Load custom config file.
訊息命令：
-i, --init Create config file (in project root).
-h, --help 顯示幫助畫面。
-v, --version 顯示版本號。
--stats 顯示 npm 統計資訊。
--debug [targetKey] 顯示調試日誌。
```
#
### 設定檔
**scss-to-css** 可以透過放置在專案根目錄下的 `scss-to-css.config.mjs` 或 `scss-to-css.config.js` 進行自訂。
預設值範例：
```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 檔案編譯的 CSS，如果未找到，則輸出 `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-tw#-%E5%A6%82%E4%BD%95%E5%AE%89%E8%A3%9D) /
[自述文件](https://github.com/adamlui/minify.js/tree/main/node.js/docs/zh-tw/#readme) /
[CLI 用法](https://github.com/adamlui/minify.js/tree/main/node.js/docs/zh-tw#-%E5%91%BD%E4%BB%A4%E5%88%97%E4%BD%BF%E7%94%A8) /
[API 使用](https://github.com/adamlui/minify.js/tree/main/node.js/docs/zh-tw#-api-%E4%BD%BF%E7%94%A8) /
[討論](https://github.com/adamlui/minify.js/discussions)
**更多 JavaScript 實用程式** /
讨论 /
報告錯誤 /
報告漏洞 /
回到顶部 ↑
