JavaScript编码规范

JavaScript已经成为开发基于WordPress的应用程序(主题和插件)以及WordPress核心的关键组件。格式化和造型JavaScript代码需要标准来保持与WordPress标准提供的核心PHP,HTML和CSS代码相同的代码一致性。任何代码库中的所有代码应该看起来像一个人打字,无论有多少人贡献。

WordPress JavaScript编码标准是从jQuery JavaScript样式指南中进行的。我们的标准与jQuery指南在以下方面不同:

  • WordPress使用单引号来进行字符串声明。
  • Case语句在切换块中缩进。
  • 函数内容始终缩小,包括全文件封闭包装器。
  • 一些空格规则不一致,与WordPress PHP编码标准保持一致。
  • 鼓励jQuery的100字符硬线限制,但不会严格执行。

下面的很多例子直接从jQuery风格指南中进行了调整;这些差异已经被整合到这个页面上的例子中。以下任何标准和示例应被视为WordPress代码的最佳做法,除非明确指出为反模式。

代码重构

“代码重构不应该只是因为我们可以做到。” - Lead Developer Andrew Nacin

JavaScriptWordPress代码结构的许多部分的风格不一致。 WordPress正在努力逐步改进这一点,所以代码将一览无余,易于阅读。

虽然编码标准很重要,但重构旧的.js文件只是为了符合标准不是一个紧迫的问题。强烈建议不要使用旧的文件“仅空白”补丁。

所有新的或更新的JavaScript代码将被审查,以确保它符合标准,并通过JSHint。

间距

在你的代码中使用空格。 “当有疑问的时候,空间就出来了。

这些规则鼓励自由空间提高开发者的可读性。缩小过程创建一个文件,该文件针对浏览器进行了优化,以进行读取和处理。

  • 用标签缩进。
  • 在行尾或空白行没有空格。
  • 线条通常不应超过80个字符,不应超过100个(将标签计数为4个空格)。这是一个“软”规则,但长行通常表示不可读或无组织的代码。
  • 如果/ else / for / while / try块应该总是使用大括号,并且始终在多行上。
  • 一元的特殊字符运算符(例如,++, - )不能在它们的操作数旁边有空格。
  • 任何和不得有上一个空格。
  • 任何 ;用作声明终止符必须在行尾。
  • 任何:在对象定义中的属性名后面不得有前面的空格。并且:在三元条件下,双方必须有空间。空构造中没有填充空间(例如{},[],fn())。
  • 每个文件末尾应该有一行。
  • 任何 !否定运算符应具有以下空格。
  • 所有功能体都缩进一个选项卡,即使整个文件被封装在一起。
  • 空格可以在文档块内或行内对齐代码,但只能在行的开头使用选项卡。

WordPress JavaScript标准比jQuery样式指南更倾向于略宽的空白规则。这些偏差是WordPress代码库中PHP和JavaScript文件之间的一致性。

空格可以轻松地累积在行的末尾 - 避免这一点,因为尾随的空格被捕获为JSHint中的错误。捕获空格累积的一种方法是在文本编辑器中启用可见的空白字符。

对象

如果对象声明很短,可以在一行上进行对象声明(记住行长度指南)。当一个对象声明太长而不能适合一行时,每行必须有一个属性。如果属性名称是保留字或包含特殊字符,则只需引用属性名称:

// Preferred
var map = {
    ready: 9,
    when: 4,
    'you are': 15
};
 
// Acceptable for small objects
var map = { ready: 9, when: 4, 'you are': 15 };
 
// Bad
var map = { ready: 9,
    when: 4, 'you are': 15 };

数组和函数调用

在元素和参数上总是包含多余的空格:

array = [ a, b ];
 
foo( arg );
 
foo( 'string', object );
 
foo( options, object[ property ] );
 
foo( node, 'property', 2 );

例外:

// For consistency with our PHP standards, do not include a space around
// string literals or integers used as key values in array notation:
prop = object['default'];
firstArrayElement = arr[0];
 
// Function with a callback, object, or array as the sole argument:
// No space on either side of the argument
foo(function() {
    // Do stuff
});
 
foo({
    a: 'alpha',
    b: 'beta'
});
 
foo([
    'alpha',
    'beta'
]);
 
// Function with a callback, object, or array as the first argument:
// No space before the first argument
foo(function() {
    // Do stuff
}, options );
 
