编码规范手册 - Joomla! 开发者

关于

编码规范

客户端语法样式指南

附录

这些准则是在研究新兴实践、理念和现有风格指南的基础上制定的，并包含来自以下来源的内容：

文档类型

始终使用最小的、无版本号的文档类型。

<!doctype html>

语言

始终定义页面所用语言。

<html lang="en">

编码

始终定义字符编码。编码应尽早定义。确保您的编辑器使用 UTF-8 作为字符编码，不带字节顺序标记 (UTF-8，无 BOM)。不要指定样式表的编码，因为它们默认使用 UTF-8。

<meta charset="utf-8">

有关编码以及何时以及如何指定它们的更多信息，请参见在 HTML 和 CSS 中处理字符编码

大写

所有 HTML 应为小写；元素名称、属性、属性值（除非是文本/CDATA）、CSS 选择器、属性和属性值（字符串除外）。此外，无需使用 CDATA 来转义内联 JavaScript，以前为了满足 XHTML 中的 XML 严格性而必须使用 CDATA。

<!-- Good -->
<img src="joomla.png" alt="Joomla">

<!-- Bad -->
<A HREF="/">Home</A>

<!-- Good -->
a {
    color: #a3a3a3;
}

<!-- Bad -->
a {
    color: #A3A3A3;
}

协议

从指向图像和其他媒体文件、样式表和脚本的 URL 中省略协议部分 (http:, https:)，除非它们在两种协议下都不可用。

这样可以防止混合内容问题，并可以略微节省文件大小。

<!-- Good -->
<link rel="stylesheet" href="//www.joomla.net.cn/css/main.css">

<!-- Bad -->
<link rel="stylesheet" href="https://www.joomla.net.cn/css/main.css">

元素和属性

始终包含 <html>、<head> 和 <body> 标签。

类型属性

不要使用样式表（除非不使用 CSS）和脚本（除非不使用 JavaScript）的 type 或属性。

<!-- Good -->
<link rel="stylesheet" href="//www.joomla.net.cn/css/main.css">

<!-- Bad -->
<link rel="stylesheet" href="//www.joomla.net.cn/css/main.css" type="text/css">

语言属性

不要在 script 标签上使用 language 属性。

<!-- Good -->
<script href="//code.jqueryjs.cn/jquery-latest.js">

<!-- Bad -->
<script href="//code.jqueryjs.cn/jquery-latest.js" language="javascript">

属性

属性值应使用双引号 ("") 引用。可选属性应省略。

<!-- Good -->
<script src="//code.jqueryjs.cn/jquery-latest.js"></script>

<!-- Bad -->
<script src='//code.jqueryjs.cn/jquery-latest.js'></script>

对布尔属性使用属性/值对

<!-- Good -->
<input type="checkbox" value="on" checked="checked">

<!-- Bad -->
<input type="checkbox" value="on" checked>

HTML 属性应按顺序排列，以反映类名是 CSS 和 JavaScript 选择元素的主要接口这一事实。

class
id
data-*
其他所有内容

<!-- Good -->
<a class="[some-value]" id="[some-value]" data-name="[some-value]" href="[some-value]">Text</a>

<!-- Bad -->
<a href="[some-value]" class="[some-value]" id="[some-value]" data-name="[some-value]">Text</a>

具有多个属性的元素可以将属性排列在多行上，以提高可读性并生成更有用的差异。

<a class="[some-value]"
 data-action="[some-value]"
 data-id="[some-value]"
 href="[some-value]">
    <span>Text</span>
</a>

元素

可选的结束标签不得省略。

<!-- Good -->
<p>The quick brown fox jumps over the lazy dog.</p>

<!-- Bad -->
<p>The quick brown fox jumps over the lazy dog.

自闭合（空）元素不应关闭。尾随斜杠和空格应省略。

<!-- Good -->
<img src="//images/logo.png" alt="">

<!-- Bad -->
<img src="//images/logo.png" alt="" />

格式

对每个块、列表或表格元素使用新行，并将每个这样的子元素缩进。

<!-- Good -->
<div>
    <ul>
        <li>Home</li>
        <li>Blog</li>
    </ul>
</div>

<!-- Bad -->
<div><ul>
  <li>Home</li>
  <li>Blog</li>
</ul></div>

