Prettier 代码风格
附录2、Prettier 代码风格说明文档
官网链接: Prettier Options
Prettier 默认提供了一系列的格式化选项。
代码输入宽度
指定了单行代码的最大行长。
为了便于阅读，我们建议不要使用超过80个字符：
在印刷界风格指南中，最大行长规则通常被设置为 100 或 120 个字符。然而，当我们写代码时，并不会刻意达到每行的最大列数。开发人员经常使用空白来分割长行，以提高可读性。在实践中，平均行长往往最终远远低于最大行长。
Prettier 的 printWidth 选项的工作方式并不一样。它不是硬性允许的行长上限。它是一种向 Prettier 说明你希望行的大致长度的方法。Prettier 会生成较短和较长的行，但通常会努力满足我们所指定的 printWidth。
记住，计算机是愚蠢的。你需要明确地告诉它们该怎么做，而人类可以做出自己的判断，例如，何时断行。
换句话说，不要试图把 printWidth 当作 ESLint 的 max-len 来使用，它们是不一样的。max-len 只是说允许的最大行长是什么，而不是一般的首选长度。
| Default | CLI Override | API Override |
|---|---|---|
80 | --print-width <int> | printWidth: <int> |
在 .editorconfig 文件中设置 max_line_length 将配置 Prettier 的代码输入宽度，除非被覆盖。
注：根据组内和架构师投票结果，建议在项目中将printWidth设置为100~120
缩进宽度
指定每个缩进级别的空格数。
| Default | CLI Override | API Override |
|---|---|---|
2 | --tab-width <int> | tabWidth: <int> |
在 .editorconfig 文件中设置 indent_size 与 tab_width 将配置 Prettier 的缩进宽度，除非被覆盖。
制表符缩进
强制用制表符而不是空格缩进行。
| Default | CLI Override | API Override |
|---|---|---|
false | --use-tabs | useTabs: <bool> |
在 .editorconfig 文件中设置 indent_style 将配置 Prettier 如何使用缩进，除非被覆盖。
(Prettier 默认使用空格来对齐，而非制表符。)
分号
在语句的结尾处打印分号。
有效的选项：
true- 在每条语句的结尾处添加一个分号。false- 只在 可能引入 ASI 故障 的行首添加分号。
| Default | CLI Override | API Override |
|---|---|---|
true | --no-semi | semi: <bool> |
引号
使用单引号来替代双引号。
- JSX 引号忽略了这个选项，见 jsx-single-quote 。
- 如果引号的数量超过了另一个引号，那么使用较少的引号将被用来格式化字符串。例如：
"I'm double quoted"的结果是"I'm double quoted"，而"This "example" is single quoted"的结果是这个'This "example" is single quoted'。
可查看 strings rationale 文档获得更多有用信息。
| Default | CLI Override | API Override |
|---|---|---|
false | --single-quote | singleQuote: <bool> |
JSX 引号
在 JSX 中，使用单引号替代双引号。
| Default | CLI Override | API Override |
|---|---|---|
false | --jsx-single-quote | jsxSingleQuote: <bool> |
行尾逗号
在多行逗号分隔的语法结构中尽可能输入行尾逗号。（例如，单行数组永远不会有行尾逗号）。
有效的选项：
"es5"- 在 ES5（对象、数组等）中，行尾逗号是有效的。TypeScript 中的类型参数没有行尾逗号。"none"- 没有行尾逗号。"all"- 在任何可能的地方都有行尾逗号（包括函数参数和调用）。这样格式化的 JavaScript 代码需要一个支持 ES2017 的引擎（Node.js 8+或现代浏览器）或下层编译才能运行。这也使 TypeScript 中类型参数的行尾逗号成为可能（从 2018 年 1 月发布的 TypeScript 2.7 开始支持）。
| Default | CLI Override | API Override | ||||
|---|---|---|---|---|---|---|
"es5" | `--trailing-comma <es5 | none | all>` | `trailingComma: "<es5 | none | all>"` |
括号空格
在对象字面量的括号内部前后都留有空格。
有效的选项：
true- 例子：{ foo: bar }.false- 例子：{foo: bar}.
| Default | CLI Override | API Override |
|---|---|---|
true | --no-bracket-spacing | bracketSpacing: <bool> |
关闭标签单独行
将多行 HTML（HTML、JSX、Vue、Angular）元素的 > 放在最后一行的末尾，而不是单独放在下一行（不适用于自闭元素）。
有效的选项：
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>
| Default | CLI Override | API Override |
|---|---|---|
false | --bracket-same-line | bracketSameLine: <bool> |
箭头函数单一参数使用括号
该选项在 v1.9.0 版本中首次使用，在 v2.0.0 版本中默认值从 avoid 改为 always。
箭头函数使用单一参数时，依然使用括号包裹。
有效的选项：
"always"- 使用括号。例子：(x) => x"avoid"- 不实用括号。例子：x => x
| Default | CLI Override | API Override | ||
|---|---|---|---|---|
"always" | `--arrow-parens <always | avoid>` | `arrowParens: "<always | avoid>"` |
乍一看，避免使用小括号可能是一个更好的选择，因为可以减少视觉噪音。
然而，当 Prettier 删除小括号时，就很难添加类型注释、额外的参数或默认值以及进行其他修改。
在编辑真正的代码库时，小括号的一致使用为开发者提供了更好的体验，这证明了该选项的默认值是合理的。
格式化范围
是否只格式化一个文件的一个片段。
这两个选项（可设置为 0 或者 Infinity）可以用来格式化以给定的字符偏移量为起点和终点的代码（分别为包含和排斥）。
- 向后延伸到包含所选语句的第一行的开头。
- 向前延伸到所选语句的结尾。
这些选项不能与 cursorOffset 一起使用。
| Default | CLI Override | API Override |
|---|---|---|
0 | --range-start <int> | rangeStart: <int> |
Infinity | --range-end <int> | rangeEnd: <int> |
解析器
指定要使用的解析器。
Prettier 会自动从输入文件的路径推断出解析器，所以你不应该改变这个设置。
babel 和 flow 解析器都支持相同的 JavaScript 特性（包括 Flow 类型注释）。它们在一些边缘情况下可能有所不同，所以如果你遇到这些情况，你可以尝试 flow 而不是 babel。几乎同样适用于 typescript 和 babel-ts。 babel-ts 可能支持 TypeScript 尚未支持的 JavaScript 特性（建议），但在涉及到无效代码时，它的宽容度较差，而且不如 typescript 解析器经过实际考验。
有效的选项：
"babel"(via @babel/parser)"babel-flow"(像"babel"一样，但明确启用 Flow 解析以避免歧义)"babel-ts"(类似于"typescript"，但使用了 Babel 和它的TypeScript插件)"flow"(via flow-parser)"typescript"(via @typescript-eslint/typescript-estree)"espree"(via espree)"meriyah"(via meriyah)"acorn"(via acorn)"css"(via postcss-scss and postcss-less, 自动检测并使用其中之一)"scss"(与"css"的解析器相同，更倾向于 postcss-scss)"less"(与"css"的解析器相同，更倾向于 postcss-less)"json"(via @babel/parser parseExpression)"json5"(与"json"解析器相同，但输出为 json5)"json-stringify"(与"json"解析器相同，但更像是使用JSON.stringify输出)"graphql"(via graphql/language)"markdown"(via remark-parse)"mdx"(via remark-parse and @mdx-js/mdx)"html"(via angular-html-parser)"vue"(与"html"解析器相同, 但同时格式化为 vue 规范语法)"angular"(与"html"解析器相同, 但同时格式化为 angular 规范语法)"lwc"(与"html"解析器相同, 但也为未引用的模板属性提供了LWC特定的语法格式)"yaml"(via yaml and yaml-unist-parser)
| Default | CLI Override | API Override |
|---|---|---|
| None | --parser <string> --parser ./my-parser | parser: "<string>" parser: require("./my-parser") |
文件路径
指定文件名来推断使用哪个解析器。
例如，下面将使用 CSS 解析器：
cat foo | prettier --stdin-filepath foo.css
这个选项只在 CLI 和 API 中有用。在配置文件中使用它是没有意义的。
| Default | CLI Override | API Override |
|---|---|---|
| None | --stdin-filepath <string> | filepath: "<string>" |
格式化限制
Prettier 可以限制自己只格式化那些在文件顶部包含特殊注释（称为 pragma）的文件。这在逐步将大型的、未格式化的代码库过渡到 Prettier 时非常有用。
当 --require-pragma 被提供时，一个有以下注释的文件将被格式化。
/**
* @prettier
*/
or
/**
* @format
*/
| Default | CLI Override | API Override |
|---|---|---|
false | --require-pragma | requirePragma: <bool> |
Insert Pragma（无法直译，请看说明）
Prettier 可以在文件的顶部插入一个特殊的 @format 标记，指定该文件已经被 Prettier 格式化。这在与 --require-pragma 选项一起使用时效果很好。如果文件的顶部已经有一个文档块，那么这个选项将在其上添加一个换行，并加上 @format 标记。
注意，当这两个选项同时使用时，--require-pragma 有优先权，所以 --insert-pragma 被忽略。试想这样一个场景，在一个大的代码库中逐步启用 Prettier 时，参与过渡过程的开发者使用 --insert-pragma，而 --require-pragma 被团队的其他成员和自动化工具使用，只处理已经过渡的文件。
| Default | CLI Override | API Override |
|---|---|---|
false | --insert-pragma | insertPragma: <bool> |
HTML 空格敏感度
指定 HTML、Vue、Angular 和 Handlebars 的全局空白敏感度。更多信息请参见空白敏感格式化。
有效的选项：
"css"- 像 CSSdisplay一样规则的默认值。"strict"- 所有标签周围的空白（或没有空白）被认为是重要的。"ignore"- 所有标签周围的空白（或没有空白）被认为是不重要的。"css"- 尊重 属性的默认值。
| Default | CLI Override | API Override | ||||
|---|---|---|---|---|---|---|
"css" | `--html-whitespace-sensitivity <css | strict | ignore>` | `htmlWhitespaceSensitivity: "<css | strict | ignore>"` |
Vue 文件中 script 和 style 标签内容的缩进
是否缩进 Vue 文件中 <script> 和 <style> 标签内的代码。有些人（比如Vue 作者认为）以不缩进来保存一个缩进级别，但这可能会破坏编辑器中的代码折叠。
有效的选项：
false- 不缩进。true- 缩进。
| Default | CLI Override | API Override |
|---|---|---|
false | --vue-indent-script-and-style | vueIndentScriptAndStyle: <bool> |
行结束符
由于历史原因，在文本文件中存在两种常见的行结束方式。
即 \n（或 LF 代表换行）和 \r\n（或 CRLF 代表回车 + 换行）。
前者在 Linux 和 macOS 上很常见，而后者在 Windows 上很普遍。
当人们在不同的操作系统上合作一个项目时，很容易在一个共享的 git 仓库中出现混合的行尾。
Windows 用户也有可能不小心将之前提交的文件的行尾从 LF 改为 CRLF。
这样做会产生一个大的 git diff，从而使一个文件的逐行历史（git blame）更难探索。
如果你想确保你的整个 git 仓库在 Prettier 覆盖的文件中只包含 Linux 风格的行尾。
- 确保 Prettier 的
endOfLine选项被设置为lf（自 v2.0.0 起这是一个默认值）。 - 配置 pre-commit hook，以运行 Prettier。
- 使用
--check标志 配置 Prettier 在你的 CI 流水线中运行。如果你使用 Travis CI，在.travis.yml中设置autocrlf选项 为input。 - 在代码仓库的
.gitattributes文件中添加* text=auto eol=lf。
你可能需要要求 Windows 用户在此改动后重新克隆你的 Repo，以确保 git 在签出时没有将LF转换成CRLF。
所有操作系统中的现代文本编辑器都能够在使用 \n（LF）时正确显示行尾。
然而，旧版本的 Windows 记事本会在视觉上把这些行压成一行，因为它们只能处理 \r\n（CRLF）。
有效的选项：
"lf"- 仅仅是换行（\n），在 Linux 和 macOS 以及 git repos 中很常见。"crlf"- 回车+换行字符（\r\n），在 Windows 上很常见。"cr"- 只有回车字符（\r），极少使用。"auto"- 保持现有的行结束符。
| Default | CLI Override | API Override | ||||||
|---|---|---|---|---|---|---|---|---|
"lf" | `--end-of-line <lf | crlf | cr | auto>` | `endOfLine: "<lf | crlf | cr | auto>"` |
嵌入语言格式化
控制 Prettier 是否格式化嵌入文件中的引号代码。
当 Prettier 发现你在另一个文件的字符串中放置了一些它知道如何格式化的代码时，比如在 JavaScript 中带有 html 标签的标记模板中或在 Markdown 中的代码块中，它将默认尝试格式化这些代码。
有时这种行为是不可取的，特别是在你可能没有打算将字符串解释为代码的情况下。这个选项允许你在默认行为（auto）和完全禁用该功能（off）之间切换。
有效的选项：
"auto"– 格式化可以识别的嵌入代码。"off"- 从不格式化嵌入的代码。
| Default | CLI Override | API Override |
|---|---|---|
"auto" | --embedded-language-formatting=off | embeddedLanguageFormatting: "off" |
每行单一属性
在 HTML、Vue 和 JSX 中强制执行每行单一属性。
有效的选项：
false- 不执行每行单一属性。true- 每行强制执行单一属性。
| Default | CLI Override | API Override |
|---|---|---|
false | --single-attribute-per-line | singleAttributePerLine: <bool> |
