Manual:Coding conventions/CSS/zh

本页面记述了MediaWiki代码库中CSS和LESS样式表的代码编写约定.

检查
我们使用stylelint作为我们的代码质量工具，并为Wikimedia定制配置（stylelint-config-wikimedia）. 你可以使用节点模块 来检查你的CSS和LESS，MediaWiki和大多数扩展将其作为的一部分运行. MediaWiki核心的设置可在 找到.

命名
用同样的方式命名Class：所有单词小写，用连接号分隔. 在MediaWiki核心中，用 前缀避免与用户在维基文本模板、章节标题、小工具以及其他软件库中添加的Class和Id冲突. 在可能的情况下，使用Class，避免引入Id.

一些示例：

注意，单词用连接号分隔，是为了简化非英语母语者的代码可读性，并为依赖像屏幕阅读器之类辅助技术的程序员提供更好的体验. 是一个过去的Class名，可追溯到上述建议之前，因此它将是.

在扩展和皮肤中，使用或前缀.

一些示例：



构造Class名
当在代码中动态构造Class时，确保在上面放一个注释，列出所有可能的Class. 参见手册:代码编写约定#动态标识符. 例如：

优先级
尽量提供低优先级选择器，最好是单个Class的选择器. 这简化了他们在如某些扩展或用户脚本的特定上下文中重写他们的过程.

空格
这样添加空格：


 * 每个选择器后换行.
 * 每个属性声明后换行.
 * （最后一行）选择器与CSS声明块的大括号之间添加一个空格.
 * 用制表符缩进每个属性声明.
 * 冒号（ ）前不添加空格.
 * 冒号和值之间添加一个空格.
 * 在多个值的属性中，逗号（ ）后添加一个空格.
 * 在选择器（如 ）和属性（如 ）中，左括号（( ）后与右括号（ )）前添加一个空格.
 * 每行声明（包括最后一行）后的分号（ ）后换行.
 * 右大括号不缩进.
 * 和注释应放在他们单独的行上，所针对的CSS声明上方.
 * 两个CSS规则集之间空一行.

引号
Wikimedia uses single quotes for values that require quotation. Such as the values of the  CSS property, and in attribute selectors.

Quotes are unnecessary in the  parameter of a   declaration. The only case where this could cause problems is when an unescaped closing parenthesis occurs in the path; in which case, you should URL-escape such characters.

Colour property values
CSS3 supports many different kinds of colour values for CSS properties like,  ,  , et al.  For consistency and compatibility, only use these three:


 * Hex colour values like  and  . ( Use lowercase for better gzip compression! Use shorthand notation when possible. )
 * values if an alpha transparency is required like . ( Attention: IE8 doesn't support   notation, so always provide a matching declaration before this one with a hex colour value as fallback. )
 * colour keyword. ( Attention: IE8 supports it only for  and  . It draws   as black. )

Prefer all values in lowercase for consistency and optimised file compression. See also Talk page section.

Avoid other colour values (including colour names/keywords – think i18n while picturing,  ,  , and   notations). Also make sure that your colour contrast ratio of foreground and background (including background gradients, and fallback colours) complies to WCAG 2.0 Level AA, ideally Level AAA.

Read further at MDN Web Docs.

Sizing units
Wikimedia Foundation aims to support a diverse audience and a wide range of technologies and use cases. A very popular accessibility user setting is increasing browser default font size while providing the best design for average users. It also reduces burden of  calculation and predictability on developers to the absolute minimum. Use  for all elements that are not directly affecting reading or understanding the user interface. Mostly,  , icon sizing by   or.



变量命名
CSS and LESS variables are set to follow a naming logic, going from repeating property to application usage to possible modifier or in short. Variables are generally used for one property, like, there are very few variables that are able to be used in different contexts. For example size variables.

It's simpler, specifically in big projects with many CSS/LESS files to have single usage variables, even though that might result in a larger variables definition file. See archived discussion for problem description. It's also more fail-safe when the variable contents get changed (think of  versus   applications).

 CSS variables example: 

 LESS variables example: 

Vendor prefixes
Always put the standardised versions of CSS properties after vendor-prefixed versions. It is important for avoiding bugs in old implementation, like in the following example of. See also https://css-tricks.com/ordering-css3-properties/.

 Right, and including annotation: 

.client-js and .client-nojs
MediaWiki outputs class  on the  element on every page. At runtime, JavaScript code replaces this with class. Hence you can use this class in your selector to conditionally show, hide, or customise certain elements depending on whether the browser has JavaScript enabled and is supported by. Note that for this to be useful, the stylesheet in question must be loaded with, not  (see )

Anti-patterns
Anti-patterns are mostly covered by use of central 'stylelint-config-wikimedia' already. Please also see the inline comments on master. Beyond there are some special properties/functionalities that deserve further explanation.

Don't rely on px unit based values
This is not a general rule, but it is general for a few properties. When a user increases their default font size preferences in a browser due to addressing visual impairments, a widely used accessibility feature, all sizes defined in  are not scaled. In order to let users scale text with this setting, rely on relative sizes like  or , specifically on properties that would result in non-scalable text like font-size or line-height or would overflow and be hidden, often with certain width or height limitations.

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

When use of z-index is required, please use the appropriate Codex design token.

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

In most cases you don't need it at all. 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).

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.
 * Add or repeat attribute selectors, like.
 * Use default elements as ancestor selector (e.g.,  ).

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, there is native support in for using LESS (with file extension  ) 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  in CSS).
 * No quotes around parameter values (same as for  in CSS).

Example:

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

Structure

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

Import of LESS/CSS files

 * The filename of an import statement has to include the  file extension.
 * If the extension was omitted, in a folder with 'foo.css' and 'foo.less' LESS would import the latter.
 * If the code is ever used outside MediaWiki context, for example in Webpack as part of storybook, it will throw an error as it will assume it is a package with an index.css or index.js file meaning the code cannot be used.
 * Use  to load mixins and variables so that they may be used by the current LESS stylesheet; these are processed synchronously by LESS and will not be present in the generated CSS output. Load mixins first, variables second. Mixins should be free of variable values and parameters in mixin calls provide values with variables.
 * Don't use  to bundle stylesheets that are related to one another only conceptually; instead, reference the set of files in the   array of a ResourceLoader module.
 * Don't use  to import CSS files in LESS files, as the LESS parser will create an invalid import statement based on the physical location of the CSS file. Use   instead.

Troubleshooting import
If your LESS  doesn't work please check:


 * Does your code contain ? See this question on Stack Overflow about how to use @font-face with LESS.

Mixins
Mixin names should use hyphen-case, just like CSS class names, property keys and variable names.

They should be prefixed with  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 a semicolon  in LESS to separate the arguments. This allows you to use commas in the literal value.

Built-in mixins
is a LESS library maintained as part of MediaWiki that is automatically available to any LESS stylesheet in MediaWiki. It can be imported from any LESS stylesheet in core, skins, and extensions.

Since, the built-in mixins contain utilities for using CSS Flexbox. Support is present all browsers that implemented at least one of the specs, including Internet Explorer 10. You need to specify your own fallback for older browsers, e.g. you can use floats for a more basic experience. Mixins available:

Example usage: