JavaScript编码标准 · WordPress开发手册

# JavaScript编码标准 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（））。 - 每个文件末尾应该有一行。 - 任何！否定运算符应具有以下空格。 - 所有功能体都缩进一个选项卡，即使整个文件被封装在一起。 - 空格可以在文档块内或行内对齐代码，但只能在行的开头使用选项卡。 >[warning] 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 }); ``` ## 良好间距的示例 ```javascript 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 **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'; ``` 当字符串包含单引号时，需要使用反斜杠（\）进行转义： ``` // 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(); } ``` >[info] 不建议从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 */ ```