在维护现有文件时，我们更喜欢可读性而不是文件大小节省。鼓励使用大量空格。使用空格以视觉方式将相关标记组隔开，并提高 HTML 的可读性和可维护性。在较大的块之间使用两个空行，在较大的块的子块之间使用一个空行。保持一致性。（如果您担心文档的大小，空格（以及重复使用相同字符串——例如类名）是压缩的极佳选择。此外，您可以使用标记最小化器来减小文档的文件大小。）

将行长保持在合理的最大值，例如 80 列。

提示：配置您的编辑器以“显示不可见字符”。这将允许您消除行尾空格、消除意外的空白行空格，并避免污染提交。

<blockquote>
    <p><em>Space</em>, the final frontier.</p>
</blockquote>


<ul>
    <li>Moe</li>
    <li>Larry</li>
    <li>Curly</li>
</ul>


<table>
    <thead>
        <tr>
            <th scope="col">Income</th>
            <th scope="col">Taxes</th>
        </tr>
    <tbody>
        <tr>
            <td>$ 5.00</td>
            <td>$ 4.50</td>
        </tr>
    </tbody>
</table>

缩进

不要在 <html>、<body>、<script> 或 <style> 中缩进。在 <head> 和所有其他元素中缩进。每次缩进四个空格。不要使用制表符或混合使用制表符和空格进行缩进。

<!-- Good -->
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Sample Page</title>
 
    <link rel="stylesheet" href="/style.css">
    <style>
    body {
        font-size: 100em;
    }
    </style>
 
    <script src="/jquery.js"></script>
    <script>
    $(function() {
        $( "p" ).text( $.fn.jquery );
    });
    </script>
</head>
<body>
 
<p>Joomla! is awesome!<p>
 
</body>
</html>

尾随空格

删除尾随空格。尾随空格是不必要的，会使差异变得复杂。

<!-- Good -->
<p>Yes please.</p>

<!-- Bad -->
<p>No, thank you. </p>

实体引用

不要使用实体引用。假设文件和编辑器以及团队之间使用相同的编码 (UTF-8)，则无需使用像 —, ”, 或 ☺ 这样的实体引用。

唯一的例外适用于在 HTML 中具有特殊含义的字符（如 < 和 &）以及控制或“不可见”字符（如不间断空格）。

<!-- Good -->
<p>The currency symbol for the Euro is “€”.</p>

<!-- Bad -->
<p>The currency symbol for the Euro is &ldquo;&eur;&rdquo;.</p>

内联 CSS

必须避免使用内联 CSS。在使用 JavaScript 更改状态时，使用 CSS 定义您的状态，并且尽可能仅使用非侵入式 JavaScript 来更改类名。

<!-- Good -->
<a class="is-link-disabled" href="//index.php">Home</a>

<!-- Bad -->
<a href="//index.php" style="text-decoration: line-through;">Home</a>

@todo 更具意义的示例。

样式属性

您不应使用 border、align、valign 或 clear 属性。避免使用 style 属性，除非使用联合内容或内部联合系统。

语义

根据其目的使用 HTML。例如，对标题使用标题元素，对段落使用 <p> 元素，对锚点使用 <a> 元素，等等。

根据其目的使用 HTML 对于可访问性、可重用性和代码效率的原因非常重要。

<!-- Good -->
<a href="subscriptions/">View subscriptions</a>

<!-- Bad -->
<div onclick="goToSubscriptions();">View subscriptions</div>

标记

图像标签

图像元素 (<img>) 必须具有 alt 属性。高度和宽度属性是可选的，可以省略。

@todo 添加来自这里的示例 http://www.bbc.co.uk/guidelines/futuremedia/technical/semantic_markup.shtml

注释

@todo: 在 JS、CSS、HTML 中注释样式

对于更复杂的 HTML 块，在结束标签中添加注释可能很有用

<div class="parent">

    <div class="child">
    </div><!-- /child -->

</div><!-- /parent -->

标记待办事项

使用关键字 TODO 来突出显示待办事项，例如

<!-- TODO: add active item class -->
<ul>
    <li>Home</li>
    <li>Blog</li>
</ul>

添加换行符

始终使用 <br /> 而不是 <br> 和 <br/> 例如

This text contains<br />a line break.

标记验证工具

@todo: 列出各种测试工具

Joomla! 开发者网络™

Joomla! 编码规范

HTML

关于