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。

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

4.2 Tab Width

製表符寬度，每個層級縮排幾個空格。預設值 2

4.3 Tabs

是否使用 tab 代替 space(空格) 為單位縮排，預設 false

4.4 Semicolons

分號，句尾是否自動補全“分號”，預設 true

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

4.5 Quotes

預設 false，啟用雙引號，不啟用單引號。Prettier 會預設把單引號變成雙引號。

注：

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

詳情請檢視 strings rationale

4.6 Quote Props

自定義引號配置：

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

4.7 JSX Quotes

在 JSX 檔案中使用單引號代替雙引號

4.8 Trailing Commas

為多行陣列的非末尾行新增逗號（單行陣列不需要逗號），配置項：

• "none" - 不新增逗號
• "es5" - 在 ES5 中生效的逗號 (物件，陣列等等)
• "all" - 任何可以新增逗號的地方 (包括函式實參). 此配置需要 node 8 或一個 transform 方法。

4.9 Bracket Spacing

括號空格，在物件字面量和括號之間新增空格，配置項：

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

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>

4.11 Arrow Function Parentheses 箭頭函式圓括號

v1.9.0 及以上

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

4.12 Range

區間格式化

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

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

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

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

4.14 File Path

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

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

4.15 Require pragma 編譯附註

v1.7.0 及以上支援

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

例如，當設定--require-pragma時，檔案中第一個註釋寫成下面這樣，該檔案將會被格式化：

/**
 * @prettier
 */

或

/**
 * @format
 */

4.16 Prose Wrap

v1.8.2 及以上支援

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

有效配置項：

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

4.17 HTML Whitespace Sensitivity 空格敏感度

v1.15.0 及以上支援

為 HTML 檔案定義全域性空格敏感度，詳情請檢視 whitespace-sensitive formatting

有效配置項:

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

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) 使用機率超小超小

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