Prettier

本文根据官网意译（V2.4.1），如有错误，欢迎指正

简介

Prettier 是一个包含大量固有规范的代码格式化工具，支持多种前端开发语言以及 Markdown 、YAML，它能够保证代码呈现的一致性。

为什么要用 Prettier ？

Prettier 官网上说 “使用 Prettier 最重要的原因就是停止在代码风格上的争论”。确实如此，在一个团队里或者项目中，有一个共同的代码风格指南是一件非常有价值的事情。但如果仅靠人为的去控制编程时的代码风格是一件非常痛苦且不值得这样去做。所以需要借助 Prettier 来帮我们实现代码风格的统一，因为它是全自动的帮我们修改代码格式。

Prettier 和 Linters 的区别

Linters ( ESLint / TSLint 等) 主要包含2类规则：

• 代码风格规则

  可以用来检查代码风格是否符合约定规范，但并不会自动排版，Prettier 则会基于约定好的代码规范自动排版。所以用了 Prettier 之后，此类规则大部分就不再需要了。

• 代码质量规则

  可以用来帮我们检查语法错误、拼写错误等，可以规避一些真实的 bugs，但 Prettier 并不能在这些方面提供帮助。

总结来说，Linters 主要用于检查代码规范和语法错误，Prettier 则主要用于检查代码风格并自动排版，因此，两者搭配使用能更大程度的帮助开发者们提高编程效率。

固有风格

Prettier 只有很少的配置项，且以后也不会增加。

Prettier 所提供的代码格式化规范并不是随心所欲、完全可配的，大部分都是内置固定的代码规范。因为它的初衷就是为了停止在代码风格上的争论，所以并不是完全自由的，但它提供的代码格式化规范已经度过了研究阶段，被很多大型组织或项目采用，是一个足够成熟的方案。

使用

安装插件

使用 npm 安装

npm install --save-dev --save-exact prettier

使用 yarn安装

yarn add --dev --exact prettier

创建配置文件

项目根目录下创建 .prettierrc.json 文件

{}

创建忽略文件

项目根目录下创建 .prettierignore 文件

Tip! Base your .prettierignore on .gitignore and .eslintignore (if you have one).

示例

# 忽略文件夹:
build
coverage

# 忽略某一类型文件:
*.html

单文件中忽略格式化

JavaScript

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

JSX

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

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>

CSS

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

}

Markdown

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

多行忽略

<!-- prettier-ignore-start -->

<!-- prettier-ignore-end -->

使用命令行格式化

格式化所有文件

// npm
npx prettier --write .
// yarn
yarn prettier --write .

格式化文件夹

// npm
npx prettier --write app/
// yarn
yarn prettier --write app/

格式化文件

// npm
npx prettier --write app/components/Button.js
// yarn
yarn prettier --write app/components/Button.js
//
yarn prettier --write "app/**/*.test.js"

检查文件是否已经格式化

// npm
npx prettier --check .

// yarn
yarn prettier --check .

--check 命令只会检查已经格式化的文件，而不会重写它们。

--write 则会自动检查并排版。

编辑器集成

在编辑器中集成 Prettier 是最广泛的使用方式。具体集成方式请查看各编辑器的 扩展/插件 使用说明。

注意 ! 需要在每个项目中都安装 Prettier 插件，从而保证它们使用正确的版本。

VSCode 扩展下载 Prettier - Code formatter

ESLint

使用 eslint-plugin-prettier 可以确保 ESLint 和 Prettier 能够完美搭配，避免两者的语法规则产生冲突。

安装插件

npm install -D eslint-plugin-prettier eslint-config-prettier

修改 Eslint 配置文件

// .eslintrc.json 
{
  "extends": ["plugin:prettier/recommended"]
}

到这里就已经配置好了，可以放手开撸了。

如果出现错误提示：Delete ␍ eslint prettier/prettier ，只需要在 .prettier.config.js 中加入

{
    endOfLine: 'auto'
}

就可以解决。其他解决办法可根据报错信息自行搜索。

同样的，如果你使用了 Stylelint，也可以安装 stylelint-config-prettier 插件。

