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