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

shortcut: CC/LESS
From mediawiki.org
This page is a translated version of the page Manual:Coding conventions/CSS and the translation is 80% complete.
Languages:
Podívejte se na Příručka:CSS pro další upozornění a tipy, které nejsou zde uvedeny.

Pojmenovávání

Viz Manual:Interface/IDs and classes pro dokumentaci běžných ID a tříd.

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 */
.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.
  • Anotace pro CSSJanus a CSSMin by měla být na samostatném řádku, nad deklarací CSS, pro kterou je určena.
  • 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 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í.
	 * 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 {
	/* 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ří:

!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í:

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');
}

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;
}

/* 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.
	 */
}

Poznámky pod čarou

  1. ↑ Smallcase markup má menší výstup gzip, HTML5 Boilerplate 2015
  2. ↑ WCAG 2.0 Understanding Contrast
  3. ↑ Zvláštnosti CSS Specificity, css-tricks.com
  4. ↑ 3.14 věci, které jsem o CSS nevěděl, CSS Day Conference 2014


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