WordPress中文开发手册

  2. Home
  4. Docs
  6. WordPress中文开发手册
  8. WordPress主题开发
  10. 编码标准
  12. CSS编码标准

CSS编码标准

#CSS编码标准

像任何编码标准一样，WordPress CSS编码标准的目的是在WordPress开源项目和社区的各个方面，从核心代码到主题到插件，创建一个基准。 项目中的文件应该显示为由单个实体创建。 最重要的是，创建可读，有意义，一致和美观的代码。

在核心样式表中，通常会发现不一致。 我们正在努力解决这些问题，并尽一切努力从这一点开始补丁并提出遵循CSS编码标准。 有关上述的更多信息和对UI /前端开发的贡献将在一套单独的指南中提出。

结构

有很多不同的方法来构造样式表。 以CSS为核心，重要的是要保持高度的可读性。 这使得后续的贡献者能够清楚地了解文档的流程。

  • 使用制表符，而不是空格来缩进每个属性。
  • 在段之间添加两条空白行，并在段中添加一行空白行。
  • 每个选择器应该在自己的行上，以逗号或开放的大括号结尾。 属性值对应该在自己的行上，一个缩进的选项卡和一个结尾的分号。 关闭支架应该向左齐平，使用与打开选择器相同的缩进水平。

正确:

#selector-1,
#selector-2,
#selector-3 {
    background: #fff;
    color: #000;
}

不正确

#selector-1, #selector-2, #selector-3 {
    background: #fff;
    color: #000;
}
 
#selector-1 { background: #fff; color: #000; }

选择器

具有特殊性，承担着很大的责任。 广泛的选择器使我们能够高效，但如果没有测试可能会产生不利后果。 特定于位置的选择器可以节省时间，但会很快导致杂乱的样式表。 做出最好的判断，创建选择器，在DOM的整体风格和布局之间找到适当的平衡。

  • 类似于用于文件名的WordPress PHP编码标准，在命名选择器时使用带有连字符的小写和单独的单词。 避免使用驼峰命名和下划线。
  • 使用人类可读选择器来描述他们的风格。
  • 属性选择器应该围绕值使用双引号
  • 避免使用组合的选择器，div.container可以简单地表示为.container

正确：

#comment-form {
    margin: 1em 0;
}
 
input[type="text"] {
    line-height: 1.1;
}

不正确

#commentForm { /* 避免使用驼峰命名 */
    margin: 0;
}
 
#comment_form { /* 避免下划线。 */
    margin: 0;
}
 
div#comment_form { /* 避免使用组合的选择器。 */
    margin: 0;
}
 
#c1-xr { /* 使用更好的名字。 */
    margin: 0;
}
 
input[type=text] { /* 属性选择器应该围绕值使用双引号 */
    line-height: 110% /* Also doubly incorrect */
}

属性

类似于选择器，太具体的属性将阻碍设计的灵活性。 少即是多。 确保您不会重复造型或引入固定尺寸（当液体溶液更可接受时）。

  • 属性后面应该有一个冒号和一个空格。
  • 除字体名称和供应商特定属性外，所有属性和值都应为小写。
  • 对于颜色使用十六进制代码，如果需要透明度，则使用rgba（）。 避免RGB格式和大写字母，并尽可能缩短值：#fff而不是#FFFFFF。
  • 尽可能使用缩写（除了覆盖样式）的背景，边框，字体，列表样式，边距和填充值。 （有关速记参考，请参阅CSS速记。）

正确：

#selector-1 {
    background: #fff;
    display: block;
    margin: 0;
    margin-left: 20px;
}

不正确:

#selector-1 {
    background:#FFFFFF;
    display: BLOCK;
    margin-left: 20PX;
    margin: 0;
}

属性排序

最重要的是，以某种方式选择对您有意义的内容和语义。随机排序是混乱，不是诗歌。在WordPress Core中，我们的选择是逻辑或分组排序，其中属性按意义进行分组，并在这些组内特别排序。组内的属性也有策略地排序，以在节之间创建转换，例如直接在颜色之前的背景。订购的基准是：

  • 显示
  • 定位
  • 盒子模型
  • 颜色和排版
  • 其他

