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