eslint

Prettier 代码格式化插件 -- 配置翻译

2019-05-06  本文已影响0人  MercuryWang

版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

原文地址

1. 简介：

一款 Opinionated「预设立场型」的代码格式化工具，支持以下语言：

题外：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。

默认 CLI 重写定义 API 重写定义
80 --print-width <int> printWidth: <int>

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

4.2 Tab Width

制表符宽度，每个层级缩进几个空格。默认值 2

默认 CLI 重写定义 API 重写定义
2 --tab-width <int> tabWidth: <int>

4.3 Tabs

是否使用 tab 代替 space(空格) 为单位缩进，默认 false

默认 CLI 重写定义 API 重写定义
false --use-tabs useTabs: <bool>

4.4 Semicolons

分号，句尾是否自动补全“分号”，默认 true

默认 CLI 重写定义 API 重写定义
true --no-semi semi: <bool>

4.5 Quotes

默认 false，启用双引号，不启用单引号。Prettier 会默认把单引号变成双引号。

注：

详情请查看 strings rationale

默认 CLI 重写定义 API 重写定义
false --single-quote singleQuote: <bool>

4.6 Quote Props

自定义引号配置：

默认 CLI 重写定义 API 重写定义
"as-needed" --quote-props <as-needed|consistent|preserve> quoteProps: "<as-needed|consistent|preserve>"

4.7 JSX Quotes

在 JSX 文件中使用单引号代替双引号

默认 CLI 重写定义 API 重写定义
false --jsx-single-quote jsxSingleQuote: <bool>

4.8 Trailing Commas

为多行数组的非末尾行添加逗号（单行数组不需要逗号），配置项：

默认 CLI 重写定义 API 重写定义
none --trailing-comma <none|es5|all> trailingComma: "<none|es5|all>"

4.9 Bracket Spacing

括号空格，在对象字面量和括号之间添加空格，配置项：

默认 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 元素的 > 放置于最后一行的末尾，而非换行。例：

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

<button
  className="prettier-class"
  id="prettier-id"
  onClick={this.handleClick}
>
  Click Here
</button>
默认 CLI 重写定义 API 重写定义
false --jsx-bracket-same-line jsxBracketSameLine: <bool>

4.11 Arrow Function Parentheses 箭头函数圆括号

v1.9.0 及以上

默认 CLI 重写定义 API 重写定义
"avoid" --arrow-parens <avoid|always> arrowParens: "<avoid|always>"

4.12 Range

区间格式化

两个配置项可以用于「起始」(闭区间)/ 「截止」(开区间) 于某个标识：

与 cursorOffset 冲突，不可同时使用。

默认 CLI 重写定义 API 重写定义
0 --range-start <int> rangeStart: <int>
Infinity --range-end <int> rangeEnd: <int>

4.13 Parser

指定使用的解析器

Prettier 可以根据文件路径推断出解析器的类型，因此无需更改此配置项。

babel 和 flow 解析器都支持同一组 JS 特性集(包含 Flow 类型注解). 在某些特殊情况下，有可能会产生差异，当遇到这些情况时，推荐使用 flow 代替 babel.

有效配置项:

自定义解析器 Custom parsers 亦可支持. First available in v1.5.0

默认 CLI 重写定义 API 重写定义
none --parser <string>
--parser ./my-parser 		parser: "<string>"
parser: require("./my-parser")

4.14 File Path

指定文件名称以确认应用何种解析器。
例如，以下会应用 CSS 解析器：

cat foo | prettier --stdin-filepath foo.css
默认 CLI 重写定义 AP I 重写定义
none --stdin-filepath <string> filepath: "<string>"

4.15 Require pragma 编译附注

v1.7.0 及以上支持

Prettier 支持在一个文件的头部设置约束，仅格式化那些包含「特殊注释」的文件，这种约束称为「 pragma 编译附注」。当需要逐步迁移体积较大的且未格式化过的基础代码时，此配置项是很有用处的。

例如，当设置--require-pragma时，文件中第一个注释写成下面这样，该文件将会被格式化：

/**
 * @prettier
 */

或

/**
 * @format
 */
默认 CLI 重写定义 AP I 重写定义
false --insert-pragma insertPragma: <bool>

4.16 Prose Wrap

v1.8.2 及以上支持

默认情况下，prettier 对于 markdown 文件的段落是执行超出长度换行的。但一些情况下，如果需要设置不换行，可以使用 "never" 这个配置。

有效配置项：

默认 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

有效配置项:

默认 CLI 重写定义 AP I 重写定义
"css" --html-whitespace-sensitivity
<css|strict|ignore> 		htmlWhitespaceSensitivity:
"<css|strict|ignore>"

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:

默认 CLI 重写定义 AP I 重写定义
"auto" --end-of-line <auto|lf|crlf|cr> endOfLine: "<auto|lf|crlf|cr>"

5. Configuration File 配置文件

Prettier 使用 cosmiconfig 配置方式。 以下任意一种皆可：

格式化代码时，查找配置文件的顺序是由当前目录项上一层层查找。如果有 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

上一篇下一篇

猜你喜欢

热点阅读