diff --git a/docs/intro.md b/docs/intro.md index 090764e..b68e983 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -121,74 +121,238 @@ input.map(function (item) { 上面的原始代码用了箭头函数，这个特性还没有得到广泛支持，Babel将其转为普通函数，就能在现有的JavaScript环境执行了。 -### 命令行环境 +### 配置文件`.babelrc` -命令行下，Babel的安装命令如下。 +Babel的配置文件是`.babelrc`，存放在项目的根目录下。使用Babel的第一步，就是配置这个文件。 -```bash -$ npm install --global babel-cli -$ npm install --save babel-preset-es2015 -``` - -然后在当前目录下，新建一个配置文件`.babelrc`。 +该文件用来设置转码规则和插件，基本格式如下。 ```javascript -// .babelrc { - "presets": ['es2015'] + "presets": [], + "plugins": [] } ``` -Babel自带一个`babel-node`命令，提供支持ES6的REPL环境。它支持Node的REPL环境的所有功能，而且可以直接运行ES6代码。 +`preset`字段设定转码规则，官方提供以下的规则集，你可以根据需要安装。 + +```bash +# ES2015转码规则 +$ npm install --save-dev babel-preset-es2015 + +# react转码规则 +$ npm install --save-dev babel-preset-react + +# ES7不同阶段语法提案的转码规则（共有4个阶段），选装一个 +$ npm install --save-dev babel-preset-stage-0 +$ npm install --save-dev babel-preset-stage-1 +$ npm install --save-dev babel-preset-stage-2 +$ npm install --save-dev babel-preset-stage-3 +``` + +然后，将这些规则加入`.babelrc`。 + +```javascript + { + "presets": [ + "es2015", + "react", + "stage-2" + ], + "plugins": [] + } +``` + +注意，以下所有Babel工具和模块的使用，都必须先写好`.babelrc`。 + +### 命令行转码`babel-cli` + +Babel提供`babel-cli`工具，用于命令行转码。 + +它的安装命令如下。 + +```bash +$ npm install --global babel-cli +``` + +它的命令行基本用法如下。 + +```bash +# 转码结果输出到标准输出 +$ babel example.js + +# 转码结果写入一个文件 +$ babel example.js --out-file compiled.js +# 或者 +$ babel example.js -o compiled.js + +# 整个目录转码 +# --out-dir 或 -d 参数指定输出目录 +$ babel src --out-dir lib +# 或者 +$ babel src -d lib + +# -s 参数生成source map文件 +$ babel src -d lib -s +``` + +上面代码是在全局环境下，进行Babel转码。但这意味着，如果项目要运行，全局环境必须有Babel，这就让项目产生了对环境的依赖，也无法支持不同项目使用不同版本的Babel。 + +一个解决办法是将`babel-cli`安装在项目之中。 + +```bash +# 安装 +$ npm install --save-dev babel-cli +``` + +然后，改写`package.json`。 + +```javascript +{ + // ... + "devDependencies": { + "babel-cli": "^6.0.0" + }, + "scripts": { + "build": "babel src -d lib" + }, +} +``` + +转码的时候，就执行下面的命令。 + +```javascript +$ npm run build +``` + +### babel-node + +`babel-cli`工具自带一个`babel-node`命令，提供一个支持ES6的REPL环境。它支持Node的REPL环境的所有功能，而且可以直接运行ES6代码。 + +它不用单独安装，而是随`babel-cli`一起安装。然后，执行`babel-node`就进入PEPL环境。 ```bash $ babel-node -> -> console.log([1,2,3].map(x => x * x)) - [ 1, 4, 9 ] -> +> (x => x * 2)(1) +2 ``` `babel-node`命令也可以直接运行ES6脚本。假定将上面的代码放入脚本文件`es6.js`。 ```bash $ babel-node es6.js -[1, 4, 9] +2 ``` -`babel`命令可以将ES6代码转为ES5代码。 +`babel-node`也可以安装在项目中。 ```bash -$ babel es6.js -"use strict"; - -console.log([1, 2, 3].map(function (x) { - return x * x; -})); +# 安装 +$ npm install --save-dev babel-cli ``` -`-o`参数将转换后的代码，从标准输出导入文件。 +然后，改写`package.json`。 + +```javascript +{ + "scripts": { + "script-name": "babel-node script.js" + } +} +``` + +上面代码中，使用`babel-node`替代`node`，这样`script.js`本身就不用做任何改变。 + +### babel-register + +`babel-register`模块改写`require`命令，为它加上一个钩子。每当使用`require`加载某个文件，就会先用Babel进行转码。 ```bash -$ babel es6.js -o es5.js -# 或者 -$ babel es6.js --out-file es5.js +$ npm install --save-dev babel-register ``` -`-d`参数用于转换整个目录。 +使用时，必须首先加载`babel-register`。 ```bash -$ babel -d build-dir source-dir +require("babel-register"); +require("./index.js"); ``` -注意，`-d`参数后面跟的是输出目录。 +然后，就不需要手动对`index.js`转码了。 -如果希望生成source map文件，则要加上`-s`参数。 +需要注意的是，`babel-register`只会对`require`命令加载的文件转码，而不会对当前文件转码。另外，由于它是实时转码，所以只适合在开发环境使用。 + +### babel-core + +如果某些代码需要调用API进行转码，就要使用`babel-core`模块。 + +安装命令如下。 ```bash -$ babel -d build-dir source-dir -s +$ npm install babel-core ``` +然后，在项目中就可以调用`babel-core`。 + +```javascript +var babel = require("babel-core"); + +// 字符串转码 +babel.transform("code();", options); +// => { code, map, ast } + +// 文件转码（异步） +babel.transformFile("filename.js", options, function(err, result) { + result; // => { code, map, ast } +}); + +// 文件转码（同步） +babel.transformFileSync("filename.js", options); +// => { code, map, ast } + +// Babel AST转码 +babel.transformFromAst(ast, code, options); +// => { code, map, ast } +``` + +配置对象`options`，可以参看官方文档[http://babeljs.io/docs/usage/options/](http://babeljs.io/docs/usage/options/)。 + +下面是一个例子。 + +```javascript +var es5Code = 'let x = n => n + 1'; +var es6Code = require('babel-core') + .transform(es5Code, { + presets: ['es2015'] + }) + .code; +// '"use strict";\n\nvar x = function x(n) {\n return n + 1;\n};' +``` + +上面代码中，`transform`方法的第一个参数是一个字符串，表示需要转换的ES5代码，第二个参数是转换的配置对象。 + +### babel-polyfill + +Babel默认只转换新的JavaScript句法（syntax），而不转换新的API，比如Iterator、Generator、Set、Maps、Proxy、Reflect、Symbol、Promise等全局对象，以及一些定义在全局对象上的方法（比如`Object.assign`）。 + +举例来说，ES6在`Array`对象上新增了`Array.from`方法。Babel就不会转换这个方法。如果想让这个方法运行，必须使用`babel-polyfill`。 + +安装命令如下。 + +```bash +$ npm install --save babel-polyfill +``` + +然后，在脚本头部，加入如下一行代码。 + +```javascript +import 'babel-polyfill'; +// 或者 +require('babel-polyfill'); +``` + +Babel默认不转码的API非常多，详细清单可以查看`babel-plugin-transform-runtime`模块的[`definitions.js`](https://github.com/babel/babel/blob/master/packages/babel-plugin-transform-runtime/src/definitions.js)文件。 + ### 浏览器环境 Babel也可以用于浏览器。但是，从Babel 6.0开始，不再直接提供浏览器版本，而是要用构建工具构建出来。如果你没有或不想使用构建工具，只有通过安装5.x版本的`babel-core`模块获取。 @@ -237,70 +401,53 @@ $ browserify script.js -o bundle.js \ } ``` -### Node环境 - -Node脚本之中，需要转换ES6脚本，可以像下面这样写。 - -先安装`babel-core`和`babel-preset-es2015`。 - -```javascript -$ npm install --save-dev babel-core babel-preset-es2015 -``` - -然后，在项目根目录下新建一个`.babelrc`文件。 - -```javascript -{ - "presets": ["es2015"] -} -``` - -然后在脚本中，调用`babel-core`的`transform`方法。 - -```javascript -var es5Code = 'let x = n => n + 1'; -var es6Code = require('babel-core') - .transform(es5Code, {presets: ['es2015']}) - .code; -// '"use strict";\n\nvar x = function x(n) {\n return n + 1;\n};' -``` - -上面代码中，`transform`方法的第一个参数是一个字符串，表示需要转换的ES5代码，第二个参数是转换的配置对象。 - -Node脚本还有一种特殊的`babel`用法，即把`babel`加载为`require`命令的一个钩子。安装`babel-core`和`babel-preset-es2015`以后，先在项目的根目录下面，设置一个配置文件`.babelrc`。 - -```javascript -// .babelrc -{ - "presets": ["es2015"] -} -``` - -然后，在你的应用的入口脚本（entry script）头部，加入下面的语句。 - -```javascript -require("babel-core/register"); -``` - -有了上面这行语句，后面所有通过`require`命令加载的后缀名为`.es6`、`.es`、`.jsx`和`.js`的脚本，都会先通过`babel`转码后再加载。 - -需要注意的是，Babel默认不会转换Iterator、Generator、Set、Maps、Proxy、Reflect、Symbol、Promise等全局对象，以及一些定义在全局对象上的方法（比如`Object.assign`）。如果你用到了这些功能，当前的运行环境又不支持。就需要安装`babel-polyfill`模块。 - -```bash -$ npm install babel-polyfill --save -``` - -然后，在所有脚本头部加上一行。 - -```javascript -require('babel-polyfill'); -// 或者 -import 'babel-polyfill'; -``` - ### 在线转换 -Babel提供一个[REPL在线编译器](https://babeljs.io/repl/)，可以在线将ES6代码转为ES5代码。转换后的代码，可以直接作为ES5代码插入网页运行 +Babel提供一个[REPL在线编译器](https://babeljs.io/repl/)，可以在线将ES6代码转为ES5代码。转换后的代码，可以直接作为ES5代码插入网页运行。 + +### 与其他工具的配合 + +许多工具需要Babel进行前置转码，这里举两个例子：ESLint和Mocha。 + +ESLint用于静态检查代码的语法和风格，安装命令如下。 + +```bash +$ npm install --save-dev eslint babel-eslint +``` + +然后，在项目根目录下，新建一个配置文件`.eslint`，在其中加入`parser`字段。 + +```javascript +{ + "parser": "babel-eslint", + "rules": { + ... + } +} +``` + +再在`package.json`之中，加入相应的`scripts`脚本。 + +```javascript + { + "name": "my-module", + "scripts": { + "lint": "eslint my-files.js" + }, + "devDependencies": { + "babel-eslint": "...", + "eslint": "..." + } + } +``` + +Mocha则是一个测试框架，如果需要执行使用ES6语法的测试脚本，可以修改`package.json`的`scripts.test`脚本如下。 + +```javascript + "test": "mocha --ui qunit --compilers js:babel-core/register" +``` + +上面命令中，`--compilers`参数指定脚本的转码器，意为后缀名为`js`的文件，都需要使用`babel-core/register`先转码。 ## Traceur转码器