Příručka:Konvence pro psaní kódu/CSS
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ř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 polistyles
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