手册:代码编写约定/CSS

快捷方式： CC/LESS
From mediawiki.org
This page is a translated version of the page Manual:Coding conventions/CSS and the translation is 28% complete.
Outdated translations are marked like this.
Languages:
参见Manual:CSS 了解此处未提及的其他警告和提示。

命名

参见Manual:Interface/IDs and classes ，常见Id和Class的文档。

用同样的方式命名Class：所有单词小写，用连接号分隔。 Use the mw- prefix to avoid conflicts with IDs generated by the wikitext parser to mark section headings.

一些示例： 

/* 站内元素 */
.mw-body,
.mw-headline,
.mw-label,
.mw-input {
}

/* 特殊页面 */
.mw-body-content,
/* - Special:AllPages */
.mw-allpages-table-form,
.mw-allpages-nav {
}

空格

  • 每个选择器后换行。
  • （最后一行）选择器与CSS声明块的大括号之间添加一个空格。
  • 用制表符缩进每个属性声明。
  • 冒号（:）前不添加空格。
  • 冒号和值之间添加一个空格。
  • 在多个值的属性中，逗号（, ）后添加一个空格。
  • 每行声明（包括最后一行）后的分号（;）后换行。
  • 右大括号不缩进。
  • $1和$2注释应放在他们单独的行上，所针对的CSS声明上方。
  • 两个CSS规则集之间空一行。
.mw-selector,
#mw-some-element {
	background-color: #fff;
	color: #252525;
	float: right;
	font-family: Arial, Helvetica, sans-serif;
	text-align: left;
}

/* CSSMin/CSSJanus example annotations */
.mw-look-at-the-left {
	/* @embed */
	background-image: url( images/foobar.png );
	/* @noflip */
	float: left;
}


引号

In the background-image declaration, the url() syntax is preferred to be used without quotes. They are not needed. The only case where it could cause problems is when an unescaped closing parenthesis occurs in the given path, but those should be URL-escaped.

颜色属性值

With CSS3 developers have a plethora of accepted colour values for CSS properties like background-color, color, border-color and all others. For maintainability and file size[1] use in lowercase:

  • 十六进制颜色值，如#fff和#fefefe。
  • 如果需要alpha透明度，使用rgba()值，如$2。
  • transparent颜色关键词。

避免其他颜色值（包括颜色名/关键字——在使用$2、rgb()、hsl()和hsla()符号时考虑i18n）。 还要确保你的前景和背景（包括背景渐变和退色）的色彩对比度符合WCAG 2.0 AA级，最好是AAA级。[2]

Read further at MDN.

厂商前缀

通常把CSS属性的标准化版本放在厂商前缀版本之后。 参见https://css-tricks.com/ordering-css3-properties/。 

/* Wrong */
.bar {
	border-radius: 30px 10px;
	-webkit-border-radius: 30px 10px;
}

/* Right */
.bar {
	-webkit-border-radius: 30px 10px;
	/* It is important that the -webkit version is before the standardized version.
	 * Otherwise it will override it (as expected in CSS), including triggering the
	 * bugs the old -webkit- version has that WebKit has since fixed (in CSS3), but keeps
	 * in the old implementation (for backwards compatibility).
	 */
	border-radius: 30px 10px;
}

