JavaScript Standard Style

One JavaScript Style to Rule Them All

其他语言: English, Português, Spanish, 繁體中文


本工具通过以下三种方式为你(及你的团队)节省大量时间:

无须犹豫。再也不用维护 .eslintrc, .jshintrc, or .jscsrc 。开箱即用。

安装:

npm install standard --save-dev

说了那么多,看看这个遵循了 Standard 规范的示例文件 中的代码吧。或者,这里还有一大波使用了此规范的项目 代码可供参考。

使用本规范最便捷的方式是全局安装,运行:

$ npm install standard --global

或者非全局的方式,针对某个项目进行安装:

$ npm install standard --save-dev

注意:运行以上命令的前提是已经安装了 Node.jsnpm

安装完就可以开心使用了。最简单的使用场景是检查项目内所有的 JavaScript 文件:

$ standard
Error: Use JavaScript Standard Style
  lib/torrent.js:950:11: Expected '===' and instead saw '=='.

可以跟上 glob 形式的路径参数,但记得带引号以确保 standard 工具正确解析,否则会被命令行解析。

$ standard "src/util/**/*.js" "test/**/*.js"

注意: standard 默认查找 **/*.js, **/*.jsx 所匹配到的文件。

  1. 添加配置到 package.json
{
  "name": "my-cool-package",
  "devDependencies": {
    "standard": "*"
  },
  "scripts": {
    "test": "standard && node my-tests.js"
  }
}
  1. 这样检查工作就会在运行 npm test 自动进行
$ npm test
Error: Use JavaScript Standard Style
  lib/torrent.js:950:11: Expected '===' and instead saw '=='.
  1. 从此告别在提 PR 时的代码风格的问题!

本规范特点之一是简洁。谁也不想为每个项目维护一份有成百上千行语句的代码风格配置文件。有此规范就够了。

本工具通过以下三种方式为你(及你的团队)节省大量时间:

一旦使用 standard 规范表明代码的简明性及社区的约定要高于个人的编码风格。这不一定100%适用于所有项目和多元的编程文化,但开源项目代码容易受到新手的影响。把规范讲明,严格执行对于项目的长远维护不无裨益。

我们是有群众基础的!

除公司组织外,很多个人也在项目中使用,这里就不一一罗列了。

并且 standard 在 GitHub 的代码检查类工具 展示列表中也排名第一。

首先安装 standard。剩下的就是不同编译器安装对应的插件:

通过 Package Control,安装 SublimeLinterSublimeLinter-contrib-standard

如果想要保存时自动格式化,还需安装 StandardFormat

安装 linter-js-standard

如果想要保存时自动格式化,还需安装 standard-formatter。安装 standardjs-snippets 可以获得 snippets 特性。

安装 vscode-standardjs(已经包含了自动格式化)。

安装 vscode-standardjs-snippets 以获得 JS snippets。安装 vscode-react-standard 以获得 React snippets。

安装 Syntastic 并添加如下配置到 .vimrc

let g:syntastic_javascript_checkers = ['standard']

如果想要保存时自动格式化,添加以下配置到 .vimrc

autocmd bufwritepost *.js silent !standard --fix %
set autoread

安装 Flycheck 后查看 manual 以了解如何在项目在启用。

插件中搜索 "Standard Code Style" 然后点击 "Install"。

WebStorm 最近宣布在其 IDE 中 自带 standard 规范。

但是如果你仍然想自己动手配置,那么请看此教程。此教程适用于 JetBrains 全家桶,包括 PhpStorm、IntelliJ、RubyMine 等。

必需的!如果你的项目使用了 standard 规范,可以任选一个下面的徽章放入项目中来进行展示。

