Prettier 代碼格式化插件 -- 配置翻譯

1. 簡介：

一款 Opinionated「預設立場型」的代碼格式化工具，支持以下語言：

• JavaScript, including ES2017
• JSX
• Angular
• Vue
• Flow
• TypeScript
• CSS, Less, and SCSS
• HTML
• JSON
• GraphQL
• Markdown, including GFM and MDX
• YAML

題外：Opinionated 這個詞我反復斟酌，實在不知如何翻譯才好。即使是英文中大家討論的也很激烈，非一句半句說的清楚，可以看看參考鏈接。在 FCC 群請教過，有位前輩回復我 「預設立場型」軟件。我覺得翻譯的很好。

如果你這樣寫：

foo(reallyLongArg(), omgSoManyParameters(), IShouldRefactorThis(), isThereSeriouslyAnotherOne());

Prettier 會幫你格式化成：

foo(
    reallyLongArg(),
    omgSoManyParameters(),
    IShouldRefactorThis(),
    isThereSeriouslyAnotherOne()
  );

 

2. 安裝

yarn

yarn add prettier --dev --exact # or globally yarn global add prettier 

npm

npm install --save-dev --save-exact prettier # or globally npm install --global prettier 

IDE 安裝直接在 plugin market 搜索 Prettier，參考https://www.jianshu.com/p/0ada1096be5a

 

3. 不需要格式化的文件或者代碼，該怎樣標識？

3.1 Ignoring Files 標識無需格式化的文件比較簡單：

項目根目錄下創建 .prettierignore 文件，和 .gitignore 相似。然后直接添加文件名即可：

task_form.html

這也是翻譯官文的原因。目前項目有個文件引用的 layui, 格式化前：

<select name="level" id="level" lay-verify="required" {{{if .Task}}}disabled="disabled" {{{end}}} class="selece_greg"> <option value="1" {{{if .Task}}} {{{if eq .Task.Level 1}}}selected{{{end}}} {{{end}}}>主任務</option> <option value="2" {{{if .Task}}} {{{if eq .Task.Level 2}}}selected{{{end}}} {{{end}}}>子任務</option> </select> 

格式化后：

<select name="level" id="level" lay-verify="required" {{{if .Task}}}disabled="disabled" {{{end}}} class="selece_greg" > <option value="1" {{{if .Task}}} {{{if eq .Task.Level 1}}}selected{{{end}}} {{{end}}} >主任務</option > <option value="2" {{{if .Task}}} {{{if eq .Task.Level 2}}}selected{{{end}}} {{{end}}} >子任務</option > </select> 

這樣本身已經沒有美觀可言了，要命的是項目啟動報錯，指說這個文件有標簽沒有閉合。一查官文還真有這種操作呢，可以忽略格式化某些文件或者行。

3.2 標識忽略格式化的代碼，需要添加注釋 prettier-ignore，例：

3.2.1 JS

matrix( 1, 0, 0, 0, 1, 0, 0, 0, 1 ) // prettier-ignore matrix( 1, 0, 0, 0, 1, 0, 0, 0, 1 ) 

格式化后：

matrix(1, 0, 0, 0, 1, 0, 0, 0, 1); // prettier-ignore matrix( 1, 0, 0, 0, 1, 0, 0, 0, 1 ) 

3.2.2 JSX

<div> {/* prettier-ignore */} <span ugly format='' /> </div> 

3.2.3 HTML

<!-- prettier-ignore --> <div class="x" >hello world</div > <!-- prettier-ignore-attribute --> <div (mousedown)=" onStart ( ) " (mouseup)=" onEnd ( ) " ></div> <!-- prettier-ignore-attribute (mouseup) --> <div (mousedown)="onStart()" (mouseup)=" onEnd ( ) " ></div> 

3.2.4 CSS

/* prettier-ignore */ .my ugly rule { } 

3.2.5 Markdown

<!-- prettier-ignore --> Do not format this 

3.2.6 Range Ignore 有范圍的注釋（v1.12.0+ 支持）

這種方式只適用於 top-level 和自動生成代碼的內容，比如 all-contributors, markdown-toc 等等。

例

<!-- prettier-ignore-start --> <!-- SOMETHING AUTO-GENERATED BY TOOLS - START --> | MY | AWESOME | AUTO-GENERATED | TABLE | |-|-|-|-| | a | b | c | d | <!-- SOMETHING AUTO-GENERATED BY TOOLS - END --> <!-- prettier-ignore-end --> 