// Function with a callback, object, or array as the last argument:
// No space after after the last argument
foo( data, function() {
    // Do stuff
});

良好间距的示例

var i;
 
if ( condition ) {
    doSomething( 'with a string' );
} else if ( otherCondition ) {
    otherThing({
        key: value,
        otherKey: otherValue
    });
} else {
    somethingElse( true );
}
 
// Unlike jQuery, WordPress prefers a space after the ! negation operator.
// This is also done to conform to our PHP standards.
while ( ! condition ) {
    iterating++;
}
 
for ( i = 0; i < 100; i++ ) {
    object[ array[ i ] ] = someFn( i );
    $( '.container' ).val( array[ i ] );
}
 
try {
    // Expressions
} catch ( e ) {
    // Expressions
}

分号

使用它们。 不要依靠自动分号插入(ASI)。

缩进和换行符

缩进和换行符增加了对复杂语句的可读性。

标签应用于缩进。 即使整个文件包含在一个闭包(即一个立即被调用的函数)中,该函数的内容应该被一个tab缩进:

(function( $ ) {
    // Expressions indented
 
    function doSomething() {
        // Expressions indented
    }
})( jQuery );

块和大括号

如果,其他,for,while和try块应该始终使用大括号,并且始终在多行。 开放大括号应与功能定义,条件或循环在同一行。 关闭括号应该直接跟随块的最后一个语句。

var a, b, c;
 
if ( myFunction() ) {
    // Expressions
} else if ( ( a && b ) || c ) {
    // Expressions
} else {
    // Expressions
}

多行语句

当一个语句太长而不能适合一行,换行符必须在操作符之后发生。

// Bad
var html = '<p>The sum of ' + a + ' and ' + b + ' plus ' + c
    + ' is ' + ( a + b + c );
 
// Good
var html = '<p>The sum of ' + a + ' and ' + b + ' plus ' + c +
    ' is ' + ( a + b + c );

如果提高可读性,则将行分解为逻辑组,例如将三元运算符的每个表达式分割到其自己的行上,即使两者都适合单行。

// Acceptable
var baz = ( true === conditionalStatement() ) ? 'thing 1' : 'thing 2';
 
// Better
var baz = firstCondition( foo ) && secondCondition( bar ) ?qux( foo, bar ):foo;

当条件太长而不能适合一行时,连续的行必须缩进一个额外的级别以将其与身体区分开来。

if ( firstCondition() && secondCondition() &&
        thirdCondition() ) {
    doStuff();
}

链接方法调用

当一连串的方法调用太长时间不适合一行,每行必须有一个调用,第一个调用与调用方法的对象分开。 如果方法更改上下文,则必须使用额外的缩进级别。

elements
    .addClass( 'foo' )
    .children()
        .html( 'hello' )
    .end()
    .appendTo( 'body' );

var声明变量和全局变量

用var声明变量

每个函数应该以一个逗号分隔的var语句开始,该语句声明任何必需的局部变量。 如果函数没有使用var声明变量,则该变量可能会泄漏到外部范围(通常是全局范围,最坏情况),并且可能会无意间引用并修改该数据。

var语句中的赋值应该列在单独的行上,而声明可以分组在一行。 任何额外的行应该缩进一个额外的选项卡。 占用多个行的对象和函数应该被分配到var语句之外,以避免过度缩进。

// Good
var k, m, length,
    // Indent subsequent lines by one tab
    value = 'WordPress';
 
// Bad
var foo = true;
var bar = false;
var a;
var b;
var c;

全局变量

在过去,WordPress核心使用更大的全局变量。 由于内核JavaScript文件有时在插件中使用,所以现有的全局变量不应该被删除。

文件中使用的所有全局变量都应记录在该文件的顶部。 多个全局变量可以以逗号分隔。

这个例子会使passwordStrength是该文件中允许的全局变量:

/* global passwordStrength:true */ passwordStrength之后的“true”表示在此文件中定义了该全局。 如果要访问在其他地方定义的全局,请省略:将全局指定为只读。

公共库

Backbone,jQuery,Underscore和全局wp对象都被注册为根.jshintrc文件中的允许全局变量。

Backbone和Underscore可以随时直接访问。 jQuery应该通过$通过将jQuery对象传递给匿名函数来访问:

(function( $ ) {
  // Expressions
})( jQuery );