[![JavaScript Style Guide](https://cdn.rawgit.com/feross/standard/master/badge.svg)](https://github.com/feross/standard)

[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)

不行。制定这套 standard 规范的目的就是让大家都不必再花时间浪费在无谓的代码风格之争上面了。关于缩进该用制表符还是空格这个问题已经争论了很久了,永远也没有答案。争论这个都可以把需求提前写完了。遵循 standard 规范,你就不用再犹豫了,毕竟不管怎样争论总归会选择一种风格的。希望大家也能在个人语义和普适价值上做一个权衡。

如果你非要自己去配置成百上千项的 ESLint 规则,那你可以直接使用 eslint-config-standard 来将个人配置包装在上层。

小贴士:选择 standard 然后保持吧。把时间留下来解决其他有意义的问题!(^____^)/

确实!这份规范不隶属于任何官方组织,所以才叫 feross/standard 而不是 ECMA/standard 嘛。

standard (标准) 一词在这里不局限于 “web 标准” :-) 。 举个例子:

当然!你可以使用 standard --fix 来纠正大部分的代码问题。

standard --fix 可以修正大部分约定俗成的问题,但有些错误(譬如忘记了错误处理)只能手动去修复了。

为了使用方便,standard 会在检测到有能够自动被修复的问题的时候,给出相应的提示 "运行 standard --fix 来自动修正一些问题"。

node_modules/coverage/vendor/*.min.jsbundle.js 这些目录,还有以 . 开头的文件(譬如 .git/)或者文件夹自动被排除在外。

.gitignore 里配置的文件也会自动排除掉。

有时你还是需要添加一些自定义的排除文件,可以在 package.json 里添加 standard.ignore 属性来配置:

"standard"{
  "ignore": [
    "**/out/",
    "/lib/select2/",
    "/lib/ckeditor/",
    "tmp.js"
  ]
}

很少的情况下你需要绕开 standard 以隐藏某些警告信息。

JavaScript Standard 代码规范底层使用的是 ESLint。所以如果你想隐藏某些警告,方法和使用 ESLint 时一样。

打印详细信息(这样你就能找到你想隐藏的警告在配置中对应的名称了):

$ standard --verbose
Error: Use JavaScript Standard Style
  routes/error.js:20:36: 'file' was used before it was defined. (no-use-before-define)

对某一行禁用所有规则

file = 'I know what I am doing' // eslint-disable-line 

或者,只禁"no-use-before-define" 这条规则:

file = 'I know what I am doing' // eslint-disable-line no-use-before-define 

或者,对多行禁用 "no-use-before-define" 这一规则:

/* eslint-disable no-use-before-define */
console.log('offending code goes here...')
console.log('offending code goes here...')
console.log('offending code goes here...')
/* eslint-enable no-use-before-define */

一些三方库(比如 mocha)会向全局暴露变量(describeit)。这些变量或方法即没有定义,也没有被 require 进来,所以 standard 会报出变量未定义的警告(这种警告通常情况下是很有用的)。这种情况下我们想对这些全局变量禁用检查。

为了让 standard 检测通过(同时也使代码更加易懂),在文件顶部添加如下配置:

/* global myVar1, myVar2 */

但如果你需要添加的文件太多,这种方式就显得繁琐了。这种情况下,运行:

$ standard --global myVar1 --global myVar2

或者在 package.json 里配置:

{
  "standard": {
    "globals": [ "myVar1", "myVar2" ]
  }
}

注意:globalglobals 效果一样

standard 支持最新的 ECMAScript 特性,ES8(ES2017),包括处于 “Stage 4” 仍在提案阶段的特性。

为了支持实验性的特性,standard 支持自定义 JavaScript 解析器。添加自定义解析器前请思考一下必要性。

从 npm 安装并使用自定义的解析器(示例:npm install babel-eslint):

$ standard --parser babel-eslint

或者将其添加到 package.json 配置中:

{
  "standard": {
    "parser": "babel-eslint"
  }
}

如果全局安装(npm install standard --global)了 standard 的话,那么请确保 babel-eslint 也用 npm install babel-eslint --global 全局安装。

同样地,想要使用一个 JS 变种之前,先考虑添加和使用它所带来的复杂度看是否值得这么去做。

standard 支付 ESLint 插件。在 standard 处理代码前,使用任何一个插件来将代码编译成合法的 JS 即可。 从 npm 安装一个自定义的解析器 (示例:npm install eslint-plugin-flowtype) 然后运行:

$ standard --plugin flowtype

或者添加到package.json:

{
  "standard": {
    "plugins": [ "flowtype" ]
  }
}

