Apache ECharts 是一个正在由 Apache 孵化器赞助的 Apache 开源基金会孵化的项目。

我们正在处理将本站跳转到 https://echarts.apache.org 的迁移工作。您可以现在就前往我们的 Apache 官网。

访问官网
x

代码规范

如果你想要为 ECharts 贡献代码,请遵从以下代码规范。

Apache ECharts (incubating)TM

代码规范

源文件

[强制] JavaScript源文件必须以无BOM的UTF-8编码。

缩进

[强制] 必须采用4个空格缩进,不允许以Tab制表符或2个空格代替。

[强制] switch 中的 casedefault 必须保持缩进。

// 正例
switch (variable) {
    case '1':
        // do...
        break;
    case '2':
        // do...
        break;
    default:
        // do...
}

// 反例
switch (variable) {
case '1':
    // do...
    break;
case '2':
    // do...
    break;
default:
    // do...
}

空格

[强制] 二元运算符两个操作数之间必须使用空格,但一元运算符与其操作数间不能有空格。

var a = !arr.length;
a++;
a = b + c;

[强制]{ 前必须有1个空格。

// 正例

if (condition) {
}

set('attr', {
    some: 'xxx',
    any: 'yyy'
});

function funcName() {
}


// 反例

if (condition){
}

set('attr',{
    some: 'xxx',
    any: 'yyy'
});

function funcName(){
}

[强制] if / else / for / while / function / switch / do / try / catch / finally 等关键字与括号之间都必须加一个空格。

// 正例

if (condition) {
}

while (condition) {
}

(function () {
})();


// 反例

if(condition) {
}

while(condition) {
}

(function() {
})();

[强制] 在创建对象的语句中,: 后必须加一个空格,: 前不能有空格。

// 正例
var obj = {
    a: 1,
    b: 2,
    c: 3
};

// 反例
var obj = {
    a : 1,
    b:2,
    c :3
};

[强制] 在函数声明、命名函数表达式和函数调用时,函数名称和 ( 间不能有空格。

// 正例

function funcName() {
}

var funcName = function funcName() {
};

funcName();


// 反例

function funcName () {
}

var funcName = function funcName () {
};

funcName ();

[强制] ,; 前不能有空格。

// 正例
callFunc(a, b);

// 反例
callFunc(a , b) ;

[强制] ([ 之后、 )] 之前不能有空格。

// 正例

callFunc(param1, param2, param3);

save(this.list[this.indexes[i]]);

needIncream && (variable += increament);

if (num > list.length) {
}

while (len--) {
}


// 反例

callFunc( param1, param2, param3 );

save( this.list[ this.indexes[ i ] ] );

needIncreament && ( variable += increament );

if ( num > list.length ) {
}

while ( len-- ) {
}


// 正例
var arr1 = [];
var arr2 = [1, 2, 3];
var obj1 = {};
var obj2 = {name: 'obj'};
var obj3 = {
    name: 'obj',
    age: 20,
    sex: 1
};

// 反例
var arr1 = [ ];
var arr2 = [ 1, 2, 3 ];
var obj1 = { };
var obj2 = { name: 'obj' };
var obj3 = {name: 'obj', age: 20, sex: 1};

[强制] 每行代码后不能有尾随空格。

换行

[强制] 必须在语句的结尾换行。

[强制] 单行字符数不能超过120个,超出则需要换行。

[强制] 如果需要换行,运算符必须放在新行的开头。

// 正例
if (user.isAuthenticated()
    && user.isInRole('admin')
    && user.hasAuthority('add-admin')
    || user.hasAuthority('delete-admin')
) {
    // Code
}

var result = number1 + number2 + number3
    + number4 + number5;


// 反例
if (user.isAuthenticated() &&
    user.isInRole('admin') &&
    user.hasAuthority('add-admin') ||
    user.hasAuthority('delete-admin')) {
    // Code
}

var result = number1 + number2 + number3 +
    number4 + number5;

[强制] 如果括号中的内容有多行,必须为 )]} 另开一个新行,并使新行与 ([{ 所在行的缩进相对应。

// 正例
if (product) {
    product.load();
    if (user.isAuthenticated()
        && user.isInRole('admin')
        && user.hasAuthority('add-admin')
    ) {
        sendProduct(user, product);
    }
}
var arr = [
    'candy', 'sugar'
];

// 反例
if (product) {
    product.load();
    if (user.isAuthenticated()
        && user.isInRole('admin')
        && user.hasAuthority('add-admin')) {
        sendProduct(user, product);
    }
}
var arr = [
        'candy', 'sugar'
    ];

[强制] ,; 前不能有换行。

// 正例
var obj = {
    a: 1,
    b: 2,
    c: 3
};

foo(
    aVeryVeryLongArgument,
    anotherVeryLongArgument,
    callback
);


// 反例
var obj = {
    a: 1
    , b: 2
    , c: 3
};

foo(
    aVeryVeryLongArgument
    , anotherVeryLongArgument
    , callback
);

[推荐] 建议换行和缩进遵循如下风格:

if (user.isAuthenticated()
    && user.isInRole('admin')
    && user.hasAuthority('add-admin')
) {
    // Code
}

foo(
    aVeryVeryLongArgument,
    anotherVeryLongArgument,
    callback
);

baidu.format(
    dateFormatTemplate,
    year, month, date, hour, minute, second
);

$('#items')
    .find('.selected')
    .highlight()
    .end();

var result = thisIsAVeryVeryLongCondition
    ? resultA : resultB;

var result = condition
    ? thisIsAVeryVeryLongResult
    : resultB;

[强制] 如果使用多行代码块,elsecatch 必须另开一个新行。

// 正例

if (condition) {
    // some statements;
}
else {
    // some statements;
}

try {
    // some statements;
}
catch (ex) {
    // some statements;
}


// 反例

if (condition) {
    // some statements;
} else {
    // some statements;
}

try {
    // some statements;
} catch (ex) {
    // some statements;
}

语句

[强制] 语句必须以 ; 结尾。

[强制] 如果只有一行,{} 不能被省略。

// 正例
if (condition) {
    callFunc();
}

// 反例
if (condition) callFunc();
if (condition)
    callFunc();

[强制] 函数定义的末尾不能有分号 ;

// 正例
function funcName() {
}

// 反例
function funcName() {
};

// 对于函数表达式,不能忽略分号
var funcName = function () {
};

[强制] 对象和数组的声明中不能有尾随逗号。

// 正例

var obj = {
    attr1: 'xxx',
    attr2: 'yyy'
};

var arr = [
    'xxx',
    'yyy'
];


// 反例

var obj = {
    attr1: 'xxx',
    attr2: 'yyy',
};

var arr = [
    'xxx',
    'yyy',
];

命名规约

[强制] 变量名、属性名及函数名的命名必须遵循 lowerCamelCase(小骆驼拼写法)。

var loadingModules = {};
function loadProduct() {
}

[强制] class类的命名必须遵循 UpperCamelCase (Pascal),即大骆驼拼写法(帕斯卡拼写法)。

function Element(options) {
}

[推荐] 缩略词的所有字符应当一并大写或一并小写。

function parseSVG() {
}
var svgParser;

语法特性

兼容性

[强制] ECharts的JavaScript源代码应基于 ECMAScript Language Specification Edition 3 (ES3),不能使用ES3不支持的语法特性(即不能使用ES5、ES6或更高版本的语法特性)。

但允许使用ES Module。

语法特性可以通过一些工具方法进行弥补,但不能通过修改内置JavaScript对象的原型来实现。

// 正例

import * as zrUtil from 'zrender/src/core/util';

zrUtil.each(array, function (val, index) {
    sum += val;
});

var result = zrUtil.map(array, function (val) {
    return parse(val);
});

var pos = zrUtil.indexOf(array, val);

var obj2 = zrUtil.extend({}, obj1);

function Element() {
    // ...
}


// 反例

array.forEach(function (val, index) {
    sum += val;
});

let result = array.map(function (val) {
    return parse(val);
});

const pos = array.indexOf(val);

var obj2 = Object.assign({}, obj1);

class Element {
    // ...
}

String.prototype.trim = function () {
};

变量

[强制] 变量必须用 var 声明,且一个 var 不能同时声明多个变量。

// 正例
var name = 'MyName';
var hangModules = [];
var missModules = [];
var visited = {};

// 反例
name = 'MyName';
var hangModules = [],
    missModules = [],
    visited = {};

条件判断

[强制] 对于相等运算符,== 只能用于检查是否为 null 或者 undefined,其余情况必须使用 ===

// 正例
if (age === 30) {
    // ...
}
if (type == null) {
    // ...
}

// 反例
if (age == 30) {
    // ......
}

[推荐] 建议使用 xxx == null 来判断 nullundefined

[推荐] 尽量让 nullundefined 的含义相同。也就是说,不要让用户或开发者去区分变量是 null 还是 undefined

[推荐] 函数表达式或者函数声明不应该放在循环体中。

// 正例
function clicker() {
    // ......
}

for (var i = 0, len = elements.length; i < len; i++) {
    var element = elements[i];
    addListener(element, 'click', clicker);
}


// 反例
for (var i = 0, len = elements.length; i < len; i++) {
    var element = elements[i];
    addListener(element, 'click', function () {});
}

类型转换

[推荐] 建议使用 + '' 将值转为字符串。

// 正例
num + '';

// 反例
new String(num);
num.toString();
String(num);

[推荐] 建议使用 + 将值转为数值。

// 正例
+str;

// 反例
Number(str);

[强制] 在使用 parseInt 时,必须传入第二个参数。

// 正例
parseInt(str, 10);

// 反例
parseInt(str);

字符串,对象,数组

[强制] 必须使用 ' 而不是 " 定义字符串。

[强制] 必须使用对象字面量 {} 来创建简单对象。

// 正例
var obj = {};

// 反例
var obj = new Object();

[强制] 如果一个对象字面量的所有属性都不需要引号,引号必须省略。如果需要加引号,须使用 ' 而不是 "

// 正例
var info = {
    name: 'someone',
    age: 28
};

// 反例
var info = {
    'name': 'someone',
    'age': 28
};
var info2 = {
    "age": 40
};

[强制] 禁止修改内置对象的原型。

// 禁止
String.prototype.trim = function () {
};

[推荐] 尽可能使用 . 而不是 [] 访问对象的属性。

[推荐] 使用 for ... in ... 时,应当注意使用 hasOwnProperty 以防 Object 的原型在某些运行时环境中被添加一些额外属性的情况。

var newInfo = {};
for (var key in info) {
    if (info.hasOwnProperty(key)) {
        newInfo[key] = info[key];
    }
}

[强制] 除非需要创建指定长度的数组,否则必须使用数组字面量 [] 创建数组。

// 正例
var arr = [];
var arr2 = new Array(1e4);

// 反例
var arr = new Array();

[强制] 不要使用 for in 语句对数组进行遍历。

其他

[强制] 不要使用 evalwith。允许使用new Function