選項 · Prettier 繁體中文

Prettier 提供了一些格式化選項。

要瞭解更多關於 Prettier 對選項的立場，請參閱選項哲學。

如果您要更改任何選項，建議您透過設定檔來進行。這樣 Prettier CLI、編輯器整合和其他工具才能知道您使用的選項。

實驗性三元運算子格式

在 prettier 的新的三元運算子格式成為預設行為之前試用它。

有效選項

true - 使用奇特的三元運算子格式，問號放在條件之後。
false - 保留三元運算子的預設行為；將問號與結果放在同一行。

預設值	CLI 覆寫	API 覆寫
`false`	`--experimental-ternaries`	`experimentalTernaries: <布林值>`

列印寬度

指定格式化工具將換行的行長度。

為了方便閱讀，建議不要使用超過 80 個字元

在程式碼風格指南中，最大行長規則通常設定為 100 或 120。然而，當人們編寫程式碼時，他們並不會努力讓每一行都達到最大欄數。開發人員經常使用空格來斷開長行以提高可讀性。實際上，平均行長通常遠低於最大值。

Prettier 的 printWidth 選項運作方式不同。它不是硬性的行長度上限。它是一種告訴 Prettier 您希望行的大致長度的方式。Prettier 會產生更短和更長的線，但通常會努力滿足指定的 printWidth。

記住，電腦是笨的。您需要明確地告訴它們該做什麼，而人類可以做出自己的（隱含的）判斷，例如何時斷行。

換句話說，不要試圖將 printWidth 用作 ESLint 的 max-len - 它們不一樣。max-len 只是說明允許的最大行長度是多少，而不是通常的首選長度是多少 - 這正是 printWidth 指定的。

預設值	CLI 覆寫	API 覆寫
`80`	`--print-width <整數>`	`printWidth: <整數>`

在 .editorconfig 檔案中設定 max_line_length 將設定 Prettier 的列印寬度，除非被覆蓋。

（如果您在格式化 Markdown 時不想要換行，可以將 Prose Wrap 選項設定為停用它。）

Tab 寬度

指定每個縮排級別的空格數。

預設值	CLI 覆寫	API 覆寫
`2`	`--tab-width <整數>`	`tabWidth: <整數>`

在 .editorconfig 檔案中設定 indent_size 或 tab_width 將設定 Prettier 的 Tab 寬度，除非被覆蓋。

使用 Tab 字元

使用 Tab 字元而不是空格來縮排程式碼。

預設值	CLI 覆寫	API 覆寫
`false`	`--use-tabs`	`useTabs: <布林值>`

在 .editorconfig 檔案中設定 indent_style 將設定 Prettier 的 Tab 使用方式，除非被覆蓋。

（Tab 字元將用於_縮排_，但 Prettier 使用空格來_對齊_內容，例如在三元運算子中。這種行為稱為 SmartTabs。）

分號

在語句結尾處列印分號。

有效選項

true - 在每個語句的結尾加上分號。
false - 僅在可能導致 ASI 錯誤的行首新增分號。

預設值	CLI 覆寫	API 覆寫
`true`	`--no-semi`	`semi: <布林值>`

引號

使用單引號而不是雙引號。

注意事項

JSX 引號會忽略此選項 - 請參閱 jsx-single-quote。
如果一種引號的數量超過另一種引號，則會使用較少使用的引號來格式化字串 - 例如："I'm double quoted" 結果為 "I'm double quoted"，而 "This \"example\" is single quoted" 結果為 'This "example" is single quoted'。

更多資訊，請參閱字串原理說明。

預設值	CLI 覆寫	API 覆寫
`false`	`--single-quote`	`singleQuote: <布林值>`

屬性引號

更改物件屬性何時使用引號。

有效選項

"as-needed" - 僅在物件屬性需要時才加上引號。
"consistent" - 如果物件中至少有一個屬性需要引號，則所有屬性都使用引號。
"preserve" - 保留物件屬性中輸入的引號用法。

預設值	CLI 覆寫	API 覆寫
`"as-needed"`	`--quote-props <as-needed\|consistent\|preserve>`	`quoteProps: "<as-needed\|consistent\|preserve>"`

請注意，Prettier 不會移除 Angular 表達式、TypeScript 和 Flow 中數字屬性名稱的引號，因為在這些語言中，字串和數字鍵的區別很重要。請參閱：Angular、TypeScript、Flow。Prettier 也不會移除 Vue 的數字屬性引號（請參閱關於此問題的議題）。

JSX 引號

在 JSX 中使用單引號而不是雙引號。

預設值	CLI 覆寫	API 覆寫
`false`	`--jsx-single-quote`	`jsxSingleQuote: <布林值>`