核心本身尚未使用的内容（例如CSS3动画）可能没有上述规定的位置，但可能以合乎逻辑的方式适合上述之一。正如CSS正在发展，所以我们的标准将会随之发展。

  • top/right/buttom/left（TRBL /故障）应该是任何相关属性（例如边距）的顺序，就像顺序在值中一样。拐角说明符（例如border-radius - * - *）应该是左上，右上，右下，左下角。这来自于如何订购速记值。

示例:

#overlay {
    position: absolute;
    z-index: 1;
    padding: 10px;
    background: #fff;
    color: #777;
}

经常使用的另一种方法，包括Automattic / WordPress.com主题小组，是按字母顺序排列属性，有或没有某些例外。

示例:

#overlay {
    background: #fff;
    color: #777;
    padding: 10px;
    position: absolute;
    z-index: 1;
}

浏览器前缀

我们使用Autoprefixer作为预提交工具来轻松管理必要的浏览器前缀，从而使本部分的大部分成为可能。 对于没有使用Grunt感兴趣的用户，浏览器前缀应该最长（-webkit-）到最短（未修改）。 所有其他间距依照其余标准。

.sample-output {
    -webkit-box-shadow: inset 0 0 1px 1px #eee;
    -moz-box-shadow: inset 0 0 1px 1px #eee;
    box-shadow: inset 0 0 1px 1px #eee;
}

属性的值

有许多方法可以输入属性的值。遵循以下准则，帮助我们保持高度的一致性。

  • 空格之前的值，冒号后
  • 不要用空格填写圆括号
  • 总是以分号结尾
  • 使用双引号而不是单引号，只有在需要时，例如当字体名称有空格时。
  • 应使用数值来定义字体权重（例如，400而不是正常值，而不是粗体）。
  • 除非必要，否则0值不应有单位，例如具有过渡持续时间。
  • 线高度也应该是无单位的，除非有必要将其定义为特定的像素值。这不仅仅是一个风格的惯例，但值得一提的是这里。更多信息：http://meyerweb.com/eric/thoughts/2006/02/08/unitless-line-heights/
  • 对于十进制值使用前导零，包括在rgba（）中。
  • 一个属性的多个逗号分隔值应由空格或换行符（包括rgba（））分隔开。换行符应用于较长的多部分值，例如速写属性（如box-shadow和text-shadow）。然后，第一个之后的每个后续值应该在新行上，缩进到与选择器相同的级别，然后间隔到左上与先前的值对齐。

正确：

.class { /* Correct usage of quotes */
    background-image: url(images/bg.png);
    font-family: "Helvetica Neue", sans-serif;
    font-weight: 700;
}
 
.class { /* Correct usage of zero values */
    font-family: Georgia, serif;
    text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.5),
                       0 1px 0 #fff;
}

不正确:

.class { /* Avoid missing space and semicolon */
    background:#fff
}
 
.class { /* Avoid adding a unit on a zero value */
    margin: 0px 0px 20px 0px;
}
 
.class {
    font-family: Times New Roman, serif; /* Quote font names when required */
    font-weight: bold; /* Avoid named font weights */
}

媒体查询

媒体查询允许我们优化降低不同屏幕大小的DOM。 如果您正在添加任何内容，请务必在您所针对的突破点上方和下方进行测试。

通常建议将媒体按媒体分组保存在样式表的底部。
对于核心中的wp-admin.css文件是一个例外，因为它非常大，每个部分基本上都代表自己的样式表。 因此，介质查询在适用的部分底部添加。
媒体查询的规则集应该缩进一级。

例：

@media all and (max-width: 699px) and (min-width: 520px) {
 
        /* Your selectors */
}

注释