其他插件查看文档 Integrating with Linters

Pre-commit Hook

Prettier 也可用于 pre-commit ,具体使用参见 Pre-commit Hook

配置项

Print Width

指定代码换行的字符长度，默认为 80，超过该长度会换行。

出于可读性考虑，官方建议不超过 80个字符。

Default	CLI Override	API Override
80	--print-width <int>	printWidth: <int>

Tab Width

指定缩进长度，默认为 2。

Default	CLI Override	API Override
2	--tab-width <int>	tabWidth: <int>

Tabs

指定缩进的方式：空格 或 Tab，默认为 false，即使用空格缩进。

Default	CLI Override	API Override
false	--use-tabs	useTabs: <bool>

Semicolons

指定语句的结尾是否要使用分号。

Default	CLI Override	API Override
true	--no-semi	semi: <bool>

Quotes

使用单引号代替双引号。

JSX 引号会忽略这条规则。

Default	CLI Override	API Override
false	--single-quote	singleQuote: <bool>

Quote

对象的属性是否需要添加引号，默认 as-needed

• "as-needed" - 对象的属性需要加引号时才会添加
• "consistent" - 只要有一个对象属性需要加引号，则都会加上引号
• "preserve" - 原样保存

Default	CLI Override	API Override
"as-needed"	`--quote-props <as-needed	consistent	preserve>`	`quoteProps: "<as-needed	consistent	preserve>"`

注意，在 Vue、Angular、 TypeScript and Flow 语句中，Prettier 不会对数值类型的属性添加引号

JSX Quotes

在 JSX 中使用单引号替代双引号，默认 false

Default	CLI Override	API Override
false	--jsx-single-quote	jsxSingleQuote: <bool>

Trailing Commas

元素末尾的逗号。默认为 es5

如下例中数组最后一个元素后的逗号已经对象最后一个属性后的逗号。

const array = [1,2,3,];
cosnt object = {
	name: 'cat',
	age: 3,
}

• "es5" - ES5中的 objects, arrays 等会添加逗号，TypeScript 中的 type 后不加逗号
• "none" - 都不添加逗号
• "all" - 总是添加逗号，包括函数的参数后也会加逗号

Default	CLI Override	API Override
"es5"	`--trailing-comma <es5	none	all>`	`trailingComma: "<es5	none	all>"`

Bracket Spacing

对象中的空格，默认为 true

• true - 例如: { foo: bar }
• false - 例如: {foo: bar}

Default	CLI Override	API Override
true	--no-bracket-spacing	bracketSpacing: <bool>

JSX Brackets

将 html 开始标签的后面一个 > 放在最后一行的末尾，而不是单独一行。

默认 false，即单独一行

• true - 例如:

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

• false - 例如:

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

Default	CLI Override	API Override
false	--jsx-bracket-same-line	jsxBracketSameLine: <bool>

Arrow Function Parentheses

当箭头函数只有一个参数时，是否加上括号，默认 always 。

带上括号有利于添加类型注释，扩展参数或者设置参数默认值

• "always" - 例如: (x) => x
• "avoid" - 例如: x => x

Default	CLI Override	API Override
"always"	`--arrow-parens <always	avoid>`	`arrowParens: "<always	avoid>"`

Range

只格式化文件中的某一段代码

Default	CLI Override	API Override
0	--range-start <int>	rangeStart: <int>
Infinity	--range-end <int>	rangeEnd: <int>

Parser

指定代码格式化的解析器。 Prettier 会自动根据文件类型推断解析器，通常不需要额外指定。 Parser

File Path

指定文件名用来推断使用哪一种解析器 parser

该配置项只在 CLI 和 API 生效，在配置文件中设置是无效的

Require Pragma

指定编译指示：只格式化在文件顶部包含特定注释的文件。

当需要逐步格式化某个大体量的项目时，这是非常有用的。

默认为 fasle 。设置为 true 时，使用以下两种注释的文件，会被格式化。

/**
 * @prettier
 */

/**
 * @format
 */