/* Wrong */
.foo {
	background-image: linear-gradient(top, #444444, #999999);
	background-image: -o-linear-gradient(top, #444444, #999999);
	background-image: -moz-linear-gradient(top, #444444, #999999);
	background-image: -webkit-linear-gradient(top, #444444, #999999);
	background-image: -webkit-gradient(linear, left top, left bottom, from(#444444), to(#999999));
}

/* Right */
.foo {
	background-color: #444;
	background-image: -webkit-gradient(linear, left top, left bottom, from(#444), to(#999));
	background-image: -webkit-linear-gradient(      top, #444, #999);
	background-image:    -moz-linear-gradient(      top, #444, #999);
	background-image:      -o-linear-gradient(      top, #444, #999);
	background-image:         linear-gradient(to bottom, #444, #999);
}

/* Right (commented) */
.foo {
	/* 不支持背景图像渐变时的回退颜色 */
	background-color: #444;
	/* Safari 4+，Chrome 2，iOS 2 */
	background-image: -webkit-gradient(linear, left top, left bottom, from(#444), to(#999));
	/* Safari 5.1+，Chrome 10+，iOS 5 */
	background-image: -webkit-linear-gradient(      top, #444, #999);
	/* Firefox 3.6 - 15 */
	background-image:    -moz-linear-gradient(      top, #444, #999);
	/* Opera 11.10 - 12.5 */
	background-image:      -o-linear-gradient(      top, #444, #999);
	/* Standard (Firefox 16+, Opera 12.5+, IE10) */
	background-image:         linear-gradient(to bottom, #444, #999);
}


.client-js和.client-nojs

MediaWiki在每个页面的‎<html>元素上输出Class client-nojs。 在运行时，JavaScript代码用client-js替换它。 因此，你可以在选择器中使用这个Class来有条件地显示、隐藏或定制某些元素，取决于浏览器是否启用了JavaScript并支持资源加载器 。 请注意，要使它有用，所讨论的样式表必须用$1加载，而不是mw.loader（参见资源加载器开发 ）

反模式

z-index

Avoid using z-index when possible. Instead, try to use the natural stacking order in the DOM. Known exceptions include:

!important

Avoid using !important (with the exception of working around upstream code running on the same page that also uses !important, because only !important can override !important).

In most cases you don't need it at all (e.g. paranoia). In other cases it may be the result of a bug elsewhere in the program. In general, to override a rule you use the same selector as the original style rule. Since CSS cascades, this works naturally (styles applied later override styles applied earlier, selectors don't need to be of higher specificity).[3]

If the overriding styles apply before the original styles, the styles got loaded in the wrong order. That should be addressed, but you may resort to workarounds to artificially increase the specificity:

  • Repeat the same selector to increase weight, like .foo.foo.foo.foo.[4]
  • Add or repeat attribute selectors, like [class].
  • Use default elements as ancestor selector (e.g. body .foo, html body .foo).

Add however many points you need. It will still allow multiple stylesheets to use the same technique and each express their specificity. Better than adding in ancestors classes not related to your code. (And more maintainable as they won't change.)

LESS

Starting with MediaWiki 1.22 , there is native support in 资源加载器 for transparently using LESS (with file extension .less) in place of CSS. Most of the LESS syntax can be formatted using the CSS conventions:

  • Indent nested blocks with 1 tab (same as for indenting declarations inside CSS rules).
  • Don't space-align declarations values inside mixins (same as for CSS rules).
  • No spaces on the outside of the parameter lists in function invocations, mixin uses and mixin definitions (same as for url( image.png ) in CSS).
  • No quotes around parameter values (same as for url( image.png ) in CSS).

示例： 

/*
	You do not need to copy '.background-image' into your code.
	It is provided by MediaWiki core (in mediawiki.less).
	It is here as an example of guard syntax.
*/
.background-image(@url) when (embeddable(@url)) {
	background-image: embed(@url);
	background-image: url(@url)!ie;
}

.background-image(@url) when not (embeddable(@url)) {
	background-image: url(@url);
}

.mw-example {
	padding: 0.2em 0.5em;
	border: 1px solid #aaa;
	.background-image(images/example.png);
	font-size: 1em;

	.mw-example-thing {
		display: inline-block;
		/* @noflip */
		float: left;
		border: 1px solid #ddd;
		padding: 1px 4px;
		border-radius: 2px;
	}
}

There's a few new concepts that don't map to CSS conventions, outlined below.

结构

  • Separate nested CSS rules from the parent declarations by 1 empty line.
  • @noflip tags must be on the immediate line above the declaration, as shown in the example above.

导入LESS/CSS文件

  • The filename of an import statement should omit the .less file extension.
  • Use @import to load mixins and variables so that they may be used by the current LESS stylesheet; these are processed synchronously by phpless and are not present in the generated CSS output.
  • Don't use @import to bundle stylesheets that are related to one another only conceptually; instead, reference the set of files in the styles array of a ResourceLoader module.

故障排除导入

If your LESS import doesn't work, here some things to check:

MediaWiki LESS library

resources/src/mediawiki.less/mediawiki.mixins.less is a common LESS library for MediaWiki. The directory is in $wgResourceLoaderLESSImportPaths, so you don't need to provide the full path to it. For example: 

@import "mediawiki.mixins";

.my-create-link {
    .background-image-svg('images/create_normal.svg', 'images/create_normal.png');
}

混合

Mixin names should use hyphen-case, just like CSS properties.

They should be prefixed with mixin- to avoid confusing developers who are familiar with CSS, but not LESS and distinguish them from classes, the syntax for which is similar.

As mentioned above, no spaces on the outside of the parameter list and avoid quoting values.

If you need to call a mixin with one or more arguments that contain a comma use the semi colon ; in LESS to separate the arguments instead. This will free up the comma to be used in the literal value. 

.mixin-example(@function, @properties) {
	transition-timing-function: @function;
	transition-property: @property;
}

/* Good */
.mw-example {
	.mixin-example(easy-in-out; opacity, color);

	/* Expands to: */
	transition-timing-function: easy-in-out;
	transition-property: opacity, color;
}

/* Bad */
.mw-example {
	.mixin-example('easy-in-out', 'opacity, color');

	/* Expands to: */
	transition-timing-function: 'easy-in-out';
	transition-property: 'opacity, color';

	/* Values include the quotes, this is invalid CSS
	 * and results in the browser ignoring these properties
	 */
}

/* Bad */
.mw-example {
	.mixin-example(~'easy-in-out', ~'opacity, color');

	/* Expands to: */
	transition-timing-function: easy-in-out;
	transition-property: opacity, color;

	/* The ~ operator instructs LESS to unquote the values.
	 * This produces good CSS but we avoid this pattern
	 * in favour of using ';' consistently.
	 */
}

参考资料

  1. ↑ Lowercase markup has smaller gzip output, HTML5 Boilerplate 2015
  2. ↑ WCAG 2.0 Understanding Contrast
  3. ↑ Specifics on CSS Specificity, css-tricks.com
  4. ↑ 3.14 things I didn’t know about CSS, CSS Day Conference 2014


Retrieved from "https://www.mediawiki.org/w/index.php?title=Manual:Coding_conventions/CSS/zh&oldid=6421014"