3.2.7 GraphQL

{
  # prettier-ignore
  addReaction(input:{superLongInputFieldName:"MDU6SXNzdWUyMzEzOTE1NTE=",content:HOORAY}) {
    reaction {content}
  }
}

 

4. 配置項

4.1 Print Width 即 Line Width，排版寬度即每行最大寬度。默認值是 80。

默認	CLI 重寫定義	API 重寫定義
80	--print-width <int>	printWidth: <int>

注：如果想在 Markdown 文件中禁用折行功能，可以在 Prose Wrap 中配置。

4.2 Tab Width

制表符寬度，每個層級縮進幾個空格。默認值 2

默認	CLI 重寫定義	API 重寫定義
2	--tab-width <int>	tabWidth: <int>

4.3 Tabs

是否使用 tab 代替 space(空格) 為單位縮進，默認 false

默認	CLI 重寫定義	API 重寫定義
false	--use-tabs	useTabs: <bool>

4.4 Semicolons

分號，句尾是否自動補全“分號”，默認 true

• true 為每個 statement 末尾都添加分號
• false 只為會引起 ASI Failure 語句的開始行添加分號

默認	CLI 重寫定義	API 重寫定義
true	--no-semi	semi: <bool>

4.5 Quotes

默認 false，啟用雙引號，不啟用單引號。Prettier 會默認把單引號變成雙引號。

注：

• JSX 會忽略此配置項 -- 詳情 jsx-single-quote
• 當其中一種引號的使用頻率遠遠大於另一種時，較少使用的那種引號會被用作格式化字符串的引號。 例如："This \"example\" is single quoted" 會被格式化為'This "example" is single quoted'（因為大部分項目是 "雙引號" 居多，所以保存后，整個字符串語句就被 '單引號' 包裹了）

詳情請查看 strings rationale

默認	CLI 重寫定義	API 重寫定義
false	--single-quote	singleQuote: <bool>

4.6 Quote Props

自定義引號配置：

• "as-needed" -- 按需添加
• "consistent" -- 一致原則，即對象中若有一個屬性添加了引號，其他所有屬性都添加
• "preserve" -- 遵循原則，遵循輸入的引號

默認	CLI 重寫定義	API 重寫定義
"as-needed"	--quote-props <as-needed|consistent|preserve>	quoteProps: "<as-needed|consistent|preserve>"

4.7 JSX Quotes

在 JSX 文件中使用單引號代替雙引號

默認	CLI 重寫定義	API 重寫定義
false	--jsx-single-quote	jsxSingleQuote: <bool>

4.8 Trailing Commas

為多行數組的非末尾行添加逗號（單行數組不需要逗號），配置項：

• "none" - 不添加逗號
• "es5" - 在 ES5 中生效的逗號 (對象，數組等等)
• "all" - 任何可以添加逗號的地方 (包括函數實參). 此配置需要 node 8 或一個 transform 方法。

默認	CLI 重寫定義	API 重寫定義
none	--trailing-comma <none|es5|all>	trailingComma: "<none|es5|all>"

4.9 Bracket Spacing

括號空格，在對象字面量和括號之間添加空格，配置項：

• true - Example: { foo: bar }.
• false - Example: {foo: bar}.

默認	CLI 重寫定義	API 重寫定義
true	--no-bracket-spacing	bracketSpacing: <bool>

4.10 JSX Brackets

Put the > of a multi-line JSX element at the end of the last line instead of being alone on the next line (does not apply to self closing elements).
將多行 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: <bool>

4.11 Arrow Function Parentheses 箭頭函數圓括號

v1.9.0 及以上

• "avoid" - 在可以消除的情況下，消除括號. Example: x => x
• "always" - 一直保留括號. Example: (x) => x

默認	CLI 重寫定義	API 重寫定義
"avoid"	--arrow-parens <avoid|always>	arrowParens: "<avoid|always>"

4.12 Range

區間格式化

兩個配置項可以用於「起始」(閉區間)/ 「截止」(開區間) 於某個標識：

• 包含被選中語句，向上至第一行都是選中的區間
• 選中區間從該行向下至最后一行

與 cursorOffset 沖突，不可同時使用。

默認	CLI 重寫定義	API 重寫定義
0	--range-start <int>	rangeStart: <int>
Infinity	--range-end <int>	rangeEnd: <int>

4.13 Parser

指定使用的解析器

Prettier 可以根據文件路徑推斷出解析器的類型，因此無需更改此配置項。

