WordPress 编码标准

HTML 编码规范

💡 云策文档标注

概述

本文说明 WordPress 项目中 HTML 的编码规范,涵盖验证、自闭合标签、标签与属性大小写、引号使用和缩进等要求。目标是保证标记结构良好、可维护,并降低安全风险,尤其在与 PHP 混写时保持清晰的逻辑缩进。

关键要点

  • 所有 HTML 页面应通过 W3C 验证器检查标记是否良好;自动验证不能替代人工代码审查。
  • 所有标签必须正确闭合;自闭合标签的斜杠前必须恰好有一个空格,如 <br />,而不是 <br/>。
  • 标签和属性名必须使用小写;仅供机器解析的属性值也应小写,供人阅读的文本则遵循正常标题大小写。
  • 属性值应始终使用单引号或双引号包裹,以避免安全漏洞;布尔属性可省略值,但不要写 disabled="true"。
  • HTML 缩进应使用制表符(tab)而非空格,并反映逻辑结构;PHP 与 HTML 混写时,PHP 块的缩进应与周围 HTML 匹配,结束块与开始块同级。

代码示例

<br />

<input type="text" name="email" disabled />

<?php if ( ! have_posts() ) : ?>
<div id="post-1" class="post">
    <h1 class="entry-title">Not Found</h1>
    <div class="entry-content">
        <p>Apologies, but no results were found.</p>
        <?php get_search_form(); ?>
    </div>
</div>
<?php endif; ?>

注意事项

  • 始终为属性加引号;虽然 HTML 中部分属性可不加引号,但这可能带来安全风险。
  • 布尔属性不要使用 true/false 作为值;省略值即可。
  • 自动验证只能帮助发现可自动化检测的问题,仍需人工审查代码可读性与结构。

📄 原文内容

HTML

Validation

All HTML pages should be verified against the W3C validator to ensure that the markup is well formed. This in and of itself is not directly indicative of good code, but it helps to weed out problems that are able to be tested via automation. It is no substitute for manual code review. (For other validators, see HTML Validation in the Codex.)

Self-closing Elements

All tags must be properly closed. For tags that can wrap nodes such as text or other elements, termination is a trivial enough task. For tags that are self-closing, the forward slash should have exactly one space preceding it:

<br />

rather than the compact but incorrect:

<br/>

The W3C specifies that a single space should precede the self-closing slash (source).

Attributes and Tags

All tags and attributes must be written in lowercase. Additionally, attribute values should be lowercase when the purpose of the text therein is only to be interpreted by machines. For instances in which the data needs to be human readable, proper title capitalization should be followed.

For machines:

<meta http-equiv="content-type" content="text/html; charset=utf-8" />

For humans:

<a href="http://example.com/" title="Description Here">Example.com</a>

Quotes

According to the W3C specifications for XHTML, all attributes must have a value, and must use double- or single-quotes (source). The following are examples of proper and improper usage of quotes and attribute/value pairs.

Correct:

<input type="text" name="email" disabled="disabled" />
<input type='text' name='email' disabled='disabled' />

Incorrect:

<input type=text name=email disabled>

In HTML, attributes do not all have to have values, and attribute values do not always have to be quoted. While all of the examples above are valid HTML, failing to quote attributes can lead to security vulnerabilities. Always quote attributes. Omitting the value on boolean attributes is allowed. The values true and false are not valid on boolean attributes (HTML5 source).

Correct:

<input type="text" name="email" disabled />

Incorrect:

<input type="text" name="email" disabled="true" />

Indentation

As with PHP, HTML indentation should always reflect logical structure. Use tabs and not spaces.

When mixing PHP and HTML together, indent PHP blocks to match the surrounding HTML code. Closing PHP blocks should match the same indentation level as the opening block.

Correct:

<?php if ( ! have_posts() ) : ?>
<div id="post-1" class="post">
    <h1 class="entry-title">Not Found</h1>
    <div class="entry-content">
        <p>Apologies, but no results were found.</p>
        <?php get_search_form(); ?>
    </div>
</div>
<?php endif; ?>

Incorrect:

<?php if ( ! have_posts() ) : ?>
<div id="post-0" class="post error404 not-found">
<h1 class="entry-title">Not Found</h1>
<div class="entry-content">
<p>Apologies, but no results were found.</p>
<?php get_search_form(); ?>
</div>
</div>
<?php endif; ?>

Credits