diff --git a/docs/README.zh.md b/docs/README.zh.md index 37124a0..7a395c2 100644 --- a/docs/README.zh.md +++ b/docs/README.zh.md @@ -47,7 +47,7 @@ 一条规约的级别会在规约描述的开头标注,如有对应的 Lint 规则会在结尾标注,例如: -> 1.1.1【强制】使用 2 个空格缩进。eslint: [indent](https://eslint.org/docs/rules/indent) +> 1.1.1 `强制` 使用 2 个空格缩进。eslint: [indent](https://eslint.org/docs/rules/indent) ### 代码示例 diff --git a/docs/coding/css.md b/docs/coding/css.md index 5f598b2..c505822 100644 --- a/docs/coding/css.md +++ b/docs/coding/css.md @@ -15,7 +15,7 @@ order: 2 上图是一张符合规约要求编码风格的速览图,详细规则如下: -- 1.1.1【强制】所有声明都应该以分号结尾,不能省略。stylelint: [declaration-block-trailing-semicolon](https://stylelint.io/user-guide/rules/declaration-block-trailing-semicolon) +- 1.1.1 `mandatory` 所有声明都应该以分号结尾,不能省略。stylelint: [declaration-block-trailing-semicolon](https://stylelint.io/user-guide/rules/declaration-block-trailing-semicolon) 虽然 CSS 语法中最后一条声明的分号是可选的,但是使用分号可以增加代码的一致性和易用性。 @@ -33,7 +33,7 @@ order: 2 } ``` -- 1.1.2【推荐】使用 2 个空格缩进,不要使用 4 个空格或 tab 缩进。stylelint: [indentation](https://stylelint.io/user-guide/rules/indentation) +- 1.1.2 `recommended` 使用 2 个空格缩进,不要使用 4 个空格或 tab 缩进。stylelint: [indentation](https://stylelint.io/user-guide/rules/indentation) ```css /* bad */ @@ -47,7 +47,7 @@ order: 2 } ``` -- 1.1.3【推荐】选择器和 `{` 之间保留一个空格。stylelint: [block-opening-brace-space-before](https://stylelint.io/user-guide/rules/block-opening-brace-space-before) +- 1.1.3 `recommended` 选择器和 `{` 之间保留一个空格。stylelint: [block-opening-brace-space-before](https://stylelint.io/user-guide/rules/block-opening-brace-space-before) ```css /* bad */ @@ -61,7 +61,7 @@ order: 2 } ``` -- 1.1.4【推荐】属性名和 `:` 之前无空格,`:` 和属性值之间保留一个空格。stylelint: [declaration-colon-space-after](https://stylelint.io/user-guide/rules/declaration-colon-space-after) [declaration-colon-space-before](https://stylelint.io/user-guide/rules/declaration-colon-space-before) +- 1.1.4 `recommended` 属性名和 `:` 之前无空格,`:` 和属性值之间保留一个空格。stylelint: [declaration-colon-space-after](https://stylelint.io/user-guide/rules/declaration-colon-space-after) [declaration-colon-space-before](https://stylelint.io/user-guide/rules/declaration-colon-space-before) ```css /* bad */ @@ -77,7 +77,7 @@ order: 2 } ``` -- 1.1.5【推荐】`>`、`+`、`~` 、`||` 等组合器前后各保留一个空格。stylelint: [selector-combinator-space-before](https://stylelint.io/user-guide/rules/selector-combinator-space-before) [selector-combinator-space-after](https://stylelint.io/user-guide/rules/selector-combinator-space-after) +- 1.1.5 `recommended` `>`、`+`、`~` 、`||` 等组合器前后各保留一个空格。stylelint: [selector-combinator-space-before](https://stylelint.io/user-guide/rules/selector-combinator-space-before) [selector-combinator-space-after](https://stylelint.io/user-guide/rules/selector-combinator-space-after) ```css /* bad */ @@ -97,7 +97,7 @@ order: 2 } ``` -- 1.1.6【推荐】在使用 `,` 分隔的属性值中,`,` 之后保留一个空格。stylelint: [value-list-comma-space-after](https://stylelint.io/user-guide/rules/value-list-comma-space-after) +- 1.1.6 `recommended` 在使用 `,` 分隔的属性值中,`,` 之后保留一个空格。stylelint: [value-list-comma-space-after](https://stylelint.io/user-guide/rules/value-list-comma-space-after) ```css /* bad */ @@ -113,7 +113,7 @@ order: 2 } ``` -- 1.1.7【推荐】注释内容和注释符之间留有一个空格。stylelint: [comment-whitespace-inside](https://stylelint.io/user-guide/rules/comment-whitespace-inside) +- 1.1.7 `recommended` 注释内容和注释符之间留有一个空格。stylelint: [comment-whitespace-inside](https://stylelint.io/user-guide/rules/comment-whitespace-inside) ```css /* bad */ @@ -136,7 +136,7 @@ order: 2 } ``` -- 1.1.8【推荐】声明块的右大括号 `}` 应单独成行。 +- 1.1.8 `recommended` 声明块的右大括号 `}` 应单独成行。 ```css /* bad */ @@ -149,7 +149,7 @@ order: 2 } ``` -- 1.1.9【推荐】属性声明应单独成行。stylelint: [declaration-block-single-line-max-declarations](https://stylelint.io/user-guide/rules/declaration-block-single-line-max-declarations) +- 1.1.9 `recommended` 属性声明应单独成行。stylelint: [declaration-block-single-line-max-declarations](https://stylelint.io/user-guide/rules/declaration-block-single-line-max-declarations) ```css /* bad */ @@ -165,7 +165,7 @@ order: 2 ``` -- 1.1.10【推荐】单行代码最多不要超过 100 个字符。 stylelint: [max-line-length](https://stylelint.io/user-guide/rules/max-line-length) 除了以下两种情况: +- 1.1.10 `recommended` 单行代码最多不要超过 100 个字符。 stylelint: [max-line-length](https://stylelint.io/user-guide/rules/max-line-length) 除了以下两种情况: - 使用 [`url()`](https://developer.mozilla.org/en-US/docs/Web/CSS/url) 函数时 - CSS 属性值本身无法换行时,即属性值内无空格或逗号时 @@ -184,7 +184,7 @@ order: 2 ); ``` -- 1.1.11【参考】使用多个选择器时,每个选择器应该单独成行。stylelint: [selector-list-comma-newline-after](https://stylelint.io/user-guide/rules/selector-list-comma-newline-after) +- 1.1.11 `referenced` 使用多个选择器时,每个选择器应该单独成行。stylelint: [selector-list-comma-newline-after](https://stylelint.io/user-guide/rules/selector-list-comma-newline-after) ```css /* bad */ @@ -202,7 +202,7 @@ order: 2 } ``` -- 1.1.12【参考】声明块内只有一条语句时,也应该写成多行。 +- 1.1.12 `referenced` 声明块内只有一条语句时,也应该写成多行。 ```css /* bad */ @@ -214,7 +214,7 @@ order: 2 } ``` -- 1.1.13【参考】注释行上方需留有一行空行,除非上一行是注释或块的顶部。stylelint: [comment-empty-line-before](https://stylelint.io/user-guide/rules/comment-empty-line-before) +- 1.1.13 `referenced` 注释行上方需留有一行空行,除非上一行是注释或块的顶部。stylelint: [comment-empty-line-before](https://stylelint.io/user-guide/rules/comment-empty-line-before) ```css /* bad */ @@ -238,7 +238,7 @@ order: 2 ### 1.2 选择器 -- 1.2.1【参考】不要使用 id 选择器。stylelint: [selector-max-id](https://stylelint.io/user-guide/rules/selector-max-id) +- 1.2.1 `referenced` 不要使用 id 选择器。stylelint: [selector-max-id](https://stylelint.io/user-guide/rules/selector-max-id) id 会带来过高的[选择器优先级](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity),使得后续很难进行样式覆盖(继而引发使用 `!important` 覆盖样式的恶性循环)。 @@ -260,7 +260,7 @@ order: 2 } ``` -- 1.2.2【参考】属性选择器的值始终用双引号包裹。stylelint: [selector-attribute-quotes](https://stylelint.io/user-guide/rules/selector-attribute-quotes) +- 1.2.2 `referenced` 属性选择器的值始终用双引号包裹。stylelint: [selector-attribute-quotes](https://stylelint.io/user-guide/rules/selector-attribute-quotes) 属性选择器的值的引号只有在[某些情况下](https://mathiasbynens.be/notes/unquoted-attribute-values#css)可以省略。 @@ -276,7 +276,7 @@ order: 2 } ``` -- 1.2.3【参考】使用 CSS 选择器时,应注意以下性能问题: +- 1.2.3 `referenced` 使用 CSS 选择器时,应注意以下性能问题: - 使用 class 而不是原生元素标签 - 减少在经常出现的组件中使用个别属性选择器(如 `[class^="..."]`) @@ -296,7 +296,7 @@ order: 2 ### 1.3 属性和属性值 -- 1.3.1【推荐】使用尽可能短的十六进制值。stylelint: [color-hex-length](https://stylelint.io/user-guide/rules/color-hex-length) +- 1.3.1 `recommended` 使用尽可能短的十六进制值。stylelint: [color-hex-length](https://stylelint.io/user-guide/rules/color-hex-length) ```css /* bad */ @@ -310,9 +310,9 @@ order: 2 } ``` -- 1.3.2【推荐】不要使用 !important 重写样式。 +- 1.3.2 `recommended` 不要使用 !important 重写样式。 -- 1.3.3【推荐】十六进制值统一使用小写字母(小写字母更容易分辨)。stylelint: [color-hex-case](https://stylelint.io/user-guide/rules/color-hex-case) +- 1.3.3 `recommended` 十六进制值统一使用小写字母(小写字母更容易分辨)。stylelint: [color-hex-case](https://stylelint.io/user-guide/rules/color-hex-case) ```css /* bad */ @@ -326,7 +326,7 @@ order: 2 } ``` -- 1.3.4【推荐】长度值为 0 时,省略掉长度单位。stylelint: [length-zero-no-unit](https://stylelint.io/user-guide/rules/length-zero-no-unit) +- 1.3.4 `recommended` 长度值为 0 时,省略掉长度单位。stylelint: [length-zero-no-unit](https://stylelint.io/user-guide/rules/length-zero-no-unit) 在 CSS 中,长度值为 0 时,它的单位是可选的(长度单位包括:em, ex, ch, vw, vh, cm, mm, in, pt, pc, px, rem, vmin, and vmax)。省略长度单位可以使代码更简洁: @@ -344,7 +344,7 @@ order: 2 } ``` -- 1.3.5【参考】保留小数点前的 0。stylelint: [number-leading-zero](https://stylelint.io/user-guide/rules/number-leading-zero) +- 1.3.5 `referenced` 保留小数点前的 0。stylelint: [number-leading-zero](https://stylelint.io/user-guide/rules/number-leading-zero) 在 CSS 中,大于 -1 小于 1 的小数,小数点前的 0 可以省略: @@ -371,7 +371,7 @@ order: 2 我们推荐保留 0,因为当今很多 CSS 压缩工具会在压缩时帮我们去掉 0,不存在多占用一个字符的问题。保留 0 能增强代码的可读性和一致性。 -- 1.3.6【参考】属性声明的顺序。 +- 1.3.6 `referenced` 属性声明的顺序。 相关联的属性声明最好写成一组,并按如下顺序排序: @@ -441,7 +441,7 @@ order: 2 |overflow*||||||| |clip||||||| -- 1.3.7【参考】适时使用简写属性。stylelint: [declaration-block-no-shorthand-property-overrides](https://stylelint.io/user-guide/rules/declaration-block-no-shorthand-property-overrides) [declaration-block-no-redundant-longhand-properties](https://stylelint.io/user-guide/rules/declaration-block-no-redundant-longhand-properties) +- 1.3.7 `referenced` 适时使用简写属性。stylelint: [declaration-block-no-shorthand-property-overrides](https://stylelint.io/user-guide/rules/declaration-block-no-shorthand-property-overrides) [declaration-block-no-redundant-longhand-properties](https://stylelint.io/user-guide/rules/declaration-block-no-redundant-longhand-properties) 常见的[简写属性](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties)包括: @@ -471,7 +471,7 @@ order: 2 ### 1.4 其他 -- 1.4.1【推荐】不要使用 CSS 的 @import。 +- 1.4.1 `recommended` 不要使用 CSS 的 @import。 与 `` 相比,`@import` 会在关键渲染路径上增加更多的往返(即关键路径的深度变长),这样会导致浏览器处理 CSS 文件速度变慢,因此我们应该避免使用 `@import`。 @@ -493,7 +493,7 @@ order: 2 >* 更建议使用 PostCSS 处理器,它类似于 CSS 中的 Babel,不但具备 Sass 和 Less 的功能,而且社区繁荣,同时还可以根据自己的需求扩展相关的插件。 >* 随着 CSS 的一些新特性出现,Sass 和 Less 以往的优势也会慢慢消失。 -- 2.1【推荐】四则运算符两侧各保留一个空格: +- 2.1 `recommended` 四则运算符两侧各保留一个空格: ```css /* bad */ @@ -507,7 +507,7 @@ order: 2 } ``` -- 2.2【推荐】Mixin 名称和括号 `()` 间无空格,在拥有多个参数的表达式中, `,` 之前无空格,`,` 之后保留一个空格: +- 2.2 `recommended` Mixin 名称和括号 `()` 间无空格,在拥有多个参数的表达式中, `,` 之前无空格,`,` 之后保留一个空格: ```css /* bad */ @@ -523,7 +523,7 @@ order: 2 } ``` -- 2.3【推荐】按如下顺序组织 Sass / Less 代码: +- 2.3 `recommended` 按如下顺序组织 Sass / Less 代码: - `@import` 语句 - 全局变量声明 @@ -539,7 +539,7 @@ order: 2 } ``` -- 2.4【推荐】对于 Sass 和 Less,块内的属性声明按如下顺序排序: +- 2.4 `recommended` 对于 Sass 和 Less,块内的属性声明按如下顺序排序: - 标准属性声明:除了 mixin 调用、extend 子级选择器的声明,其他属性声明的顺序与「属性声明的顺序」章节的规则一致 - mixin 调用:Sass 的 `@include` 声明、Less 的 mixin 调用 @@ -557,7 +557,7 @@ order: 2 } ``` -- 2.5【推荐】嵌套选择器的深度不要超过 3 层,否则可能带来一些副作用: +- 2.5 `recommended` 嵌套选择器的深度不要超过 3 层,否则可能带来一些副作用: - 与 HTML 结构强耦合,难以复用 - 过高的[选择器优先级](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) @@ -572,7 +572,7 @@ order: 2 } ``` -- 2.6【推荐】可以使用双斜杠注释。但需要注意的是,编译为 CSS 后,代码中的双斜杠注释会被删除,而 `/* */` 会被保留。 +- 2.6 `recommended` 可以使用双斜杠注释。但需要注意的是,编译为 CSS 后,代码中的双斜杠注释会被删除,而 `/* */` 会被保留。 ```css // 单行注释 @@ -605,7 +605,7 @@ order: 2 } ``` -- 2.7【推荐】使用 Mixin (@mixin 和 @include 指令) 来让代码遵循 DRY 原则(Don't Repeat Yourself)、增加抽象性和降低复杂度。 +- 2.7 `recommended` 使用 Mixin (@mixin 和 @include 指令) 来让代码遵循 DRY 原则(Don't Repeat Yourself)、增加抽象性和降低复杂度。 应避免使用 @extend 指令,它不够直观且具有潜在风险,尤其是在嵌套选择器中。即使继承的是顶层选择器,如果选择器的顺序发生变化,也可能引起问题(比如,如果它们存在于其他文件,而加载顺序发生了变化)。 diff --git a/docs/coding/css.zh.md b/docs/coding/css.zh.md index 637a260..5777709 100644 --- a/docs/coding/css.zh.md +++ b/docs/coding/css.zh.md @@ -15,7 +15,7 @@ order: 2 上图是一张符合规约要求编码风格的速览图,详细规则如下: -- 1.1.1【强制】所有声明都应该以分号结尾,不能省略。stylelint: [declaration-block-trailing-semicolon](https://stylelint.io/user-guide/rules/declaration-block-trailing-semicolon) +- 1.1.1 `强制` 所有声明都应该以分号结尾,不能省略。stylelint: [declaration-block-trailing-semicolon](https://stylelint.io/user-guide/rules/declaration-block-trailing-semicolon) 虽然 CSS 语法中最后一条声明的分号是可选的,但是使用分号可以增加代码的一致性和易用性。 @@ -33,7 +33,7 @@ order: 2 } ``` -- 1.1.2【推荐】使用 2 个空格缩进,不要使用 4 个空格或 tab 缩进。stylelint: [indentation](https://stylelint.io/user-guide/rules/indentation) +- 1.1.2 `推荐` 使用 2 个空格缩进,不要使用 4 个空格或 tab 缩进。stylelint: [indentation](https://stylelint.io/user-guide/rules/indentation) ```css /* bad */ @@ -47,7 +47,7 @@ order: 2 } ``` -- 1.1.3【推荐】选择器和 `{` 之间保留一个空格。stylelint: [block-opening-brace-space-before](https://stylelint.io/user-guide/rules/block-opening-brace-space-before) +- 1.1.3 `推荐` 选择器和 `{` 之间保留一个空格。stylelint: [block-opening-brace-space-before](https://stylelint.io/user-guide/rules/block-opening-brace-space-before) ```css /* bad */ @@ -61,7 +61,7 @@ order: 2 } ``` -- 1.1.4【推荐】属性名和 `:` 之前无空格,`:` 和属性值之间保留一个空格。stylelint: [declaration-colon-space-after](https://stylelint.io/user-guide/rules/declaration-colon-space-after) [declaration-colon-space-before](https://stylelint.io/user-guide/rules/declaration-colon-space-before) +- 1.1.4 `推荐` 属性名和 `:` 之前无空格,`:` 和属性值之间保留一个空格。stylelint: [declaration-colon-space-after](https://stylelint.io/user-guide/rules/declaration-colon-space-after) [declaration-colon-space-before](https://stylelint.io/user-guide/rules/declaration-colon-space-before) ```css /* bad */ @@ -77,7 +77,7 @@ order: 2 } ``` -- 1.1.5【推荐】`>`、`+`、`~` 、`||` 等组合器前后各保留一个空格。stylelint: [selector-combinator-space-before](https://stylelint.io/user-guide/rules/selector-combinator-space-before) [selector-combinator-space-after](https://stylelint.io/user-guide/rules/selector-combinator-space-after) +- 1.1.5 `推荐` `>`、`+`、`~` 、`||` 等组合器前后各保留一个空格。stylelint: [selector-combinator-space-before](https://stylelint.io/user-guide/rules/selector-combinator-space-before) [selector-combinator-space-after](https://stylelint.io/user-guide/rules/selector-combinator-space-after) ```css /* bad */ @@ -97,7 +97,7 @@ order: 2 } ``` -- 1.1.6【推荐】在使用 `,` 分隔的属性值中,`,` 之后保留一个空格。stylelint: [value-list-comma-space-after](https://stylelint.io/user-guide/rules/value-list-comma-space-after) +- 1.1.6 `推荐` 在使用 `,` 分隔的属性值中,`,` 之后保留一个空格。stylelint: [value-list-comma-space-after](https://stylelint.io/user-guide/rules/value-list-comma-space-after) ```css /* bad */ @@ -113,7 +113,7 @@ order: 2 } ``` -- 1.1.7【推荐】注释内容和注释符之间留有一个空格。stylelint: [comment-whitespace-inside](https://stylelint.io/user-guide/rules/comment-whitespace-inside) +- 1.1.7 `推荐` 注释内容和注释符之间留有一个空格。stylelint: [comment-whitespace-inside](https://stylelint.io/user-guide/rules/comment-whitespace-inside) ```css /* bad */ @@ -136,7 +136,7 @@ order: 2 } ``` -- 1.1.8【推荐】声明块的右大括号 `}` 应单独成行。 +- 1.1.8 `推荐` 声明块的右大括号 `}` 应单独成行。 ```css /* bad */ @@ -149,7 +149,7 @@ order: 2 } ``` -- 1.1.9【推荐】属性声明应单独成行。stylelint: [declaration-block-single-line-max-declarations](https://stylelint.io/user-guide/rules/declaration-block-single-line-max-declarations) +- 1.1.9 `推荐` 属性声明应单独成行。stylelint: [declaration-block-single-line-max-declarations](https://stylelint.io/user-guide/rules/declaration-block-single-line-max-declarations) ```css /* bad */ @@ -165,7 +165,7 @@ order: 2 ``` -- 1.1.10【推荐】单行代码最多不要超过 100 个字符。 stylelint: [max-line-length](https://stylelint.io/user-guide/rules/max-line-length) 除了以下两种情况: +- 1.1.10 `推荐` 单行代码最多不要超过 100 个字符。 stylelint: [max-line-length](https://stylelint.io/user-guide/rules/max-line-length) 除了以下两种情况: - 使用 [`url()`](https://developer.mozilla.org/en-US/docs/Web/CSS/url) 函数时 - CSS 属性值本身无法换行时,即属性值内无空格或逗号时 @@ -184,7 +184,7 @@ order: 2 ); ``` -- 1.1.11【参考】使用多个选择器时,每个选择器应该单独成行。stylelint: [selector-list-comma-newline-after](https://stylelint.io/user-guide/rules/selector-list-comma-newline-after) +- 1.1.11 `参考` 使用多个选择器时,每个选择器应该单独成行。stylelint: [selector-list-comma-newline-after](https://stylelint.io/user-guide/rules/selector-list-comma-newline-after) ```css /* bad */ @@ -202,7 +202,7 @@ order: 2 } ``` -- 1.1.12【参考】声明块内只有一条语句时,也应该写成多行。 +- 1.1.12 `参考` 声明块内只有一条语句时,也应该写成多行。 ```css /* bad */ @@ -214,7 +214,7 @@ order: 2 } ``` -- 1.1.13【参考】注释行上方需留有一行空行,除非上一行是注释或块的顶部。stylelint: [comment-empty-line-before](https://stylelint.io/user-guide/rules/comment-empty-line-before) +- 1.1.13 `参考` 注释行上方需留有一行空行,除非上一行是注释或块的顶部。stylelint: [comment-empty-line-before](https://stylelint.io/user-guide/rules/comment-empty-line-before) ```css /* bad */ @@ -238,7 +238,7 @@ order: 2 ### 1.2 选择器 -- 1.2.1【参考】不要使用 id 选择器。stylelint: [selector-max-id](https://stylelint.io/user-guide/rules/selector-max-id) +- 1.2.1 `参考` 不要使用 id 选择器。stylelint: [selector-max-id](https://stylelint.io/user-guide/rules/selector-max-id) id 会带来过高的[选择器优先级](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity),使得后续很难进行样式覆盖(继而引发使用 `!important` 覆盖样式的恶性循环)。 @@ -260,7 +260,7 @@ order: 2 } ``` -- 1.2.2【参考】属性选择器的值始终用双引号包裹。stylelint: [selector-attribute-quotes](https://stylelint.io/user-guide/rules/selector-attribute-quotes) +- 1.2.2 `参考` 属性选择器的值始终用双引号包裹。stylelint: [selector-attribute-quotes](https://stylelint.io/user-guide/rules/selector-attribute-quotes) 属性选择器的值的引号只有在[某些情况下](https://mathiasbynens.be/notes/unquoted-attribute-values#css)可以省略。 @@ -276,7 +276,7 @@ order: 2 } ``` -- 1.2.3【参考】使用 CSS 选择器时,应注意以下性能问题: +- 1.2.3 `参考` 使用 CSS 选择器时,应注意以下性能问题: - 使用 class 而不是原生元素标签 - 减少在经常出现的组件中使用个别属性选择器(如 `[class^="..."]`) @@ -296,7 +296,7 @@ order: 2 ### 1.3 属性和属性值 -- 1.3.1【推荐】使用尽可能短的十六进制值。stylelint: [color-hex-length](https://stylelint.io/user-guide/rules/color-hex-length) +- 1.3.1 `推荐` 使用尽可能短的十六进制值。stylelint: [color-hex-length](https://stylelint.io/user-guide/rules/color-hex-length) ```css /* bad */ @@ -310,9 +310,9 @@ order: 2 } ``` -- 1.3.2【推荐】不要使用 !important 重写样式。 +- 1.3.2 `推荐` 不要使用 !important 重写样式。 -- 1.3.3【推荐】十六进制值统一使用小写字母(小写字母更容易分辨)。stylelint: [color-hex-case](https://stylelint.io/user-guide/rules/color-hex-case) +- 1.3.3 `推荐` 十六进制值统一使用小写字母(小写字母更容易分辨)。stylelint: [color-hex-case](https://stylelint.io/user-guide/rules/color-hex-case) ```css /* bad */ @@ -326,7 +326,7 @@ order: 2 } ``` -- 1.3.4【推荐】长度值为 0 时,省略掉长度单位。stylelint: [length-zero-no-unit](https://stylelint.io/user-guide/rules/length-zero-no-unit) +- 1.3.4 `推荐` 长度值为 0 时,省略掉长度单位。stylelint: [length-zero-no-unit](https://stylelint.io/user-guide/rules/length-zero-no-unit) 在 CSS 中,长度值为 0 时,它的单位是可选的(长度单位包括:em, ex, ch, vw, vh, cm, mm, in, pt, pc, px, rem, vmin, and vmax)。省略长度单位可以使代码更简洁: @@ -344,7 +344,7 @@ order: 2 } ``` -- 1.3.5【参考】保留小数点前的 0。stylelint: [number-leading-zero](https://stylelint.io/user-guide/rules/number-leading-zero) +- 1.3.5 `参考` 保留小数点前的 0。stylelint: [number-leading-zero](https://stylelint.io/user-guide/rules/number-leading-zero) 在 CSS 中,大于 -1 小于 1 的小数,小数点前的 0 可以省略: @@ -371,7 +371,7 @@ order: 2 我们推荐保留 0,因为当今很多 CSS 压缩工具会在压缩时帮我们去掉 0,不存在多占用一个字符的问题。保留 0 能增强代码的可读性和一致性。 -- 1.3.6【参考】属性声明的顺序。 +- 1.3.6 `参考` 属性声明的顺序。 相关联的属性声明最好写成一组,并按如下顺序排序: @@ -441,7 +441,7 @@ order: 2 |overflow*||||||| |clip||||||| -- 1.3.7【参考】适时使用简写属性。stylelint: [declaration-block-no-shorthand-property-overrides](https://stylelint.io/user-guide/rules/declaration-block-no-shorthand-property-overrides) [declaration-block-no-redundant-longhand-properties](https://stylelint.io/user-guide/rules/declaration-block-no-redundant-longhand-properties) +- 1.3.7 `参考` 适时使用简写属性。stylelint: [declaration-block-no-shorthand-property-overrides](https://stylelint.io/user-guide/rules/declaration-block-no-shorthand-property-overrides) [declaration-block-no-redundant-longhand-properties](https://stylelint.io/user-guide/rules/declaration-block-no-redundant-longhand-properties) 常见的[简写属性](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties)包括: @@ -471,7 +471,7 @@ order: 2 ### 1.4 其他 -- 1.4.1【推荐】不要使用 CSS 的 @import。 +- 1.4.1 `推荐` 不要使用 CSS 的 @import。 与 `` 相比,`@import` 会在关键渲染路径上增加更多的往返(即关键路径的深度变长),这样会导致浏览器处理 CSS 文件速度变慢,因此我们应该避免使用 `@import`。 @@ -493,7 +493,7 @@ order: 2 >* 更建议使用 PostCSS 处理器,它类似于 CSS 中的 Babel,不但具备 Sass 和 Less 的功能,而且社区繁荣,同时还可以根据自己的需求扩展相关的插件。 >* 随着 CSS 的一些新特性出现,Sass 和 Less 以往的优势也会慢慢消失。 -- 2.1【推荐】四则运算符两侧各保留一个空格: +- 2.1 `推荐` 四则运算符两侧各保留一个空格: ```css /* bad */ @@ -507,7 +507,7 @@ order: 2 } ``` -- 2.2【推荐】Mixin 名称和括号 `()` 间无空格,在拥有多个参数的表达式中, `,` 之前无空格,`,` 之后保留一个空格: +- 2.2 `推荐` Mixin 名称和括号 `()` 间无空格,在拥有多个参数的表达式中, `,` 之前无空格,`,` 之后保留一个空格: ```css /* bad */ @@ -523,7 +523,7 @@ order: 2 } ``` -- 2.3【推荐】按如下顺序组织 Sass / Less 代码: +- 2.3 `推荐` 按如下顺序组织 Sass / Less 代码: - `@import` 语句 - 全局变量声明 @@ -539,7 +539,7 @@ order: 2 } ``` -- 2.4【推荐】对于 Sass 和 Less,块内的属性声明按如下顺序排序: +- 2.4 `推荐` 对于 Sass 和 Less,块内的属性声明按如下顺序排序: - 标准属性声明:除了 mixin 调用、extend 子级选择器的声明,其他属性声明的顺序与「属性声明的顺序」章节的规则一致 - mixin 调用:Sass 的 `@include` 声明、Less 的 mixin 调用 @@ -557,7 +557,7 @@ order: 2 } ``` -- 2.5【推荐】嵌套选择器的深度不要超过 3 层,否则可能带来一些副作用: +- 2.5 `推荐` 嵌套选择器的深度不要超过 3 层,否则可能带来一些副作用: - 与 HTML 结构强耦合,难以复用 - 过高的[选择器优先级](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) @@ -572,7 +572,7 @@ order: 2 } ``` -- 2.6【推荐】可以使用双斜杠注释。但需要注意的是,编译为 CSS 后,代码中的双斜杠注释会被删除,而 `/* */` 会被保留。 +- 2.6 `推荐` 可以使用双斜杠注释。但需要注意的是,编译为 CSS 后,代码中的双斜杠注释会被删除,而 `/* */` 会被保留。 ```css // 单行注释 @@ -605,7 +605,7 @@ order: 2 } ``` -- 2.7【推荐】使用 Mixin (@mixin 和 @include 指令) 来让代码遵循 DRY 原则(Don't Repeat Yourself)、增加抽象性和降低复杂度。 +- 2.7 `推荐` 使用 Mixin (@mixin 和 @include 指令) 来让代码遵循 DRY 原则(Don't Repeat Yourself)、增加抽象性和降低复杂度。 应避免使用 @extend 指令,它不够直观且具有潜在风险,尤其是在嵌套选择器中。即使继承的是顶层选择器,如果选择器的顺序发生变化,也可能引起问题(比如,如果它们存在于其他文件,而加载顺序发生了变化)。 diff --git a/docs/coding/html.md b/docs/coding/html.md index f7158b5..b84d9cc 100644 --- a/docs/coding/html.md +++ b/docs/coding/html.md @@ -11,7 +11,7 @@ order: 1 ### 1.1 文档类型 -- 1.1.1【强制】使用 HTML5 DOCTYPE。 +- 1.1.1 `mandatory` 使用 HTML5 DOCTYPE。 在 HTML 文档的开头使用 `` 来声明文档的 HTML 版本。 @@ -29,7 +29,7 @@ order: 1 ### 1.2 语言 -- 1.2.1【推荐】指定 `html` 标签上的 `lang` 属性。 +- 1.2.1 `recommended` 指定 `html` 标签上的 `lang` 属性。 [HTML5 规范](http://w3c.github.io/html/semantics.html#the-html-element)中提到: @@ -45,7 +45,7 @@ order: 1 ### 1.3 元数据 -- 1.3.1【推荐】使用 UTF-8 字符编码。 +- 1.3.1 `recommended` 使用 UTF-8 字符编码。 声明一个明确的字符编码,可以让浏览器更快速高效地确定适合网页内容的渲染方式。 @@ -59,7 +59,7 @@ order: 1 ``` -- 1.3.2【推荐】页面提供给移动设备使用时,需要设置 [viewport](https://drafts.csswg.org/css-device-adapt/#viewport-meta)。 +- 1.3.2 `recommended` 页面提供给移动设备使用时,需要设置 [viewport](https://drafts.csswg.org/css-device-adapt/#viewport-meta)。 设置 viewport-fit 设置为“cover”来兼容 iPhone X 的刘海屏,[了解更多](https://webkit.org/blog/7929/designing-websites-for-iphone-x/) 。 @@ -70,7 +70,7 @@ order: 1 ### 1.4 资源加载 -- 1.4.1【推荐】引入 CSS 和 JavaScript 时无需指定 type。 +- 1.4.1 `recommended` 引入 CSS 和 JavaScript 时无需指定 type。 根据 HTML5 规范,引入 CSS 和 JavaScript 时通常不需要指明 type,因为 [text/css](https://html.spec.whatwg.org/multipage/obsolete.html#attr-style-type) 和 [text/javascript](https://html.spec.whatwg.org/multipage/scripting.html#attr-script-type) 分别是他们的默认值。 ```html @@ -89,7 +89,7 @@ order: 1 ``` -- 1.4.2【推荐】在 head 标签内引入 CSS,在 body 结束标签前引入 JS。 +- 1.4.2 `recommended` 在 head 标签内引入 CSS,在 body 结束标签前引入 JS。 在 `` 中指定外部样式表和嵌入式样式块可能会导致页面的重排和重绘,对页面的渲染造成影响。因此,一般情况下,CSS 应在 `` 标签里引入,[了解更多](https://developer.yahoo.com/performance/rules.html#css_top)。 @@ -132,20 +132,20 @@ order: 1 ``` -- 1.4.3【推荐】外部资源的引用地址跟随页面协议,省略协议部分。 +- 1.4.3 `recommended` 外部资源的引用地址跟随页面协议,省略协议部分。 ```html ``` -- 1.4.4【推荐】使用 preload 预加载关键资源,[了解更多](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Preloading_content)。 +- 1.4.4 `recommended` 使用 preload 预加载关键资源,[了解更多](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Preloading_content)。 ```html ``` -- 1.4.5【推荐】使用 dns-prefetch 和 preconnect 处理 DNS 解析延迟问题,提高网页加载性能,[了解更多](https://developer.mozilla.org/zh-CN/docs/Web/Performance/dns-prefetch)。 +- 1.4.5 `recommended` 使用 dns-prefetch 和 preconnect 处理 DNS 解析延迟问题,提高网页加载性能,[了解更多](https://developer.mozilla.org/zh-CN/docs/Web/Performance/dns-prefetch)。 ```html @@ -154,7 +154,7 @@ order: 1 ### 1.5 页面标题 -- 1.5.1【强制】页面需要指定 title 标签,有且仅有 1 个。 +- 1.5.1 `mandatory` 页面需要指定 title 标签,有且仅有 1 个。 ```html @@ -167,7 +167,7 @@ order: 1 ### 2.1 缩进 -- 2.1.1【推荐】统一使用 2 个空格缩进,不要使用 4 个空格或 tab 缩进。 +- 2.1.1 `recommended` 统一使用 2 个空格缩进,不要使用 4 个空格或 tab 缩进。 ```html @@ -184,7 +184,7 @@ order: 1 ### 2.2 注释 -- 2.2.1【强制】在 HTML 注释代码中,不允许出现任何敏感信息。 +- 2.2.1 `mandatory` 在 HTML 注释代码中,不允许出现任何敏感信息。 常见的敏感信息包括: @@ -195,13 +195,13 @@ order: 1 - 内网 IP、URL - 其他公司、员工相关的内部信息、敏感信息 -- 2.2.2【推荐】单行注释,需在注释内容和注释符之间需留有一个空格,以增强可读性。 +- 2.2.2 `recommended` 单行注释,需在注释内容和注释符之间需留有一个空格,以增强可读性。 ```html ``` -- 2.2.3【推荐】多行注释,注释符单独占一行,注释内容 2 个空格缩进。 +- 2.2.3 `recommended` 多行注释,注释符单独占一行,注释内容 2 个空格缩进。 ```html @@ -222,7 +222,7 @@ order: 1

Hello, world!

``` -- 2.3.2【推荐】不要省略自闭合标签结尾处的斜线,且斜线前需留有一个空格。 +- 2.3.2 `recommended` 不要省略自闭合标签结尾处的斜线,且斜线前需留有一个空格。 虽然 [HTML5 规范](https://dev.w3.org/html5/spec-author-view/syntax.html#syntax-start-tag) 中指出结尾的斜线是可选的,但保留它们可以明确表达该标签已闭合的语义,更易于维护和理解。 @@ -240,7 +240,7 @@ order: 1 ### 2.4 属性 -- 2.4.1【强制】属性值使用双引号,不要使用单引号。 +- 2.4.1 `mandatory` 属性值使用双引号,不要使用单引号。 ```html @@ -250,7 +250,7 @@ order: 1 ``` -- 2.4.2【推荐】不要为 Boolean 属性添加取值。 +- 2.4.2 `recommended` 不要为 Boolean 属性添加取值。 XHTML 需要每个属性声明取值,但是 HTML5 并不需要。一个元素中 Boolean 属性存在即表示取值 `true`,不存在则表示取值 `false`,[了解更多](http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#boolean-attributes)。 @@ -270,7 +270,7 @@ order: 1 ``` -- 2.4.3【推荐】自定义属性的命名:以 data- 为前缀。 +- 2.4.3 `recommended` 自定义属性的命名:以 data- 为前缀。 建议自定义属性的命名都以 `data-` 为前缀,以便区分。 @@ -288,7 +288,7 @@ order: 1 ### 2.5 语义化 -- 2.5.1【参考】尽量根据语义使用 HTML 标签。 +- 2.5.1 `referenced` 尽量根据语义使用 HTML 标签。 HTML 标签(更严谨的叫法是 HTML 元素)都有其语义,例如 `p` 标签即“paragraphs”用于章节,`a` 标签即“anchors”用于锚点链接,[了解更多](https://www.w3.org/TR/2018/WD-html53-20181018/fullindex.html#index-elements)。 @@ -312,7 +312,7 @@ order: 1 ### 2.6 可访问性 -- 2.6.1【参考】注意 HTML 的可访问性(Accessibility)。 +- 2.6.1 `referenced` 注意 HTML 的可访问性(Accessibility)。 网页可访问性使网页内容落实“无障碍”,让不同程度或需求的用户可以顺畅的获取网站上的信息。传统上我们认为这只与残疾人士有关,但提升网站的可访问性也可以让其他用户群体受益,比如使用移动设备的人群或低速网络的人群。 diff --git a/docs/coding/html.zh.md b/docs/coding/html.zh.md index 398bb0c..e8962fc 100644 --- a/docs/coding/html.zh.md +++ b/docs/coding/html.zh.md @@ -11,7 +11,7 @@ order: 1 ### 1.1 文档类型 -- 1.1.1【强制】使用 HTML5 DOCTYPE。 +- 1.1.1 `强制` 使用 HTML5 DOCTYPE。 在 HTML 文档的开头使用 `` 来声明文档的 HTML 版本。 @@ -29,7 +29,7 @@ order: 1 ### 1.2 语言 -- 1.2.1【推荐】指定 `html` 标签上的 `lang` 属性。 +- 1.2.1 `推荐` 指定 `html` 标签上的 `lang` 属性。 [HTML5 规范](http://w3c.github.io/html/semantics.html#the-html-element)中提到: @@ -45,7 +45,7 @@ order: 1 ### 1.3 元数据 -- 1.3.1【推荐】使用 UTF-8 字符编码。 +- 1.3.1 `推荐` 使用 UTF-8 字符编码。 声明一个明确的字符编码,可以让浏览器更快速高效地确定适合网页内容的渲染方式。 @@ -59,7 +59,7 @@ order: 1 ``` -- 1.3.2【推荐】页面提供给移动设备使用时,需要设置 [viewport](https://drafts.csswg.org/css-device-adapt/#viewport-meta)。 +- 1.3.2 `推荐` 页面提供给移动设备使用时,需要设置 [viewport](https://drafts.csswg.org/css-device-adapt/#viewport-meta)。 设置 viewport-fit 设置为“cover”来兼容 iPhone X 的刘海屏,[了解更多](https://webkit.org/blog/7929/designing-websites-for-iphone-x/) 。 @@ -70,7 +70,7 @@ order: 1 ### 1.4 资源加载 -- 1.4.1【推荐】引入 CSS 和 JavaScript 时无需指定 type。 +- 1.4.1 `推荐` 引入 CSS 和 JavaScript 时无需指定 type。 根据 HTML5 规范,引入 CSS 和 JavaScript 时通常不需要指明 type,因为 [text/css](https://html.spec.whatwg.org/multipage/obsolete.html#attr-style-type) 和 [text/javascript](https://html.spec.whatwg.org/multipage/scripting.html#attr-script-type) 分别是他们的默认值。 ```html @@ -89,7 +89,7 @@ order: 1 ``` -- 1.4.2【推荐】在 head 标签内引入 CSS,在 body 结束标签前引入 JS。 +- 1.4.2 `推荐` 在 head 标签内引入 CSS,在 body 结束标签前引入 JS。 在 `` 中指定外部样式表和嵌入式样式块可能会导致页面的重排和重绘,对页面的渲染造成影响。因此,一般情况下,CSS 应在 `` 标签里引入,[了解更多](https://developer.yahoo.com/performance/rules.html#css_top)。 @@ -132,20 +132,20 @@ order: 1 ``` -- 1.4.3【推荐】外部资源的引用地址跟随页面协议,省略协议部分。 +- 1.4.3 `推荐` 外部资源的引用地址跟随页面协议,省略协议部分。 ```html ``` -- 1.4.4【推荐】使用 preload 预加载关键资源,[了解更多](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Preloading_content)。 +- 1.4.4 `推荐` 使用 preload 预加载关键资源,[了解更多](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Preloading_content)。 ```html ``` -- 1.4.5【推荐】使用 dns-prefetch 和 preconnect 处理 DNS 解析延迟问题,提高网页加载性能,[了解更多](https://developer.mozilla.org/zh-CN/docs/Web/Performance/dns-prefetch)。 +- 1.4.5 `推荐` 使用 dns-prefetch 和 preconnect 处理 DNS 解析延迟问题,提高网页加载性能,[了解更多](https://developer.mozilla.org/zh-CN/docs/Web/Performance/dns-prefetch)。 ```html @@ -154,7 +154,7 @@ order: 1 ### 1.5 页面标题 -- 1.5.1【强制】页面需要指定 title 标签,有且仅有 1 个。 +- 1.5.1 `强制` 页面需要指定 title 标签,有且仅有 1 个。 ```html @@ -167,7 +167,7 @@ order: 1 ### 2.1 缩进 -- 2.1.1【推荐】统一使用 2 个空格缩进,不要使用 4 个空格或 tab 缩进。 +- 2.1.1 `推荐` 统一使用 2 个空格缩进,不要使用 4 个空格或 tab 缩进。 ```html @@ -184,7 +184,7 @@ order: 1 ### 2.2 注释 -- 2.2.1【强制】在 HTML 注释代码中,不允许出现任何敏感信息。 +- 2.2.1 `强制` 在 HTML 注释代码中,不允许出现任何敏感信息。 常见的敏感信息包括: @@ -195,13 +195,13 @@ order: 1 - 内网 IP、URL - 其他公司、员工相关的内部信息、敏感信息 -- 2.2.2【推荐】单行注释,需在注释内容和注释符之间需留有一个空格,以增强可读性。 +- 2.2.2 `推荐` 单行注释,需在注释内容和注释符之间需留有一个空格,以增强可读性。 ```html ``` -- 2.2.3【推荐】多行注释,注释符单独占一行,注释内容 2 个空格缩进。 +- 2.2.3 `推荐` 多行注释,注释符单独占一行,注释内容 2 个空格缩进。 ```html @@ -222,7 +222,7 @@ order: 1

Hello, world!

``` -- 2.3.2【推荐】不要省略自闭合标签结尾处的斜线,且斜线前需留有一个空格。 +- 2.3.2 `推荐` 不要省略自闭合标签结尾处的斜线,且斜线前需留有一个空格。 虽然 [HTML5 规范](https://dev.w3.org/html5/spec-author-view/syntax.html#syntax-start-tag) 中指出结尾的斜线是可选的,但保留它们可以明确表达该标签已闭合的语义,更易于维护和理解。 @@ -240,7 +240,7 @@ order: 1 ### 2.4 属性 -- 2.4.1【强制】属性值使用双引号,不要使用单引号。 +- 2.4.1 `强制` 属性值使用双引号,不要使用单引号。 ```html @@ -250,7 +250,7 @@ order: 1 ``` -- 2.4.2【推荐】不要为 Boolean 属性添加取值。 +- 2.4.2 `推荐` 不要为 Boolean 属性添加取值。 XHTML 需要每个属性声明取值,但是 HTML5 并不需要。一个元素中 Boolean 属性存在即表示取值 `true`,不存在则表示取值 `false`,[了解更多](http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#boolean-attributes)。 @@ -270,7 +270,7 @@ order: 1 ``` -- 2.4.3【推荐】自定义属性的命名:以 data- 为前缀。 +- 2.4.3 `推荐` 自定义属性的命名:以 data- 为前缀。 建议自定义属性的命名都以 `data-` 为前缀,以便区分。 @@ -288,7 +288,7 @@ order: 1 ### 2.5 语义化 -- 2.5.1【参考】尽量根据语义使用 HTML 标签。 +- 2.5.1 `参考` 尽量根据语义使用 HTML 标签。 HTML 标签(更严谨的叫法是 HTML 元素)都有其语义,例如 `p` 标签即“paragraphs”用于章节,`a` 标签即“anchors”用于锚点链接,[了解更多](https://www.w3.org/TR/2018/WD-html53-20181018/fullindex.html#index-elements)。 @@ -312,7 +312,7 @@ order: 1 ### 2.6 可访问性 -- 2.6.1【参考】注意 HTML 的可访问性(Accessibility)。 +- 2.6.1 `参考` 注意 HTML 的可访问性(Accessibility)。 网页可访问性使网页内容落实“无障碍”,让不同程度或需求的用户可以顺畅的获取网站上的信息。传统上我们认为这只与残疾人士有关,但提升网站的可访问性也可以让其他用户群体受益,比如使用移动设备的人群或低速网络的人群。 diff --git a/docs/coding/javascript.md b/docs/coding/javascript.md index 30aab32..bf3dfd5 100644 --- a/docs/coding/javascript.md +++ b/docs/coding/javascript.md @@ -17,7 +17,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 1.1 缩进 -- 1.1.1【强制】使用 2 个空格缩进。eslint: [indent](https://eslint.org/docs/rules/indent) +- 1.1.1 `mandatory` 使用 2 个空格缩进。eslint: [indent](https://eslint.org/docs/rules/indent) 统一使用 2 个空格缩进,不要使用 4 个空格或 tab 缩进: @@ -35,7 +35,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 1.2 分号 -- 1.2.1【强制】使用分号。eslint: [semi](https://eslint.org/docs/rules/semi) +- 1.2.1 `mandatory` 使用分号。eslint: [semi](https://eslint.org/docs/rules/semi) 统一以分号结束语句,可以避免 JS 引擎自动分号插入机制的怪异行为,在语义上也更加明确。 @@ -80,7 +80,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 1.3 逗号 -- 1.3.1【强制】对于逗号分隔的多行结构,不使用行首逗号。eslint: [comma-style](https://eslint.org/docs/rules/comma-style) +- 1.3.1 `mandatory` 对于逗号分隔的多行结构,不使用行首逗号。eslint: [comma-style](https://eslint.org/docs/rules/comma-style) ```js // bad @@ -112,7 +112,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 1.3.2【强制】对于逗号分隔的多行结构,始终加上最后一个逗号。eslint: [comma-dangle](https://eslint.org/docs/rules/comma-dangle) +- 1.3.2 `mandatory` 对于逗号分隔的多行结构,始终加上最后一个逗号。eslint: [comma-dangle](https://eslint.org/docs/rules/comma-dangle) 这样可以使增删行更加容易,也会使 git diffs 更清晰。Babel 等编译器会在编译后的代码里帮我们去掉最后额外的逗号,因此不必担心在旧浏览器中的问题。 @@ -199,7 +199,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 > 术语解释:**块(block)** 可以理解为类、函数、控制语句等由大括号 `{}` 分隔的代码块状结构,由一对大括号界定,用于组合若干条语句 [了解更多](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/block) -- 1.4.1【推荐】始终使用大括号包裹代码块。eslint: [curly](https://eslint.org/docs/rules/curly) [nonblock-statement-body-position](https://eslint.org/docs/rules/nonblock-statement-body-position) +- 1.4.1 `recommended` 始终使用大括号包裹代码块。eslint: [curly](https://eslint.org/docs/rules/curly) [nonblock-statement-body-position](https://eslint.org/docs/rules/nonblock-statement-body-position) 多行代码块必须用大括号包裹: @@ -234,7 +234,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 #### 1.4.2 大括号换行风格 -- 1.4.2.1【强制】对于非空代码块,采用 Egyptian Brackets 风格。eslint: [brace-style](https://eslint.org/docs/rules/brace-style) +- 1.4.2.1 `mandatory` 对于非空代码块,采用 Egyptian Brackets 风格。eslint: [brace-style](https://eslint.org/docs/rules/brace-style) 对于非空的代码块,大括号的换行方式采用 [Egyptian Brackets](https://blog.codinghorror.com/new-programming-jargon/) 风格,具体规则如下: @@ -261,7 +261,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 1.4.2.2【参考】对于空代码块,可以将大括号直接闭合。 +- 1.4.2.2 `referenced` 对于空代码块,可以将大括号直接闭合。 对于空的代码块,且不在类似 `if..else..` 或 `try..catch..finally..` 的多块结构中时,可以立即将大括号闭合: @@ -300,7 +300,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 1.4.3【强制】不要使用空代码块。eslint: [no-empty](https://eslint.org/docs/rules/no-empty) +- 1.4.3 `mandatory` 不要使用空代码块。eslint: [no-empty](https://eslint.org/docs/rules/no-empty) 不要让代码中出现空代码块,这会使阅读者感到困惑。如果必须使用空块,需在块内写明注释。 @@ -323,7 +323,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 合理并一致地使用空格有助于提升代码的可读性和可维护性。具体来说,我们采用如下的空格风格: -- 1.5.1【强制】空格风格。eslint: [space-before-blocks](https://eslint.org/docs/rules/space-before-blocks) [keyword-spacing](https://eslint.org/docs/rules/keyword-spacing) [space-in-parens](https://eslint.org/docs/rules/space-in-parens) [array-bracket-spacing](https://eslint.org/docs/rules/array-bracket-spacing) [object-curly-spacing](https://eslint.org/docs/rules/object-curly-spacing) [space-infix-ops](https://eslint.org/docs/rules/space-infix-ops) [key-spacing](https://eslint.org/docs/rules/key-spacing) +- 1.5.1 `mandatory` 空格风格。eslint: [space-before-blocks](https://eslint.org/docs/rules/space-before-blocks) [keyword-spacing](https://eslint.org/docs/rules/keyword-spacing) [space-in-parens](https://eslint.org/docs/rules/space-in-parens) [array-bracket-spacing](https://eslint.org/docs/rules/array-bracket-spacing) [object-curly-spacing](https://eslint.org/docs/rules/object-curly-spacing) [space-infix-ops](https://eslint.org/docs/rules/space-infix-ops) [key-spacing](https://eslint.org/docs/rules/key-spacing) 块的左大括号 `{` 前有一个空格: @@ -473,7 +473,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 1.6 空行 -- 1.6.1【推荐】在文件末尾保留一行空行。eslint: [eol-last](https://eslint.org/docs/rules/eol-last) +- 1.6.1 `recommended` 在文件末尾保留一行空行。eslint: [eol-last](https://eslint.org/docs/rules/eol-last) 在非空文件中保留拖尾换行是一种常见的 UNIX 风格。它的好处同输出文件到终端一样,方便在串联和追加文件时不会打断 shell 的提示。 @@ -498,7 +498,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ``` -- 1.6.2【强制】块的开始和结束不能是空行。eslint: [padded-blocks](https://eslint.org/docs/rules/padded-blocks) +- 1.6.2 `mandatory` 块的开始和结束不能是空行。eslint: [padded-blocks](https://eslint.org/docs/rules/padded-blocks) ```js // bad @@ -530,7 +530,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 1.6.3【参考】在块末和新语句间插入一个空行。 +- 1.6.3 `referenced` 在块末和新语句间插入一个空行。 ```js // bad @@ -569,7 +569,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 1.7 最大字符数和最大行数 -- 1.7.1【推荐】单行最大字符数:100。eslint: [max-len](https://eslint.org/docs/rules/max-len) +- 1.7.1 `recommended` 单行最大字符数:100。eslint: [max-len](https://eslint.org/docs/rules/max-len) 过长的单行代码不易阅读和维护,需要进行合理换行。 @@ -603,11 +603,11 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 .fail(() => console.log('You have failed this city.')); ``` -- 1.7.2【参考】文件最大行数:1000。eslint: [max-lines](https://eslint.org/docs/rules/max-lines) +- 1.7.2 `referenced` 文件最大行数:1000。eslint: [max-lines](https://eslint.org/docs/rules/max-lines) 过长的文件不易阅读和维护,最好对其进行拆分。 -- 1.7.3【参考】函数最大行数:80。eslint: [max-lines-per-function](https://eslint.org/docs/rules/max-lines-per-function) +- 1.7.3 `referenced` 函数最大行数:80。eslint: [max-lines-per-function](https://eslint.org/docs/rules/max-lines-per-function) 过长的函数不易阅读和维护,最好对其进行拆分。 @@ -615,7 +615,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.1 变量声明 -- 2.1.1【强制】使用 const 或 let 声明变量。eslint: [no-var](https://eslint.org/docs/rules/no-var) [no-undef](https://eslint.org/docs/rules/no-undef) +- 2.1.1 `mandatory` 使用 const 或 let 声明变量。eslint: [no-var](https://eslint.org/docs/rules/no-var) [no-undef](https://eslint.org/docs/rules/no-undef) 从 ES6 开始,可以使用 `let` 和 `const` 关键字在块级作用域下声明变量。块级作用域在很多其他编程语言中都有使用,这样声明的变量不会污染全局命名空间。 @@ -641,7 +641,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const foo = 'foo'; ``` -- 2.1.2【强制】正确地使用 const 和 let。eslint: [prefer-const](https://eslint.org/docs/rules/prefer-const) +- 2.1.2 `mandatory` 正确地使用 const 和 let。eslint: [prefer-const](https://eslint.org/docs/rules/prefer-const) 声明变量时,应优先使用 `const`,只有当变量会被重新赋值时才使用 `let`: @@ -675,7 +675,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 obj.name = 'bar'; ``` -- 2.1.3【强制】一条声明语句声明一个变量。eslint: [one-var](https://eslint.org/docs/rules/one-var) +- 2.1.3 `mandatory` 一条声明语句声明一个变量。eslint: [one-var](https://eslint.org/docs/rules/one-var) 这样做更易于追加新的声明语句(你不需要总去把最后的 `;` 改成 `,` 了),也更易于进行单步调试。 @@ -689,7 +689,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const bar = 2; ``` -- 2.1.4【强制】声明的变量必须被使用。eslint: [no-unused-vars](https://eslint.org/docs/rules/no-unused-vars) +- 2.1.4 `mandatory` 声明的变量必须被使用。eslint: [no-unused-vars](https://eslint.org/docs/rules/no-unused-vars) 声明而未使用的变量、表达式可能带来潜在的问题,也会给维护者造成困扰,应将它们删除。 @@ -723,7 +723,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.1.5【强制】不要在声明前就使用变量。eslint: [no-use-before-define](https://eslint.org/docs/rules/no-use-before-define) +- 2.1.5 `mandatory` 不要在声明前就使用变量。eslint: [no-use-before-define](https://eslint.org/docs/rules/no-use-before-define) 在 ES5 中,由于 `var` 的声明提升作用,变量可以在声明前使用,但这样做可能给人带来疑惑和隐患,所以不要在声明前就使用变量: @@ -749,7 +749,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 console.log(foo); // => foo ``` -- 2.1.6【参考】哪里使用,哪里声明。 +- 2.1.6 `referenced` 哪里使用,哪里声明。 在变量被使用前再进行声明,而不是统一在块开始处进行声明。 @@ -787,7 +787,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.1.7【强制】变量不要与外层作用域已存在的变量同名。eslint: [no-shadow](https://eslint.org/docs/rules/no-shadow) +- 2.1.7 `mandatory` 变量不要与外层作用域已存在的变量同名。eslint: [no-shadow](https://eslint.org/docs/rules/no-shadow) 如果变量与外层已存在变量同名,会降低可读性,也会导致内层作用域无法读取外层作用域的同名变量。 @@ -808,7 +808,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.1.8【强制】不要重复声明变量和函数。eslint: [no-redeclare](https://eslint.org/docs/rules/no-redeclare) +- 2.1.8 `mandatory` 不要重复声明变量和函数。eslint: [no-redeclare](https://eslint.org/docs/rules/no-redeclare) 在 ES5 中,尽管使用 `var` 重复声明不会报错,但这样做会令人疑惑,降低程序的可维护性。同理,函数的声明也不要与已存在的变量和函数重名: @@ -866,7 +866,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 myFunc('bar'); // => 'bar' ``` -- 2.1.9【强制】禁止连续赋值。eslint: [no-multi-assign](https://eslint.org/docs/rules/no-multi-assign) +- 2.1.9 `mandatory` 禁止连续赋值。eslint: [no-multi-assign](https://eslint.org/docs/rules/no-multi-assign) 变量的连续赋值让人难以阅读和理解,并且可能导致意想不到的结果(如产生全局变量)。 @@ -892,7 +892,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 console.log(c); // throws ReferenceError ``` -- 2.1.10【参考】将 let 和 const 分别归类。 +- 2.1.10 `referenced` 将 let 和 const 分别归类。 将 `let` 和 `const` 归类写在一起,可以提高代码整洁性。此外,如果你想按变量的含义排序分组也是允许的。 @@ -916,7 +916,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 > JS的数据类型包括 7 种原始类型(primitive type),即 Boolean, Null, Undefined, Number, String, Symbol (ES6 新定义), BigInt(ES11新定义),以及 Object 类型,[了解更多](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures)。这个章节主要介绍原始类型相关的规约。 -- 2.2.1【强制】不要使用 new Number/String/Boolean。eslint: [no-new-wrappers](https://eslint.org/docs/rules/no-new-wrappers) +- 2.2.1 `mandatory` 不要使用 new Number/String/Boolean。eslint: [no-new-wrappers](https://eslint.org/docs/rules/no-new-wrappers) 使用 new Number/String//Boolean 声明不会有任何好处,还会导致变量成为 `object` 类型,可能引起 bug。 @@ -942,7 +942,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.2.2【推荐】类型转换。 +- 2.2.2 `recommended` 类型转换。 【数字】使用 `Number()` 或 `parseInt()` : @@ -988,7 +988,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const hasAge = !!age; ``` -- 2.2.3【推荐】使用 parseInt() 方法时总是带上基数。eslint: [radix](https://eslint.org/docs/rules/radix) +- 2.2.3 `recommended` 使用 parseInt() 方法时总是带上基数。eslint: [radix](https://eslint.org/docs/rules/radix) `parseInt` 方法的第一个参数是待转换的字符串,第二个参数是转换基数。当第二个参数省略时,`parseInt` 会根据第一个参数自动判断基数: @@ -1008,7 +1008,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 parseInt("071", 10); // => 71 ``` -- 2.2.4【强制】避免不必要的布尔类型转换。eslint: [no-extra-boolean-cast](https://eslint.org/docs/rules/no-extra-boolean-cast) +- 2.2.4 `mandatory` 避免不必要的布尔类型转换。eslint: [no-extra-boolean-cast](https://eslint.org/docs/rules/no-extra-boolean-cast) 在 `if` 等条件语句中,将表达式的结果强制转换成布尔值是多余的: @@ -1038,7 +1038,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 #### 2.2.5 字符串 -- 2.2.5.1【强制】字符串优先使用单引号。eslint: [quotes](https://eslint.org/docs/rules/quotes) +- 2.2.5.1 `mandatory` 字符串优先使用单引号。eslint: [quotes](https://eslint.org/docs/rules/quotes) ```js // bad @@ -1049,7 +1049,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const name = 'tod'; ``` -- 2.2.5.2【推荐】使用模板字符串替代字符串拼接。eslint: [prefer-template](https://eslint.org/docs/rules/prefer-template) +- 2.2.5.2 `recommended` 使用模板字符串替代字符串拼接。eslint: [prefer-template](https://eslint.org/docs/rules/prefer-template) 模板字符串让代码更简洁,可读性更强 @@ -1065,7 +1065,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.2.5.3【强制】禁止不必要的转义字符。[no-useless-escape](https://eslint.org/docs/rules/no-useless-escape) +- 2.2.5.3 `mandatory` 禁止不必要的转义字符。[no-useless-escape](https://eslint.org/docs/rules/no-useless-escape) 转义字符会大大降低代码的可读性,因此尽量不要滥用它们。 @@ -1080,7 +1080,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.3 数组 -- 2.3.1【强制】使用字面量创建数组。eslint: [no-array-constructor](https://eslint.org/docs/rules/no-array-constructor) +- 2.3.1 `mandatory` 使用字面量创建数组。eslint: [no-array-constructor](https://eslint.org/docs/rules/no-array-constructor) 不要使用 `new Array()` 和 `Array()` 创建数组,除非为了构造某一长度的空数组。 @@ -1094,7 +1094,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const b = new Array(500); // 构造长度为 500 的空数组 ``` -- 2.3.2【强制】某些数组方法的回调函数中必须包含 return 语句。eslint: [array-callback-return](https://eslint.org/docs/rules/array-callback-return) +- 2.3.2 `mandatory` 某些数组方法的回调函数中必须包含 return 语句。eslint: [array-callback-return](https://eslint.org/docs/rules/array-callback-return) 以下数组方法:`map`, `filter`, `from `, `every`, `find`, `findIndex`, `reduce`, `reduceRight`, `some`, `sort` 的回调函数中必须包含 `return` 语句,否则可能会产生误用或错误。 @@ -1135,7 +1135,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }, {}); ``` -- 2.3.3【推荐】使用扩展运算符 ... 处理数组。 +- 2.3.3 `recommended` 使用扩展运算符 ... 处理数组。 ES6 提供了扩展运算符 `...`,可以简化一些数组操作。 @@ -1201,7 +1201,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const baz = Array.from(foo, bar); ``` -- 2.3.4【推荐】使用解构获取数组元素。 +- 2.3.4 `recommended` 使用解构获取数组元素。 使用 ES6 提供的解构方法获取数组元素: @@ -1234,7 +1234,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.4 对象 -- 2.4.1【强制】使用字面量创建对象。eslint: [no-new-object](https://eslint.org/docs/rules/no-new-object) +- 2.4.1 `mandatory` 使用字面量创建对象。eslint: [no-new-object](https://eslint.org/docs/rules/no-new-object) ```js // bad @@ -1244,7 +1244,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const obj = {}; ``` -- 2.4.2【强制】使用对象属性和方法的简写语法。eslint: [object-shorthand](https://eslint.org/docs/rules/object-shorthand) +- 2.4.2 `mandatory` 使用对象属性和方法的简写语法。eslint: [object-shorthand](https://eslint.org/docs/rules/object-shorthand) ES6 提供了对象属性和方法的简写语法,可以使代码更加简洁: @@ -1268,7 +1268,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 2.4.3【参考】将对象的简写属性写在一起。 +- 2.4.3 `referenced` 将对象的简写属性写在一起。 将简写的属性写在一起,置于对象的起始或末尾,可以提高代码整洁性。当然,如果你出于属性的含义或其他考虑进行排序也是允许的。 @@ -1297,7 +1297,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 2.4.4【强制】对象的属性名不要用引号包裹,除非包含特殊字符。eslint: [quote-props](https://eslint.org/docs/rules/quote-props) +- 2.4.4 `mandatory` 对象的属性名不要用引号包裹,除非包含特殊字符。eslint: [quote-props](https://eslint.org/docs/rules/quote-props) 这样更加简洁,也有助于语法高亮和一些 JS 引擎的优化。 @@ -1319,7 +1319,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 2.4.5【强制】优先使用 . 访问对象的属性。eslint: [dot-notation](https://eslint.org/docs/rules/dot-notation) +- 2.4.5 `mandatory` 优先使用 . 访问对象的属性。eslint: [dot-notation](https://eslint.org/docs/rules/dot-notation) 这样可以提高代码可读性。`[]` 仅应在访问动态属性名或包含特殊字符的属性名时被使用。 @@ -1339,7 +1339,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const bar = obj['data-bar']; ``` -- 2.4.6【推荐】使用扩展运算符 ... 处理对象。 +- 2.4.6 `recommended` 使用扩展运算符 ... 处理对象。 替代 `Object.assign` 方法,来进行对象的浅拷贝: @@ -1366,7 +1366,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const { a, ...noA } = copy; // noA => { b: 2, c: 3 } ``` -- 2.4.7【推荐】使用解构获取对象属性。eslint: [prefer-destructuring](https://eslint.org/docs/rules/prefer-destructuring) +- 2.4.7 `recommended` 使用解构获取对象属性。eslint: [prefer-destructuring](https://eslint.org/docs/rules/prefer-destructuring) 获取对象的同名属性、多个属性时,使用解构让代码更简洁,也可以减少为了使用属性而创建的临时引用。 @@ -1391,7 +1391,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.4.8【参考】对象的动态属性名应直接写在字面量定义中。 +- 2.4.8 `referenced` 对象的动态属性名应直接写在字面量定义中。 ES6 允许在新建对象字面量时使用表达式作为属性名,这样可以将所有属性定义在一个地方。 @@ -1415,7 +1415,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 2.4.9【强制】不要直接在对象上调用 Object.prototypes 上的方法。eslint: [no-prototype-builtins](https://eslint.org/docs/rules/no-prototype-builtins) +- 2.4.9 `mandatory` 不要直接在对象上调用 Object.prototypes 上的方法。eslint: [no-prototype-builtins](https://eslint.org/docs/rules/no-prototype-builtins) 不要直接在对象上调用 `Object.prototypes` 上的方法,例如 `hasOwnProperty`、`propertyIsEnumerable`、`isPrototypeOf`。 @@ -1439,7 +1439,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.5 函数 -- 2.5.1【强制】不要用 Function 构造函数创建函数。eslint: [no-new-func](https://eslint.org/docs/rules/no-new-func) +- 2.5.1 `mandatory` 不要用 Function 构造函数创建函数。eslint: [no-new-func](https://eslint.org/docs/rules/no-new-func) 使用 `new Function` 创建函数会像 `eval()` 方法一样执行字符串,带来安全隐患 @@ -1451,7 +1451,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const sum = (a, b) => (a + b); ``` -- 2.5.2【强制】不要在块中使用函数声明。eslint: [no-inner-declarations](https://eslint.org/docs/rules/no-inner-declarations) +- 2.5.2 `mandatory` 不要在块中使用函数声明。eslint: [no-inner-declarations](https://eslint.org/docs/rules/no-inner-declarations) 在非函数块(如 `if`、`while` 等)中,不要使用函数声明: @@ -1483,7 +1483,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 test(); // => test ``` -- 2.5.3【参考】使用函数表达式替代函数声明。 +- 2.5.3 `referenced` 使用函数表达式替代函数声明。 这样可以保证函数不能在定义前被调用。 @@ -1511,7 +1511,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 2.5.4【强制】使用箭头函数代替匿名函数。eslint: [prefer-arrow-callback](https://eslint.org/docs/rules/prefer-arrow-callback) +- 2.5.4 `mandatory` 使用箭头函数代替匿名函数。eslint: [prefer-arrow-callback](https://eslint.org/docs/rules/prefer-arrow-callback) ES6 提供的箭头函数可以解决 `this` 指向的问题,而且语法更简洁。 @@ -1529,7 +1529,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }); ``` -- 2.5.5【推荐】箭头函数编码风格。eslint: [arrow-parens](https://eslint.org/docs/rules/arrow-parens) [arrow-body-style](https://eslint.org/docs/rules/arrow-body-style) +- 2.5.5 `recommended` 箭头函数编码风格。eslint: [arrow-parens](https://eslint.org/docs/rules/arrow-parens) [arrow-body-style](https://eslint.org/docs/rules/arrow-body-style) 箭头函数参数的小括号、函数体的大括号在某些时候可以省略,这可能导致风格的不统一,因此需要规范其编码风格: @@ -1606,7 +1606,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 [1, 2, 3].map((x) => x * x); ``` -- 2.5.6【强制】不要将函数参数命名为 arguments。 +- 2.5.6 `mandatory` 不要将函数参数命名为 arguments。 这会覆盖掉函数作用域中的 `arguments` 对象。 @@ -1622,7 +1622,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.5.7【强制】不要使用 arguments 对象。eslint: [prefer-rest-params](https://eslint.org/docs/rules/prefer-rest-params) +- 2.5.7 `mandatory` 不要使用 arguments 对象。eslint: [prefer-rest-params](https://eslint.org/docs/rules/prefer-rest-params) 不要使用 `arguments` 对象,使用剩余参数操作符 `...` 代替。 @@ -1643,7 +1643,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 foo(1, 2, 3, 4); // => [3, 4] ``` -- 2.5.8【推荐】使用默认参数语法。 +- 2.5.8 `recommended` 使用默认参数语法。 ES6 中引入了默认参数语法,相比之前为参数赋默认值的方法更加简洁、可读性更好。重新对参数赋值是不推荐的行为,且当参数的布尔类型转换结果是 `false` 时可能会错误地被赋予默认值。 @@ -1663,7 +1663,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.5.9【推荐】有默认值的函数参数需要放到参数列表的最后。 +- 2.5.9 `recommended` 有默认值的函数参数需要放到参数列表的最后。 否则你将无法享受到默认参数的便利,只能通过传 `undefined` 触发参数使用默认值。 @@ -1682,7 +1682,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const x = multiply(42); // => 42 ``` -- 2.5.10【推荐】不要修改函数参数。eslint: [no-param-reassign](https://eslint.org/docs/rules/no-param-reassign) +- 2.5.10 `recommended` 不要修改函数参数。eslint: [no-param-reassign](https://eslint.org/docs/rules/no-param-reassign) 不要修改引用类型的参数,这可能导致作为入参的原变量发生变化: @@ -1720,7 +1720,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.5.11【强制】将立即执行函数表达式(IIFE)用小括号包裹。eslint: [wrap-iife](https://eslint.org/docs/rules/wrap-iife) +- 2.5.11 `mandatory` 将立即执行函数表达式(IIFE)用小括号包裹。eslint: [wrap-iife](https://eslint.org/docs/rules/wrap-iife) IIFE 是一个独立的执行单元,将它用小括号包裹可以更清晰的体现这点。需要提醒的是,由于 ES6 模块语法的引入,你可能不再需要使用 IIFE 了。 @@ -1730,14 +1730,14 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }()); ``` -- 2.5.12【参考】函数的复杂度不应过高。eslint: [complexity](https://eslint.org/docs/rules/complexity) +- 2.5.12 `referenced` 函数的复杂度不应过高。eslint: [complexity](https://eslint.org/docs/rules/complexity) 过高的复杂度意味着代码难以维护和测试。我们推荐函数的复杂度不要超过以下阈值: - 圈复杂度不超过 **10** - 认知复杂度不超过 **15** -- 2.5.13【参考】函数的参数不应过多。eslint: [max-params](https://eslint.org/docs/rules/max-params) +- 2.5.13 `referenced` 函数的参数不应过多。eslint: [max-params](https://eslint.org/docs/rules/max-params) 如果函数的参数过多,将不利于函数的维护和调用。这时你需要考虑是否函数做了太多的事情,是否有必要对其进行拆分。 如果必须使用过多的参数,可以考虑用对象代替参数列表: @@ -1756,7 +1756,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 doSomething({ param1: 1, param2: 2, param3: 3, param4: 4, param5: 5, param6: 6, param7: 7, param8: 8 }); ``` -- 2.5.14【强制】generator 函数内必须有 yield 语句。eslint: [require-yield](https://eslint.org/docs/rules/require-yield) +- 2.5.14 `mandatory` generator 函数内必须有 yield 语句。eslint: [require-yield](https://eslint.org/docs/rules/require-yield) 如果一个 `generator` 中没有 `yield` 语句,那么这个 `generator` 就不是必须的。 @@ -1773,7 +1773,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.5.15【参考】优先使用 JS 提供的高阶函数进行迭代运算。 +- 2.5.15 `referenced` 优先使用 JS 提供的高阶函数进行迭代运算。 需要迭代运算时,应优先使用 JS 提供的高阶函数,减少直接使用 for 循环(包括 for-in 和 for-of)。 @@ -1818,7 +1818,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.6 类 -- 2.6.1【推荐】使用 class 语句声明类,而不是使用 prototype。 +- 2.6.1 `recommended` 使用 class 语句声明类,而不是使用 prototype。 `class` 语句是 ES6 中引入的用于声明类的语法糖,更加简洁易维护。 @@ -1842,7 +1842,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.6.2【推荐】使用 extends 语句进行类的继承。 +- 2.6.2 `recommended` 使用 extends 语句进行类的继承。 `extends` 是用于原型继承的内建方法,不会破坏 `instanceof`。 @@ -1865,7 +1865,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.6.3【强制】避免不必要的 constructor。 +- 2.6.3 `mandatory` 避免不必要的 constructor。 ES6 class 会提供一个默认的 `constructor`,空 `constructor` 或者只调用父类的 `constructor` 是不必要的。eslint: [no-useless-constructor](https://eslint.org/docs/rules/no-useless-constructor) @@ -1904,7 +1904,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.6.4【强制】正确地使用 super 方法。eslint: [constructor-super](https://eslint.org/docs/rules/constructor-super) [no-this-before-super](https://eslint.org/docs/rules/no-this-before-super) +- 2.6.4 `mandatory` 正确地使用 super 方法。eslint: [constructor-super](https://eslint.org/docs/rules/constructor-super) [no-this-before-super](https://eslint.org/docs/rules/no-this-before-super) - 子类的 `constructor` 中必须使用 `super()`,且必须在 `this` 和 `super` 关键词前调用 - 非子类的 `constructor` 中不能使用 `super()` @@ -1949,7 +1949,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.6.5【强制】避免重复的类成员命名。eslint: [no-dupe-class-members](https://eslint.org/docs/rules/no-dupe-class-members) +- 2.6.5 `mandatory` 避免重复的类成员命名。eslint: [no-dupe-class-members](https://eslint.org/docs/rules/no-dupe-class-members) 重复的类成员声明最终生效的将是最后一个: @@ -1970,7 +1970,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.7 模块 -- 2.7.1【推荐】使用 ES6 modules 而非其他非标准的模块系统。eslint: [import/module-systems](https://github.com/benmosher/eslint-plugin-import#module-systems) +- 2.7.1 `recommended` 使用 ES6 modules 而非其他非标准的模块系统。eslint: [import/module-systems](https://github.com/benmosher/eslint-plugin-import#module-systems) 使用 ES6 modules (`import`/`export`),而不是其他非标准的模块系统,如 CommonJS、AMD、CMD。 @@ -1986,7 +1986,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 export default Component; ``` -- 2.7.2【强制】不要用多个 import 引入同一模块。eslint: [import/no-duplicates](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-duplicates.md) +- 2.7.2 `mandatory` 不要用多个 import 引入同一模块。eslint: [import/no-duplicates](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-duplicates.md) 多条 `import` 语句引入了同一模块会降低可维护性,你需要将它们合成一条语句。 @@ -1999,7 +1999,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 import React, { Component } from 'react'; ``` -- 2.7.3【强制】import 语句需要放到模块的最上方。eslint: [import/first](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/first.md) +- 2.7.3 `mandatory` import 语句需要放到模块的最上方。eslint: [import/first](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/first.md) 由于 `import` 语句会被声明提升,将它们放到模块的最上方以防止异常行为。 @@ -2019,7 +2019,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 bar.init(); ``` -- 2.7.4【强制】禁止 default import 的名字跟文件内的其他 export 命名相同。eslint: [import/no-named-as-default](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-named-as-default.md) +- 2.7.4 `mandatory` 禁止 default import 的名字跟文件内的其他 export 命名相同。eslint: [import/no-named-as-default](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-named-as-default.md) ```js // foo.js @@ -2033,11 +2033,11 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 import foo from './foo.js'; ``` -- 2.7.5【强制】禁止引用自身。eslint: [import/no-self-import](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-self-import.md) +- 2.7.5 `mandatory` 禁止引用自身。eslint: [import/no-self-import](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-self-import.md) -- 2.7.6【强制】禁止循环引用。eslint: [import/no-cycle](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-cycle.md) +- 2.7.6 `mandatory` 禁止循环引用。eslint: [import/no-cycle](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-cycle.md) -- 2.7.7【推荐】不要在 default export 上使用一个已导出的名称作为属性。eslint: [import/no-named-as-default-member](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-named-as-default-member.md) +- 2.7.7 `recommended` 不要在 default export 上使用一个已导出的名称作为属性。eslint: [import/no-named-as-default-member](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-named-as-default-member.md) ```js // foo.js @@ -2053,7 +2053,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 import foo, { bar } from './foo.js'; ``` -- 2.7.8【推荐】在模块导入之后保留一个空行。eslint: [import/newline-after-import](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/newline-after-import.md) +- 2.7.8 `recommended` 在模块导入之后保留一个空行。eslint: [import/newline-after-import](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/newline-after-import.md) ```js // bad @@ -2066,7 +2066,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const FOO = 'FOO' ``` -- 2.7.9【参考】import 语句的排序。eslint: [import/order](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/order.md) +- 2.7.9 `referenced` import 语句的排序。eslint: [import/order](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/order.md) `import` 语句建议按以下规则排序: @@ -2085,7 +2085,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 import './index.scss'; ``` -- 2.7.10【参考】当模块内只有一个 export 时,使用 default export。eslint: [import/prefer-default-export](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/prefer-default-export.md) +- 2.7.10 `referenced` 当模块内只有一个 export 时,使用 default export。eslint: [import/prefer-default-export](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/prefer-default-export.md) 我们也建议文件内只包含一个 export,这有利于代码的可维护性。 @@ -2097,7 +2097,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 export default function foo() {} ``` -- 2.7.11【参考】不要在 import 时直接 export。 +- 2.7.11 `referenced` 不要在 import 时直接 export。 虽然一行代码更简洁,但这不利于代码的可读性和一致性。 @@ -2112,13 +2112,13 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ``` -- 2.7.12【参考】模块开发者选择EMS和CJS时,需要判断运行时环境:如果你的模块是只面向浏览器的则选择ESM;如果你的模块是只面向Node.js的则选择CJS,并且确定遵循[CJS命名空间规则](https://nodejs.org/api/esm.html#esm_commonjs_namespaces);如果你的模块是2者都要兼容的,则ESM和CJS都要支持。 +- 2.7.12 `referenced` 模块开发者选择EMS和CJS时,需要判断运行时环境:如果你的模块是只面向浏览器的则选择ESM;如果你的模块是只面向Node.js的则选择CJS,并且确定遵循[CJS命名空间规则](https://nodejs.org/api/esm.html#esm_commonjs_namespaces);如果你的模块是2者都要兼容的,则ESM和CJS都要支持。 Node.js的模块,历史上Node.js遵循的是CommonJS,因此ES6 Module会有比较严重的兼容性问题。暂时没有特别好的解法,只能在Node.js中跟进运行时环境,判断使用模块标准。[讨论issue](https://github.com/nodejs/node/issues/33954) ### 2.8 操作符 -- 2.8.1【推荐】使用严格相等运算符。eslint: [eqeqeq](https://eslint.org/docs/rules/eqeqeq) +- 2.8.1 `recommended` 使用严格相等运算符。eslint: [eqeqeq](https://eslint.org/docs/rules/eqeqeq) 非严格相等运算符(`==` 和 `!=`)会在比较前将被比较值转换为相同类型,对于不熟悉 JS 语言特性的人来说,这可能造成不小的隐患。[了解更多](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness) @@ -2138,7 +2138,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.8.2【强制】不要使用一元自增自减运算符。eslint: [no-plusplus](https://eslint.org/docs/rules/no-plusplus) +- 2.8.2 `mandatory` 不要使用一元自增自减运算符。eslint: [no-plusplus](https://eslint.org/docs/rules/no-plusplus) 不要使用一元自增自减运算符(`++` 和 `--`),除非在 `for` 循环条件中。 @@ -2157,7 +2157,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ``` -- 2.8.3【强制】不要使用 void 运算符。eslint: [no-void](https://eslint.org/docs/rules/no-void) +- 2.8.3 `mandatory` 不要使用 void 运算符。eslint: [no-void](https://eslint.org/docs/rules/no-void) 在很老版本的 JS 中,`undefined` 值是可变的,因此使用 `void` 语句一般是用来得到一个 `undefined` 值。而在新版本的 JS 中,上面的问题已不复存在。因此出于程序可读性的考虑,禁止使用 `void` 运算符。 @@ -2169,7 +2169,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const foo = undefined; ``` -- 2.8.4【强制】避免嵌套的三元表达式。eslint: [no-nested-ternary](https://eslint.org/docs/rules/no-nested-ternary) +- 2.8.4 `mandatory` 避免嵌套的三元表达式。eslint: [no-nested-ternary](https://eslint.org/docs/rules/no-nested-ternary) 嵌套的三元表达式会降低代码可读性。 @@ -2182,7 +2182,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const foo = bar ? baz : qu; ``` -- 2.8.5【强制】避免不必要的三元表达式。eslint: [no-unneeded-ternary](https://eslint.org/docs/rules/no-unneeded-ternary) +- 2.8.5 `mandatory` 避免不必要的三元表达式。eslint: [no-unneeded-ternary](https://eslint.org/docs/rules/no-unneeded-ternary) ```js // bad @@ -2196,7 +2196,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const baz = !c; ``` -- 2.8.6【强制】混合使用多种操作符时,用小括号包裹分组。eslint: [no-mixed-operators](https://eslint.org/docs/rules/no-mixed-operators) +- 2.8.6 `mandatory` 混合使用多种操作符时,用小括号包裹分组。eslint: [no-mixed-operators](https://eslint.org/docs/rules/no-mixed-operators) 这可以更清晰地表达代码意图,提高可读性。四则运算符(`+`, `-`, `*`, `/`)可以不包裹,因为大多数人熟知它们的优先级。 @@ -2229,7 +2229,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.9 控制语句 -- 2.9.1【强制】switch 语句中的 case 需要以 break 结尾。eslint: [no-fallthrough](https://eslint.org/docs/rules/no-fallthrough) +- 2.9.1 `mandatory` switch 语句中的 case 需要以 break 结尾。eslint: [no-fallthrough](https://eslint.org/docs/rules/no-fallthrough) ```js // bad @@ -2255,7 +2255,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.9.2【推荐】switch 语句需要始终包含 default 分支。eslint: [default-case](https://eslint.org/docs/rules/default-case) +- 2.9.2 `recommended` switch 语句需要始终包含 default 分支。eslint: [default-case](https://eslint.org/docs/rules/default-case) 在使用 `switch` 语句时,有时会出现因开发者忘记设置 `default` 而导致错误,因此建议总是给出 `default`。如果有意省略 `default`,请在 `switch` 语句末尾用 `// no default` 注释指明: @@ -2288,7 +2288,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.9.3【参考】switch 语句应包含至少 3 个条件分支。 +- 2.9.3 `referenced` switch 语句应包含至少 3 个条件分支。 `switch` 语句在有许多条件分支的情况下可以使代码结构更清晰。但对于只有一个或两个条件分支的情况,更适合使用 `if` 语句,`if` 语句更易于书写和阅读。 @@ -2312,7 +2312,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.9.4【参考】控制语句的嵌套层级不要过深。eslint: [max-depth](https://eslint.org/docs/rules/max-depth) +- 2.9.4 `referenced` 控制语句的嵌套层级不要过深。eslint: [max-depth](https://eslint.org/docs/rules/max-depth) 控制语句的嵌套层级不要超过 **4** 级,否则将难以阅读和维护: @@ -2336,7 +2336,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.9.5【强制】for 循环中的计数器应朝着正确方向移动。eslint: [for-direction](https://eslint.org/docs/rules/for-direction) +- 2.9.5 `mandatory` for 循环中的计数器应朝着正确方向移动。eslint: [for-direction](https://eslint.org/docs/rules/for-direction) 当 `for` 循环中更新子句的计数器朝着错误的方向移动时,循环的终止条件将永远无法达到,这会导致死循环的出现。这时要么是程序出现了错误,要么应将 `for` 循环改为 `while` 循环。 @@ -2352,7 +2352,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.9.6【推荐】for-in 循环中需要对 key 进行验证。eslint: [guard-for-in](https://eslint.org/docs/rules/guard-for-in) +- 2.9.6 `recommended` for-in 循环中需要对 key 进行验证。eslint: [guard-for-in](https://eslint.org/docs/rules/guard-for-in) 使用 `for-in` 循环时需要避免对象从原型链上继承来的属性也被遍历出来,因此保险的做法是对 key 是否是对象自身的属性进行验证: @@ -2370,7 +2370,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.9.7【参考】如果一个 if 语句的结果总是返回一个 return 语句,那么最后的 else 是不必要的。eslint: [no-else-return](https://eslint.org/docs/rules/no-else-return) +- 2.9.7 `referenced` 如果一个 if 语句的结果总是返回一个 return 语句,那么最后的 else 是不必要的。eslint: [no-else-return](https://eslint.org/docs/rules/no-else-return) ```js // bad @@ -2392,7 +2392,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.9.8【参考】条件表达式的计算结果。 +- 2.9.8 `referenced` 条件表达式的计算结果。 条件表达式(例如 `if` 语句的条件)的值为通过抽象方法 `ToBoolean` 进行强制转换所得,计算结果遵守下面的规则: @@ -2422,7 +2422,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.10 其他 -- 2.10.1【强制】禁止使用 eval。eslint: [no-eval](https://eslint.org/docs/rules/no-eval) +- 2.10.1 `mandatory` 禁止使用 eval。eslint: [no-eval](https://eslint.org/docs/rules/no-eval) `eval` 语句存在安全风险,可能导致注入攻击。 @@ -2438,7 +2438,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const value = obj[key]; ``` -- 2.10.2【强制】禁止使用 debugger。eslint: [no-debugger](https://eslint.org/docs/rules/no-debugger) +- 2.10.2 `mandatory` 禁止使用 debugger。eslint: [no-debugger](https://eslint.org/docs/rules/no-debugger) `debugger` 语句会让程序暂停,并在当前位置开启调试器。它通常在程序调试阶段使用,不应发布到线上。 @@ -2451,7 +2451,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ``` -- 2.10.3【推荐】禁止使用 alert。eslint: [no-alert](https://eslint.org/docs/rules/no-alert) +- 2.10.3 `recommended` 禁止使用 alert。eslint: [no-alert](https://eslint.org/docs/rules/no-alert) `alert` 语句会使浏览器弹出原生警告框,这可能让人感觉你的程序出错了。如果需要对用户弹出警告信息,好的做法是使用第三方的弹窗组件或自己定义警告框样式。同理,`confirm` 和 `prompt` 语句也不应被使用。 @@ -2463,7 +2463,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 Alert('Oops!'); ``` -- 2.10.4【推荐】生产环境禁止使用 console。eslint: [no-console](https://eslint.org/docs/rules/no-console) +- 2.10.4 `recommended` 生产环境禁止使用 console。eslint: [no-console](https://eslint.org/docs/rules/no-console) `console` 语句通常在调试阶段使用,发布上线前,应该去掉代码里所有的 `console` 语句。 @@ -2483,7 +2483,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 utils.log('Some debug messages..'); ``` -- 2.10.5【强制】禁止对原生对象或只读的全局对象进行赋值。eslint: [no-global-assign](https://eslint.org/docs/rules/no-global-assign) +- 2.10.5 `mandatory` 禁止对原生对象或只读的全局对象进行赋值。eslint: [no-global-assign](https://eslint.org/docs/rules/no-global-assign) JS 执行环境中会包含一些全局变量和原生对象,如浏览器环境中的 `window`,node 环境中的 `global` 、`process`,`Object`,`undefined` 等。除了像 `window` 这样的众所周知的对象,JS 还提供了数百个内置全局对象,你可能在定义全局变量时无意对它们进行了重新赋值,因此最好的做法是不要定义全局变量。 @@ -2499,7 +2499,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 > 注释的目的:提高代码的可读性,从而提高代码的可维护性 > 注释的原则:如无必要,勿增注释;如有必要,尽量详尽 -- 3.1【推荐】单行注释使用 //。 +- 3.1 `recommended` 单行注释使用 //。 注释应单独一行写在被注释对象的上方,不要追加在某条语句的后面: @@ -2552,7 +2552,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 3.2【推荐】多行注释使用 /** ... */,而不是多行的 //。 +- 3.2 `recommended` 多行注释使用 /** ... */,而不是多行的 //。 ```js // bad @@ -2576,7 +2576,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 3.3【强制】注释内容和注释符之间需要有一个空格。eslint: [spaced-comment](https://eslint.org/docs/rules/spaced-comment) +- 3.3 `mandatory` 注释内容和注释符之间需要有一个空格。eslint: [spaced-comment](https://eslint.org/docs/rules/spaced-comment) 注释内容和注释符之间需要有一个空格,以增加可读性: @@ -2612,7 +2612,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 3.4【参考】合理使用特殊注释标记。eslint: [no-warning-comments](https://eslint.org/docs/rules/no-warning-comments) +- 3.4 `referenced` 合理使用特殊注释标记。eslint: [no-warning-comments](https://eslint.org/docs/rules/no-warning-comments) 有时我们发现某个可能的 bug,但因为一些原因还没法修复;或者某个地方还有一些待完成的功能,这时我们需要使用相应的特殊标记注释来告知未来的自己或合作者。最常用的特殊标记有两种: @@ -2635,7 +2635,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 3.5【参考】文档类注释使用 jsdoc 规范。 +- 3.5 `referenced` 文档类注释使用 jsdoc 规范。 文档类注释,如函数、类、文件、事件等,推荐使用 [jsdoc](http://usejsdoc.org/) 规范或类 jsdoc 的规范。 @@ -2672,15 +2672,15 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 3.6【参考】无用的代码注释应被即时删除。 +- 3.6 `referenced` 无用的代码注释应被即时删除。 无用的注释代码会使程序变得臃肿并降低可读性,应被即时删除。你可以通过版本控制系统找回被删除的代码。 ## 4 命名 -- 4.1【参考】文件名:使用小写字母命名。考虑到部分操作系统(如 Windows, MacOS)下文件系统大小写不敏感,推荐使用 `-` 连接。例如:hello-world.js。 +- 4.1 `referenced` 文件名:使用小写字母命名。考虑到部分操作系统(如 Windows, MacOS)下文件系统大小写不敏感,推荐使用 `-` 连接。例如:hello-world.js。 -- 4.2【参考】使用小驼峰(camelCase)命名原始类型、对象、函数、实例。[camelcase](https://eslint.org/docs/rules/camelcase) +- 4.2 `referenced` 使用小驼峰(camelCase)命名原始类型、对象、函数、实例。[camelcase](https://eslint.org/docs/rules/camelcase) ```js // bad @@ -2694,7 +2694,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 function thisIsMyFunction() {} ``` -- 4.3【强制】使用大驼峰(PascalCase)命名类和构造函数。eslint: [new-cap](https://eslint.org/docs/rules/new-cap) +- 4.3 `mandatory` 使用大驼峰(PascalCase)命名类和构造函数。eslint: [new-cap](https://eslint.org/docs/rules/new-cap) ```js // bad @@ -2718,7 +2718,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }); ``` -- 4.4【参考】全部大写字母&单词间用下划线分割的命名模式(UPPERCASE_VARIABLES)。 +- 4.4 `referenced` 全部大写字母&单词间用下划线分割的命名模式(UPPERCASE_VARIABLES)。 全大写字母、单词间使用下划线分割的命名模式(UPPERCASE_VARIABLES),仅用于命名常量,且该常量需同时满足如下条件: @@ -2752,7 +2752,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 4.5【参考】模块相关的命名规范。 +- 4.5 `referenced` 模块相关的命名规范。 使用小驼峰(camelCase)命名 `export` 的函数: @@ -2776,7 +2776,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 export default AnObject; ``` -- 4.6【参考】命名不要以下划线开头或结尾。eslint: [no-underscore-dangle](https://eslint.org/docs/rules/no-underscore-dangle) +- 4.6 `referenced` 命名不要以下划线开头或结尾。eslint: [no-underscore-dangle](https://eslint.org/docs/rules/no-underscore-dangle) JS 没有私有属性或私有方法的概念,这样的命名可能会让人误解。 @@ -2794,7 +2794,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 这个章节是为还在使用 ES5 及之前版本 JS 的同学准备。因为本规约以 ES6 编写,你可以通过阅读本章节来了解 ES5 中有哪些需要额外注意的地方。 -- 5.1【推荐】ES5 中的变量声明。 +- 5.1 `recommended` ES5 中的变量声明。 使用 `var` 进行声明: @@ -2838,7 +2838,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 console.log(foo); // => foo ``` -- 5.2【强制】对于逗号分隔的多行结构,不要加上最后一个行末逗号。eslint: [comma-dangle](https://eslint.org/docs/rules/comma-dangle) +- 5.2 `mandatory` 对于逗号分隔的多行结构,不要加上最后一个行末逗号。eslint: [comma-dangle](https://eslint.org/docs/rules/comma-dangle) 这样做会在 IE6/7 和 IE9 怪异模式下引起问题。另外,多余的逗号在某些 ES3 的实现里会增加数组的长度。 @@ -2856,7 +2856,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 5.3【参考】使用 Array 的 slice 方法进行数组复制和类数组对象转换。 +- 5.3 `referenced` 使用 Array 的 slice 方法进行数组复制和类数组对象转换。 数组复制: @@ -2882,7 +2882,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 5.4【推荐】不要使用保留字作为对象的属性名。 +- 5.4 `recommended` 不要使用保留字作为对象的属性名。 不要使用[保留字](http://es5.github.io/#x7.6.1)作为对象的属性名,它们在 IE8 中不工作 diff --git a/docs/coding/javascript.zh.md b/docs/coding/javascript.zh.md index 7fdbc95..e13cc02 100644 --- a/docs/coding/javascript.zh.md +++ b/docs/coding/javascript.zh.md @@ -17,7 +17,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 1.1 缩进 -- 1.1.1【强制】使用 2 个空格缩进。eslint: [indent](https://eslint.org/docs/rules/indent) +- 1.1.1 `强制` 使用 2 个空格缩进。eslint: [indent](https://eslint.org/docs/rules/indent) 统一使用 2 个空格缩进,不要使用 4 个空格或 tab 缩进: @@ -35,7 +35,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 1.2 分号 -- 1.2.1【强制】使用分号。eslint: [semi](https://eslint.org/docs/rules/semi) +- 1.2.1 `强制` 使用分号。eslint: [semi](https://eslint.org/docs/rules/semi) 统一以分号结束语句,可以避免 JS 引擎自动分号插入机制的怪异行为,在语义上也更加明确。 @@ -80,7 +80,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 1.3 逗号 -- 1.3.1【强制】对于逗号分隔的多行结构,不使用行首逗号。eslint: [comma-style](https://eslint.org/docs/rules/comma-style) +- 1.3.1 `强制` 对于逗号分隔的多行结构,不使用行首逗号。eslint: [comma-style](https://eslint.org/docs/rules/comma-style) ```js // bad @@ -112,7 +112,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 1.3.2【强制】对于逗号分隔的多行结构,始终加上最后一个逗号。eslint: [comma-dangle](https://eslint.org/docs/rules/comma-dangle) +- 1.3.2 `强制` 对于逗号分隔的多行结构,始终加上最后一个逗号。eslint: [comma-dangle](https://eslint.org/docs/rules/comma-dangle) 这样可以使增删行更加容易,也会使 git diffs 更清晰。Babel 等编译器会在编译后的代码里帮我们去掉最后额外的逗号,因此不必担心在旧浏览器中的问题。 @@ -199,7 +199,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 > 术语解释:**块(block)** 可以理解为类、函数、控制语句等由大括号 `{}` 分隔的代码块状结构,由一对大括号界定,用于组合若干条语句 [了解更多](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/block) -- 1.4.1【推荐】始终使用大括号包裹代码块。eslint: [curly](https://eslint.org/docs/rules/curly) [nonblock-statement-body-position](https://eslint.org/docs/rules/nonblock-statement-body-position) +- 1.4.1 `推荐` 始终使用大括号包裹代码块。eslint: [curly](https://eslint.org/docs/rules/curly) [nonblock-statement-body-position](https://eslint.org/docs/rules/nonblock-statement-body-position) 多行代码块必须用大括号包裹: @@ -234,7 +234,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 #### 1.4.2 大括号换行风格 -- 1.4.2.1【强制】对于非空代码块,采用 Egyptian Brackets 风格。eslint: [brace-style](https://eslint.org/docs/rules/brace-style) +- 1.4.2.1 `强制` 对于非空代码块,采用 Egyptian Brackets 风格。eslint: [brace-style](https://eslint.org/docs/rules/brace-style) 对于非空的代码块,大括号的换行方式采用 [Egyptian Brackets](https://blog.codinghorror.com/new-programming-jargon/) 风格,具体规则如下: @@ -261,7 +261,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 1.4.2.2【参考】对于空代码块,可以将大括号直接闭合。 +- 1.4.2.2 `参考` 对于空代码块,可以将大括号直接闭合。 对于空的代码块,且不在类似 `if..else..` 或 `try..catch..finally..` 的多块结构中时,可以立即将大括号闭合: @@ -300,7 +300,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 1.4.3【强制】不要使用空代码块。eslint: [no-empty](https://eslint.org/docs/rules/no-empty) +- 1.4.3 `强制` 不要使用空代码块。eslint: [no-empty](https://eslint.org/docs/rules/no-empty) 不要让代码中出现空代码块,这会使阅读者感到困惑。如果必须使用空块,需在块内写明注释。 @@ -323,7 +323,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 合理并一致地使用空格有助于提升代码的可读性和可维护性。具体来说,我们采用如下的空格风格: -- 1.5.1【强制】空格风格。eslint: [space-before-blocks](https://eslint.org/docs/rules/space-before-blocks) [keyword-spacing](https://eslint.org/docs/rules/keyword-spacing) [space-in-parens](https://eslint.org/docs/rules/space-in-parens) [array-bracket-spacing](https://eslint.org/docs/rules/array-bracket-spacing) [object-curly-spacing](https://eslint.org/docs/rules/object-curly-spacing) [space-infix-ops](https://eslint.org/docs/rules/space-infix-ops) [key-spacing](https://eslint.org/docs/rules/key-spacing) +- 1.5.1 `强制` 空格风格。eslint: [space-before-blocks](https://eslint.org/docs/rules/space-before-blocks) [keyword-spacing](https://eslint.org/docs/rules/keyword-spacing) [space-in-parens](https://eslint.org/docs/rules/space-in-parens) [array-bracket-spacing](https://eslint.org/docs/rules/array-bracket-spacing) [object-curly-spacing](https://eslint.org/docs/rules/object-curly-spacing) [space-infix-ops](https://eslint.org/docs/rules/space-infix-ops) [key-spacing](https://eslint.org/docs/rules/key-spacing) 块的左大括号 `{` 前有一个空格: @@ -473,7 +473,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 1.6 空行 -- 1.6.1【推荐】在文件末尾保留一行空行。eslint: [eol-last](https://eslint.org/docs/rules/eol-last) +- 1.6.1 `推荐` 在文件末尾保留一行空行。eslint: [eol-last](https://eslint.org/docs/rules/eol-last) 在非空文件中保留拖尾换行是一种常见的 UNIX 风格。它的好处同输出文件到终端一样,方便在串联和追加文件时不会打断 shell 的提示。 @@ -498,7 +498,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ``` -- 1.6.2【强制】块的开始和结束不能是空行。eslint: [padded-blocks](https://eslint.org/docs/rules/padded-blocks) +- 1.6.2 `强制` 块的开始和结束不能是空行。eslint: [padded-blocks](https://eslint.org/docs/rules/padded-blocks) ```js // bad @@ -530,7 +530,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 1.6.3【参考】在块末和新语句间插入一个空行。 +- 1.6.3 `参考` 在块末和新语句间插入一个空行。 ```js // bad @@ -569,7 +569,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 1.7 最大字符数和最大行数 -- 1.7.1【推荐】单行最大字符数:100。eslint: [max-len](https://eslint.org/docs/rules/max-len) +- 1.7.1 `推荐` 单行最大字符数:100。eslint: [max-len](https://eslint.org/docs/rules/max-len) 过长的单行代码不易阅读和维护,需要进行合理换行。 @@ -603,11 +603,11 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 .fail(() => console.log('You have failed this city.')); ``` -- 1.7.2【参考】文件最大行数:1000。eslint: [max-lines](https://eslint.org/docs/rules/max-lines) +- 1.7.2 `参考` 文件最大行数:1000。eslint: [max-lines](https://eslint.org/docs/rules/max-lines) 过长的文件不易阅读和维护,最好对其进行拆分。 -- 1.7.3【参考】函数最大行数:80。eslint: [max-lines-per-function](https://eslint.org/docs/rules/max-lines-per-function) +- 1.7.3 `参考` 函数最大行数:80。eslint: [max-lines-per-function](https://eslint.org/docs/rules/max-lines-per-function) 过长的函数不易阅读和维护,最好对其进行拆分。 @@ -615,7 +615,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.1 变量声明 -- 2.1.1【强制】使用 const 或 let 声明变量。eslint: [no-var](https://eslint.org/docs/rules/no-var) [no-undef](https://eslint.org/docs/rules/no-undef) +- 2.1.1 `强制` 使用 const 或 let 声明变量。eslint: [no-var](https://eslint.org/docs/rules/no-var) [no-undef](https://eslint.org/docs/rules/no-undef) 从 ES6 开始,可以使用 `let` 和 `const` 关键字在块级作用域下声明变量。块级作用域在很多其他编程语言中都有使用,这样声明的变量不会污染全局命名空间。 @@ -641,7 +641,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const foo = 'foo'; ``` -- 2.1.2【强制】正确地使用 const 和 let。eslint: [prefer-const](https://eslint.org/docs/rules/prefer-const) +- 2.1.2 `强制` 正确地使用 const 和 let。eslint: [prefer-const](https://eslint.org/docs/rules/prefer-const) 声明变量时,应优先使用 `const`,只有当变量会被重新赋值时才使用 `let`: @@ -675,7 +675,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 obj.name = 'bar'; ``` -- 2.1.3【强制】一条声明语句声明一个变量。eslint: [one-var](https://eslint.org/docs/rules/one-var) +- 2.1.3 `强制` 一条声明语句声明一个变量。eslint: [one-var](https://eslint.org/docs/rules/one-var) 这样做更易于追加新的声明语句(你不需要总去把最后的 `;` 改成 `,` 了),也更易于进行单步调试。 @@ -689,7 +689,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const bar = 2; ``` -- 2.1.4【强制】声明的变量必须被使用。eslint: [no-unused-vars](https://eslint.org/docs/rules/no-unused-vars) +- 2.1.4 `强制` 声明的变量必须被使用。eslint: [no-unused-vars](https://eslint.org/docs/rules/no-unused-vars) 声明而未使用的变量、表达式可能带来潜在的问题,也会给维护者造成困扰,应将它们删除。 @@ -723,7 +723,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.1.5【强制】不要在声明前就使用变量。eslint: [no-use-before-define](https://eslint.org/docs/rules/no-use-before-define) +- 2.1.5 `强制` 不要在声明前就使用变量。eslint: [no-use-before-define](https://eslint.org/docs/rules/no-use-before-define) 在 ES5 中,由于 `var` 的声明提升作用,变量可以在声明前使用,但这样做可能给人带来疑惑和隐患,所以不要在声明前就使用变量: @@ -749,7 +749,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 console.log(foo); // => foo ``` -- 2.1.6【参考】哪里使用,哪里声明。 +- 2.1.6 `参考` 哪里使用,哪里声明。 在变量被使用前再进行声明,而不是统一在块开始处进行声明。 @@ -787,7 +787,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.1.7【强制】变量不要与外层作用域已存在的变量同名。eslint: [no-shadow](https://eslint.org/docs/rules/no-shadow) +- 2.1.7 `强制` 变量不要与外层作用域已存在的变量同名。eslint: [no-shadow](https://eslint.org/docs/rules/no-shadow) 如果变量与外层已存在变量同名,会降低可读性,也会导致内层作用域无法读取外层作用域的同名变量。 @@ -808,7 +808,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.1.8【强制】不要重复声明变量和函数。eslint: [no-redeclare](https://eslint.org/docs/rules/no-redeclare) +- 2.1.8 `强制` 不要重复声明变量和函数。eslint: [no-redeclare](https://eslint.org/docs/rules/no-redeclare) 在 ES5 中,尽管使用 `var` 重复声明不会报错,但这样做会令人疑惑,降低程序的可维护性。同理,函数的声明也不要与已存在的变量和函数重名: @@ -866,7 +866,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 myFunc('bar'); // => 'bar' ``` -- 2.1.9【强制】禁止连续赋值。eslint: [no-multi-assign](https://eslint.org/docs/rules/no-multi-assign) +- 2.1.9 `强制` 禁止连续赋值。eslint: [no-multi-assign](https://eslint.org/docs/rules/no-multi-assign) 变量的连续赋值让人难以阅读和理解,并且可能导致意想不到的结果(如产生全局变量)。 @@ -892,7 +892,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 console.log(c); // throws ReferenceError ``` -- 2.1.10【参考】将 let 和 const 分别归类。 +- 2.1.10 `参考` 将 let 和 const 分别归类。 将 `let` 和 `const` 归类写在一起,可以提高代码整洁性。此外,如果你想按变量的含义排序分组也是允许的。 @@ -916,7 +916,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 > JS的数据类型包括 7 种原始类型(primitive type),即 Boolean, Null, Undefined, Number, String, Symbol (ES6 新定义), BigInt(ES11新定义),以及 Object 类型,[了解更多](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures)。这个章节主要介绍原始类型相关的规约。 -- 2.2.1【强制】不要使用 new Number/String/Boolean。eslint: [no-new-wrappers](https://eslint.org/docs/rules/no-new-wrappers) +- 2.2.1 `强制` 不要使用 new Number/String/Boolean。eslint: [no-new-wrappers](https://eslint.org/docs/rules/no-new-wrappers) 使用 new Number/String//Boolean 声明不会有任何好处,还会导致变量成为 `object` 类型,可能引起 bug。 @@ -942,7 +942,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.2.2【推荐】类型转换。 +- 2.2.2 `推荐` 类型转换。 【数字】使用 `Number()` 或 `parseInt()` : @@ -988,7 +988,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const hasAge = !!age; ``` -- 2.2.3【推荐】使用 parseInt() 方法时总是带上基数。eslint: [radix](https://eslint.org/docs/rules/radix) +- 2.2.3 `推荐` 使用 parseInt() 方法时总是带上基数。eslint: [radix](https://eslint.org/docs/rules/radix) `parseInt` 方法的第一个参数是待转换的字符串,第二个参数是转换基数。当第二个参数省略时,`parseInt` 会根据第一个参数自动判断基数: @@ -1008,7 +1008,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 parseInt("071", 10); // => 71 ``` -- 2.2.4【强制】避免不必要的布尔类型转换。eslint: [no-extra-boolean-cast](https://eslint.org/docs/rules/no-extra-boolean-cast) +- 2.2.4 `强制` 避免不必要的布尔类型转换。eslint: [no-extra-boolean-cast](https://eslint.org/docs/rules/no-extra-boolean-cast) 在 `if` 等条件语句中,将表达式的结果强制转换成布尔值是多余的: @@ -1038,7 +1038,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 #### 2.2.5 字符串 -- 2.2.5.1【强制】字符串优先使用单引号。eslint: [quotes](https://eslint.org/docs/rules/quotes) +- 2.2.5.1 `强制` 字符串优先使用单引号。eslint: [quotes](https://eslint.org/docs/rules/quotes) ```js // bad @@ -1049,7 +1049,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const name = 'tod'; ``` -- 2.2.5.2【推荐】使用模板字符串替代字符串拼接。eslint: [prefer-template](https://eslint.org/docs/rules/prefer-template) +- 2.2.5.2 `推荐` 使用模板字符串替代字符串拼接。eslint: [prefer-template](https://eslint.org/docs/rules/prefer-template) 模板字符串让代码更简洁,可读性更强 @@ -1065,7 +1065,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.2.5.3【强制】禁止不必要的转义字符。[no-useless-escape](https://eslint.org/docs/rules/no-useless-escape) +- 2.2.5.3 `强制` 禁止不必要的转义字符。[no-useless-escape](https://eslint.org/docs/rules/no-useless-escape) 转义字符会大大降低代码的可读性,因此尽量不要滥用它们。 @@ -1080,7 +1080,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.3 数组 -- 2.3.1【强制】使用字面量创建数组。eslint: [no-array-constructor](https://eslint.org/docs/rules/no-array-constructor) +- 2.3.1 `强制` 使用字面量创建数组。eslint: [no-array-constructor](https://eslint.org/docs/rules/no-array-constructor) 不要使用 `new Array()` 和 `Array()` 创建数组,除非为了构造某一长度的空数组。 @@ -1094,7 +1094,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const b = new Array(500); // 构造长度为 500 的空数组 ``` -- 2.3.2【强制】某些数组方法的回调函数中必须包含 return 语句。eslint: [array-callback-return](https://eslint.org/docs/rules/array-callback-return) +- 2.3.2 `强制` 某些数组方法的回调函数中必须包含 return 语句。eslint: [array-callback-return](https://eslint.org/docs/rules/array-callback-return) 以下数组方法:`map`, `filter`, `from `, `every`, `find`, `findIndex`, `reduce`, `reduceRight`, `some`, `sort` 的回调函数中必须包含 `return` 语句,否则可能会产生误用或错误。 @@ -1135,7 +1135,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }, {}); ``` -- 2.3.3【推荐】使用扩展运算符 ... 处理数组。 +- 2.3.3 `推荐` 使用扩展运算符 ... 处理数组。 ES6 提供了扩展运算符 `...`,可以简化一些数组操作。 @@ -1201,7 +1201,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const baz = Array.from(foo, bar); ``` -- 2.3.4【推荐】使用解构获取数组元素。 +- 2.3.4 `推荐` 使用解构获取数组元素。 使用 ES6 提供的解构方法获取数组元素: @@ -1234,7 +1234,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.4 对象 -- 2.4.1【强制】使用字面量创建对象。eslint: [no-new-object](https://eslint.org/docs/rules/no-new-object) +- 2.4.1 `强制` 使用字面量创建对象。eslint: [no-new-object](https://eslint.org/docs/rules/no-new-object) ```js // bad @@ -1244,7 +1244,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const obj = {}; ``` -- 2.4.2【强制】使用对象属性和方法的简写语法。eslint: [object-shorthand](https://eslint.org/docs/rules/object-shorthand) +- 2.4.2 `强制` 使用对象属性和方法的简写语法。eslint: [object-shorthand](https://eslint.org/docs/rules/object-shorthand) ES6 提供了对象属性和方法的简写语法,可以使代码更加简洁: @@ -1268,7 +1268,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 2.4.3【参考】将对象的简写属性写在一起。 +- 2.4.3 `参考` 将对象的简写属性写在一起。 将简写的属性写在一起,置于对象的起始或末尾,可以提高代码整洁性。当然,如果你出于属性的含义或其他考虑进行排序也是允许的。 @@ -1297,7 +1297,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 2.4.4【强制】对象的属性名不要用引号包裹,除非包含特殊字符。eslint: [quote-props](https://eslint.org/docs/rules/quote-props) +- 2.4.4 `强制` 对象的属性名不要用引号包裹,除非包含特殊字符。eslint: [quote-props](https://eslint.org/docs/rules/quote-props) 这样更加简洁,也有助于语法高亮和一些 JS 引擎的优化。 @@ -1319,7 +1319,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 2.4.5【强制】优先使用 . 访问对象的属性。eslint: [dot-notation](https://eslint.org/docs/rules/dot-notation) +- 2.4.5 `强制` 优先使用 . 访问对象的属性。eslint: [dot-notation](https://eslint.org/docs/rules/dot-notation) 这样可以提高代码可读性。`[]` 仅应在访问动态属性名或包含特殊字符的属性名时被使用。 @@ -1339,7 +1339,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const bar = obj['data-bar']; ``` -- 2.4.6【推荐】使用扩展运算符 ... 处理对象。 +- 2.4.6 `推荐` 使用扩展运算符 ... 处理对象。 替代 `Object.assign` 方法,来进行对象的浅拷贝: @@ -1366,7 +1366,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const { a, ...noA } = copy; // noA => { b: 2, c: 3 } ``` -- 2.4.7【推荐】使用解构获取对象属性。eslint: [prefer-destructuring](https://eslint.org/docs/rules/prefer-destructuring) +- 2.4.7 `推荐` 使用解构获取对象属性。eslint: [prefer-destructuring](https://eslint.org/docs/rules/prefer-destructuring) 获取对象的同名属性、多个属性时,使用解构让代码更简洁,也可以减少为了使用属性而创建的临时引用。 @@ -1391,7 +1391,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.4.8【参考】对象的动态属性名应直接写在字面量定义中。 +- 2.4.8 `参考` 对象的动态属性名应直接写在字面量定义中。 ES6 允许在新建对象字面量时使用表达式作为属性名,这样可以将所有属性定义在一个地方。 @@ -1415,7 +1415,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 2.4.9【强制】不要直接在对象上调用 Object.prototypes 上的方法。eslint: [no-prototype-builtins](https://eslint.org/docs/rules/no-prototype-builtins) +- 2.4.9 `强制` 不要直接在对象上调用 Object.prototypes 上的方法。eslint: [no-prototype-builtins](https://eslint.org/docs/rules/no-prototype-builtins) 不要直接在对象上调用 `Object.prototypes` 上的方法,例如 `hasOwnProperty`、`propertyIsEnumerable`、`isPrototypeOf`。 @@ -1439,7 +1439,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.5 函数 -- 2.5.1【强制】不要用 Function 构造函数创建函数。eslint: [no-new-func](https://eslint.org/docs/rules/no-new-func) +- 2.5.1 `强制` 不要用 Function 构造函数创建函数。eslint: [no-new-func](https://eslint.org/docs/rules/no-new-func) 使用 `new Function` 创建函数会像 `eval()` 方法一样执行字符串,带来安全隐患 @@ -1451,7 +1451,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const sum = (a, b) => (a + b); ``` -- 2.5.2【强制】不要在块中使用函数声明。eslint: [no-inner-declarations](https://eslint.org/docs/rules/no-inner-declarations) +- 2.5.2 `强制` 不要在块中使用函数声明。eslint: [no-inner-declarations](https://eslint.org/docs/rules/no-inner-declarations) 在非函数块(如 `if`、`while` 等)中,不要使用函数声明: @@ -1483,7 +1483,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 test(); // => test ``` -- 2.5.3【参考】使用函数表达式替代函数声明。 +- 2.5.3 `参考` 使用函数表达式替代函数声明。 这样可以保证函数不能在定义前被调用。 @@ -1511,7 +1511,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 2.5.4【强制】使用箭头函数代替匿名函数。eslint: [prefer-arrow-callback](https://eslint.org/docs/rules/prefer-arrow-callback) +- 2.5.4 `强制` 使用箭头函数代替匿名函数。eslint: [prefer-arrow-callback](https://eslint.org/docs/rules/prefer-arrow-callback) ES6 提供的箭头函数可以解决 `this` 指向的问题,而且语法更简洁。 @@ -1529,7 +1529,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }); ``` -- 2.5.5【推荐】箭头函数编码风格。eslint: [arrow-parens](https://eslint.org/docs/rules/arrow-parens) [arrow-body-style](https://eslint.org/docs/rules/arrow-body-style) +- 2.5.5 `推荐` 箭头函数编码风格。eslint: [arrow-parens](https://eslint.org/docs/rules/arrow-parens) [arrow-body-style](https://eslint.org/docs/rules/arrow-body-style) 箭头函数参数的小括号、函数体的大括号在某些时候可以省略,这可能导致风格的不统一,因此需要规范其编码风格: @@ -1606,7 +1606,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 [1, 2, 3].map((x) => x * x); ``` -- 2.5.6【强制】不要将函数参数命名为 arguments。 +- 2.5.6 `强制` 不要将函数参数命名为 arguments。 这会覆盖掉函数作用域中的 `arguments` 对象。 @@ -1622,7 +1622,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.5.7【强制】不要使用 arguments 对象。eslint: [prefer-rest-params](https://eslint.org/docs/rules/prefer-rest-params) +- 2.5.7 `强制` 不要使用 arguments 对象。eslint: [prefer-rest-params](https://eslint.org/docs/rules/prefer-rest-params) 不要使用 `arguments` 对象,使用剩余参数操作符 `...` 代替。 @@ -1643,7 +1643,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 foo(1, 2, 3, 4); // => [3, 4] ``` -- 2.5.8【推荐】使用默认参数语法。 +- 2.5.8 `推荐` 使用默认参数语法。 ES6 中引入了默认参数语法,相比之前为参数赋默认值的方法更加简洁、可读性更好。重新对参数赋值是不推荐的行为,且当参数的布尔类型转换结果是 `false` 时可能会错误地被赋予默认值。 @@ -1663,7 +1663,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.5.9【推荐】有默认值的函数参数需要放到参数列表的最后。 +- 2.5.9 `推荐` 有默认值的函数参数需要放到参数列表的最后。 否则你将无法享受到默认参数的便利,只能通过传 `undefined` 触发参数使用默认值。 @@ -1682,7 +1682,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const x = multiply(42); // => 42 ``` -- 2.5.10【推荐】不要修改函数参数。eslint: [no-param-reassign](https://eslint.org/docs/rules/no-param-reassign) +- 2.5.10 `推荐` 不要修改函数参数。eslint: [no-param-reassign](https://eslint.org/docs/rules/no-param-reassign) 不要修改引用类型的参数,这可能导致作为入参的原变量发生变化: @@ -1720,7 +1720,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.5.11【强制】将立即执行函数表达式(IIFE)用小括号包裹。eslint: [wrap-iife](https://eslint.org/docs/rules/wrap-iife) +- 2.5.11 `强制` 将立即执行函数表达式(IIFE)用小括号包裹。eslint: [wrap-iife](https://eslint.org/docs/rules/wrap-iife) IIFE 是一个独立的执行单元,将它用小括号包裹可以更清晰的体现这点。需要提醒的是,由于 ES6 模块语法的引入,你可能不再需要使用 IIFE 了。 @@ -1730,14 +1730,14 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }()); ``` -- 2.5.12【参考】函数的复杂度不应过高。eslint: [complexity](https://eslint.org/docs/rules/complexity) +- 2.5.12 `参考` 函数的复杂度不应过高。eslint: [complexity](https://eslint.org/docs/rules/complexity) 过高的复杂度意味着代码难以维护和测试。我们推荐函数的复杂度不要超过以下阈值: - 圈复杂度不超过 **10** - 认知复杂度不超过 **15** -- 2.5.13【参考】函数的参数不应过多。eslint: [max-params](https://eslint.org/docs/rules/max-params) +- 2.5.13 `参考` 函数的参数不应过多。eslint: [max-params](https://eslint.org/docs/rules/max-params) 如果函数的参数过多,将不利于函数的维护和调用。这时你需要考虑是否函数做了太多的事情,是否有必要对其进行拆分。 如果必须使用过多的参数,可以考虑用对象代替参数列表: @@ -1756,7 +1756,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 doSomething({ param1: 1, param2: 2, param3: 3, param4: 4, param5: 5, param6: 6, param7: 7, param8: 8 }); ``` -- 2.5.14【强制】generator 函数内必须有 yield 语句。eslint: [require-yield](https://eslint.org/docs/rules/require-yield) +- 2.5.14 `强制` generator 函数内必须有 yield 语句。eslint: [require-yield](https://eslint.org/docs/rules/require-yield) 如果一个 `generator` 中没有 `yield` 语句,那么这个 `generator` 就不是必须的。 @@ -1773,7 +1773,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.5.15【参考】优先使用 JS 提供的高阶函数进行迭代运算。 +- 2.5.15 `参考` 优先使用 JS 提供的高阶函数进行迭代运算。 需要迭代运算时,应优先使用 JS 提供的高阶函数,减少直接使用 for 循环(包括 for-in 和 for-of)。 @@ -1818,7 +1818,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.6 类 -- 2.6.1【推荐】使用 class 语句声明类,而不是使用 prototype。 +- 2.6.1 `推荐` 使用 class 语句声明类,而不是使用 prototype。 `class` 语句是 ES6 中引入的用于声明类的语法糖,更加简洁易维护。 @@ -1842,7 +1842,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.6.2【推荐】使用 extends 语句进行类的继承。 +- 2.6.2 `推荐` 使用 extends 语句进行类的继承。 `extends` 是用于原型继承的内建方法,不会破坏 `instanceof`。 @@ -1865,7 +1865,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.6.3【强制】避免不必要的 constructor。 +- 2.6.3 `强制` 避免不必要的 constructor。 ES6 class 会提供一个默认的 `constructor`,空 `constructor` 或者只调用父类的 `constructor` 是不必要的。eslint: [no-useless-constructor](https://eslint.org/docs/rules/no-useless-constructor) @@ -1904,7 +1904,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.6.4【强制】正确地使用 super 方法。eslint: [constructor-super](https://eslint.org/docs/rules/constructor-super) [no-this-before-super](https://eslint.org/docs/rules/no-this-before-super) +- 2.6.4 `强制` 正确地使用 super 方法。eslint: [constructor-super](https://eslint.org/docs/rules/constructor-super) [no-this-before-super](https://eslint.org/docs/rules/no-this-before-super) - 子类的 `constructor` 中必须使用 `super()`,且必须在 `this` 和 `super` 关键词前调用 - 非子类的 `constructor` 中不能使用 `super()` @@ -1949,7 +1949,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.6.5【强制】避免重复的类成员命名。eslint: [no-dupe-class-members](https://eslint.org/docs/rules/no-dupe-class-members) +- 2.6.5 `强制` 避免重复的类成员命名。eslint: [no-dupe-class-members](https://eslint.org/docs/rules/no-dupe-class-members) 重复的类成员声明最终生效的将是最后一个: @@ -1970,7 +1970,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.7 模块 -- 2.7.1【推荐】使用 ES6 modules 而非其他非标准的模块系统。eslint: [import/module-systems](https://github.com/benmosher/eslint-plugin-import#module-systems) +- 2.7.1 `推荐` 使用 ES6 modules 而非其他非标准的模块系统。eslint: [import/module-systems](https://github.com/benmosher/eslint-plugin-import#module-systems) 使用 ES6 modules (`import`/`export`),而不是其他非标准的模块系统,如 CommonJS、AMD、CMD。 @@ -1986,7 +1986,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 export default Component; ``` -- 2.7.2【强制】不要用多个 import 引入同一模块。eslint: [import/no-duplicates](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-duplicates.md) +- 2.7.2 `强制` 不要用多个 import 引入同一模块。eslint: [import/no-duplicates](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-duplicates.md) 多条 `import` 语句引入了同一模块会降低可维护性,你需要将它们合成一条语句。 @@ -1999,7 +1999,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 import React, { Component } from 'react'; ``` -- 2.7.3【强制】import 语句需要放到模块的最上方。eslint: [import/first](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/first.md) +- 2.7.3 `强制` import 语句需要放到模块的最上方。eslint: [import/first](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/first.md) 由于 `import` 语句会被声明提升,将它们放到模块的最上方以防止异常行为。 @@ -2019,7 +2019,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 bar.init(); ``` -- 2.7.4【强制】禁止 default import 的名字跟文件内的其他 export 命名相同。eslint: [import/no-named-as-default](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-named-as-default.md) +- 2.7.4 `强制` 禁止 default import 的名字跟文件内的其他 export 命名相同。eslint: [import/no-named-as-default](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-named-as-default.md) ```js // foo.js @@ -2033,11 +2033,11 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 import foo from './foo.js'; ``` -- 2.7.5【强制】禁止引用自身。eslint: [import/no-self-import](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-self-import.md) +- 2.7.5 `强制` 禁止引用自身。eslint: [import/no-self-import](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-self-import.md) -- 2.7.6【强制】禁止循环引用。eslint: [import/no-cycle](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-cycle.md) +- 2.7.6 `强制` 禁止循环引用。eslint: [import/no-cycle](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-cycle.md) -- 2.7.7【推荐】不要在 default export 上使用一个已导出的名称作为属性。eslint: [import/no-named-as-default-member](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-named-as-default-member.md) +- 2.7.7 `推荐` 不要在 default export 上使用一个已导出的名称作为属性。eslint: [import/no-named-as-default-member](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/no-named-as-default-member.md) ```js // foo.js @@ -2053,7 +2053,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 import foo, { bar } from './foo.js'; ``` -- 2.7.8【推荐】在模块导入之后保留一个空行。eslint: [import/newline-after-import](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/newline-after-import.md) +- 2.7.8 `推荐` 在模块导入之后保留一个空行。eslint: [import/newline-after-import](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/newline-after-import.md) ```js // bad @@ -2066,7 +2066,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const FOO = 'FOO' ``` -- 2.7.9【参考】import 语句的排序。eslint: [import/order](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/order.md) +- 2.7.9 `参考` import 语句的排序。eslint: [import/order](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/order.md) `import` 语句建议按以下规则排序: @@ -2085,7 +2085,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 import './index.scss'; ``` -- 2.7.10【参考】当模块内只有一个 export 时,使用 default export。eslint: [import/prefer-default-export](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/prefer-default-export.md) +- 2.7.10 `参考` 当模块内只有一个 export 时,使用 default export。eslint: [import/prefer-default-export](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/prefer-default-export.md) 我们也建议文件内只包含一个 export,这有利于代码的可维护性。 @@ -2097,7 +2097,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 export default function foo() {} ``` -- 2.7.11【参考】不要在 import 时直接 export。 +- 2.7.11 `参考` 不要在 import 时直接 export。 虽然一行代码更简洁,但这不利于代码的可读性和一致性。 @@ -2112,13 +2112,13 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ``` -- 2.7.12【参考】模块开发者选择EMS和CJS时,需要判断运行时环境:如果你的模块是只面向浏览器的则选择ESM;如果你的模块是只面向Node.js的则选择CJS,并且确定遵循[CJS命名空间规则](https://nodejs.org/api/esm.html#esm_commonjs_namespaces);如果你的模块是2者都要兼容的,则ESM和CJS都要支持。 +- 2.7.12 `参考` 模块开发者选择EMS和CJS时,需要判断运行时环境:如果你的模块是只面向浏览器的则选择ESM;如果你的模块是只面向Node.js的则选择CJS,并且确定遵循[CJS命名空间规则](https://nodejs.org/api/esm.html#esm_commonjs_namespaces);如果你的模块是2者都要兼容的,则ESM和CJS都要支持。 Node.js的模块,历史上Node.js遵循的是CommonJS,因此ES6 Module会有比较严重的兼容性问题。暂时没有特别好的解法,只能在Node.js中跟进运行时环境,判断使用模块标准。[讨论issue](https://github.com/nodejs/node/issues/33954) ### 2.8 操作符 -- 2.8.1【推荐】使用严格相等运算符。eslint: [eqeqeq](https://eslint.org/docs/rules/eqeqeq) +- 2.8.1 `推荐` 使用严格相等运算符。eslint: [eqeqeq](https://eslint.org/docs/rules/eqeqeq) 非严格相等运算符(`==` 和 `!=`)会在比较前将被比较值转换为相同类型,对于不熟悉 JS 语言特性的人来说,这可能造成不小的隐患。[了解更多](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness) @@ -2138,7 +2138,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.8.2【强制】不要使用一元自增自减运算符。eslint: [no-plusplus](https://eslint.org/docs/rules/no-plusplus) +- 2.8.2 `强制` 不要使用一元自增自减运算符。eslint: [no-plusplus](https://eslint.org/docs/rules/no-plusplus) 不要使用一元自增自减运算符(`++` 和 `--`),除非在 `for` 循环条件中。 @@ -2157,7 +2157,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ``` -- 2.8.3【强制】不要使用 void 运算符。eslint: [no-void](https://eslint.org/docs/rules/no-void) +- 2.8.3 `强制` 不要使用 void 运算符。eslint: [no-void](https://eslint.org/docs/rules/no-void) 在很老版本的 JS 中,`undefined` 值是可变的,因此使用 `void` 语句一般是用来得到一个 `undefined` 值。而在新版本的 JS 中,上面的问题已不复存在。因此出于程序可读性的考虑,禁止使用 `void` 运算符。 @@ -2169,7 +2169,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const foo = undefined; ``` -- 2.8.4【强制】避免嵌套的三元表达式。eslint: [no-nested-ternary](https://eslint.org/docs/rules/no-nested-ternary) +- 2.8.4 `强制` 避免嵌套的三元表达式。eslint: [no-nested-ternary](https://eslint.org/docs/rules/no-nested-ternary) 嵌套的三元表达式会降低代码可读性。 @@ -2182,7 +2182,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const foo = bar ? baz : qu; ``` -- 2.8.5【强制】避免不必要的三元表达式。eslint: [no-unneeded-ternary](https://eslint.org/docs/rules/no-unneeded-ternary) +- 2.8.5 `强制` 避免不必要的三元表达式。eslint: [no-unneeded-ternary](https://eslint.org/docs/rules/no-unneeded-ternary) ```js // bad @@ -2196,7 +2196,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const baz = !c; ``` -- 2.8.6【强制】混合使用多种操作符时,用小括号包裹分组。eslint: [no-mixed-operators](https://eslint.org/docs/rules/no-mixed-operators) +- 2.8.6 `强制` 混合使用多种操作符时,用小括号包裹分组。eslint: [no-mixed-operators](https://eslint.org/docs/rules/no-mixed-operators) 这可以更清晰地表达代码意图,提高可读性。四则运算符(`+`, `-`, `*`, `/`)可以不包裹,因为大多数人熟知它们的优先级。 @@ -2229,7 +2229,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.9 控制语句 -- 2.9.1【强制】switch 语句中的 case 需要以 break 结尾。eslint: [no-fallthrough](https://eslint.org/docs/rules/no-fallthrough) +- 2.9.1 `强制` switch 语句中的 case 需要以 break 结尾。eslint: [no-fallthrough](https://eslint.org/docs/rules/no-fallthrough) ```js // bad @@ -2255,7 +2255,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.9.2【推荐】switch 语句需要始终包含 default 分支。eslint: [default-case](https://eslint.org/docs/rules/default-case) +- 2.9.2 `推荐` switch 语句需要始终包含 default 分支。eslint: [default-case](https://eslint.org/docs/rules/default-case) 在使用 `switch` 语句时,有时会出现因开发者忘记设置 `default` 而导致错误,因此建议总是给出 `default`。如果有意省略 `default`,请在 `switch` 语句末尾用 `// no default` 注释指明: @@ -2288,7 +2288,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.9.3【参考】switch 语句应包含至少 3 个条件分支。 +- 2.9.3 `参考` switch 语句应包含至少 3 个条件分支。 `switch` 语句在有许多条件分支的情况下可以使代码结构更清晰。但对于只有一个或两个条件分支的情况,更适合使用 `if` 语句,`if` 语句更易于书写和阅读。 @@ -2312,7 +2312,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.9.4【参考】控制语句的嵌套层级不要过深。eslint: [max-depth](https://eslint.org/docs/rules/max-depth) +- 2.9.4 `参考` 控制语句的嵌套层级不要过深。eslint: [max-depth](https://eslint.org/docs/rules/max-depth) 控制语句的嵌套层级不要超过 **4** 级,否则将难以阅读和维护: @@ -2336,7 +2336,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.9.5【强制】for 循环中的计数器应朝着正确方向移动。eslint: [for-direction](https://eslint.org/docs/rules/for-direction) +- 2.9.5 `强制` for 循环中的计数器应朝着正确方向移动。eslint: [for-direction](https://eslint.org/docs/rules/for-direction) 当 `for` 循环中更新子句的计数器朝着错误的方向移动时,循环的终止条件将永远无法达到,这会导致死循环的出现。这时要么是程序出现了错误,要么应将 `for` 循环改为 `while` 循环。 @@ -2352,7 +2352,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.9.6【推荐】for-in 循环中需要对 key 进行验证。eslint: [guard-for-in](https://eslint.org/docs/rules/guard-for-in) +- 2.9.6 `推荐` for-in 循环中需要对 key 进行验证。eslint: [guard-for-in](https://eslint.org/docs/rules/guard-for-in) 使用 `for-in` 循环时需要避免对象从原型链上继承来的属性也被遍历出来,因此保险的做法是对 key 是否是对象自身的属性进行验证: @@ -2370,7 +2370,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.9.7【参考】如果一个 if 语句的结果总是返回一个 return 语句,那么最后的 else 是不必要的。eslint: [no-else-return](https://eslint.org/docs/rules/no-else-return) +- 2.9.7 `参考` 如果一个 if 语句的结果总是返回一个 return 语句,那么最后的 else 是不必要的。eslint: [no-else-return](https://eslint.org/docs/rules/no-else-return) ```js // bad @@ -2392,7 +2392,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 2.9.8【参考】条件表达式的计算结果。 +- 2.9.8 `参考` 条件表达式的计算结果。 条件表达式(例如 `if` 语句的条件)的值为通过抽象方法 `ToBoolean` 进行强制转换所得,计算结果遵守下面的规则: @@ -2422,7 +2422,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ### 2.10 其他 -- 2.10.1【强制】禁止使用 eval。eslint: [no-eval](https://eslint.org/docs/rules/no-eval) +- 2.10.1 `强制` 禁止使用 eval。eslint: [no-eval](https://eslint.org/docs/rules/no-eval) `eval` 语句存在安全风险,可能导致注入攻击。 @@ -2438,7 +2438,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 const value = obj[key]; ``` -- 2.10.2【强制】禁止使用 debugger。eslint: [no-debugger](https://eslint.org/docs/rules/no-debugger) +- 2.10.2 `强制` 禁止使用 debugger。eslint: [no-debugger](https://eslint.org/docs/rules/no-debugger) `debugger` 语句会让程序暂停,并在当前位置开启调试器。它通常在程序调试阶段使用,不应发布到线上。 @@ -2451,7 +2451,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 ``` -- 2.10.3【推荐】禁止使用 alert。eslint: [no-alert](https://eslint.org/docs/rules/no-alert) +- 2.10.3 `推荐` 禁止使用 alert。eslint: [no-alert](https://eslint.org/docs/rules/no-alert) `alert` 语句会使浏览器弹出原生警告框,这可能让人感觉你的程序出错了。如果需要对用户弹出警告信息,好的做法是使用第三方的弹窗组件或自己定义警告框样式。同理,`confirm` 和 `prompt` 语句也不应被使用。 @@ -2463,7 +2463,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 Alert('Oops!'); ``` -- 2.10.4【推荐】生产环境禁止使用 console。eslint: [no-console](https://eslint.org/docs/rules/no-console) +- 2.10.4 `推荐` 生产环境禁止使用 console。eslint: [no-console](https://eslint.org/docs/rules/no-console) `console` 语句通常在调试阶段使用,发布上线前,应该去掉代码里所有的 `console` 语句。 @@ -2483,7 +2483,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 utils.log('Some debug messages..'); ``` -- 2.10.5【强制】禁止对原生对象或只读的全局对象进行赋值。eslint: [no-global-assign](https://eslint.org/docs/rules/no-global-assign) +- 2.10.5 `强制` 禁止对原生对象或只读的全局对象进行赋值。eslint: [no-global-assign](https://eslint.org/docs/rules/no-global-assign) JS 执行环境中会包含一些全局变量和原生对象,如浏览器环境中的 `window`,node 环境中的 `global` 、`process`,`Object`,`undefined` 等。除了像 `window` 这样的众所周知的对象,JS 还提供了数百个内置全局对象,你可能在定义全局变量时无意对它们进行了重新赋值,因此最好的做法是不要定义全局变量。 @@ -2499,7 +2499,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 > 注释的目的:提高代码的可读性,从而提高代码的可维护性 > 注释的原则:如无必要,勿增注释;如有必要,尽量详尽 -- 3.1【推荐】单行注释使用 //。 +- 3.1 `推荐` 单行注释使用 //。 注释应单独一行写在被注释对象的上方,不要追加在某条语句的后面: @@ -2552,7 +2552,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 3.2【推荐】多行注释使用 /** ... */,而不是多行的 //。 +- 3.2 `推荐` 多行注释使用 /** ... */,而不是多行的 //。 ```js // bad @@ -2576,7 +2576,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 3.3【强制】注释内容和注释符之间需要有一个空格。eslint: [spaced-comment](https://eslint.org/docs/rules/spaced-comment) +- 3.3 `强制` 注释内容和注释符之间需要有一个空格。eslint: [spaced-comment](https://eslint.org/docs/rules/spaced-comment) 注释内容和注释符之间需要有一个空格,以增加可读性: @@ -2612,7 +2612,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 3.4【参考】合理使用特殊注释标记。eslint: [no-warning-comments](https://eslint.org/docs/rules/no-warning-comments) +- 3.4 `参考` 合理使用特殊注释标记。eslint: [no-warning-comments](https://eslint.org/docs/rules/no-warning-comments) 有时我们发现某个可能的 bug,但因为一些原因还没法修复;或者某个地方还有一些待完成的功能,这时我们需要使用相应的特殊标记注释来告知未来的自己或合作者。最常用的特殊标记有两种: @@ -2635,7 +2635,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 3.5【参考】文档类注释使用 jsdoc 规范。 +- 3.5 `参考` 文档类注释使用 jsdoc 规范。 文档类注释,如函数、类、文件、事件等,推荐使用 [jsdoc](http://usejsdoc.org/) 规范或类 jsdoc 的规范。 @@ -2672,15 +2672,15 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 3.6【参考】无用的代码注释应被即时删除。 +- 3.6 `参考` 无用的代码注释应被即时删除。 无用的注释代码会使程序变得臃肿并降低可读性,应被即时删除。你可以通过版本控制系统找回被删除的代码。 ## 4 命名 -- 4.1【参考】文件名:使用小写字母命名。考虑到部分操作系统(如 Windows, MacOS)下文件系统大小写不敏感,推荐使用 `-` 连接。例如:hello-world.js。 +- 4.1 `参考` 文件名:使用小写字母命名。考虑到部分操作系统(如 Windows, MacOS)下文件系统大小写不敏感,推荐使用 `-` 连接。例如:hello-world.js。 -- 4.2【参考】使用小驼峰(camelCase)命名原始类型、对象、函数、实例。[camelcase](https://eslint.org/docs/rules/camelcase) +- 4.2 `参考` 使用小驼峰(camelCase)命名原始类型、对象、函数、实例。[camelcase](https://eslint.org/docs/rules/camelcase) ```js // bad @@ -2694,7 +2694,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 function thisIsMyFunction() {} ``` -- 4.3【强制】使用大驼峰(PascalCase)命名类和构造函数。eslint: [new-cap](https://eslint.org/docs/rules/new-cap) +- 4.3 `强制` 使用大驼峰(PascalCase)命名类和构造函数。eslint: [new-cap](https://eslint.org/docs/rules/new-cap) ```js // bad @@ -2718,7 +2718,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }); ``` -- 4.4【参考】全部大写字母&单词间用下划线分割的命名模式(UPPERCASE_VARIABLES)。 +- 4.4 `参考` 全部大写字母&单词间用下划线分割的命名模式(UPPERCASE_VARIABLES)。 全大写字母、单词间使用下划线分割的命名模式(UPPERCASE_VARIABLES),仅用于命名常量,且该常量需同时满足如下条件: @@ -2752,7 +2752,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 4.5【参考】模块相关的命名规范。 +- 4.5 `参考` 模块相关的命名规范。 使用小驼峰(camelCase)命名 `export` 的函数: @@ -2776,7 +2776,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 export default AnObject; ``` -- 4.6【参考】命名不要以下划线开头或结尾。eslint: [no-underscore-dangle](https://eslint.org/docs/rules/no-underscore-dangle) +- 4.6 `参考` 命名不要以下划线开头或结尾。eslint: [no-underscore-dangle](https://eslint.org/docs/rules/no-underscore-dangle) JS 没有私有属性或私有方法的概念,这样的命名可能会让人误解。 @@ -2794,7 +2794,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 这个章节是为还在使用 ES5 及之前版本 JS 的同学准备。因为本规约以 ES6 编写,你可以通过阅读本章节来了解 ES5 中有哪些需要额外注意的地方。 -- 5.1【推荐】ES5 中的变量声明。 +- 5.1 `推荐` ES5 中的变量声明。 使用 `var` 进行声明: @@ -2838,7 +2838,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 console.log(foo); // => foo ``` -- 5.2【强制】对于逗号分隔的多行结构,不要加上最后一个行末逗号。eslint: [comma-dangle](https://eslint.org/docs/rules/comma-dangle) +- 5.2 `强制` 对于逗号分隔的多行结构,不要加上最后一个行末逗号。eslint: [comma-dangle](https://eslint.org/docs/rules/comma-dangle) 这样做会在 IE6/7 和 IE9 怪异模式下引起问题。另外,多余的逗号在某些 ES3 的实现里会增加数组的长度。 @@ -2856,7 +2856,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 }; ``` -- 5.3【参考】使用 Array 的 slice 方法进行数组复制和类数组对象转换。 +- 5.3 `参考` 使用 Array 的 slice 方法进行数组复制和类数组对象转换。 数组复制: @@ -2882,7 +2882,7 @@ JavaScript 编码规约主要包含编码风格、语言特性、注释、命名 } ``` -- 5.4【推荐】不要使用保留字作为对象的属性名。 +- 5.4 `推荐` 不要使用保留字作为对象的属性名。 不要使用[保留字](http://es5.github.io/#x7.6.1)作为对象的属性名,它们在 IE8 中不工作 diff --git a/docs/coding/node.md b/docs/coding/node.md index c702c7f..93af203 100644 --- a/docs/coding/node.md +++ b/docs/coding/node.md @@ -11,7 +11,7 @@ Node.js 规约主要包含编码风格、安全规约、最佳实践等几个部 ## 1 编码风格 -- 1.1【推荐】使用 Node.js 内置的全局变量。eslint: [node/prefer-global](https://github.com/mysticatea/eslint-plugin-node/blob/v11.1.0/docs/rules/prefer-global) +- 1.1 `recommended` 使用 Node.js 内置的全局变量。eslint: [node/prefer-global](https://github.com/mysticatea/eslint-plugin-node/blob/v11.1.0/docs/rules/prefer-global) ```js // bad @@ -57,7 +57,7 @@ console.log('hello'); console.log('hello'); ``` -- 1.2【推荐】使用模块内支持的 `promises` API。eslint: [node/prefer-promises](https://github.com/mysticatea/eslint-plugin-node/tree/master/docs/rules/prefer-promises) +- 1.2 `recommended` 使用模块内支持的 `promises` API。eslint: [node/prefer-promises](https://github.com/mysticatea/eslint-plugin-node/tree/master/docs/rules/prefer-promises) Node.js 从 v11.14.0 开始支持 `require('dns').promises` 和 `require('fs').promises` API。 @@ -93,7 +93,7 @@ async function readData(filePath) { } ``` -- 1.3【推荐】如无特殊需求,模块引用声明放在文件顶端,注意引用顺序。eslint: [import/order](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/order.md) +- 1.3 `recommended` 如无特殊需求,模块引用声明放在文件顶端,注意引用顺序。eslint: [import/order](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/order.md) 如无特殊需求(如动态 require),模块引用声明需要放在文件顶端。引用顺序如无特殊需求,按以下顺序来引入依赖:node 内置模块、npm 包、本地文件或其他,几类文件代码块之间各空一行,每类文件代码块中的引用顺序按照字典排序,如有解构引用情况,字典序以解构的第一个为准,解构内部按照字典排序。 @@ -139,7 +139,7 @@ import note from 'note'; import Car from './models/car'; ``` -- 1.4【推荐】抛出异常时,使用原生 `Error` 对象。eslint: [no-throw-literal](https://eslint.org/docs/rules/no-throw-literal) +- 1.4 `recommended` 抛出异常时,使用原生 `Error` 对象。eslint: [no-throw-literal](https://eslint.org/docs/rules/no-throw-literal) ```js // bad @@ -172,7 +172,7 @@ try { } ``` -1.5【推荐】线上环境尽量不要使用 `fs/child_process` 模块的 `sync` 方法,如 `fs.readFileSync()`、`cp.execSync()` 等。 +1.5 `recommended` 线上环境尽量不要使用 `fs/child_process` 模块的 `sync` 方法,如 `fs.readFileSync()`、`cp.execSync()` 等。 这样会阻塞 Node.js 应用的进程,导致不能继续处理新的请求,或当前正在处理的请求超时。推荐使用 `require('fs').promises` 方式或使用 [mz](https://www.npmjs.com/package/mz)。 @@ -201,61 +201,61 @@ async function test() { ## 2 安全规约 -- 2.1【强制】在客户端隐藏错误详情。 +- 2.1 `mandatory` 在客户端隐藏错误详情。 错误提示有可能会暴露出敏感的系统信息,容易被利用去做进一步的攻击。 -- 2.2【强制】隐藏或伪造技术栈和框架标识。 +- 2.2 `mandatory` 隐藏或伪造技术栈和框架标识。 隐藏或伪造 X-Powered-By 响应头,应用广泛的框架多有公开的漏洞,防止标识露出被恶意利用。 -- 2.3【强制】JSONP 跨域接口必须严格校验访问来源。 +- 2.3 `mandatory` JSONP 跨域接口必须严格校验访问来源。 配置域名白名单,防止通过 JSONP 接口获取到敏感信息的风险。 -- 2.4【强制】禁止使用从参数或明文 cookie 中获取的用户标识进行敏感信息查询输出。 +- 2.4 `mandatory` 禁止使用从参数或明文 cookie 中获取的用户标识进行敏感信息查询输出。 防止未授权访问/越权访问。 -- 2.5【强制】防止 SQL 注入。 +- 2.5 `mandatory` 防止 SQL 注入。 含有用户输入内容的 SQL 语句必须使用预编译模式。若用户输入无法使用预编译模式(输入为表名/字段名等内容),需要对用户输入进行转义/过滤之后再拼接到 SQL 中。 -- 2.6【推荐】定期检查过期依赖和依赖漏洞升级。 +- 2.6 `recommended` 定期检查过期依赖和依赖漏洞升级。 检测依赖,对于有漏洞或者过期的依赖要及时升级或替换。 -- 2.7【推荐】用户上传文件不允许至服务器本地,需要上传到 OSS 等服务。 +- 2.7 `recommended` 用户上传文件不允许至服务器本地,需要上传到 OSS 等服务。 任意文件上传漏洞,防止用户上传恶意文件,入侵服务器。 -- 2.8【推荐】服务端 URL 重定向需要设置白名单。 +- 2.8 `recommended` 服务端 URL 重定向需要设置白名单。 若需要对用户输入内容作为目标 URL 进行重定向,需要对其进行域名白名单校验,不允许跳转至白名单外的域名。 -- 2.9【推荐】对接口入参严格校验。 +- 2.9 `recommended` 对接口入参严格校验。 使用 [jsonschema](https://www.npmjs.com/package/jsonschema) 或 [joi](https://www.npmjs.com/package/joi) 校验入参,减少意外输入造成的程序报错或崩溃,同时也能减少脏数据形成。 ## 3 最佳实践 -- 3.1【推荐】应用不应该有状态。 +- 3.1 `recommended` 应用不应该有状态。 使用外部数据存储。保证即使结束某个应用实例也不会影响数据和服务。 -- 3.2【推荐】尽量不要用 Node.js 应用去托管前端静态文件。 +- 3.2 `recommended` 尽量不要用 Node.js 应用去托管前端静态文件。 应该把前端静态文件放到 CDN,当静态文件的访问量很大的时候,可能会阻塞其他服务的执行。 -- 3.3【推荐】把 CPU 密集型任务委托给反向代理。 +- 3.3 `recommended` 把 CPU 密集型任务委托给反向代理。 Node.js 应用不合适做 CPU 密集型任务(例如 gzip,SSL),请尽量把这类任务代理给 nginx 或其他服务。 -- 3.4【推荐】使用 `async/await`,尽量避免使用回调函数。 +- 3.4 `recommended` 使用 `async/await`,尽量避免使用回调函数。 `async/await` 可以让你的代码看起来更简洁,可以规避掉回调地狱的问题,并且使异常处理也变得清晰简单。 -- 3.5【推荐】使用 `util.promisify` 处理回调函数,使其返回 `Promise`。 +- 3.5 `recommended` 使用 `util.promisify` 处理回调函数,使其返回 `Promise`。 ```js const util = require('util'); @@ -269,9 +269,9 @@ async function callStat() { } ``` -- 3.6【推荐】使用 Node.js 原生 `Promise`,而不是三方库如 `bluebird`。 +- 3.6 `recommended` 使用 Node.js 原生 `Promise`,而不是三方库如 `bluebird`。 -- 3.7【推荐】在类方法中返回 `this` 方便链式调用。 +- 3.7 `recommended` 在类方法中返回 `this` 方便链式调用。 ```js class Jedi { @@ -292,7 +292,7 @@ luke.jump() .setHeight(20); ``` -- 3.8【推荐】使用 [阿里云 Node.js 性能平台](https://www.aliyun.com/product/nodejs) 作为应用的性能监控工具。 +- 3.8 `recommended` 使用 [阿里云 Node.js 性能平台](https://www.aliyun.com/product/nodejs) 作为应用的性能监控工具。 [阿里云 Node.js 性能平台](https://www.aliyun.com/product/nodejs)提供 Node.js 应用性能监控、管理及报警,性能快照远程截取与调优, 安全与依赖更新提示,异常日志与慢 HTTP 日志等功能,能有效帮助开发者监控和排查 Node.js 应用性能问题。 diff --git a/docs/coding/node.zh.md b/docs/coding/node.zh.md index f93f0bc..961dc50 100644 --- a/docs/coding/node.zh.md +++ b/docs/coding/node.zh.md @@ -11,7 +11,7 @@ Node.js 规约主要包含编码风格、安全规约、最佳实践等几个部 ## 1 编码风格 -- 1.1【推荐】使用 Node.js 内置的全局变量。eslint: [node/prefer-global](https://github.com/mysticatea/eslint-plugin-node/blob/v11.1.0/docs/rules/prefer-global) +- 1.1 `推荐` 使用 Node.js 内置的全局变量。eslint: [node/prefer-global](https://github.com/mysticatea/eslint-plugin-node/blob/v11.1.0/docs/rules/prefer-global) ```js // bad @@ -57,7 +57,7 @@ console.log('hello'); console.log('hello'); ``` -- 1.2【推荐】使用模块内支持的 `promises` API。eslint: [node/prefer-promises](https://github.com/mysticatea/eslint-plugin-node/tree/master/docs/rules/prefer-promises) +- 1.2 `推荐` 使用模块内支持的 `promises` API。eslint: [node/prefer-promises](https://github.com/mysticatea/eslint-plugin-node/tree/master/docs/rules/prefer-promises) Node.js 从 v11.14.0 开始支持 `require('dns').promises` 和 `require('fs').promises` API。 @@ -93,7 +93,7 @@ async function readData(filePath) { } ``` -- 1.3【推荐】如无特殊需求,模块引用声明放在文件顶端,注意引用顺序。eslint: [import/order](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/order.md) +- 1.3 `推荐` 如无特殊需求,模块引用声明放在文件顶端,注意引用顺序。eslint: [import/order](https://github.com/benmosher/eslint-plugin-import/blob/master/docs/rules/order.md) 如无特殊需求(如动态 require),模块引用声明需要放在文件顶端。引用顺序如无特殊需求,按以下顺序来引入依赖:node 内置模块、npm 包、本地文件或其他,几类文件代码块之间各空一行,每类文件代码块中的引用顺序按照字典排序,如有解构引用情况,字典序以解构的第一个为准,解构内部按照字典排序。 @@ -139,7 +139,7 @@ import note from 'note'; import Car from './models/car'; ``` -- 1.4【推荐】抛出异常时,使用原生 `Error` 对象。eslint: [no-throw-literal](https://eslint.org/docs/rules/no-throw-literal) +- 1.4 `推荐` 抛出异常时,使用原生 `Error` 对象。eslint: [no-throw-literal](https://eslint.org/docs/rules/no-throw-literal) ```js // bad @@ -172,7 +172,7 @@ try { } ``` -1.5【推荐】线上环境尽量不要使用 `fs/child_process` 模块的 `sync` 方法,如 `fs.readFileSync()`、`cp.execSync()` 等。 +1.5 `推荐` 线上环境尽量不要使用 `fs/child_process` 模块的 `sync` 方法,如 `fs.readFileSync()`、`cp.execSync()` 等。 这样会阻塞 Node.js 应用的进程,导致不能继续处理新的请求,或当前正在处理的请求超时。推荐使用 `require('fs').promises` 方式或使用 [mz](https://www.npmjs.com/package/mz)。 @@ -201,61 +201,61 @@ async function test() { ## 2 安全规约 -- 2.1【强制】在客户端隐藏错误详情。 +- 2.1 `强制` 在客户端隐藏错误详情。 错误提示有可能会暴露出敏感的系统信息,容易被利用去做进一步的攻击。 -- 2.2【强制】隐藏或伪造技术栈和框架标识。 +- 2.2 `强制` 隐藏或伪造技术栈和框架标识。 隐藏或伪造 X-Powered-By 响应头,应用广泛的框架多有公开的漏洞,防止标识露出被恶意利用。 -- 2.3【强制】JSONP 跨域接口必须严格校验访问来源。 +- 2.3 `强制` JSONP 跨域接口必须严格校验访问来源。 配置域名白名单,防止通过 JSONP 接口获取到敏感信息的风险。 -- 2.4【强制】禁止使用从参数或明文 cookie 中获取的用户标识进行敏感信息查询输出。 +- 2.4 `强制` 禁止使用从参数或明文 cookie 中获取的用户标识进行敏感信息查询输出。 防止未授权访问/越权访问。 -- 2.5【强制】防止 SQL 注入。 +- 2.5 `强制` 防止 SQL 注入。 含有用户输入内容的 SQL 语句必须使用预编译模式。若用户输入无法使用预编译模式(输入为表名/字段名等内容),需要对用户输入进行转义/过滤之后再拼接到 SQL 中。 -- 2.6【推荐】定期检查过期依赖和依赖漏洞升级。 +- 2.6 `推荐` 定期检查过期依赖和依赖漏洞升级。 检测依赖,对于有漏洞或者过期的依赖要及时升级或替换。 -- 2.7【推荐】用户上传文件不允许至服务器本地,需要上传到 OSS 等服务。 +- 2.7 `推荐` 用户上传文件不允许至服务器本地,需要上传到 OSS 等服务。 任意文件上传漏洞,防止用户上传恶意文件,入侵服务器。 -- 2.8【推荐】服务端 URL 重定向需要设置白名单。 +- 2.8 `推荐` 服务端 URL 重定向需要设置白名单。 若需要对用户输入内容作为目标 URL 进行重定向,需要对其进行域名白名单校验,不允许跳转至白名单外的域名。 -- 2.9【推荐】对接口入参严格校验。 +- 2.9 `推荐` 对接口入参严格校验。 使用 [jsonschema](https://www.npmjs.com/package/jsonschema) 或 [joi](https://www.npmjs.com/package/joi) 校验入参,减少意外输入造成的程序报错或崩溃,同时也能减少脏数据形成。 ## 3 最佳实践 -- 3.1【推荐】应用不应该有状态。 +- 3.1 `推荐` 应用不应该有状态。 使用外部数据存储。保证即使结束某个应用实例也不会影响数据和服务。 -- 3.2【推荐】尽量不要用 Node.js 应用去托管前端静态文件。 +- 3.2 `推荐` 尽量不要用 Node.js 应用去托管前端静态文件。 应该把前端静态文件放到 CDN,当静态文件的访问量很大的时候,可能会阻塞其他服务的执行。 -- 3.3【推荐】把 CPU 密集型任务委托给反向代理。 +- 3.3 `推荐` 把 CPU 密集型任务委托给反向代理。 Node.js 应用不合适做 CPU 密集型任务(例如 gzip,SSL),请尽量把这类任务代理给 nginx 或其他服务。 -- 3.4【推荐】使用 `async/await`,尽量避免使用回调函数。 +- 3.4 `推荐` 使用 `async/await`,尽量避免使用回调函数。 `async/await` 可以让你的代码看起来更简洁,可以规避掉回调地狱的问题,并且使异常处理也变得清晰简单。 -- 3.5【推荐】使用 `util.promisify` 处理回调函数,使其返回 `Promise`。 +- 3.5 `推荐` 使用 `util.promisify` 处理回调函数,使其返回 `Promise`。 ```js const util = require('util'); @@ -269,9 +269,9 @@ async function callStat() { } ``` -- 3.6【推荐】使用 Node.js 原生 `Promise`,而不是三方库如 `bluebird`。 +- 3.6 `推荐` 使用 Node.js 原生 `Promise`,而不是三方库如 `bluebird`。 -- 3.7【推荐】在类方法中返回 `this` 方便链式调用。 +- 3.7 `推荐` 在类方法中返回 `this` 方便链式调用。 ```js class Jedi { @@ -292,7 +292,7 @@ luke.jump() .setHeight(20); ``` -- 3.8【推荐】使用 [阿里云 Node.js 性能平台](https://www.aliyun.com/product/nodejs) 作为应用的性能监控工具。 +- 3.8 `推荐` 使用 [阿里云 Node.js 性能平台](https://www.aliyun.com/product/nodejs) 作为应用的性能监控工具。 [阿里云 Node.js 性能平台](https://www.aliyun.com/product/nodejs)提供 Node.js 应用性能监控、管理及报警,性能快照远程截取与调优, 安全与依赖更新提示,异常日志与慢 HTTP 日志等功能,能有效帮助开发者监控和排查 Node.js 应用性能问题。 diff --git a/docs/coding/react.md b/docs/coding/react.md index 0adbd27..d43ee7c 100644 --- a/docs/coding/react.md +++ b/docs/coding/react.md @@ -9,7 +9,7 @@ order: 5 ### 1.1 缩进 -- 1.1.1【强制】JSX 语法使用 2 个空格缩进。eslint: [react/jsx-indent](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-indent.md) [react/jsx-indent-props](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-indent-props.md) [react/jsx-closing-tag-location](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-closing-tag-location.md) +- 1.1.1 `mandatory` JSX 语法使用 2 个空格缩进。eslint: [react/jsx-indent](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-indent.md) [react/jsx-indent-props](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-indent-props.md) [react/jsx-closing-tag-location](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-closing-tag-location.md) 对于 JSX 语法,遵循与 JS 规约和 HTML 规约一致的 2 个空格缩进,不要使用 4 空格或 tab 缩进: @@ -33,7 +33,7 @@ order: 5 ### 1.2 空格 -- 1.2.1【强制】自闭合标签的斜线前有且仅有一个空格。eslint: [no-multi-spaces](https://eslint.org/docs/rules/no-multi-spaces) [react/jsx-tag-spacing](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-tag-spacing.md) +- 1.2.1 `mandatory` 自闭合标签的斜线前有且仅有一个空格。eslint: [no-multi-spaces](https://eslint.org/docs/rules/no-multi-spaces) [react/jsx-tag-spacing](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-tag-spacing.md) ```jsx static // bad @@ -50,7 +50,7 @@ order: 5 ``` -- 1.2.2【强制】JSX 行内属性之间仅有一个空格。eslint: [react/jsx-props-no-multi-spaces](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-props-no-multi-spaces.md) +- 1.2.2 `mandatory` JSX 行内属性之间仅有一个空格。eslint: [react/jsx-props-no-multi-spaces](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-props-no-multi-spaces.md) 同一行中标签和属性之间、属性之间只有一个空格。 ```jsx static @@ -63,7 +63,7 @@ order: 5 ``` -- 1.2.3【强制】JSX 属性的大括号内部两侧无空格。eslint: [react/jsx-curly-spacing](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-curly-spacing.md) +- 1.2.3 `mandatory` JSX 属性的大括号内部两侧无空格。eslint: [react/jsx-curly-spacing](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-curly-spacing.md) ```jsx static // bad @@ -73,7 +73,7 @@ order: 5 ``` -- 1.2.4【强制】不要在 JSX 属性的等号两边加空格。eslint: [jsx-equals-spacing](https://eslint.org/docs/rules/jsx-equals-spacing) +- 1.2.4 `mandatory` 不要在 JSX 属性的等号两边加空格。eslint: [jsx-equals-spacing](https://eslint.org/docs/rules/jsx-equals-spacing) ```jsx static // bad @@ -85,7 +85,7 @@ order: 5 ### 1.3 引号 -- 1.3.1【强制】JSX 属性使用双引号,不要使用单引号。eslint: [jsx-quotes](https://eslint.org/docs/rules/jsx-quotes) +- 1.3.1 `mandatory` JSX 属性使用双引号,不要使用单引号。eslint: [jsx-quotes](https://eslint.org/docs/rules/jsx-quotes) 为什么?HTML 属性通常使用双引号而不是单引号,因此 JSX 属性沿用了这种约定。 其他 JS 使用单引号。 @@ -106,7 +106,7 @@ order: 5 ### 1.4 小括号 -- 1.4.1【强制】多行的 JSX 标签需用小括号包裹。eslint: [react/jsx-wrap-multilines](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-wrap-multilines.md) +- 1.4.1 `mandatory` 多行的 JSX 标签需用小括号包裹。eslint: [react/jsx-wrap-multilines](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-wrap-multilines.md) ```jsx static // bad @@ -134,7 +134,7 @@ order: 5 ### 1.5 标签 -- 1.5.1【强制】无子元素的标签需写成自闭合标签。eslint: [react/self-closing-comp](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/self-closing-comp.md) +- 1.5.1 `mandatory` 无子元素的标签需写成自闭合标签。eslint: [react/self-closing-comp](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/self-closing-comp.md) ```jsx static // bad @@ -144,7 +144,7 @@ order: 5 ``` -- 1.5.2【强制】标签属性的换行。eslint: [react/jsx-max-props-per-line](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-max-props-per-line.md) [react/jsx-first-prop-new-line](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-first-prop-new-line.md) +- 1.5.2 `mandatory` 标签属性的换行。eslint: [react/jsx-max-props-per-line](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-max-props-per-line.md) [react/jsx-first-prop-new-line](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-first-prop-new-line.md) 对 JSX 标签属性的换行,遵循以下规则: @@ -181,7 +181,7 @@ order: 5 /> ``` -- 1.5.3【强制】标签的属性有多行时,结束标签需另起一行。eslint: [react/jsx-closing-bracket-location](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-closing-bracket-location.md) +- 1.5.3 `mandatory` 标签的属性有多行时,结束标签需另起一行。eslint: [react/jsx-closing-bracket-location](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-closing-bracket-location.md) ```jsx static // bad @@ -196,7 +196,7 @@ order: 5 /> ``` -- 1.5.4【强制】禁止在有子节点的组件或 DOM 元素中使用 dangerouslySetInnerHTML 属性。eslint: [react/no-danger-with-children](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-danger-with-children.md) +- 1.5.4 `mandatory` 禁止在有子节点的组件或 DOM 元素中使用 dangerouslySetInnerHTML 属性。eslint: [react/no-danger-with-children](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-danger-with-children.md) ```jsx static // bad @@ -222,7 +222,7 @@ order: 5 ``` -- 1.5.5【强制】HTML 自闭标签不能有子节点。eslint: [react/void-dom-elements-no-children](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/void-dom-elements-no-children.md) +- 1.5.5 `mandatory` HTML 自闭标签不能有子节点。eslint: [react/void-dom-elements-no-children](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/void-dom-elements-no-children.md) HTML 自闭标签,比如 img,br,hr,被统称为空 DOM 元素,不能给他们定义子节点。 @@ -236,7 +236,7 @@ order: 5
``` -- 1.5.6【推荐】不要使用危险属性。eslint: [react/no-danger](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-danger.md) +- 1.5.6 `recommended` 不要使用危险属性。eslint: [react/no-danger](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-danger.md) React中的危险属性是指那些已知会引起应用程序漏洞的属性。这些属性命名为 `dangerouslyXyz` 已经清楚地表明它们是危险的,应该尽量避免使用。[详细文档](https://facebook.github.io/react/tips/dangerously-set-inner-html.html) @@ -248,7 +248,7 @@ order: 5
Hello World
; ``` -- 1.5.7【强制】JSX 语句的文本节点中不要使用注释字符串(例如,以//或/ *开头)。eslint: [react/jsx-no-comment-textnodes](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-no-comment-textnodes.md) +- 1.5.7 `mandatory` JSX 语句的文本节点中不要使用注释字符串(例如,以//或/ *开头)。eslint: [react/jsx-no-comment-textnodes](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-no-comment-textnodes.md) ```jsx static // bad @@ -290,7 +290,7 @@ order: 5 }; ``` -- 1.5.8【强制】标签中禁止出现无意义字符,比如 > " } '。eslint: [react/no-unescaped-entities](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-unescaped-entities.md) +- 1.5.8 `mandatory` 标签中禁止出现无意义字符,比如 > " } '。eslint: [react/no-unescaped-entities](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-unescaped-entities.md) `>` 可用 `>` 替代 @@ -320,7 +320,7 @@ order: 5 ### 2.1 基本 -- 2.1.1【参考】使用 `JSX` 语法时,防止 `React` 变量被标记为未使用,可以使用 `@jsx` 标注来指定 `React` 之外的变量。eslint: [react/jsx-uses-react](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-uses-react.md) +- 2.1.1 `referenced` 使用 `JSX` 语法时,防止 `React` 变量被标记为未使用,可以使用 `@jsx` 标注来指定 `React` 之外的变量。eslint: [react/jsx-uses-react](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-uses-react.md) ```jsx static // bad @@ -340,7 +340,7 @@ order: 5 var Hello =
Hello {this.props.name}
; ``` -- 2.1.2【强制】不要使用未声明的组件。eslint: [react/jsx-no-undef](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-no-undef.md) [react/jsx-uses-vars](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-uses-vars.md) +- 2.1.2 `mandatory` 不要使用未声明的组件。eslint: [react/jsx-no-undef](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-no-undef.md) [react/jsx-uses-vars](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-uses-vars.md) 不允许没有引用组件就直接使用,也可能是组件名拼写错误。 @@ -354,11 +354,11 @@ order: 5 ; ``` -- 2.1.3【强制】每个文件只包含一个 React 组件。eslint: [react/no-multi-comp](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-multi-comp.md) +- 2.1.3 `mandatory` 每个文件只包含一个 React 组件。eslint: [react/no-multi-comp](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-multi-comp.md) 但是可以包含多个[函数组件](https://reactjs.org/docs/components-and-props.html#function-and-class-components)。 -- 2.1.4【强制】不要在函数组件中使用 this。eslint: [react/no-this-in-sfc](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-this-in-sfc.md) +- 2.1.4 `mandatory` 不要在函数组件中使用 this。eslint: [react/no-this-in-sfc](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-this-in-sfc.md) ```jsx static // bad @@ -380,7 +380,7 @@ order: 5 } ``` -- 2.1.5【强制】使用 ES6 class 创建组件 ,而不是 [createReactClass](https://reactjs.org/docs/react-without-es6.html) 。eslint: [react/prefer-es6-class](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/prefer-es6-class.md) +- 2.1.5 `mandatory` 使用 ES6 class 创建组件 ,而不是 [createReactClass](https://reactjs.org/docs/react-without-es6.html) 。eslint: [react/prefer-es6-class](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/prefer-es6-class.md) ```jsx static // bad @@ -400,7 +400,7 @@ order: 5 } ``` -- 2.1.6【参考】如果组件没有内部状态或 refs ,应使用函数组件,而不是类组件。eslint: [react/prefer-stateless-function](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/prefer-stateless-function.md) +- 2.1.6 `referenced` 如果组件没有内部状态或 refs ,应使用函数组件,而不是类组件。eslint: [react/prefer-stateless-function](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/prefer-stateless-function.md) ```jsx static // bad @@ -421,13 +421,13 @@ order: 5 } ``` -- 2.1.7【强制】不要使用 React.createElement,除非你不是用 JSX 文件初始化应用程序。 +- 2.1.7 `mandatory` 不要使用 React.createElement,除非你不是用 JSX 文件初始化应用程序。 ### 2.2 方法 -- 2.2.1【推荐】不要在 JSX 属性中使用 .bind()。eslint: [react/jsx-no-bind](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-no-bind.md) +- 2.2.1 `recommended` 不要在 JSX 属性中使用 .bind()。eslint: [react/jsx-no-bind](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-no-bind.md) 这不利于组件性能,每次 render 都会创建一个新的函数。 @@ -481,7 +481,7 @@ order: 5 } ``` -- 2.2.2【强制】render 方法必须要有返回值。eslint: [react/require-render-return](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/require-render-return.md) +- 2.2.2 `mandatory` render 方法必须要有返回值。eslint: [react/require-render-return](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/require-render-return.md) ```jsx static // bad @@ -495,7 +495,7 @@ order: 5 } ``` -- 2.2.3【强制】禁止使用 ReactDOM.render 的返回值。eslint: [react/no-render-return-value](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-render-return-value.md) +- 2.2.3 `mandatory` 禁止使用 ReactDOM.render 的返回值。eslint: [react/no-render-return-value](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-render-return-value.md) render()返回 ReactComponent 实例的引用。然而,应该避免使用这个返回值,因为在某些情况下,React 的未来版本中 render 方法可能会异步执行。如果需要引用 ReactComponent 实例,根元素需要增加 ref 回调。 @@ -510,7 +510,7 @@ order: 5 ReactDOM.render(, document.body, doSomethingWithInst); ``` -- 2.2.4【强制】在扩展 React.PureComponent 时禁止使用 shouldComponentUpdate。eslint: [react/no-redundant-should-component-update](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-redundant-should-component-update.md) +- 2.2.4 `mandatory` 在扩展 React.PureComponent 时禁止使用 shouldComponentUpdate。eslint: [react/no-redundant-should-component-update](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-redundant-should-component-update.md) 定义 React.PureComponent 扩展组件时使用 shouldComponentUpdate 虽然有效,但是扩展 PureComponent 变得毫无意义。 @@ -568,7 +568,7 @@ order: 5 } ``` -- 2.2.5【强制】禁止使用已经废弃的方法。eslint: [react/no-deprecated](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-deprecated.md) +- 2.2.5 `mandatory` 禁止使用已经废弃的方法。eslint: [react/no-deprecated](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-deprecated.md) 随着React版本升级,有些方法逐渐被弃用。 @@ -631,7 +631,7 @@ order: 5 } ``` -- 2.2.6【强制】不要使用 findDOMNode。eslint: [react/no-find-dom-node](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-find-dom-node.md) +- 2.2.6 `mandatory` 不要使用 findDOMNode。eslint: [react/no-find-dom-node](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-find-dom-node.md) [严格模式下已经弃用 findDOMNode](https://reactjs.org/docs/strict-mode.html#warning-about-deprecated-finddomnode-usage)。 @@ -659,7 +659,7 @@ order: 5 } ``` -- 2.2.7【强制】不要使用 componentWillMount、componentWillReceiveProps、componentWillUpdate。 +- 2.2.7 `mandatory` 不要使用 componentWillMount、componentWillReceiveProps、componentWillUpdate。 不要再使用 [componentWillMount](https://reactjs.org/docs/react-component.html#unsafe_componentwillmount) 、[componentWillReceiveProps](https://reactjs.org/docs/react-component.html#unsafe_componentwillreceiveprops)、[componentWillUpdate](https://reactjs.org/docs/react-component.html#unsafe_componentwillupdate)。使用这些生命周期方法通常会导致错误和不一致,因此React 计划在17版本删掉这些方法。 @@ -672,7 +672,7 @@ order: 5 - UNSAFE_componentWillReceiveProps() - UNSAFE_componentWillUpdate() -- 2.2.8【强制】不要在 componentWillUpdate 内改变 state 值。eslint: [react/no-will-update-set-state](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-will-update-set-state.md) +- 2.2.8 `mandatory` 不要在 componentWillUpdate 内改变 state 值。eslint: [react/no-will-update-set-state](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-will-update-set-state.md) 首先,不要再使用 componentWillUpdate,[React 未来在17版本计划删掉 componentWillUpdate](https://reactjs.org/docs/react-component.html#unsafe_componentwillupdate)。通常可以用 componentDidUpdate() 替代。使用[rename-unsafe-lifecycles codemod](https://github.com/reactjs/react-codemod#rename-unsafe-lifecycles)自动更新组件。 @@ -720,7 +720,7 @@ order: 5 ### 2.3 Props -- 2.3.1【强制】采用小驼峰风格命名 prop 。eslint: [react/no-unknown-property](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-unknown-property.md) +- 2.3.1 `mandatory` 采用小驼峰风格命名 prop 。eslint: [react/no-unknown-property](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-unknown-property.md) ```jsx static // bad @@ -736,7 +736,7 @@ order: 5 /> ``` -- 2.3.2【强制】声明的 prop 必须被使用。eslint: [react/no-unused-prop-types](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-unused-prop-types.md) +- 2.3.2 `mandatory` 声明的 prop 必须被使用。eslint: [react/no-unused-prop-types](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-unused-prop-types.md) 声明而未使用的 prop 可能带来潜在的问题,也会给维护者造成困扰,应将它们删除。 @@ -773,7 +773,7 @@ order: 5 }); ``` -- 2.3.3【参考】 props,state 优先使用解构赋值。eslint: [react/destructuring-assignment](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/destructuring-assignment.md) +- 2.3.3 `referenced` props,state 优先使用解构赋值。eslint: [react/destructuring-assignment](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/destructuring-assignment.md) ```jsx static // bad @@ -792,7 +792,7 @@ order: 5 }; ``` -- 2.3.4【强制】prop 值为 true 时,可以省略它的值。eslint: [react/jsx-boolean-value](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-boolean-value.md) +- 2.3.4 `mandatory` prop 值为 true 时,可以省略它的值。eslint: [react/jsx-boolean-value](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-boolean-value.md) ```jsx static // bad @@ -806,7 +806,7 @@ order: 5 /> ``` -- 2.3.5【推荐】prop 需要 propTypes 验证。eslint: [react/prop-types](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/prop-types.md) +- 2.3.5 `recommended` prop 需要 propTypes 验证。eslint: [react/prop-types](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/prop-types.md) PropTypes 验证接收到的数据从而提高组件的可重用性。如果其他开发传入了不正确数据类型,可以及时警告。 @@ -834,7 +834,7 @@ order: 5 }; ``` -- 2.3.6【推荐】不要使用模糊的类型检查器。eslint: [react/forbid-prop-types](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/forbid-prop-types.md) +- 2.3.6 `recommended` 不要使用模糊的类型检查器。eslint: [react/forbid-prop-types](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/forbid-prop-types.md) 不要使用模糊的类型验证,比如 any, array, object。它们可以用其他明确的类型代替。any可以替换为任意类型,array 和 object 可以分别替换为 arrayOf 和 shape。 @@ -872,7 +872,7 @@ order: 5 }; ``` -- 2.3.7【参考】属性需要指定 defaultProps,除了 isRequired 的属性。eslint: [react/require-default-props](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/require-default-props.md) +- 2.3.7 `referenced` 属性需要指定 defaultProps,除了 isRequired 的属性。eslint: [react/require-default-props](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/require-default-props.md) ```jsx static // bad @@ -897,7 +897,7 @@ order: 5 }; ``` -- 2.3.8【强制】如果属性有 isRequired 类型检查,不要在 defaultProps 内对其赋值。eslint: [react/default-props-match-prop-types](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/default-props-match-prop-types.md) +- 2.3.8 `mandatory` 如果属性有 isRequired 类型检查,不要在 defaultProps 内对其赋值。eslint: [react/default-props-match-prop-types](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/default-props-match-prop-types.md) propTypes 类型检查发生在 defaultProps 解析之后,如果在 defaultProps 赋值,isRequired 类型检查没有实际意义。 @@ -923,7 +923,7 @@ order: 5 }; ``` -- 2.3.9【推荐】不要用数组的索引值作为 map 生成元素的 key。eslint: [react/no-array-index-key](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-array-index-key.md) +- 2.3.9 `recommended` 不要用数组的索引值作为 map 生成元素的 key。eslint: [react/no-array-index-key](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-array-index-key.md) 为什么?React 使用 key 来标识哪些项已更改,已添加或已删除, [key 应该始终稳定](https://reactjs.org/docs/lists-and-keys.html#keys)。使用不稳定的 ID 是一种[反模式](https://medium.com/@robinpokorny/index-as-a-key-is-an-anti-pattern-e0349aece318),因为它不能唯一标识元素。如果数组重新排序或将元素添加到数组的开头,可能会更改索引导致不必要的渲染,对性能产生负面影响。 @@ -947,7 +947,7 @@ order: 5 ))} ``` -- 2.3.10【强制】禁止将 children 作为属性名。eslint: [react/no-children-prop](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-children-prop.md) +- 2.3.10 `mandatory` 禁止将 children 作为属性名。eslint: [react/no-children-prop](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-children-prop.md) 使用 JSX 时,`children` 应嵌套在开始和结束标签之间。不使用JSX时,应将 `children` 作为附加参数传递给 `React.createElement`。 @@ -974,7 +974,7 @@ order: 5 React.createElement("div", 'Child 1', 'Child 2') ``` -- 2.3.11【强制】不要声明重复的属性名。eslint: [react/jsx-no-duplicate-props](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-no-duplicate-props.md) +- 2.3.11 `mandatory` 不要声明重复的属性名。eslint: [react/jsx-no-duplicate-props](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-no-duplicate-props.md) ```jsx static // bad @@ -984,7 +984,7 @@ order: 5 ; ``` -- 2.3.12【强制】style 的属性值必须是一个对象。eslint: [react/style-prop-object](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/style-prop-object.md) +- 2.3.12 `mandatory` style 的属性值必须是一个对象。eslint: [react/style-prop-object](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/style-prop-object.md) ```jsx static // bad @@ -1016,7 +1016,7 @@ order: 5 React.createElement("div", { style: styles }); ``` -- 2.3.13【推荐】不要单独使用 target='_blank'。eslint: [react/jsx-no-target-blank](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-no-target-blank.md) +- 2.3.13 `recommended` 不要单独使用 target='_blank'。eslint: [react/jsx-no-target-blank](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-no-target-blank.md) `target='_blank'` 常用于在新标签页打开。使用这个属性可能造成严重的安全问题。建议和 `rel='noreferrer noopener'` 一起使用。[详见](https://mathiasbynens.github.io/rel-noopener/) ```jsx static @@ -1034,7 +1034,7 @@ order: 5 ### 2.4 State -- 2.4.1【强制】不要在 setState 中使用 this.state。eslint: [react/no-access-state-in-setstate](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-access-state-in-setstate.md) +- 2.4.1 `mandatory` 不要在 setState 中使用 this.state。eslint: [react/no-access-state-in-setstate](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-access-state-in-setstate.md) 在 setState 中使用 this.state 可能导致错误,当两个 state 在同一个批处理中时,引用的是旧状态而不是新状态。 为避免这种情况,请在回调中使用 preState 作为第一个参数。 @@ -1061,7 +1061,7 @@ order: 5 setState({ value: 2 + 1 }) ``` -- 2.4.2【强制】声明的 state 必须被使用。eslint: [react/no-unused-state](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-unused-state.md) +- 2.4.2 `mandatory` 声明的 state 必须被使用。eslint: [react/no-unused-state](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-unused-state.md) 声明而未使用的 state 可能带来潜在的问题,也会给维护者造成困扰,应将它们删除。 @@ -1105,7 +1105,7 @@ order: 5 ### 2.5 Refs -- 2.5.1【强制】使用 ref 回调函数或 React.createRef(),不要使用字符串。eslint: [react/no-string-refs](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-string-refs.md) +- 2.5.1 `mandatory` 使用 ref 回调函数或 React.createRef(),不要使用字符串。eslint: [react/no-string-refs](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-string-refs.md) ```jsx static // bad - 使用字符串 @@ -1150,7 +1150,7 @@ order: 5 ### 2.6 顺序 -- 2.6.1【参考】组件方法的排序规则。eslint: [react/sort-comp](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/sort-comp.md) +- 2.6.1 `referenced` 组件方法的排序规则。eslint: [react/sort-comp](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/sort-comp.md) React 组件内有声明周期方法、事件处理方法、render 方法等几类方法,指定这些方法按固定的顺序排序可以增强代码的一致性,方便查找和阅读。 @@ -1173,15 +1173,15 @@ order: 5 ### 2.7 Mixins -- 2.7.1【强制】不要使用 mixins。 +- 2.7.1 `mandatory` 不要使用 mixins。 Mixins 引入了隐式依赖,可能导致命名冲突,并导致滚雪球式的复杂度。大多数使用 mixin 的场景都可以通过组件、高阶组件或工具模块以更好的方式完成。 ## 3 命名 -- 3.1【强制】文件扩展名: 使用 .jsx、.tsx、.js 或 .ts 作为 React 组件的文件扩展名。eslint: [react/jsx-filename-extension](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-filename-extension.md) +- 3.1 `mandatory` 文件扩展名: 使用 .jsx、.tsx、.js 或 .ts 作为 React 组件的文件扩展名。eslint: [react/jsx-filename-extension](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-filename-extension.md) -- 3.2【强制】引用名:使用大驼峰风格命名引用的组件,使用小驼峰风格命名引用组件的实例。eslint: [react/jsx-pascal-case](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-pascal-case.md) +- 3.2 `mandatory` 引用名:使用大驼峰风格命名引用的组件,使用小驼峰风格命名引用组件的实例。eslint: [react/jsx-pascal-case](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-pascal-case.md) ```jsx static // bad @@ -1197,7 +1197,7 @@ order: 5 const reservationItem = ; ``` -- 3.3【推荐】高阶组件命名:将高阶组件名和传入组件名组合作为 displayName。 +- 3.3 `recommended` 高阶组件命名:将高阶组件名和传入组件名组合作为 displayName。 例如,高阶组件 `withFoo()` ,当传入组件 `Bar` 时,应该产生一个组件,应使用 withFoo(Bar) 作为生成组件的 displayName。 @@ -1228,7 +1228,7 @@ order: 5 ## 4 Hooks -- 4.1【强制】只在最顶层调用 Hooks,不要在循环、条件和嵌套函数中调用 Hooks。eslint: [rules of Hooks - only call Hooks at the top level](https://reactjs.org/docs/hooks-rules.html#only-call-hooks-at-the-top-level) +- 4.1 `mandatory` 只在最顶层调用 Hooks,不要在循环、条件和嵌套函数中调用 Hooks。eslint: [rules of Hooks - only call Hooks at the top level](https://reactjs.org/docs/hooks-rules.html#only-call-hooks-at-the-top-level) ```jsx static // bad - call Hooks inside conditions @@ -1258,7 +1258,7 @@ order: 5 } ``` -- 4.2【强制】Hooks 命名必须以 `use` 开头,小驼峰形式 +- 4.2 `mandatory` Hooks 命名必须以 `use` 开头,小驼峰形式 ```jsx static // bad @@ -1268,7 +1268,7 @@ order: 5 const useCustomHook = () => {} ``` -- 4.3【强制】只在 React 函数组件和自定义 Hooks 中调用 Hooks,不能在普通的 JavaScript 函数中调用 Hooks。eslint: [rules of Hooks - only call Hooks from React functions](https://reactjs.org/docs/hooks-rules.html#only-call-hooks-from-react-functions) +- 4.3 `mandatory` 只在 React 函数组件和自定义 Hooks 中调用 Hooks,不能在普通的 JavaScript 函数中调用 Hooks。eslint: [rules of Hooks - only call Hooks from React functions](https://reactjs.org/docs/hooks-rules.html#only-call-hooks-from-react-functions) ``` jsx // bad - call Hooks inside class componennt @@ -1294,7 +1294,7 @@ order: 5 } ``` -- 4.4【推荐】`useEffect` 及[类似 Hooks ](https://github.com/facebook/react/blob/3c1a7ac87c5b4903aa0de02d11bd9ec2590ad598/packages/eslint-plugin-react-hooks/src/ExhaustiveDeps.js#L1518)需要声明所有依赖。eslint: [exhaustive-deps](https://github.com/facebook/react/issues/14920) +- 4.4 `recommended` `useEffect` 及[类似 Hooks ](https://github.com/facebook/react/blob/3c1a7ac87c5b4903aa0de02d11bd9ec2590ad598/packages/eslint-plugin-react-hooks/src/ExhaustiveDeps.js#L1518)需要声明所有依赖。eslint: [exhaustive-deps](https://github.com/facebook/react/issues/14920) 此规则在某些场景下可能过于严格,并且 ESLint autofix 可能会造成一些[问题](https://github.com/facebook/react/issues/16313),因此需注意: - 升级 `eslint-plugin-react-hooks` 到 2.4.0 版本及以上,因为 [2.4.0 版本后该规则的 autofix 被默认禁用](https://github.com/facebook/react/blob/master/packages/eslint-plugin-react-hooks/CHANGELOG.md#240) @@ -1329,7 +1329,7 @@ order: 5 [这篇文档](https://developer.mozilla.org/zh-CN/docs/Learn/Accessibility/WAI-ARIA_basics)对 WAI-ARIA 规范的内容和使用做了初步介绍。 -- 5.1【推荐】img 标签应包含 alt 属性。eslint: [jsx-a11y/alt-text](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/alt-text.md) +- 5.1 `recommended` img 标签应包含 alt 属性。eslint: [jsx-a11y/alt-text](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/alt-text.md) 如果图片无需被无障碍阅读器识别(如作为 button 的 icon 使用),你可以将 `alt` 属性写为空字符串 @@ -1347,7 +1347,7 @@ order: 5 ``` -- 5.2【推荐】img 标签的 alt 属性不要使用 "image","photo","picture" 之类的关键词。eslint: [jsx-a11y/img-redundant-alt](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/img-redundant-alt.md) +- 5.2 `recommended` img 标签的 alt 属性不要使用 "image","photo","picture" 之类的关键词。eslint: [jsx-a11y/img-redundant-alt](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/img-redundant-alt.md) 屏幕阅读器已会将 `img` 元素识别成图片,再在 alt 中包含这类关键词没有意义。 @@ -1359,7 +1359,7 @@ order: 5 Me waving hello ``` -- 5.3【推荐】锚元素(即 `` 元素)必须含有内容,且内容必须对屏幕阅读器可见(这里指内容不能通过设置 `aria-hidden` 属性隐藏)。eslint: [jsx-a11y/anchor-has-content](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/master/docs/rules/anchor-has-content.md) +- 5.3 `recommended` 锚元素(即 `` 元素)必须含有内容,且内容必须对屏幕阅读器可见(这里指内容不能通过设置 `aria-hidden` 属性隐藏)。eslint: [jsx-a11y/anchor-has-content](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/master/docs/rules/anchor-has-content.md) ```jsx static // bad - empty content @@ -1373,7 +1373,7 @@ order: 5 ``` -- 5.4【推荐】禁止使用无效的 ARIA 属性,只能使用列在 [WAI-ARIA States and Properties spec](https://www.w3.org/WAI/PF/aria-1.1/states_and_properties) 中的 `aria-*` 属性。eslint: [jsx-a11y/aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/master/docs/rules/aria-props.md) +- 5.4 `recommended` 禁止使用无效的 ARIA 属性,只能使用列在 [WAI-ARIA States and Properties spec](https://www.w3.org/WAI/PF/aria-1.1/states_and_properties) 中的 `aria-*` 属性。eslint: [jsx-a11y/aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/master/docs/rules/aria-props.md) ```jsx static // bad - Labeled using incorrectly spelled aria-labeledby @@ -1385,7 +1385,7 @@ order: 5 ``` -- 5.5【推荐】ARIA 属性、状态的值必须为有效值。eslint: [jsx-a11y/aria-proptypes](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/master/docs/rules/aria-proptypes.md) +- 5.5 `recommended` ARIA 属性、状态的值必须为有效值。eslint: [jsx-a11y/aria-proptypes](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/master/docs/rules/aria-proptypes.md) ```jsx static // bad - the aria-hidden state is of type true/false foo @@ -1394,7 +1394,7 @@ order: 5 ``` -- 5.6【推荐】禁止特定元素包含 `role` 和 `aria-*` 属性。一些保留的 DOM 元素不支持设置 ARIA 角色或者属性,通常是因为这些元素是不可见的,例如 `meta, html, script, style`。eslint: [jsx-a11y/aria-unsupported-elements](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/master/docs/rules/aria-unsupported-elements.md) +- 5.6 `recommended` 禁止特定元素包含 `role` 和 `aria-*` 属性。一些保留的 DOM 元素不支持设置 ARIA 角色或者属性,通常是因为这些元素是不可见的,例如 `meta, html, script, style`。eslint: [jsx-a11y/aria-unsupported-elements](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/master/docs/rules/aria-unsupported-elements.md) ```jsx static // bad - the meta element should not be given any ARIA attributes @@ -1404,7 +1404,7 @@ order: 5 ``` -- 5.7【推荐】仅使用有效的、非抽象的 ARIA roles,[了解更多](https://www.w3.org/TR/wai-aria/#roles_categorization)。eslint: [jsx-a11y/aria-role](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/aria-role.md) +- 5.7 `recommended` 仅使用有效的、非抽象的 ARIA roles,[了解更多](https://www.w3.org/TR/wai-aria/#roles_categorization)。eslint: [jsx-a11y/aria-role](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/aria-role.md) ```jsx static // bad - not an ARIA role @@ -1417,7 +1417,7 @@ order: 5
``` -- 5.8【推荐】有 ARIA role 的元素必须也声明该 role 需要的属性,[了解更多](https://www.w3.org/TR/wai-aria/#requiredState)。eslint: [jsx-a11y/role-has-required-aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/master/docs/rules/role-has-required-aria-props.md) +- 5.8 `recommended` 有 ARIA role 的元素必须也声明该 role 需要的属性,[了解更多](https://www.w3.org/TR/wai-aria/#requiredState)。eslint: [jsx-a11y/role-has-required-aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/master/docs/rules/role-has-required-aria-props.md) ```jsx static // bad - the checkbox role requires the aria-checked state @@ -1427,7 +1427,7 @@ order: 5 ``` -- 5.9【推荐】强制拥有显式或隐式 role 的元素,只能含有该 role 支持的 `aria-*` 属性。eslint: [jsx-a11y/role-supports-aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/master/docs/rules/role-supports-aria-props.md) +- 5.9 `recommended` 强制拥有显式或隐式 role 的元素,只能含有该 role 支持的 `aria-*` 属性。eslint: [jsx-a11y/role-supports-aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/master/docs/rules/role-supports-aria-props.md) 一些元素会有隐式的 role ,譬如 `` ,会被解析为 `role="link"`。很多 ARIA 属性只能在具有特定 role 的元素上使用 @@ -1447,7 +1447,7 @@ order: 5 ``` -- 5.10【推荐】`