Příručka:Konvence pro psaní kódu/CSS

This page is a translated version of the page Manual:Coding conventions/CSS and the translation is 100% complete.

Pojmenovávání

Třídy a ID pojmenujte stejným způsobem: Všechna písmena malá a slova rozdělená pomlčkami. Použijte předponu mw-, abyste se vyhnuli konfliktům s ID generovanými analyzátorem wikitextu pro označení nadpisů sekcí.

Příklady použití:

/* Prvky na celém webu */
.mw-body,
.mw-headline,
.mw-label,
.mw-input {
}

/* Speciální stránky */
.mw-body-content,
/* - Special:AllPages (šechny speciální stránky) */
.mw-allpages-table-form,
.mw-allpages-nav {
}

Mezery

Jeden selektor/jedna vlastnost na řádek
Otevírací složené závorky pro blok deklarace CSS na stejném řádku jako (poslední) selektor.
Odsadit každé prohlášení o vlastnosti tabulátorem.
Žádná mezera před dvojtečkou (:).
Jedna mezera mezi dvojtečkou a před hodnotou.
Jedna mezera za čárkami (, ) ve vlastnostech s více hodnotami.
Středník (;) za každou deklarací (včetně poslední).
Zavírací závorky odsazeny zpět doleva.
Komentáře anotací pro CSSJanus a CSSMin by měly být na samostatném řádku nad deklarací CSS, pro kterou jsou určeny.
Prázdný řádek mezi jednou sadou pravidel CSS a další.

.mw-selector,
#mw-some-element {
	background-color: #fff;
	color: #252525;
	float: right;
	font-family: Arial, Helvetica, sans-serif;
	text-align: left;
}

/* Příklady anotací CSSMin/CSSJanus */
.mw-look-at-the-left {
	/* @embed */
	background-image: url( images/foobar.png );
	/* @noflip */
	float: left;
}

Citáty

V deklaraci background-image je preferováno použití syntaxe url() bez uvozovek. Nejsou potřeba. Jediným případem, kdy by to mohlo způsobit problémy, je situace, kdy se v dané cestě vyskytne neuzavřená uzavírací závorka, ale ty by měly být zakódovány pomocí adresy URL.

Hodnoty vlastností barev

S CSS3 mají vývojáři k dispozici nepřeberné množství akceptovaných barevných hodnot pro vlastnosti CSS jako background-color, color, border-color a všechny ostatní. Pro údržbu a velikost souboru ^[1] použijte malá písmena:

Hexadecimální hodnoty barev jako #fff (pokud je to možné, zkrácený zápis) nebo #fefefe.
Hodnoty rgba(), pokud je nutná průhlednost alfa > 0
Barevné klíčové slovo transparent (Pozor na některá upozornění <= IE9)

Vyhněte se jiným barevným hodnotám klíčových slov, rgb(), hsl() a hsla() zápisům. Také se ujistěte, že váš barevný kontrastní poměr popředí a pozadí (stejný pro přechody pozadí) by měl dosahovat alespoň úrovně AA, ale lepší AAA WCAG 2.0.^[2]

Přečtěte si více na MDN.

Předpony dodavatele

V případě předpon dodavatele CSS vždy umístěte novější verze za starší verze a na konec uveďte standardizovanou deklaraci. Více na stránce https://css-tricks.com/ordering-css3-properties/.

/* Špatně */
.bar {
	border-radius: 30px 10px;
	-webkit-border-radius: 30px 10px;
}

/* Správně */
.bar {
	-webkit-border-radius: 30px 10px;
	/* Je důležité, aby verze -webkit byla před standardizovanou verzí.
	 * Jinak to přepíše (jak se očekává v CSS), včetně spuštění
	 * chyby staré verze -webkit-, které WebKit od té doby opravil (v CSS3), ale zachovává
	 * ve staré implementaci (pro zpětnou kompatibilitu).
	 */
	border-radius: 30px 10px;
}

/* Špatně */
.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));
}

/* Správně */
.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);
}