尾端逗號

預設值在 v3.0.0 中從 es5 更改為 all

盡可能在多行逗號分隔的語法結構中列印尾端逗號。（例如，單行陣列永遠不會有尾端逗號。）

有效選項

"all" - 盡可能使用尾端逗號（包括函式參數和呼叫）。要運行以此格式格式化的 JavaScript 代碼，需要支持 ES2017（Node.js 8+ 或現代瀏覽器）的引擎或向下編譯。這也在 TypeScript 中啟用類型參數中的尾端逗號（自 2018 年 1 月發布的 TypeScript 2.7 起受支持）。
"es5" - 在 ES5 中有效的尾端逗號（物件、陣列等）。TypeScript 和 Flow 中類型參數的尾端逗號。
"none" - 沒有尾端逗號。

預設值	CLI 覆寫	API 覆寫
`"all"`	`--trailing-comma <all\|es5\|none>`	`trailingComma: "<all\|es5\|none>"`

括號間距

在物件字面值中的括號之間列印空格。

有效選項

true - 範例：{ foo: bar }。
false - 範例：{foo: bar}。

預設值	CLI 覆寫	API 覆寫
`true`	`--no-bracket-spacing`	`bracketSpacing: <布林值>`

括號換行

將多行 HTML（HTML、JSX、Vue、Angular）元素的 > 放在最後一行的末尾，而不是單獨放在下一行（不適用於自閉合元素）。

有效選項

true - 範例

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}>
  Click Here
</button>

false - 範例

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}
>
  Click Here
</button>

預設值	CLI 覆寫	API 覆寫
`false`	`--bracket-same-line`	`bracketSameLine: <布林值>`

[已棄用] JSX 括號

此選項已在 v2.4.0 中棄用，請改用 --bracket-same-line

將多行 JSX 元素的 > 放在最後一行的末尾，而不是單獨放在下一行（不適用於自閉合元素）。

有效選項

true - 範例

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}>
  Click Here
</button>

false - 範例

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}
>
  Click Here
</button>

預設值	CLI 覆寫	API 覆寫
`false`	`--jsx-bracket-same-line`	`jsxBracketSameLine: <布林值>`

箭頭函式括號

v1.9.0 首次提供，預設值在 v2.0.0 中從 avoid 更改為 always

在單個箭頭函式參數周圍加上括號。

有效選項

"always" - 一律加上括號。範例：(x) => x
"avoid" - 盡可能省略括號。範例：x => x

預設值	CLI 覆寫	API 覆寫
`"always"`	`--arrow-parens <always\|avoid>`	`arrowParens: "<always\|avoid>"`

乍看之下，避免使用括號似乎是更好的選擇，因為可以減少視覺上的干擾。然而，當 Prettier 移除括號後，會增加添加類型註釋、額外參數或預設值以及進行其他修改的難度。在實際程式碼庫中，一致地使用括號可以提供更好的開發體驗，這也說明了此選項預設值的合理性。

範圍

僅格式化檔案的某一部分。

這兩個選項可以用於格式化從給定字元偏移量開始和結束的程式碼（分別包含和不包含）。範圍將會延伸

向後延伸至包含所選語句的第一行的開頭。
向前延伸至所選語句的結尾。

預設值	CLI 覆寫	API 覆寫
`0`	`--range-start <int>`	`rangeStart: <int>`
`無限大`	`--range-end <int>`	`rangeEnd: <int>`

剖析器

指定要使用的剖析器。

Prettier 會自動從輸入檔案路徑推斷剖析器，因此您不應該需要更改此設定。

babel 和 flow 剖析器都支援相同的 JavaScript 功能集（包括 Flow 類型註釋）。它們在某些邊緣情況下可能有所不同，因此如果您遇到其中一種情況，可以嘗試使用 flow 代替 babel。typescript 和 babel-ts 也幾乎相同。babel-ts 可能支援 TypeScript 尚不支援的 JavaScript 功能（提案），但在處理無效程式碼時，它的容錯性較低，且經過實際測試的程度也低於 typescript 剖析器。

有效選項