babel 和 flow 解析器都支持同一組 JS 特性集(包含 Flow 類型注解). 在某些特殊情況下，有可能會產生差異，當遇到這些情況時，推薦使用 flow 代替 babel.

有效配置項:

• "babel" (via @babel/parser) Named "babylon" until v1.16.0
• "babel-flow" (Same as "babel" but enables Flow parsing explicitly to avoid ambiguity) First available in v1.16.0
• "flow" (via flow-parser)
• "typescript" (via @typescript-eslint/typescript-estree) First available in v1.4.0
• "css" (via postcss-scss and postcss-less, autodetects which to use) First available in v1.7.1
• "scss" (same parsers as "css", prefers postcss-scss) First available in v1.7.1
• "less" (same parsers as "css", prefers postcss-less) First available in v1.7.1
• "json" (via @babel/parser parseExpression) First available in v1.5.0
• "json5" (same parser as "json", but outputs as json5) First available in v1.13.0
• "json-stringify" (same parser as "json", but outputs like JSON.stringify) First available in v1.13.0
• "graphql" (via graphql/language) First available in v1.5.0
• "markdown" (via remark-parse) First available in v1.8.0
• "mdx" (via remark-parse and @mdx-js/mdx) First available in v1.15.0
• "html" (via angular-html-parser) First available in 1.15.0
• "vue" (same parser as "html", but also formats vue-specific syntax) First available in 1.10.0
• "angular" (same parser as "html", but also formats angular-specific syntax via angular-estree-parser) First available in 1.15.0
• "lwc" (same parser as "html", but also formats LWC-specific syntax for unquoted template attributes) First available in 1.17.0
• "yaml" (via yaml and yaml-unist-parser) First available in 1.14.0

自定義解析器 Custom parsers 亦可支持. First available in v1.5.0

默認	CLI 重寫定義	API 重寫定義
none	--parser <string> --parser ./my-parser	parser: "<string>" parser: require("./my-parser")

4.14 File Path

指定文件名稱以確認應用何種解析器。
例如，以下會應用 CSS 解析器：

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

默認	CLI 重寫定義	AP I 重寫定義
none	--stdin-filepath <string>	filepath: "<string>"

4.15 Require pragma 編譯附注

v1.7.0 及以上支持

Prettier 支持在一個文件的頭部設置約束，僅格式化那些包含「特殊注釋」的文件，這種約束稱為「 pragma 編譯附注」。當需要逐步遷移體積較大的且未格式化過的基礎代碼時，此配置項是很有用處的。

例如，當設置--require-pragma時，文件中第一個注釋寫成下面這樣，該文件將會被格式化：

/** * @prettier */ 

或

/** * @format */ 

默認	CLI 重寫定義	AP I 重寫定義
false	--insert-pragma	insertPragma: <bool>

4.16 Prose Wrap

v1.8.2 及以上支持

默認情況下，prettier 對於 markdown 文件的段落是執行超出長度換行的。但一些情況下，如果需要設置不換行，可以使用 "never" 這個配置。

有效配置項：

• "always" - 超出長度自動折行
• "never" - 用不折行
• "preserve" - 遵循原有格式. v1.9.0 及以上支持

默認	CLI 重寫定義	AP I 重寫定義
"preserve"	--prose-wrap <always|never|preserve>	proseWrap: "<always|never|preserve>"

4.17 HTML Whitespace Sensitivity 空格敏感度

v1.15.0 及以上支持

為 HTML 文件定義全局空格敏感度，詳情請查看 whitespace-sensitive formatting

有效配置項:

• "css" - 遵循 CSS display 屬性的默認值
• "strict" - 嚴格模式，
• "ignore" - 忽略模式 Whitespaces are considered insensitive.

默認	CLI 重寫定義	AP I 重寫定義
"css"	--html-whitespace-sensitivity <css|strict|ignore>	htmlWhitespaceSensitivity: "<css|strict|ignore>"

4.18 End of Line

1.15.0 及以上

歷史原因導致有兩種文件行尾處理方式： \n (or LF for Line Feed) 和 \r\n (或 CRLF for Carriage Return + Line Feed)（譯者注：這里 LF 和 CRLF 是什么都夠一篇文章討論了，詳情查看 理解 CRLF, LF )

LF 常用於 Linux 和 macOS 操作系統，CRLF 常用於 Windows 操作系統。 詳情查看 Wikipedia.

