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代码分隔为独立的部分。
注释的大小写应当与普通句子相同，并且使用一致的文本缩进。

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

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

4. 格式

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

在多个选择器的规则集中，每个单独的选择器独占一行。
在规则集的左大括号前保留一个空格。
在声明块中，每个声明独占一行。
每个声明前保留一级缩进。
每个声明的冒号后保留一个空格。
对于声明块的最后一个声明，始终保留结束的分号。
规则集的右大括号保持与该规则集的第一个字符在同一列。
每个规则集之间保留一个空行。

.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著就。

CSS编码规范

CSS编码标准

结构

选择器

属性

属性排序

浏览器前缀

属性的值

媒体查询

注释

最佳实践

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

1. 通用原则

2. 空格

3. 注释

4. 格式

声明顺序

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

杂项

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

5. 命名

6. 实例

7. 代码组织

8. 构建及部署

致谢

许可