wordpress主题开发JavaScript编码标准-WordPress主题

摘要：JavaScript已经成为开发基于WordPress的应用程序（主题和插件）以及WordPress核心的关键组件。格式...

JavaScript已经成为开发基于WordPress的应用程序（主题和插件）以及WordPress核心的关键组件。格式化和造型JavaScript代码需要标准来保持与WordPress主题标准提供的核心PHP，HTML和CSS代码相同的代码一致性。

任何代码库中的所有代码应该看起来像一个人打字，无论有多少人贡献。 – 写作一致，惯用JavaScript的原则

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

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

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

代码重构

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

JavaScript的WordPress代码结构的许多部分的风格不一致。 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 };

// 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 );

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
});

// 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
}

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 );

(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
}

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 );

// 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;

// 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();
}

if ( firstCondition() && secondCondition() &&

thirdCondition() ) {

doStuff();

}

链接方法调用

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

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

if ( firstCondition() && secondCondition() &&

thirdCondition() ) {

doStuff();

}

var声明变量和全局变量

用var声明变量

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

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

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

elements

.addClass( 'foo' )

.children()

.html( 'hello' )

.end()

.appendTo( 'body' );

全局变量

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

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

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

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

公共库

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

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

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

(function( $ ) {

// Expressions

})( jQuery );

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

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

1 2	// 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();

1 2	// 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.
 */</span>

* This is a comment that is long enough to warrant being stretched

* over the span of multiple lines.

*/</span>

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

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

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
}

// 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

undefined:

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';

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

当字符串包含单引号时，需要使用反斜杠（\）进行转义：

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

1 2	// 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 ( 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;
}

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 = [];

1	var myArray = [];

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

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

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

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

对象

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

var myObj = {};

1	var myObj = {};

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

var myObj = new ConstructorMethod();

1	var myObj = new ConstructorMethod();

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

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

prop = object.propertyName;

prop = object[ variableKey ];

prop = object['default'];

prop = object['key-with-hyphens'];

条件

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

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

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
}

// 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' ]

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
});

$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 */

/* 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 */

wordpress主题开发JavaScript编码标准

代码重构

间距

对象

数组和函数调用

良好间距的示例

分号

缩进和换行符

块和大括号

多行语句

链接方法调用

var声明变量和全局变量

用var声明变量

全局变量

命名约定

注释

比较符

类型检察

字符串

Switch语句

最佳做法

数组

对象

条件

迭代

Underscore.js集合函数

迭代jQuery集合

JSHint

安装和运行JSHint

JSHint设置

定位单个文件

JSHint覆盖：忽略块

作者: 大挖酱

推荐文章列表

WordPress网站SEO

WordPress主题定制

WordPress仿站

WordPress建站教程

最新文章

热门文章排名

联系作者Q: 8413708 WX: zdmin7

支付宝扫一扫

微信扫一扫

WordPress
网站SEO

WordPress
主题定制

WordPress
仿站

WordPress
建站教程