默認情況下，Prettier 遵循現有規則，也可以將一個文件的首行末尾作為標准格式化余下的所有行。

如果同一個項目的開發人員使用的是不同的操作系統，git 倉庫代碼的行尾會出現混亂情況。甚至有可能出現 Windows 用戶將已經提交的 LF 誤轉為 CRLF. 這種情況會引起比較棘手的 git diff，如果沒有加以留心則會導致此文件 (git blame) 的行對行歷史丟失。

如果想確保由 Prettier 格式化的文件在 git 倉庫只保留 Linux 類型的行尾，可以進行以下設置：

1. 設置配置項 endOfLine 的值為 lf
2. 配置一個 pre-commit hook 以便 Prettier 順利運行
3. 配置 Prettier 使其可以在你的 CI pipeline 中使用 --check flag
4. Windows 用戶在操作 git 倉庫之前執行 git config core.autocrlf false，這樣 checkout 的時候 git 就不會自動將 LF 轉換為 CRLF 了。 另有一種可供選擇的解決方案：添加 * text=auto eol=lf 到倉庫的 .gitattributes 文件。

如今的文本編輯器都可以糾正 \n (LF) 行尾的顯示問題。只有少數比較老舊的 Windows 的 Notepad 有可能無法實現。

Valid options:

• "auto" - 保持原有規則（如有混合使用，則按照第一行規則格式化其余所有行）
• "lf" – Line Feed only (\n) 常用語 Linux 和 macOS 操作系統以及 git 倉庫
• "crlf" - Carriage Return + Line Feed characters (\r\n) 常用於 Windows 操作系統
• "cr" - Carriage Return character only (\r) 使用幾率超小超小

默認	CLI 重寫定義	AP I 重寫定義
"auto"	--end-of-line <auto|lf|crlf|cr>	endOfLine: "<auto|lf|crlf|cr>"

 

5. Configuration File 配置文件

Prettier 使用 cosmiconfig 配置方式。 以下任意一種皆可：

• .prettierrc 文件，YAML 或 JSON 格式，可選擴展名: .yaml/.yml/.json
• .prettierrc.toml 文件，TOML 格式 (須添加 .toml 擴展名)
• prettier.config.js 或 .prettierrc.js 文件，導出一個對象
• package.json 文件添加 "prettier" key

格式化代碼時，查找配置文件的順序是由當前目錄項上一層層查找。如果有 config 文件，則按照文件規則格式化。（由此推斷，層級越近的配置文件，優先級越高）

配置項參考本文 4.0 內容。

5.1 基礎配置

JSON:

{ "trailingComma": "es5", "tabWidth": 4, "semi": false, "singleQuote": true } 

JS:

// prettier.config.js or .prettierrc.js module.exports = { trailingComma: "es5", tabWidth: 4, semi: false, singleQuote: true }; 

YAML:

# .prettierrc or .prettierrc.yaml
trailingComma: "es5"
tabWidth: 4
semi: false
singleQuote: true

TOML:

# .prettierrc.toml
trailingComma = "es5"
tabWidth = 4
semi = false
singleQuote = true

5.2 覆寫默認配置

Prettier 采用 eslint 的 覆寫格式，以便於為某些特定文件制定特定配置。

JSON：

{ "semi": false, "overrides": [ { "files": "*.test.js", "options": { "semi": true } } ] } 

YAML:

semi: false
overrides:
  - files: "*.test.js"
    options:
      semi: true

覆寫時，files(生效文件) 是必填項，值可以是字符串或者字符串數組。excludeFiles(排除文件) 是選填項，值同樣可以是字符串或者字符串數組。

5.3 設置解析器配置項

通常情況下，Prettier 可以根據文件擴展名找到相應的解析器。如果有 Prettier 不識別的文件類型，可以結合覆寫功能告訴 Prettier 如何解析。

比如告訴 Prettier 如何格式化 .prettierrc 文件：

{ "overrides": [ { "files": ".prettierrc", "options": { "parser": "json" } } ] } 

或者從 babel 解析器切換到 flow:

{ "overrides": [ { "files": "*.js", "options": { "parser": "flow" } } ] } 

注：parser 解析器配置項不可放置於外層作用於全局的配置文件，僅可應用於覆寫。

The End

作者：MercuryWang
鏈接：https://www.jianshu.com/p/4be58a69b20f
來源：簡書
著作權歸作者所有。商業轉載請聯系作者獲得授權，非商業轉載請注明出處。