版權(quán)聲明:本文為博主原創(chuàng)文章撤卢,遵循 CC 4.0 BY-SA 版權(quán)協(xié)議娃胆,轉(zhuǎn)載請附上原文出處鏈接和本聲明海诲。
1. 簡介:
一款 Opinionated「預(yù)設(shè)立場型」的代碼格式化工具屋厘,支持以下語言:
- JavaScript, including ES2017
- JSX
- Angular
- Vue
- Flow
- TypeScript
- CSS, Less, and SCSS
- HTML
- JSON
- GraphQL
- Markdown, including GFM and MDX
- YAML
題外:Opinionated 這個詞我反復(fù)斟酌,實在不知如何翻譯才好篙梢。即使是英文中大家討論的也很激烈芹啥,非一句半句說的清楚悄泥,可以看看參考鏈接臀脏。在 FCC 群請教過劝堪,有位前輩回復(fù)我 「預(yù)設(shè)立場型」軟件。我覺得翻譯的很好揉稚。
如果你這樣寫:
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秒啦,參考http://www.reibang.com/p/0ada1096be5a
3. 不需要格式化的文件或者代碼,該怎樣標(biāo)識搀玖?
3.1 Ignoring Files 標(biāo)識無需格式化的文件比較簡單:
項目根目錄下創(chuàng)建 .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}}}>主任務(wù)</option>
<option value="2" {{{if .Task}}} {{{if eq .Task.Level 2}}}selected{{{end}}} {{{end}}}>子任務(wù)</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}}}
>主任務(wù)</option
>
<option
value="2"
{{{if
.Task}}}
{{{if
eq
.Task.Level
2}}}selected{{{end}}}
{{{end}}}
>子任務(wù)</option
>
</select>
這樣本身已經(jīng)沒有美觀可言了芳来,要命的是項目啟動報錯,指說這個文件有標(biāo)簽沒有閉合延塑。一查官文還真有這種操作呢绣张,可以忽略格式化某些文件或者行答渔。
3.2 標(biāo)識忽略格式化的代碼关带,需要添加注釋 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 和自動生成代碼的內(nèi)容沼撕,比如 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,排版寬度即每行最大寬度务豺。默認(rèn)值是 80磨总。
默認(rèn) | CLI 重寫定義 | API 重寫定義 |
---|---|---|
80 | --print-width <int> |
printWidth: <int> |
注:如果想在 Markdown 文件中禁用折行功能,可以在 Prose Wrap 中配置笼沥。
4.2 Tab Width
制表符寬度蚪燕,每個層級縮進幾個空格。默認(rèn)值 2
默認(rèn) | CLI 重寫定義 | API 重寫定義 |
---|---|---|
2 | --tab-width <int> |
tabWidth: <int> |
4.3 Tabs
是否使用 tab 代替 space(空格) 為單位縮進奔浅,默認(rèn) false
默認(rèn) | CLI 重寫定義 | API 重寫定義 |
---|---|---|
false | --use-tabs |
useTabs: <bool> |
4.4 Semicolons
分號馆纳,句尾是否自動補全“分號”,默認(rèn) true
-
true
為每個 statement 末尾都添加分號 -
false
只為會引起 ASI Failure 語句的開始行添加分號
默認(rèn) | CLI 重寫定義 | API 重寫定義 |
---|---|---|
true | --no-semi |
semi: <bool> |
4.5 Quotes
默認(rèn) false汹桦,啟用雙引號鲁驶,不啟用單引號。Prettier 會默認(rèn)把單引號變成雙引號舞骆。
注:
- JSX 會忽略此配置項 -- 詳情 jsx-single-quote
- 當(dāng)其中一種引號的使用頻率遠遠大于另一種時钥弯,較少使用的那種引號會被用作格式化字符串的引號径荔。 例如:
"This \"example\" is single quoted"
會被格式化為'This "example" is single quoted'
(因為大部分項目是 "雙引號" 居多,所以保存后脆霎,整個字符串語句就被 '單引號' 包裹了)
詳情請查看 strings rationale
默認(rèn) | CLI 重寫定義 | API 重寫定義 |
---|---|---|
false | --single-quote |
singleQuote: <bool> |
4.6 Quote Props
自定義引號配置:
- "as-needed" -- 按需添加
- "consistent" -- 一致原則总处,即對象中若有一個屬性添加了引號,其他所有屬性都添加
- "preserve" -- 遵循原則睛蛛,遵循輸入的引號
默認(rèn) | CLI 重寫定義 | API 重寫定義 |
---|---|---|
"as-needed" |
--quote-props <as-needed|consistent|preserve> |
quoteProps: "<as-needed|consistent|preserve>" |
4.7 JSX Quotes
在 JSX 文件中使用單引號代替雙引號
默認(rèn) | CLI 重寫定義 | API 重寫定義 |
---|---|---|
false | --jsx-single-quote |
jsxSingleQuote: <bool> |
4.8 Trailing Commas
為多行數(shù)組的非末尾行添加逗號(單行數(shù)組不需要逗號)辨泳,配置項:
-
"none"
- 不添加逗號 -
"es5"
- 在 ES5 中生效的逗號 (對象,數(shù)組等等) -
"all"
- 任何可以添加逗號的地方 (包括函數(shù)實參). 此配置需要 node 8 或一個 transform 方法玖院。
默認(rèn) | CLI 重寫定義 | API 重寫定義 |
---|---|---|
none | --trailing-comma <none|es5|all> |
trailingComma: "<none|es5|all>" |
4.9 Bracket Spacing
括號空格菠红,在對象字面量和括號之間添加空格,配置項:
- true - Example: { foo: bar }.
- false - Example: {foo: bar}.
默認(rèn) | 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>
默認(rèn) | CLI 重寫定義 | API 重寫定義 |
---|---|---|
false | --jsx-bracket-same-line |
jsxBracketSameLine: <bool> |
4.11 Arrow Function Parentheses 箭頭函數(shù)圓括號
v1.9.0 及以上
- "avoid" - 在可以消除的情況下,消除括號. Example: x => x
- "always" - 一直保留括號. Example: (x) => x
默認(rèn) | CLI 重寫定義 | API 重寫定義 |
---|---|---|
"avoid" |
--arrow-parens <avoid|always> |
arrowParens: "<avoid|always>" |
4.12 Range
區(qū)間格式化
兩個配置項可以用于「起始」(閉區(qū)間)/ 「截止」(開區(qū)間) 于某個標(biāo)識:
- 包含被選中語句郊酒,向上至第一行都是選中的區(qū)間
- 選中區(qū)間從該行向下至最后一行
與 cursorOffset
沖突遇绞,不可同時使用。
默認(rèn) | CLI 重寫定義 | API 重寫定義 |
---|---|---|
0 |
--range-start <int> |
rangeStart: <int> |
Infinity |
--range-end <int> |
rangeEnd: <int> |
4.13 Parser
指定使用的解析器
Prettier 可以根據(jù)文件路徑推斷出解析器的類型燎窘,因此無需更改此配置項摹闽。
babel
和 flow
解析器都支持同一組 JS 特性集(包含 Flow 類型注解). 在某些特殊情況下,有可能會產(chǎn)生差異褐健,當(dāng)遇到這些情況時付鹿,推薦使用 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 likeJSON.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
默認(rèn) | CLI 重寫定義 | API 重寫定義 |
---|---|---|
none |
--parser <string> --parser ./my-parser
|
parser: "<string>" parser: require("./my-parser")
|
4.14 File Path
指定文件名稱以確認(rèn)應(yīng)用何種解析器。
例如蚜迅,以下會應(yīng)用 CSS 解析器:
cat foo | prettier --stdin-filepath foo.css
默認(rèn) | CLI 重寫定義 | AP I 重寫定義 |
---|---|---|
none | --stdin-filepath <string> |
filepath: "<string>" |
4.15 Require pragma 編譯附注
v1.7.0 及以上支持
Prettier 支持在一個文件的頭部設(shè)置約束舵匾,僅格式化那些包含「特殊注釋」的文件,這種約束稱為「 pragma 編譯附注」谁不。當(dāng)需要逐步遷移體積較大的且未格式化過的基礎(chǔ)代碼時坐梯,此配置項是很有用處的。
例如刹帕,當(dāng)設(shè)置--require-pragma
時吵血,文件中第一個注釋寫成下面這樣,該文件將會被格式化:
/**
* @prettier
*/
或
/**
* @format
*/
默認(rèn) | CLI 重寫定義 | AP I 重寫定義 |
---|---|---|
false | --insert-pragma |
insertPragma: <bool> |
4.16 Prose Wrap
v1.8.2 及以上支持
默認(rèn)情況下偷溺,prettier 對于 markdown 文件的段落是執(zhí)行超出長度換行的蹋辅。但一些情況下,如果需要設(shè)置不換行亡蓉,可以使用 "never"
這個配置晕翠。
有效配置項:
- "always" - 超出長度自動折行
- "never" - 用不折行
- "preserve" - 遵循原有格式. v1.9.0 及以上支持
默認(rèn) | 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"
- 遵循 CSSdisplay
屬性的默認(rèn)值 -
"strict"
- 嚴(yán)格模式, -
"ignore"
- 忽略模式 Whitespaces are considered insensitive.
默認(rèn) | CLI 重寫定義 | AP I 重寫定義 |
---|---|---|
"css" |
--html-whitespace-sensitivity <css|strict|ignore>
|
htmlWhitespaceSensitivity: "<css|strict|ignore>"
|
4.18 End of Line
1.15.0 及以上
歷史原因?qū)е掠袃煞N文件行尾處理方式: \n
(or LF
for Line Feed) 和 \r\n
(或 CRLF
for Carriage Return + Line Feed)(譯者注:這里 LF 和 CRLF 是什么都夠一篇文章討論了淋肾,詳情查看 理解 CRLF, LF )
LF
常用于 Linux 和 macOS 操作系統(tǒng)硫麻,CRLF
常用于 Windows 操作系統(tǒng)。 詳情查看 Wikipedia.
默認(rèn)情況下樊卓,Prettier 遵循現(xiàn)有規(guī)則拿愧,也可以將一個文件的首行末尾作為標(biāo)準(zhǔn)格式化余下的所有行。
如果同一個項目的開發(fā)人員使用的是不同的操作系統(tǒng)碌尔,git 倉庫代碼的行尾會出現(xiàn)混亂情況浇辜。甚至有可能出現(xiàn) Windows 用戶將已經(jīng)提交的 LF
誤轉(zhuǎn)為 CRLF
. 這種情況會引起比較棘手的 git diff
,如果沒有加以留心則會導(dǎo)致此文件 (git blame
) 的行對行歷史丟失唾戚。
如果想確保由 Prettier 格式化的文件在 git 倉庫只保留 Linux 類型的行尾柳洋,可以進行以下設(shè)置:
- 設(shè)置配置項
endOfLine
的值為lf
- 配置一個 pre-commit hook 以便 Prettier 順利運行
- 配置 Prettier 使其可以在你的 CI pipeline 中使用
--check
flag - Windows 用戶在操作 git 倉庫之前執(zhí)行
git config core.autocrlf false
,這樣 checkout 的時候 git 就不會自動將LF
轉(zhuǎn)換為CRLF
了叹坦。 另有一種可供選擇的解決方案:添加* text=auto eol=lf
到倉庫的.gitattributes
文件熊镣。
如今的文本編輯器都可以糾正 \n
(LF
) 行尾的顯示問題。只有少數(shù)比較老舊的 Windows 的 Notepad 有可能無法實現(xiàn)募书。
Valid options:
-
"auto"
- 保持原有規(guī)則(如有混合使用绪囱,則按照第一行規(guī)則格式化其余所有行) -
"lf"
– Line Feed only (\n
) 常用語 Linux 和 macOS 操作系統(tǒng)以及 git 倉庫 -
"crlf"
- Carriage Return + Line Feed characters (\r\n
) 常用于 Windows 操作系統(tǒng) -
"cr"
- Carriage Return character only (\r
) 使用幾率超小超小
默認(rèn) | 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
文件篮赢,導(dǎo)出一個對象 -
package.json
文件添加"prettier"
key
格式化代碼時齿椅,查找配置文件的順序是由當(dāng)前目錄項上一層層查找。如果有 config 文件荷逞,則按照文件規(guī)則格式化媒咳。(由此推斷粹排,層級越近的配置文件种远,優(yōu)先級越高)
配置項參考本文 4.0 內(nèi)容。
5.1 基礎(chǔ)配置
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 覆寫默認(rèn)配置
Prettier 采用 eslint 的 覆寫格式顽耳,以便于為某些特定文件制定特定配置坠敷。
JSON:
{
"semi": false,
"overrides": [
{
"files": "*.test.js",
"options": {
"semi": true
}
}
]
}
YAML:
semi: false
overrides:
- files: "*.test.js"
options:
semi: true
覆寫時,files
(生效文件) 是必填項射富,值可以是字符串或者字符串?dāng)?shù)組膝迎。excludeFiles
(排除文件) 是選填項,值同樣可以是字符串或者字符串?dāng)?shù)組胰耗。
5.3 設(shè)置解析器配置項
通常情況下限次,Prettier 可以根據(jù)文件擴展名找到相應(yīng)的解析器。如果有 Prettier 不識別的文件類型,可以結(jié)合覆寫功能告訴 Prettier 如何解析卖漫。
比如告訴 Prettier 如何格式化 .prettierrc 文件:
{
"overrides": [
{
"files": ".prettierrc",
"options": { "parser": "json" }
}
]
}
或者從 babel
解析器切換到 flow
:
{
"overrides": [
{
"files": "*.js",
"options": {
"parser": "flow"
}
}
]
}
注:parser 解析器配置項不可放置于外層作用于全局的配置文件费尽,僅可應(yīng)用于覆寫。
The End