"babel" (透過 @babel/parser) 在 v1.16.0 之前命名為 "babylon"
"babel-flow" (與 "babel" 相同，但明確啟用 Flow 剖析以避免歧義) v1.16.0 首次提供
"babel-ts" (類似於 "typescript"，但使用 Babel 及其 TypeScript 插件) v2.0.0 首次提供
"flow" (透過 flow-parser)
"typescript" (透過 @typescript-eslint/typescript-estree) v1.4.0 首次提供
"espree" (透過 espree) v2.2.0 首次提供
"meriyah" (透過 meriyah) v2.2.0 首次提供
"acorn" (透過 acorn) v2.6.0 首次提供
"css" (透過 postcss) v1.7.1 首次提供
"scss" (透過 postcss-scss) v1.7.1 首次提供
"less" (透過 postcss-less) v1.7.1 首次提供
"json" (透過 @babel/parser parseExpression) v1.5.0 首次提供
"json5" (與 "json" 相同的剖析器，但輸出為 json5) v1.13.0 首次提供
"jsonc" (與 "json" 相同的剖析器，但輸出為「帶註釋的 JSON」) v3.2.0 首次提供
"json-stringify" (與 "json" 相同的剖析器，但輸出像 JSON.stringify) v1.13.0 首次提供
"graphql" (透過 graphql/language) v1.5.0 首次提供
"markdown" (透過 remark-parse) v1.8.0 首次提供
"mdx" (透過 remark-parse 和 @mdx-js/mdx) v1.15.0 首次提供
"html" (透過 angular-html-parser) 1.15.0 首次提供
"vue" (與 "html" 相同的剖析器，但也格式化 vue 特定的語法) 1.10.0 首次提供
"angular" (與 "html" 相同的剖析器，但也透過 angular-estree-parser 格式化 angular 特定的語法) 1.15.0 首次提供
"lwc" (與 "html" 相同的剖析器，但也格式化 LWC 特定的語法，用於未加引號的模板屬性) 1.17.0 首次提供
"yaml" (透過 yaml 和 yaml-unist-parser) 1.14.0 首次提供

預設值	CLI 覆寫	API 覆寫
無	`--parser <string>`	`parser: "<string>"`

注意：在 v1.13.0 之前，預設值為 "babylon"。

注意：自訂剖析器 API 已在 v3.0.0 中移除。請改用插件（如何遷移）。

檔案路徑

指定用於推斷要使用哪個剖析器的檔案名稱。

例如，以下將使用 CSS 剖析器

cat foo | prettier --stdin-filepath foo.css

此選項僅在 CLI 和 API 中 hữu dụng。在設定檔中使用它沒有意義。

預設值	CLI 覆寫	API 覆寫
無	`--stdin-filepath <string>`	`filepath: "<string>"`

需要 Pragma

v1.7.0 首次提供

Prettier 可以將自身限制為僅格式化檔案頂部包含特殊註釋（稱為 pragma）的檔案。這在將大型、未格式化的程式碼庫逐步轉換到 Prettier 時非常有用。

當提供 --require-pragma 時，第一個註釋如下所示的檔案將被格式化

/**
 * @prettier
 */

或

/**
 * @format
 */

預設值	CLI 覆寫	API 覆寫
`false`	`--require-pragma`	`requirePragma: <bool>`

插入 Pragma

v1.8.0 版本開始提供

Prettier 可以在檔案頂部插入一個特殊的 @format 標記，指定該檔案已經使用 Prettier 格式化過。這與 --require-pragma 選項搭配使用效果很好。如果檔案頂部已經有一個文件區塊，則此選項將在其中添加一個帶有 @format 標記的新行。

請注意，「搭配使用」並不意味著「同時使用」。當同時使用這兩個選項時，--require-pragma 優先，因此 --insert-pragma 會被忽略。其理念是，在大型程式碼庫中逐步採用 Prettier 的過程中，參與轉換過程的開發人員使用 --insert-pragma，而團隊的其他成員和自動化工具使用 --require-pragma 來僅處理已轉換的檔案。此功能的靈感來自 Facebook 的採用策略。

預設值	CLI 覆寫	API 覆寫
`false`	`--insert-pragma`	`insertPragma: <布林值>`

散文換行

v1.8.2 版本開始提供

預設情況下，Prettier 不會更改 Markdown 文字中的換行，因為某些服務使用對換行敏感的渲染器，例如 GitHub 評論和 BitBucket。要讓 Prettier 將散文換行到列印寬度，請將此選項更改為「always」。如果您希望 Prettier 強制所有散文區塊都在一行上，並依靠編輯器/檢視器的軟換行，則可以使用 "never"。

有效選項

"always" - 如果散文超過列印寬度，則換行。
"never" - 將每個散文區塊展開成一行。
"preserve" - 不執行任何操作，保留散文原樣。 _v1.9.0 版本開始提供_

預設值	CLI 覆寫	API 覆寫
`"preserve"`	`--prose-wrap <always\|never\|preserve>`	`proseWrap: "<always\|never\|preserve>"`

HTML 空白字元敏感度

v1.15.0 版本開始提供，Handlebars 在 2.3.0 版本開始提供

指定 HTML、Vue、Angular 和 Handlebars 的全域空白字元敏感度。更多資訊，請參閱空白字元敏感的格式化。

有效選項