如果全局安装(npm install standard --global)了 standard 的话,那么请确保 eslint-plugin-flowtype 也用 npm install eslint-plugin-flowtype --global 全局安装。

注意:pluginplugins 等价

为了能让 mocha 在你的测试文件中工作,将以下配置添加到测试文件头部:

/* eslint-env mocha */

或者运行:

$ standard --env mocha

上面 mocha 也可以是 jasmine, qunit, phantomjs 等同类工具。这里有个来自 ESLint 的完整列表 环境配置 文档。环境中所有可用的全局变量可以这个 globals npm 包中查到。

注意: envenvs 用哪个都一样。

添加以下注释到文件头部:

/* eslint-env serviceworker */

这样可以让 standard 知道 self 是 web worker 中的全局变量(同时也让人更容易看懂)。

可以使用 standard-markdown 来检查 Markdown 里的区位码。

此外,也有 ESLint 插件可以检查 Markdown、HTML 等其他类型文件中的代码:

检查 Markdown 文件中的代码,可以用这个 ESLint 插件:

$ npm install eslint-plugin-markdown

然后运行以下命令来检查文件代码块中的代码:

$ standard --plugin markdown '**/*.md'

HTML 文件可以下面这个插件:

$ npm install eslint-plugin-html

然后运行以下命令来检查包含在 <script> 标签中的代码:

$ standard --plugin html '**/*.html'

这个问题问得好!

#!/bin/sh 
# 确保将要提交的所有 JavaScript 代码通过 standard 规范的检查  
git diff --name-only --cached --relative | grep '\.jsx\?$' | xargs standard
if [ $? -ne 0 ]; then exit 1; fi

自带的输出信息简洁原始,如果想要炫酷好看,安装 snazzy

$ npm install snazzy

然后运行:

$ standard --verbose | snazzy

还有 standard-tapstandard-jsonstandard-reporterstandard-summary 这些类似的工具。

有!

检查传入的 text。需要提供一个 opts 配置参数:

{
  cwd: '',      // 当前工作目录(默认为:process.cwd()) 
  filename: '', // 需要检查的文件的路径(可选,虽然有些 eslint 插件需要该参数) 
  fix: false,   // 是否自动修复问题 
  globals: [],  // 声明需要跳过检测的定义全局变量 
  plugins: [],  // 自定义的 eslint 插件列表 
  envs: [],     // 自定义的 eslint 环境 
  parser: ''    // 自定义的 js 解析器(例如 babel-eslint) 
}

如果 package.json 有相应配置也会自动被读取到。

完成后会调用 callback 回调并传入 Errorresults

包含结果的 results 包含如下属性:

var results = {
  results: [
    {
      filePath: '',
      messages: [
        { ruleId: '', message: '', line: 0, column: 0 }
      ],
      errorCount: 0,
      warningCount: 0,
      output: '' // fixed source code (only present with {fix: true} option) 
    }
  ],
  errorCount: 0,
  warningCount: 0
}

standard.lintText() 的同步版本。如果运行出错,会抛出异常。否则返回 results

检查以 glob 形式指定的 files 参数所匹配到的所有文件。可以传入一个 opts 配置参数:

var opts = {
  ignore: [],   // glob 形式的排除列表 (一般无须配置) 
  cwd: '',      // 当前工作目录(默认为:process.cwd()) 
  fix: false,   // 是否自动修复问题 
  globals: [],  // 声明需要跳过检测的定义全局变量 
  plugins: [],  // eslint 插件列表 
  envs: [],     // eslint 环境 
  parser: ''    // js 解析器(例如 babel-eslint) 
}

回调同上。

欢迎参与进来!逛逛 issues 或者 PRs 页面,如果发现没有找到想要的问题可以自己提一个。

来 freenode 的 #standard 频道与其他人一起聊天讨论!

以下是一些 standard 生态里比较重要的包:

还有很多 编辑器插件、一个 **使用 standard 规范开发的 npm 包的列表、还有一分非常棒的 standard 生态中所使用到的包**的列表。

MIT. Copyright (c) Feross Aboukhadijeh.