WordPress编码标准简述（PHP, HTML, CSS和JavaScript）

WBOLT_COM 5 月 06, 2024 55 0

WordPress编码标准简述

WordPress 开发中的编码标准对于一个强大和可持续的代码库至关重要。它们是开发人员在编写代码时遵守的准则和惯例，有助于加强协作、简化维护并确保整体可靠性。

此外，编码标准还能防止常见的陷阱和错误，提高代码质量。在 WordPress 开发中，多个贡献者通常会在一个项目上进行协作，因此编码标准是有效团队协作的基础。它们促进了沟通，缓解了潜在冲突，并有助于提高开发流程的效率。

遵守编码标准可促进各项目之间的一致性，使您更容易在不同的代码库之间无缝切换。这种一致性可扩展到代码的可读性和可维护性，并促进团队成员之间的共同理解。

WordPress 官方编码标准涵盖了五个关键领域，以确保开发过程的一致性和高效性：

确保服务器端代码一致性的 PHP
促进结构化和语义标记的 HTML
JavaScript 用于实现有效的客户端功能
CSS 用于保持风格一致
可访问性，确保最终产品对有不同需求的个人具有包容性和用户友好性

在本文中，我们将探讨 WordPress 这些编码标准，以帮助您开始构建符合标准的网站，并为 WordPress 开发社区做出贡献。

WordPress 开发中的 PHP 标准

WordPress 专用的 PHP 编码标准可确保 WordPress 代码的一致性和可读性。它们是 WordPress Core 的强制性标准，也是主题和插件的强烈推荐标准。这些标准涵盖各个方面，包括命名规则、缩进和代码结构，以提高可读性和便于协作。

WordPress PHP 标准分为以下几类：

常规 – 这些标准包括在 HTML 代码块中嵌入多行 PHP 代码片段时，将开头和结尾的 PHP 标记放在一行中，使用单引号和双引号时避免使用速记 PHP 标记，以及 include 和 require 语句的编写指南：

// Opening and closing PHP tags within HTML:
// Put open/close tags on their own lines.
## DO
function foo() {
?>
<div>
<?php
echo esc_html (
bar (
$param1,
$param2
)
);
?>
</div>
<?php
}
## DON'T
if ( $x === $y ) { ?>
<div>
<!-- HTML content -->
<?php }

// Avoid shorthand PHP tags
## DO
<?php ... ?>
<?php esc_html( $x ); ?>
## DON'T
<? ... ?>
<? esc_html( $x ); ?>

// Writing include/require statements:
// Avoid include_once as it continues execution 
// even if the file is not found. 
// Do not use brackets around the file path.
## DO
require_once ABSPATH . 'file-name.php'
## DON'T
require_once  __DIR__ . '/file-name.php'
include_once  ( ABSPATH . 'file-name.php' );

命名 – 命名标准包括命名约定和动态钩子的插值命名：

## DO
// Use lowercase letters for function and variable names.
function my_function( $some_variable ) {}
// Use uppercase letters for constant names.
define('MAX_AGE', 60);
## DON'T
// Use camelCase.
function myFunction( $someVariable ) {}