"css" - 遵循 CSS display 屬性的預設值。對於 Handlebars，處理方式與 strict 相同。
"strict" - 所有標籤周圍的空白字元（或缺少空白字元）都被視為重要。
"ignore" - 所有標籤周圍的空白字元（或缺少空白字元）都被視為不重要。

預設值	CLI 覆寫	API 覆寫
`"css"`	`--html-whitespace-sensitivity <css\|strict\|ignore>`	`htmlWhitespaceSensitivity: "<css\|strict\|ignore>"`

Vue 檔案 script 和 style 標籤縮排

v1.19.0 版本開始提供

是否縮排 Vue 檔案中 <script> 和 <style> 標籤內的程式碼。

有效選項

false - 不縮排 Vue 檔案中的 script 和 style 標籤。
true - 縮排 Vue 檔案中的 script 和 style 標籤。

預設值	CLI 覆寫	API 覆寫
`false`	`--vue-indent-script-and-style`	`vueIndentScriptAndStyle: <布林值>`

行尾符號

v1.15.0 版本開始提供，預設值在 v2.0.0 中從 auto 更改為 lf

由於歷史原因，文字檔案中存在兩種常見的行尾符號：\n（或 Line Feed 的縮寫 LF）和 \r\n（或 Carriage Return + Line Feed 的縮寫 CRLF）。前者常見於 Linux 和 macOS，而後者常見於 Windows。維基百科上有關於此的一些詳細說明。

當來自不同作業系統的人們在一個專案上協作時，很容易在共用的 git 儲存庫中出現混合的行尾符號。Windows 使用者也可能意外地將先前提交的檔案中的行尾符號從 LF 更改為 CRLF。這樣做會產生大量的 git diff，從而使檔案的行級歷史記錄（git blame）更難以瀏覽。

如果您想確保您的整個 git 儲存庫中，Prettier 涵蓋的檔案都只包含 Linux 風格的行尾符號：

確保 Prettier 的 endOfLine 選項設定為 lf（自 v2.0.0 起為預設值）
設定 pre-commit hook 來執行 Prettier
使用 --check 旗標設定 Prettier 在您的 CI 流程中運行。如果您使用 Travis CI，請在 .travis.yml 中將 autocrlf 選項設定為 input。
在儲存庫的 .gitattributes 檔案中新增 * text=auto eol=lf。您可能需要要求 Windows 使用者在此變更後重新複製您的儲存庫，以確保 git 在 checkout 時沒有將 LF 轉換為 CRLF。

所有作業系統中的所有現代文字編輯器都能夠在使用 \n (LF) 時正確顯示換行符號。但是，舊版的 Windows 記事本會將這些行視覺上壓縮成一行，因為它們只能處理 \r\n (CRLF)。

有效選項

"lf" – 僅換行 (\n)，常見於 Linux 和 macOS 以及 git 儲存庫中
"crlf" - 回車 + 換行字元 (\r\n)，常見於 Windows
"cr" - 僅回車字元 (\r)，很少使用
"auto" - 保留現有的換行符號（透過查看第一行之後使用的換行符號來標準化檔案中的混合值）

預設值	CLI 覆寫	API 覆寫
`"lf"`	`--end-of-line <lf\|crlf\|cr\|auto>`	`endOfLine: "<lf\|crlf\|cr\|auto>"`

在 .editorconfig 檔案中設定 end_of_line 將會設定 Prettier 的換行符號用法，除非被覆蓋。

嵌入式語言格式化

v2.1.0 首次提供

控制 Prettier 是否格式化嵌入在檔案中的引號程式碼。

當 Prettier 識別出您似乎將一些它知道如何格式化的程式碼放在另一個檔案的字串中時，例如在 JavaScript 中使用名為 html 的標籤標記的模板或 Markdown 中的程式碼區塊，它預設會嘗試格式化該程式碼。

有時這種行為並不可取，尤其是在您可能不希望將字串解釋為程式碼的情況下。此選項允許您在預設行為 (auto) 和完全停用此功能 (off) 之間切換。

有效選項

"auto" – 如果 Prettier 可以自動識別，則格式化嵌入的程式碼。
"off" - 永遠不要自動格式化嵌入的程式碼。

預設值	CLI 覆寫	API 覆寫
`"auto"`	`--embedded-language-formatting=<off\|auto>`	`embeddedLanguageFormatting: "<off\|auto>"`

每行單個屬性

v2.6.0 首次提供

在 HTML、Vue 和 JSX 中強制每行單個屬性。

有效選項

false - 不強制每行單個屬性。
true - 強制每行單個屬性。

預設值	CLI 覆寫	API 覆寫
`false`	`--single-attribute-per-line`	`singleAttributePerLine: <bool>`