/* Správně (komentováno) */
.foo {
	/* Záložní barva v případě, že je obrázek na pozadí poškozený nebo není podporován */
	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 a .client-nojs

MediaWiki vypíše třídu client-nojs na element ‎<html> na každé stránce. Za běhu jej kód JavaScript nahradí třídou client-js. Proto můžete tuto třídu použít ve svém selektoru k podmíněnému zobrazení, skrytí nebo přizpůsobení určitých prvků v závislosti na tom, zda má prohlížeč povolen JavaScript a zda jej podporuje ResourceLoader . Všimněte si, že aby to bylo užitečné, dotyčná šablona stylů nesmí být načtena s mw.loader (viz Vývoj s ResourceLoader )

Anti vzory

z-index

Pokud je to možné, nepoužívejte z-index. Místo toho zkuste použít přirozené pořadí překrývání v DOM. Mezi známé výjimky patří:

Compact Personal Bar a 100
Page Previews začíná v 110
Vyskakovací okno navigace od 1000.

!important

Nepoužívejte !important (s výjimkou obcházení upstream kódu spuštěného na stejné stránce, která také používá !important, protože pouze !important může přepsat !important).

Ve většině případů to vůbec nepotřebujete (např. paranoia). V jiných případech to může být výsledek chyby jinde v programu. Obecně platí, že k přepsání pravidla použijete stejný selektor jako původní pravidlo stylu. Vzhledem k tomu, že u kaskády CSS, to funguje přirozeně (styly použité později přepisují styly použité dříve, selektory nemusí mít vyšší specifičnost).^[3]

Pokud se přepisující styly použijí před původními styly, styly se načtou ve špatném pořadí. To by se mělo řešit, ale můžete se uchýlit k řešení, jak uměle zvýšit specifičnost:

Opakujte stejný výběr pro zvýšení vážnosti, například .foo.foo.foo.foo.^[4]
Přidejte nebo opakujte selektory atributů, například [class].
Použijte výchozí prvky jako selektor předchůdce (např. body .foo, html body .foo).

Přidejte tolik bodů, kolik potřebujete. Stále to umožní více šablonám stylů používat stejnou techniku a každý vyjadřovat svou specifičnost. Lepší než přidávání tříd předků, které nesouvisejí s vaším kódem. (A udržitelnější, protože se nemění.)

LESS

Počínaje MediaWiki 1.22 je v ResourceLoader nativní podpora pro transparentní použití LESS (s příponou .less) místo CSS. Většinu syntaxe LESS lze formátovat pomocí konvencí CSS:

Odsazení vnořených bloků s 1 tab (stejné jako pro odsazení deklarací uvnitř pravidel CSS).
Nezarovnávejte hodnoty deklarací mezerami uvnitř mixinů (stejně jako u pravidel CSS).
Žádné mezery na vnější straně seznamů parametrů ve vyvolání funkcí, použití mixinu a definicích mixinu (stejné jako pro url( image.png ) v CSS).
Žádné uvozovky kolem hodnot parametrů (stejné jako pro url( image.png ) v CSS).

Příklad:

/*
	Do kódu nemusíte kopírovat '.background-image'.
	Poskytuje jej jádro MediaWiki (v mediawiki.less).
	Je zde jako příklad syntaxe guard.
*/
.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;
	}
}

Níže je uvedeno několik nových konceptů, které neodpovídají konvencím CSS.

Struktura

Vnořená pravidla CSS oddělte od nadřazených deklarací 1 prázdným řádkem.
Tagy @noflip musí být na řádku bezprostředně nad deklarací, jak je znázorněno v příkladu výše.

Import

Název souboru příkazu importu by měl vynechat příponu souboru .less.
Použijte @import k načtení mixinů a proměnných, aby je mohl používat aktuální styl LESS. Ty jsou zpracovávány synchronně pomocí phpless a nejsou přítomny ve vygenerovaném výstupu CSS.
Nepoužívejte @import k seskupování stylů, které spolu souvisejí pouze koncepčně. Místo toho odkazujte na sadu souborů v poli styles modulu ResourceLoader.

Odstraňování problémů

Pokud váš import LESS nefunguje, zkontrolujte několik věcí:

Obsahuje váš kód @font-face? Viz tato otázku na StackOverflow o tom, jak používat @font-face s LESS.

Knihovna MediaWiki LESS

resources/src/mediawiki.less/mediawiki.mixins.less je běžná knihovna LESS pro MediaWiki. Adresář je v $wgResourceLoaderLESSImportPaths, takže k němu nemusíte uvádět úplnou cestu. Například:

@import "mediawiki.mixins";

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

Mixins

Mixin názvy by měly používat pomlčku-malá písmena, stejně jako CSS vlastnosti.

Měly by mít předponu mixin-, aby nedošlo ke zmatení vývojářů, kteří znají CSS, ale ne LESS, a odlišili je od tříd, jejichž syntaxe je podobná.

Jak bylo uvedeno výše, žádné mezery na vnější straně seznamu parametrů a vyvarujte se uvozování hodnot.

Pokud potřebujete volat mixin s jedním nebo více argumenty, které obsahují čárku, použijte k oddělení argumentů středník ; v LESS. Tím se uvolní čárka, která bude použita v doslovné hodnotě.

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

/* Správně */
.mw-example {
	.mixin-example(easy-in-out; opacity, color);

	/* Rozbalí se na: */
	transition-timing-function: easy-in-out;
	transition-property: opacity, color;
}

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

	/* Rozbalí se na: */
	transition-timing-function: 'easy-in-out';
	transition-property: 'opacity, color';

	/* Hodnoty zahrnují uvozovky, toto je neplatné CSS
	 * a výsledkem je, že prohlížeč tyto vlastnosti ignoruje
	 */
}

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

	/* Rozbalí se na: */
	transition-timing-function: easy-in-out;
	transition-property: opacity, color;

	/* Operátor ~ dá LESS pokyn, aby hodnoty zrušil.
	 * To vytváří dobré CSS, ale tomuto vzoru se vyhýbáme
	 * ve prospěch důsledného používání ';'.
	 */
}

Poznámky pod čarou

↑ Značení malými písmeny má menší výstup gzip, HTML5 Boilerplate 2015
↑ WCAG 2.0 Understanding Contrast
↑ Zvláštnosti CSS Specificity
↑ 3.14 věci, které jsem o CSS nevěděl, CSS Day Conference 2014

[1] Značení malými písmeny má menší výstup gzip, HTML5 Boilerplate 2015

[2] WCAG 2.0 Understanding Contrast

[3] Zvláštnosti CSS Specificity

[4] 3.14 věci, které jsem o CSS nevěděl, CSS Day Conference 2014

[1]

[2]

[3]

[4]