注释和评论自由。 如果有关于文件大小的问题，请使用最小化的文件和SCRIPT_DEBUG常量。 长注释应手动将行长度分为80个字符。

  • 应将目录用于更长的样式表，特别是高分段的样式表。 使用索引号（1.0,1.1,2.0等）有助于搜索和跳转到某个位置。
  • 注释应该像PHPDoc一样格式化。 CSSDoc标准不一定被广泛接受或使用，但其一些方面可能会随时间推移。 Section / subsection标题应该在前后有换行符。 内联注释不应该有空的换行符，将注释与它所涉及的项目分开。

示例:

/**
* #.# Section title
*
* Description of section, whether or not it has media queries, etc.
*/
 
.selector {
    float: left;
}

行内:

/* This is a comment about this selector */
.another-selector {
    position: absolute;
    top: 0 !important; /* I should explain why this is so !important */
}

最佳实践

样式表往往长度很长。 焦点慢慢失去，而预期的目标开始重复和重叠。 从一开始就编写智能代码有助于我们保留概述，同时在变化中保持灵活性。

  • 如果您尝试解决问题，请尝试在添加更多代码之前删除代码。
  • 魔法数字是不幸的。 这些是一次性用作快速修复的数字。 示例：.box {margin-top：37px}。
  • DOM会随着时间的推移而改变，将目标要使用的元素，而不是通过其父母“找到它”。 示例：在元素上使用.highlight，而不是.highlight a（选择器在父项上）
  • 知道何时使用height属性。 当您包含外部元素（如图像）时，应使用它。 否则使用line-height可以获得更大的灵活性。
  • 不要重新设置默认属性和值组合（例如，显示：块;块级元素）。

编写如一、符合习惯的CSS的原则

以下文档将概述一个合理的CSS开发风格指导。本指导文件强烈鼓励开发者使用已经存在了的、常见的、合力的文风。您应该有选择地吸纳一些内容来创造您自己的风格指南。

1. 通用原则

“作为成功的项目的一员，很重要的一点是意识到只为自己写代码是很糟糕的行为。如果将有成千上万人使用你的代码，
那么你需要编写最具明确性的代码，而不是以自我的喜好来彰显自己的智商。” - Idan Gazit

  • 别想着过早地优化代码。先得保证它们可读又可理解才行。
  • 在任何代码库中，无论有多少人参与及贡献，所有代码都应该如同一个人编写的一样。
  • 严格执行一致认可的风格。
  • 如果有疑议，则使用现有的、通用的模式。

2. 空格

在项目的所有代码中，应该只有一个风格。在空格的使用上，必须始终保持一致。使用空格来提高可读性。

  • 永远不要在缩进时混用空格和制表符（又称TAB符号）。
  • 在软缩进（使用空格）和真正的制表符间选择其一，并始终坚持这一选择。（推荐使用空格）
  • 如果使用空格进行缩进，选择每个缩进所使用的空格数。（推荐：4个空格）

提示：将编辑器配置为“显示不可见内容”。这使你可以清除行尾的空格和不需要缩进的空行里的空格，同时可以避免对注释的污染。

提示：确定好一种空格格式后，您可以用一个EditorConfig文件（或者其他相同的东西）来帮助在代码库之间维持这种基本的空格约定。

3. 注释

良好的注释是非常重要的。请留出时间来描述组件（component）的工作方式、局限性和构建它们的方法。不要让你的团队其它成员
来猜测一段不通用或不明显的代码的目的。

注释的风格应当简洁，并在代码库中保持统一。

  • 将注释放在主题上方并独占一行。
  • 控制每行长度在合理的范围内，比如80个字符。
  • 使用注释从字面上将CSS代码分隔为独立的部分。
  • 注释的大小写应当与普通句子相同，并且使用一致的文本缩进。

提示：通过配置编辑器，可以提供快捷键来输出一致认可的注释模式。

CSS示例：

/* ==========================================================================
   区块代码注释
   ========================================================================== */

/* 次级区块代码注释
   ========================================================================== */