Default	CLI Override	API Override
false	--require-pragma	requirePragma: <bool>

Insert Pragma

插入编译指示：当文件已经被 Prettier 格式化之后，会在文件顶部插入一个特殊的 @format 标记。

Default	CLI Override	API Override
false	--insert-pragma	insertPragma: <bool>

Prose Wrap

Prose Wrap

By default, Prettier will wrap markdown text as-is since some services use a linebreak-sensitive renderer, e.g. GitHub comment and BitBucket. In some cases you may want to rely on editor/viewer soft wrapping instead, so this option allows you to opt out with "never".

• "always" - Wrap prose if it exceeds the print width.
• "never" - Do not wrap prose.
• "preserve" - Wrap prose as-is. First available in v1.9.0

Default	CLI Override	API Override
"preserve"	`--prose-wrap <always	never	preserve>`	`proseWrap: "<always	never	preserve>"`

HTML Whitespace Sensitivity

指定对 HTML, Vue, Angular, and Handlebars 文件中的空格保持敏感。

如下示例，是否对保留空格将会直接影响到页面的呈现：

html	output
with spaces	1<b> 2 </b>3	1 2 3
without spaces	1<b>2</b>3	123

所以需要设置 whitespace-sensitive formatting。

设定为 css 时会根据标签的 display 属性 ( inline、block ) 采取不同的格式化方式，例如：

<!-- <span> is an inline element, <div> is a block element -->

<!-- 格式化前，根据标签属性采取格式化方式 -->
<span class="dolorum atque aspernatur">Est molestiae sunt facilis qui rem.</span>
<div class="voluptatem architecto at">Architecto rerum architecto incidunt sint.</div>

<!-- 格式化后 -->
<span class="dolorum atque aspernatur"
  >Est molestiae sunt facilis qui rem.</span
>
<div class="voluptatem architecto at">
  Architecto rerum architecto incidunt sint.
</div>

也可手动指定 display 类型

<!-- 格式化前，手动指定为 block 属性 -->
<!-- display: block -->
<span class="dolorum atque aspernatur">Est molestiae sunt facilis qui rem.</span>

<!-- 格式化后 -->
<!-- display: block -->
<span class="dolorum atque aspernatur">
  Est molestiae sunt facilis qui rem.
</span>

更详情的用法参见 Whitespace-sensitive formatting

• "css" - 遵循 CSS 的 display 属性
• "strict" - 所有空格都将认定为是有意义的
• "ignore" - 所有空格都将认定为是无意义的

Default	CLI Override	API Override
"css"	`--html-whitespace-sensitivity <css	strict	ignore>`	`htmlWhitespaceSensitivity: "<css	strict	ignore>"`

Vue files script and style tags indentation

vue 文件中，是否给 script 和 style 内的代码添加缩进。

• "false" - 不添加缩进，例如：

<script>
export default {
    mounted() {
        console.log("Component mounted!");
    }
};
</script>

• "true" - 添加缩进，例如：

<script>
    export default {
        mounted() {
            console.log('Component mounted!')
        }
    }
</script>

Default	CLI Override	API Override
false	--vue-indent-script-and-style	vueIndentScriptAndStyle: <bool>

End of Line

指定代码最后是否添加一行空行

end-of-line

• "lf" – Line Feed only (\n), common on Linux and macOS as well as inside git repos
• "crlf" - Carriage Return + Line Feed characters (\r\n), common on Windows
• "cr" - Carriage Return character only (\r), used very rarely
• "auto" - Maintain existing line endings (mixed values within one file are normalised by looking at what’s used after the first line)

Default	CLI Override	API Override
"lf"	`--end-of-line <lf	crlf	cr	auto>`	`endOfLine: "<lf	crlf	cr	auto>"`

Embedded Language Formatting

是否需要格式化在文件中引用的代码

• "auto" – 如果 Prettier 可以识别嵌入的代码，则会格式化
• "off" - 不会对嵌入的代码进行格式化

Default	CLI Override	API Override
"auto"	--embedded-language-formatting=off	embeddedLanguageFormatting: "off"

完