这将无效调用.noConflict()或使用另一个变量设置$。添加或修改wp对象的文件必须安全地访问全局,以避免覆盖以前设置的属性:

// At the top of the file, set "wp" to its existing value (if present)
window.wp = window.wp || {};

命名约定

变量和函数名称应该是完整的单词,使用小写第一个字母的骆驼壳。 这个标准与WordPress PHP编码标准不同。要用于new的构造函数应该有一个大写的第一个字母(UpperCamelCase)。名称应该是描述性的,但不是过分的。 允许迭代器使用异常,例如使用i来表示循环中的索引。

注释

注释来自他们引用的代码,并且应该始终以空行为前。 注释评论的第一个字母,并在写完整句时包括一段时间。 注释标记(//)和注释文本之间必须有一个空格。

单行注释:

// Explanation of something complex on the next line
$( 'p' ).doSomething();

多行注释应用于长期注释,另请参阅JavaScript文档标准:

/*
 * This is a comment that is long enough to warrant being stretched
 * over the span of multiple lines.
 */

使用内联注释作为异常,用于在形式参数列表中注释特殊参数:

function foo( types, selector, data, fn, /* INTERNAL */ one ) {
    // Do stuff
}

比较符

必须使用严格的等式检查(===)来有利于抽象等价检查(==)。 唯一的例外是通过null检查undefined和null。

// Check for both undefined and null values, for some important reason.
if ( undefOrNull == null ) {
    // Expressions
}

类型检察

这些是检查对象类型的首选方法:

  • String: typeof object === 'string'
  • Number: typeof object === 'number'
  • Boolean: typeof object === 'boolean'
  • Object: typeof object === 'object' or _.isObject( object )
  • Plain Object: jQuery.isPlainObject( object )
  • Function: _.isFunction( object) or jQuery.isFunction( object )
  • Array: _.isArray( object ) or jQuery.isArray( object )
  • Element: object.nodeType or _.isElement( object )
  • null: object === null
  • null or undefined: object == null
  • Global Variables: typeof variable === 'undefined'
  • Local Variables: variable === undefined
  • Properties: object.prop === undefined
  • Any of the above: _.isUndefined( object )

随着任何骨干或下划线已经被使用,我们鼓励您使用Underscore.js的类型检查方法来使用jQuery。

字符串

对字符串文字使用单引号:

var myStr = 'strings should be contained in single quotes';

当字符串包含单引号时,需要使用反斜杠(\)进行转义:

// Escape single quotes within strings:
'Note the backslash before the \'single quotes\'';

Switch语句

通常不鼓励使用switch语句,但是在有大量情况下可能会很有用 - 特别是当可以通过相同的块处理多个情况时,或者可以利用掉线逻辑(默认情况)。

使用switch语句时:

  • 对于每个案例,除了默认使用中断。 当允许语句“通过”时,明确指出。
  • 缩进案例语句开关内的一个选项卡。
switch ( event.keyCode ) {
 
    // ENTER and SPACE both trigger x()
    case $.ui.keyCode.ENTER:
    case $.ui.keyCode.SPACE:
        x();
        break;
    case $.ui.keyCode.ESCAPE:
        y();
        break;
    default:
        z();
}

不建议从switch语句中返回值:使用case块来设置值,然后在最后返回这些值。

function getKeyCode( keyCode ) {
    var result;
 
    switch ( event.keyCode ) {
        case $.ui.keyCode.ENTER:
        case $.ui.keyCode.SPACE:
            result = 'commit';
            break;
        case $.ui.keyCode.ESCAPE:
            result = 'exit';
            break;
        default:
            result = 'default';
    }
 
    return result;
}

最佳做法

数组

JavaScript中创建数组应该使用shorthand []构造函数而不是新的Array()表示法来完成。

var myArray = [];

您可以在构建期间初始化数组:

var myArray = [ 1, 'WordPress', 2, 'Blog' ];

JavaScript中,关联数组被定义为对象。

对象

有很多方法可以在JavaScript中创建对象。 对象字面符号{},既是最具性能的,也是最容易阅读的。

var myObj = {};

应该使用对象字面符号,除非对象需要特定的原型,在这种情况下,应该通过使用new调用构造函数来创建对象。

var myObj = new ConstructorMethod();

应通过.表示法访问对象属性,除非该键是变量,保留字或不是有效标识符的字符串:

prop = object.propertyName;
prop = object[ variableKey ];
prop = object['default'];
prop = object['key-with-hyphens'];

条件

为了与PHP代码标准保持一致,无论何时将对象与字符串,布尔值,整数或其他常量或字面值进行比较,变量应始终放在右侧,常量或常量放在左侧。

if ( true === myCondition ) {
    // Do stuff
}

“有点奇怪,就是阅读。 习惯了,你会的。“

迭代

当使用for循环遍历大型集合时,建议将循环的最大值存储为变量,而不是每次重新计算最大值:

// Good & Efficient
var i, max;
 
// getItemCount() gets called once
for ( i = 0, max = getItemCount(); i < max; i++ ) {
    // Do stuff
}
 
// Bad & Potentially Inefficient:
// getItemCount() gets called every time
for ( i = 0; i < getItemCount(); i++ ) {
    // Do stuff
}

Underscore.js集合函数

了解和了解Underscore的集合和数组方法。 这些函数(包括_.each,.map和 .reduce)允许大数据集的高效,可读的变换。

下划线还允许使用常规JavaScript对象进行jQuery样式链接:

var obj = {
    first: 'thing 1',
    second: 'thing 2',
    third: 'lox'
};
 
var arr = _.chain( obj )
    .keys()
    .map(function( key ) {
        return key + ' comes ' + obj[ key ];
    })
    // Exit the chain
    .value();
 
// arr === [ 'first comes thing 1', 'second comes thing 2', 'third comes lox' ]

迭代jQuery集合

jQuery应该用于迭代的唯一时间是迭代jQuery对象的集合:

$tabs.each(function( index, element ) {
    var $element = $( element );
 
    // Do stuff to $element
});

不要使用jQuery遍历原始数据或者是vanilla JavaScript对象。

JSHint

JSHint是一种自动化的代码质量工具,旨在捕获JavaScript代码中的错误。 JSHint用于WordPress开发,以快速验证补丁没有向前端引入任何逻辑或语法错误。

安装和运行JSHint

JSHint使用名为Grunt的工具运行。 JSHint和Grunt都是在Node.js中编写的程序。 WordPress开发代码随附的配置文件可以轻松安装和配置这些工具。

要安装Node.js,请单击节点网站上的安装链接。您的操作系统的正确安装文件将被下载。按照操作系统的安装步骤安装程序。

一旦安装了Node.js,打开命令行窗口并导航到您签出WordPress SVN存储库副本的目录(使用cd〜/ directoryname)。您应该在包含package.json文件的根目录中。

接下来,在命令行窗口中输入npm install。这将下载并安装WordPress开发中使用的所有Node软件包。

最后,键入npm install -g grunt-cli来安装Grunt命令行界面(CLI)包。 Grunt CLI是用于在WordPress中实际运行Grunt任务的。

您现在应该能够输入grunt jshint以使Grunt检查所有WordPress JavaScript文件的语法和逻辑错误。要检查核心代码,请键入grunt jshint:core;只检查单元测试.js文件,键入grunt jshint:tests。

JSHint设置

用于JSHint的配置选项存储在WordPress SVN存储库中的.jshintrc文件中。该文件定义JSHint应该在WordPress源代码中找到它们时应该标记哪些错误。

定位单个文件

要为JSHint指定单个文件进行检查,请在命令的末尾添加--file = filename.js。例如,这只会在WordPress的核心JavaScript文件中检查名为“admin-bar.js”的文件:grunt jshint:core --file = admin-bar.js

这只会检查单元测试目录中的“password-strength-meter.js”文件:grunt jshint:tests --file = password-strength-meter.js

将JSHint限制为单个文件可能会有用,如果您只处理一个或两个特定文件,并且不希望JSHint在每次运行时等待每个文件处理。

JSHint覆盖:忽略块

在某些情况下,文件的部分应该从JSHint中排除。作为示例,管理栏的脚本文件包含jQuery HoverIntent插件的最小化代码 - 这是不应通过JSHint的第三方代码,尽管它是WordPress核心JavaScript文件的一部分。

要排除JSHint处理的特定文件区域,请将其包含在JSHint指令注释中:

/* jshint ignore:start */
if ( typeof jQuery.fn.hoverIntent === 'undefined' ) {
    // hoverIntent r6 - Copy of wp-includes/js/hoverIntent.min.js
    (function(a){a.fn.hoverIntent=...............
}
/* jshint ignore:end */