空白字符 – 空白字符标准规定了空格使用、缩进和删除尾部空格的准则。(如果你想在开发人员中掀起一场热烈的讨论，只需问问他们在缩进代码时更喜欢制表符还是空格即可。无论您的偏好如何，WordPress 开发人员的官方建议都是使用制表符，除了 PHP 之外，JavaScript 和 CSS 也是如此。因此，在合作项目中，请记住这一点）。

## DO
// Put spaces after commas.
$colors = ['red', 'green', 'blue']
// Put spaces on both sides of the opening and 
// closing brackets of control structures. 
foreach( $foo as $bar ) { ...
// Defining a function:
function my_function() { ...
// Logical comparisons:
if ( ! $foo ) { ...
// Accessing array items:
$a = $foo['bar']
$a = $foo[ $bar ]
## DON'T
$colors = ['red','green','blue']
foreach($foo as $bar){ ...
function my_function(){ ...
if (!$foo) { ...
$a = $foo[ ‘bar’ ]
$a = $foo[$bar]

格式化 – WordPress PHP 开发的格式化标准包括括号样式、数组声明、多行函数调用指南、类型声明、神奇常量和展开运算符：

// DO
// Use the following brace style.
if ( condition ) {
action();
} elseif ( condition2 ) {
action2();
} else {
default_action();
}
// Declare arrays using the long syntax.
$numbers_long = array(1, 2, 3, 4, 5);
/* In multi-line function calls, each parameter should only take up one line.
Multi-line parameter values should be assigned a variable, and the variable passed to the function call. */
$data = array(
'user_name' => 'John Doe',
'email'     => 'john@example.com',
'address'   => '123 Main Street, Cityville',
);
$greeting_message = sprintf(
/* translation function. %s maps to User's name */
__( 'Hello, %s!', 'yourtextdomain' ),
$data['user_name']
);
$result = some_function (
$data,
$greeting_message,
/* translation function %s maps to city name*/
sprintf( __( 'User resides in %s.' ), 'Cityville' )
);
// Magic constants should be uppercase.
// The ::class constant should be lowercase with no spaces around the scope resolution operator (::).
add_action( my_action, array( __CLASS__, my_method ) );
add_action( my_action, array( My_Class::class, my_method ) );
/* Add a space or new line with appropriate
indentation before a spread operator.
There should be:
* No space between the spread operator and the 
variable/function it applies to.
* No space between the spread and the reference 
operators when combined.
*/
//DO
function some_func( &...$arg1 ) {
bar( ...$arg2 );
bar(
array( ...$arg3 ),
...array_values( $array_vals )
);
}
//DONT
function some_func( &   ...  $arg1 ) {
bar(...
$arg2 );
bar(
array( ...$arg3 ),...array_values( $array_vals )
);
}

声明语句、命名空间和导入语句 – 这些编码标准包括命名空间声明和 use 语句：

// Each namespace declaration should contain 
// capitalized words separated by underscores.
namespace My_CompanyProjectKinsta_ProjectUtilities;
// Import use statements can use aliases 
// to prevent name collisions.
use Project_NameFeatureClass_C as Aliased_Class_C;

面向对象编程（OOP）– 这些标准包括每个文件只使用一个对象结构，提供使用特质 use 语句的指导，确保始终声明可见性，概述可见性和修饰符的顺序，以及概述对象实例化的规则：

// Trait use statements should be at the top of a class.
// Trait use should have at least one line before and after
// the first and last statements.
// Always declare visibility.
class Foo {
use Bar_Trait;
public $baz = true;
...
}
// Always use parentheses when instantiating a new 
// object instance.
// Don't add space between a class name and the opening bracket.
$foo = new Foo();

控制结构 – 控制结构包括使用 elseif 、not else if 以及 Yoda 条件准则：在逻辑比较中将变量与常量、字面量或函数调用混合时，应将变量放在右侧，以防止意外赋值，如下所示：

// A "legal" comparison:
if ( true === $result ) {
// Do something with $result
}
// But a typo like this could get past you:
if ( $result = true ) {
// We will always end up here
}

运算符 – 这些标准包括三元运算符、错误控制运算符 ( @ ) 和增/减运算符：

// Always have ternary operators 
// test if the statement is true, not false.
$programming_language = ( 'PHP' === $language ) ? 'cool' : 'meh'; 
// Favor pre-increment/decrement over post-increment/decrement
// for stand-alone statements.
// DO
--$a;
// DON'T
$a--;

数据库 – 数据库编码标准提供了执行数据库查询和格式化 SQL 语句的说明。

其他建议 – 其他建议包括为函数参数使用不言自明的标志值、巧妙代码、闭包（匿名函数）、正则表达式、shell 命令以及避免使用 extract() 的说明等标准。

WordPress PHP 代码的内联文档标准

除上述指南外，WordPress还为PHP代码提供了内联文档标准。WordPress 使用定制的文档模式，该模式从 PHPDoc 语法中汲取灵感，PHPDoc 是由 phpDocumentor 维护的一个不断发展的为 PHP 代码提供文档的标准。这些标准简化了外部文档的生成，并通过促进对代码库结构的共同理解，为更广泛的 WordPress 开发者社区做出了贡献。

WordPress 中的 PHP 文档大多以格式化块或内联注释的形式出现。在 WordPress 文件中记录以下内容：

函数和类方法
类
类成员，包括属性和常量
要求和包含
钩子（动作和过滤器）
内联注释
文件头
常量

WordPress 中的 HTML 和 CSS 标准

WordPress 主题和插件遵守严格的 HTML 编码标准，以确保一致性、可访问性和可维护性。指南强调语义标记，鼓励开发人员将 HTML 元素用于其预期目的。这种做法可以增强内容结构，提高搜索引擎优化 (SEO) 性能。此外，我们还鼓励您验证 HTML，以保证跨浏览器的兼容性。

HTML 代码标准为以下方面提供了指导：

验证 – 您应根据 W3C 验证器验证所有 HTML 页面，以确保您的标记格式良好。

自闭合元素 – 自闭合元素中的正斜杠前应留一个空格。

<!-- DO -->
<br />
<!-- DON'T –>
<br/>

属性和标记 – 所有属性和标记都应小写。此外，属性值只有在机器解释时才应小写。如果是为人类编写，则应使用正确的标题大写。

<!-- DO -->
<a href="http://example.com/" title="Link Description">Descriptive text</a>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<!-- DON'T -->
<a HREF="http://example.com/" TITLE="link description">Click here</a>

引号 – 所有属性都必须有一个值，并且必须使用单引号或双引号。不使用引号可能会导致安全漏洞。

<!-- DO -->
<input type="text" name="email" disabled="disabled" />
<input type='text' name='email' disabled='disabled' />
<!-- DON'T -->
<input type=text name=email disabled>

缩进 – HTML 缩进应始终反映逻辑结构。混合使用 PHP 和 HTML 时，PHP 代码块的缩进应与周围的 HTML 代码一致。

<!-- DO -->
<?php if ( ! have_articles() ) : ?>
<div class="article">
<h1 class="article-title">Not Found</h1>
<div class="article-content">
<p>No results were found.</p>
<?php get_error_msg(); ?>
</div>
</div>
<?php endif; ?>
<!-- DON'T -->
<?php if ( ! have_articles() ) : ?>
<div class="article">
<h1 class="article-title">Not Found</h1>
<div class="article-content">
<p>No results were found.</p>
<?php get_error_msg(); ?>
</div>
</div>
<?php endif; ?>

除了这些 HTML 标准外，WordPress 的 CSS 标准还可以帮助您创建简洁、模块化和响应式的样式表。它们为从核心代码到主题再到插件的协作和审查设定了基准。这些准则有助于确保代码的可读性、一致性和意义。

WordPress CSS 代码标准强调使用特定的类来定位元素，从而促进结构的一致性和条理性。具体来说，这些标准包括：

结构

/* DO 
Each selector should be on its own line ending with 
a comma or curly brace. The closing brace should occupy 
the same indentation level as the opening selector. */
#selector-1,
#selector-2 {
property: value;
}

选择器

/* DO 
Use lowercase and separate words using hyphens.
Use double quotes around values for attribute selectors.
Avoid overqualified selectors, such as div.container. */
#contact-form {
property: value;
}
input[type="text"] {
property: value;
}

属性（排序和浏览器引擎前缀）

/* Append properties with a colon and a space. 
Properties should be lowercase — except font names 
snd vendor-specific properties — and use shorthand. */
#selector {
property: value;
}

值

/* Add a space before the value and a semicolon after.
Use double quotes.
0 values should not have units.
Use a leading zero for decimal values.
Delineate multiple comma-separated values for 
a single property with a space or new line. */
#contact-form {
font-family: "Helvetica Neue", sans-serif;
opacity: 0.9;
box-shadow:
0 0 0 1px #5b9dd9,
0 0 2px 1px rgba(20, 120, 170, 0.9);
}

媒体查询

/* Rules set for media queries should be indented one level in.
Keep media queries grouped by media at the bottom of the stylesheet. */
@media all and (max-width: 1024px) and (min-width: 780px) {
$selector {
property: value;
}        
}

注释

自 2003 年诞生以来，WordPress的HTML和CSS编码标准一直与万维网联盟（W3C）的 HTML 和 CSS 指南保持一致。W3C 标准强调整合响应式设计原则和语义标记，从发布 HTML5 和 CSS3 开始，就对主题和插件的开发产生了影响。

采用 W3C 准则可确保 WordPress 网站遵守全球网络标准，增强互操作性和用户体验，并反映出在更广泛的网络生态系统中保持最新、安全和兼容的承诺。

WordPress 对这些准则的遵守强调了根据 W3C HTML 标记验证器进行 HTML 质量验证。

这些 HTML 和 CSS 标准可确保 WordPress 网站在跨平台时具有视觉吸引力、用户友好和高效的表现形式。它们支持无缝的用户体验，并促进了 WordPress 生态系统不同方面的开发人员之间的协作。

WordPress 中的 JavaScript 编码标准

WordPress 的编码标准还为主题和插件的 JavaScript 代码的格式和样式提供了指导。此外，这些标准还有助于促进代码与核心 PHP、HTML 和 CSS 代码的一致性。

WordPress JavaScript 编码标准建立在 jQuery JavaScript 样式指南的基础上，该指南于 2012 年推出，是一套全面的编码规范，可增强代码的一致性和可读性。该指南最初专门针对j Query 项目，但它的成功促使 jQuery 框架以外的项目也广泛采用该指南。

虽然jQuery指南为WordPress标准提供了参考，但在WordPress开发中也有一些明显的不同之处：

WordPress对字符串声明使用单引号。
在开关块中，大小写语句是缩进的。
函数内容采用一致的缩进，包括全文件闭包。
为了与 PHP WordPress 标准保持一致，一些空白规则也有所不同，比如使用制表符或缩进。
jQuery 的 100 个字符硬行限制虽然值得鼓励，但并未严格执行。

WordPress JavaScript 编码标准涵盖以下方面：

代码重构。
代码间距，包括对象声明、数组和函数调用：

// Object declarations
// DO
var obj = {
name: 'John',
age: 27,
height: 179
}
// DON'T
var obj = {
name: 'John',  age: 27,
height: 179
}
// Arrays and function calls
// Include extra spaces around elements and arguments.
array = [ 1, 2 ];
foo( arg1, arg2 );

分号的使用：

// Always use semicolons
array = [ 1, 2 ];

缩进和换行，包括块和大括号、多行语句和链式方法调用：

// Use tabs for indentation
( function ( $ ) {
// Expressions indented
function doSomething() {
// Expressions indented
}
} )( jQuery );
// if, else, for, while, and try blocks should span multiple lines
if ( condition ) {
// Expressions
} else if ( ( condition && condition ) || condition ) {
// Expressions
} else {
// Expressions
}
// Line breaks must occur after an operator if the statement
// is too long to fit on one line.
var html = '<p>The sum of ' + a + ' and ' + b + ' plus ' + c +
' is ' + ( a + b + c ) + '</p>';
/* If a chain of method calls is too long to fit on a single line, 
use one call per line. The first call should be on a separate line from
the object on which the methods are called. */
elements
.addClass( 'foo' )
.children()
.html( 'hello' )
.end()
.appendTo( 'body' );

赋值和全局，包括用 const 和 let 声明变量、用 var 声明变量、全局和常用库。
命名约定，如缩写和首字母缩略词、类定义和常量：

// Abbreviations must be written in camelCase.
// All letters of acronyms should be capitalized.
const userId = 1;
const currentDOMDocument = window.document;
// Class definition must use UpperCamelCaseConvention.
class Human {
...
}
// Constants should use SCREAMING_SNAKE_CASE convention.
const SESSION_DURATION = 60

相等（==）：

// Use strict equality/inequality checks (=== and !==)
// instead of abstract checks (== and !=).
if ( name === "John" ) {
...
}
if ( result !== false ) {
...
}
// Also, with negation:
if !( result === false ) {
...
}

字符串：

// Use single-quotes for string literals.
var myString = 'Hello world!'

切换语句：

// Use a break for each case other than default.
// Indent case statements one tab within the 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();
}

此外，WordPress 编码标准还概述了编写 JavaScript 代码的几种最佳实践。

与 PHP 一样，WordPress 也为 JavaScript 代码提供了内联文档标准。这些内联标准既可以是格式化的文档块，也可以是内联注释，它们遵循 JSDoc 3 内联 JavaScript 文档标准。内联标准涵盖函数、类方法、对象、闭包、对象属性、事件和文件头。

如何确保 WordPress 开发的可访问性

可访问性标准对于确保数字内容（包括在 WordPress 等平台上创建的网站）适合各种能力的人使用至关重要。采用 W3C 的可访问性标准可确保使用 WordPress 创建的网站具有包容性并可供残障人士访问。

W3C 可访问性指南，特别是《Web Content Accessibility Guidelines》（WCAG），为提高网页内容的可访问性提供了一个全面的框架。认识到包容性的重要性，WordPress 已将这些指南纳入其核心功能。

例如，WCAG 根据《欧洲无障碍法案》来衡量合规性，该法案将从 2025 年 6 月起适用于欧盟的许多组织。

要满足不同的需求，就需要实施一些功能和设计原则，如屏幕阅读器兼容性、键盘导航和非文本内容的文本替代。

确保 WordPress 的可访问性不仅仅是一个合规性问题。这是为每个人提供平等获取信息和服务机会的承诺。通过遵守 W3C 准则，WordPress 网站变得更易于访问和用户友好，从而营造一个更具包容性的网络环境。

在主题和插件中实施可访问性功能的一些实际例子包括以下内容：

使用语义 HTML – 确保正确使用语义 HTML 标记。例如，在导航菜单中使用 <nav>，在网站页头中使用 <header>，在主要内容中使用 <main>。这些标签有助于屏幕阅读器和其他辅助技术理解页面结构。
为图像、视频和音频内容添加文本替代 – 为图像提供描述性的 alt 文本，以便向无法看到图像的用户传达其含义。在 WordPress 中，添加图片时在媒体库中添加描述性的 alt 属性。为视频添加字幕和文字说明，并为音频内容提供文本替代，以确保耳聋或听力障碍的用户能够获取信息。
在构建时考虑响应式设计 – 确保您的主题或插件具有响应性，能很好地适应不同的屏幕尺寸。这种方法有利于使用各种设备的用户，并确保跨平台的一致体验。
设计无障碍表单 – 为表单字段提供清晰的标签和说明。使用适当的输入类型，如电子邮件或电话，以便在移动设备和辅助技术上触发正确的键盘。
使用键盘导航 – 确保所有互动元素都可使用键盘导航。用户应能在链接、按钮和表单字段中使用选项卡。测试并增强键盘的无障碍性，避免只依赖鼠标进行交互。

遵守 WordPress 编码标准的工具

有许多代码嗅探工具可以帮助您遵守上述平台编码标准。让我们回顾一下您可以用来检查 WordPress 编码标准的几种验证工具。

PHP_CodeSniffer

PHP_CodeSniffer 会扫描您的 PHP 代码库，以识别与既定规范的偏差。它能精确定位违规编码和风格差异，使代码更简洁、更高效。这将提高 WordPress 网站的性能，并确保与未来的更新和插件无缝兼容。

W3 Org 的 CSS 验证服务

W3 Org 的 CSS 验证服务可扫描 CSS 样式表，识别并纠正可能妨碍网站最佳性能的潜在错误。它在保持一致性和遵守 W3C 标准方面发挥着至关重要的作用，保证了用户在各种设备上的流畅体验。因此，网站的加载时间得到改善，并符合 WordPress 规定的严格 CSS 编码标准。

JSHint

JSHint 可分析 JavaScript 代码，识别潜在错误、风格不一致之处以及是否符合最佳实践。它能帮助您编写更简洁、更高效的代码，最终优化网站性能。它非常注重 WordPress 的编码标准，确保 JavaScript 代码与 WordPress 的整体架构无缝集成，帮助您维护一个连贯、标准化的编码环境。