/**
 * “Doxygen式注释格式”的简短介绍
 *
 * 较长的说明文本从这里开始，这是这段文字的第一句话，而且这句话还
 * 没结束，过了好一会儿，我了个去终于结束了，烦不烦啊。
 *
 * 当需要进行更细致的解释说明、提供文档文本时，较长的说明文本就很
 * 有用了。这种长长的说明文本，可以包括示例HTML啦、链接啦等等其
 * 他你认为重要或者有用的东西。
 *
 * @tag 这是一个叫做“tag”的标签。
 *
 * TODO: 这个“‘需做’陈述”描述了一个接下来要去做的小工作。这种文本，
 *   如果超长了的话，应该在80个半角字符（如英文）或40个全角字符（
 *   如中文）后便换行，并（在“ * ”的基础上）再在后面缩进两个空格。
 */

/* 一般的注释 */

4. 格式

最终选择的代码风格必须保证：易于阅读，易于清晰地注释，最小化无意中引入错误的可能性，可生成有用的diff和blame。

  1. 在多个选择器的规则集中，每个单独的选择器独占一行。
  2. 在规则集的左大括号前保留一个空格。
  3. 在声明块中，每个声明独占一行。
  4. 每个声明前保留一级缩进。
  5. 每个声明的冒号后保留一个空格。
  6. 对于声明块的最后一个声明，始终保留结束的分号。
  7. 规则集的右大括号保持与该规则集的第一个字符在同一列。
  8. 每个规则集之间保留一个空行。
.selector-1,
.selector-2,
.selector-3[type="text"] {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
    display: block;
    font-family: helvetica, arial, sans-serif;
    color: #333;
    background: #fff;
    background: linear-gradient(#fff, rgba(0, 0, 0, 0.8));
}

.selector-a,
.selector-b {
    padding: 10px;
}

声明顺序

样式声明的顺序应当遵守一个单一的原则。我的倾向是将相关的属性组合在一起，并且将对结构来说比较重要的属性（如定位或者盒模型）
放在前面，先于排版、背景及颜色等属性。

小型的开发团体，可能会想要把相关的属性声明（比如说定位和箱模型）摆在一起。

.selector {
    /* Positioning */
    position: absolute;
    z-index: 10;
    top: 0;
    right: 0;
    bottom: 0;
    left: 0;

    /* Display & Box Model */
    display: inline-block;
    overflow: hidden;
    box-sizing: border-box;
    width: 100px;
    height: 100px;
    padding: 10px;
    border: 10px solid #333;
    margin: 10px;

    /* Other */
    background: #000;
    color: #fff;
    font-family: sans-serif;
    font-size: 16px;
    text-align: right;
}

大型团队，则可能更喜欢按字母排序，因为这样做起来很方便，而且维护起来很容易。

例外及细微偏移原则的情况

对于大量仅包含单条声明的声明块，可以使用一种略微不同的单行格式。在这种情况下，在左大括号之后及右大括号之前都应该保留一个空格。

.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }

对于以逗号分隔并且非常长的属性值 -- 例如一堆渐变或者阴影的声明 -- 可以放在多行中，这有助于提高可读性，并易于生成有效的diff。这种情况下有多
种格式可以选择，以下展示了一种格式。

.selector {
    box-shadow:
        1px 1px 1px #000,
        2px 2px 1px 1px #ccc inset;
    background-image:
        linear-gradient(#fff, #ccc),
        linear-gradient(#f3c, #4ec);
}

杂项

  • 在十六进制值中，使用小写，如#aaa。
  • 单引号或双引号的选择保持一致。推荐使用双引号，如content: ""。
  • 对于选择器中的属性值也加上引号，如input[type="checkbox"]。
  • 如果可以的话，不要给0加上单位, 如margin: 0。

预处理：格式方面额外的考虑

不同的CSS预处理有着不同的特性、功能以及语法。编码习惯应当根据使用的预处理程序进行扩展，以适应其特有的功能。推荐在使用SCSS时遵守以下指导。

  • 将嵌套深度限制在1级。对于超过2级的嵌套，给予重新评估。这可以避免出现过于详实的CSS选择器。
  • 避免大量的嵌套规则。当可读性受到影响时，将之打断。推荐避免出现多于20行的嵌套规则出现。
  • 始终将@extend语句放在声明块的第一行。
  • 如果可以的话，将@include语句放在声明块的顶部，紧接着@extend语句的位置。
  • 考虑在自定义函数的名字前加上x-或其它形式的前缀。这有助于避免将自己的函数和CSS的原生函数混淆，或函数命名与库函数冲突。
.selector-1 {
    @extend .other-rule;
    @include clearfix();
    @include box-sizing(border-box);
    width: x-grid-unit(1);
    // other declarations
}

5. 命名

不要试着把自己当作编译器或者预处理器，因此命名的时候尽量采用清晰的、有意义的名字。另外，对于
html文件和css文件中的代码，尽量采用一致的命名规则。

/* 没有意义的命名  */
.s-scr {
    overflow: auto;
}
.cb {
    background: #000;
}

/* 比较有意义的命名方式 */
.is-scrollable {
    overflow: auto;
}
.column-body {
    background: #000;
}

6. 实例

下面是含有上述约定的示例代码：

/* ==========================================================================
   Grid layout
   ========================================================================== */

/**
 * Column layout with horizontal scroll.
 *
 * This creates a single row of full-height, non-wrapping columns that can
 * be browsed horizontally within their parent.
 *
 * Example HTML:
 *
 * <div class="grid">
 *     <div class="cell cell-3"></div>
 *     <div class="cell cell-3"></div>
 *     <div class="cell cell-3"></div>
 * </div>
 */

/**
 * Grid container
 *
 * Must only contain `.cell` children.
 *
 * 1. Remove inter-cell whitespace
 * 2. Prevent inline-block cells wrapping
 */

.grid {
    height: 100%;
    font-size: 0; /* 1 */
    white-space: nowrap; /* 2 */
}

/**
 * Grid cells
 *
 * No explicit width by default. Extend with `.cell-n` classes.
 *
 * 1. Set the inter-cell spacing
 * 2. Reset white-space inherited from `.grid`
 * 3. Reset font-size inherited from `.grid`
 */

.cell {
    position: relative;
    display: inline-block;
    overflow: hidden;
    box-sizing: border-box;
    height: 100%;
    padding: 0 10px; /* 1 */
    border: 2px solid #333;
    vertical-align: top;
    white-space: normal; /* 2 */
    font-size: 16px; /* 3 */
}

/* Cell states */

.cell.is-animating {
    background-color: #fffdec;
}

/* Cell dimensions
   ========================================================================== */

.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }

/* Cell modifiers
   ========================================================================== */

.cell--detail,
.cell--important {
    border-width: 4px;
}

7. 代码组织

对于css代码库来说，如何组织代码文件是很重要的，尤其对于那些很大的代码库显得更加重要。这里介绍
几个组织代码的建议：

  • 逻辑上对不同的代码进行分离。
  • 不同的组件(component)的css尽量用不同的css文件（可以在build阶段用工具合并到一起）
  • 如果用到了预处理器（比如less），把一些公共的样式代码抽象成变量，例如颜色，字体等等。

8. 构建及部署

任何一个项目，都应该有一个build的过程，在这个阶段我们可以通过工具对代码进行检测，测试，压缩等等，还
可以为生产环境准备好带有版本号的代码。在这里我推荐一下grunt这个工具，我感觉它很不错。

致谢

感谢所有对idiomatic.js作出贡献的网友。

##许可
Principles of writing consistent, idiomatic CSS 是Nicolas Gallagher发布在Creative Commons Attribution 3.0 Unported License许可证下的作品。该许可证适用于本代码栈中的所有文档，包括翻译文本。

本作品基于github.com/necolas/idiomatic-css著就。