Manual:Coding conventions/CSS/cs

Tato stránka popisuje kódovací konvence pro styly CSS a LESS v MediaWiki codebase.

Odkazování
Jako nástroj pro kvalitu kódu používáme stylelint s vlastní konfigurací pro Wikimedii (stylelint-config-wikimedia). K lintování CSS nebo LESS můžete použít modul uzlu. MediaWiki a většina rozšíření ji spouští jako součást. Nastavení jádra MediaWiki najdete v.

Pojmenovávání
Třídy pojmenujte stejným způsobem: Všechna písmena malá a slova rozdělená pomlčkami. V jádru MediaWiki používejte předponu, abyste se vyhnuli konfliktům s názvy tříd a ID vytvořenými uživateli ze šablon wikitextu, nadpisů sekcí, gadgetů a dalších softwarových knihoven. Kde je to možné, vyhněte se zavádění ID a místo toho používejte třídy CSS.

Příklady použití:

Všimněte si, že slova jsou rozdělena pomlčkami, aby se zjednodušila čitelnost kódu pro nerodilé mluvčí angličtiny a aby programátorům, kteří spoléhají na asistenční technologii, poskytla lepší zkušenost, například výstup pro čtečku obrazovky. je historický název třídy, který se datuje před výše uvedenou radou. Podle této by to bylo.

V rozšířeních a vzhledech použijte předponu nebo.

Příklady použití:



Konstruované názvy tříd
Při dynamickém vytváření názvů tříd v kódu se ujistěte, že je výše umístěn komentář, který uvádí všechny možné názvy tříd. Viz také Příručka:Konvence kódování#Dynamické identifikátory. Například:

Specifičnost
Poskytněte selektory s co možná nízkou specifitou, pokud možno jeden selektor třídy modulu. To zjednodušuje jejich přepisování v konkrétních kontextech, jako jsou určitá rozšíření nebo uživatelské skripty.

Mezery
Milujeme mezery:


 * Jeden selektor na řádek.
 * Jedno prohlášení o vlastnosti na řádek.
 * Otevírací složené závorky pro blok deklarace CSS na stejném řádku jako (poslední) selektor.
 * Otevírací složené závorky pro blok deklarace CSS na stejném řádku jako (poslední) selektor.
 * Žádná mezera před dvojtečkou.
 * Jedna mezera za dvojtečkou a před hodnotou.
 * Jedna mezera za čárkami ve vlastnostech s více hodnotami.
 * Jedna mezera za začátkem a před koncem uvede ( a  ) v selektorech (např.  ) ​​​​a vlastnostech (např.  ).
 * Středník za každou deklarací (včetně poslední).
 * Zavírací závorky odsazeny zpět doleva.
 * Anotace pro a  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ší.

Citáty
Wikimedie používá jednoduché uvozovky pro hodnoty, které vyžadují citaci. Například hodnoty vlastnosti CSS  a v selektorech atributů.

Uvozovky jsou v parametru  deklarace   zbytečné. Jediným případem, kdy by to mohlo způsobit problémy, je situace, kdy se v cestě objeví neescapovaná uzavírací závorka. V takovém případě byste měli takové znaky v URL vynechat.



Hodnoty vlastností barev
CSS3 podporuje mnoho různých druhů hodnot barev pro vlastnosti CSS, jako je,  ,   a další. Pro konzistenci a kompatibilitu používejte pouze tyto tři:


 * Hexadecimální hodnoty barev jako  a  . (Používejte malá písmena pro lepší kompresi gzip! Pokud je to možné, používejte zkrácený zápis.)
 * Hodnoty, pokud je vyžadována průhlednost alfa, například  . (Upozornění: IE8 nepodporuje zápis  , proto vždy před tímto zápisem uveďte odpovídající deklaraci s hexadecimální hodnotou barvy jako záložní.)
 * barevné klíčové slovo. (Pozor: IE8 to podporuje pouze za  a  . Kreslí   jako černý.)

Upřednostňujte všechny hodnoty "malými písmeny" pro konzistenci a optimalizovanou kompresi souborů. Viz také sekce stránky Talk.

Vyhněte se jiným hodnotám barev (včetně názvů barev/klíčových slov – myslete na i18n, když si představíte zápisy,  ,   a  ). Také se ujistěte, že váš barevný kontrastní poměr popředí a pozadí (včetně přechodů pozadí a záložních barev) odpovídá WCAG 2.0 Level AA, ideálně Level AAA.

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



Jednotky velikosti
Wikimedia Foundation si klade za cíl podporovat různorodé publikum a širokou škálu technologií a případů použití. Velmi oblíbeným uživatelským nastavením přístupnosti je zvětšení výchozí velikosti písma prohlížeče a zároveň poskytnutí nejlepšího designu pro průměrné uživatele. Také snižuje zátěž kalkulace  a předvídatelnost pro vývojáře na naprosté minimum. Použijte  pro všechny prvky, které přímo neovlivňují čtení nebo porozumění uživatelskému rozhraní. Většinou,  , velikost ikony o   nebo.



Název proměnné
Proměnné CSS a LESS jsou nastaveny tak, aby se řídily logikou pojmenování, od opakování vlastnosti přes použití aplikace až po možný modifikátor nebo ve zkratce. Proměnné se obecně používají pro jednu vlastnost, jako je, existuje jen velmi málo proměnných, které lze použít v různých kontextech. Například proměnná velikosti.

Je to jednodušší, konkrétně ve velkých projektech s mnoha soubory CSS/LESS mít proměnné pro jedno použití, i když to může vést k většímu souboru definice proměnných. Popis problému viz archivovaná diskuze. Je také bezpečnější, když se změní obsah proměnné (předpokládejme aplikace  versus  ).

Příklad proměnných CSS:

Příklad proměnných LESS:



Předpony dodavatele
Standardizované verze vlastností CSS vždy umístěte „za“ verze s předponou dodavatele. Je to důležité pro zamezení chybám ve staré implementaci, jako v následujícím příkladu. Více na stránce https://css-tricks.com/ordering-css3-properties/.

Správně a včetně anotace:



.client-js a .client-nojs
MediaWiki vypíše třídu  na element  na každé stránce. Za běhu to kód JavaScript nahradí třídou. 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. Všimněte si, že aby to bylo užitečné, musí být v příslušné šabloně stylů načtena hodnota, nikoli  (viz )

Anti vzory
Anti-vzory jsou již většinou pokryty použitím centrálního 'stylelint-config-wikimedia'. Podívejte se také na vložené komentáře k předloze. Kromě toho existují některé speciální vlastnosti/funkce, které si zaslouží další vysvětlení.



Nespoléhejte na hodnoty založené na jednotkách px
Není to obecné pravidlo, ale pro několik vlastností to platí obecně. Když uživatel zvýší své výchozí předvolby velikosti písma v prohlížeči kvůli řešení zrakového postižení, což je široce používaná funkce usnadnění, všechny velikosti definované v  se nezmění. Chcete-li uživatelům umožnit měřítko textu s tímto nastavením, spolehněte se na relativní velikosti, jako je  nebo , konkrétně na vlastnosti, které by vedly k neškálovatelnému textu, jako je velikost písma nebo výška řádku, nebo by přetékal a byl skrytý, často s určitou šířkou. nebo výškové omezení.

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

Pokud je vyžadováno použití z-indexu, použijte prosím příslušný designový token Codex.

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

Ve většině případů to vůbec nepotřebujete. 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).

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:


 * Repeat the same selector to increase weight, like.
 * Add or repeat attribute selectors, like.
 * Use default elements as ancestor selector (e.g.,  ).

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 je v  nativní podpora pro použití LESS (s příponou souboru  ) místo CSS. Většinu syntaxe LESS lze formátovat pomocí konvencí CSS:


 * Odsazení vnořených bloků s 1 tabulátorem (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  v CSS).
 * Žádné uvozovky kolem hodnot parametrů (stejné jako pro  v CSS).

Příklad:

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  musí být na řádku bezprostředně nad deklarací, jak je znázorněno v příkladu výše.



Import souborů LESS/CSS

 * Název souboru příkazu importu musí obsahovat příponu souboru.
 * Pokud by byla přípona vynechána, do složky s 'foo.css' a 'foo.less' LESS by importovala druhou.
 * Pokud je kód někdy použit mimo kontext MediaWiki, například ve Webpacku jako součást storybook, vyvolá chybu, protože se bude předpokládat, že jde o balíček se souborem index.css nebo index.js, což znamená, že kód nemůže být použit.
 * Použijte  k načtení mixinů a proměnných, aby je mohl používat aktuální styl LESS. Ty jsou zpracovávány synchronně pomocí LESS a nebudou přítomny ve vygenerovaném výstupu CSS. Nejprve načtěte mixiny, poté proměnné. Mixiny by neměly obsahovat proměnné hodnoty a parametry ve voláních mixinů poskytují hodnoty s proměnnými.
 * Nepoužívejte  k seskupování stylů, které spolu souvisejí pouze koncepčně. Místo toho odkazujte na sadu souborů v poli   modulu ResourceLoader.
 * Nepoužívejte  k importu souborů CSS v souborech LESS, protože analyzátor LESS vytvoří neplatný příkaz importu na základě fyzického umístění souboru CSS. Místo ní používejte přímo.



Odstraňování problémů s importem
Pokud vaše LESS  nefunguje, zkontrolujte:


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

Mixins
Mixin názvy by měly používat pomlčku-malá písmena, stejně jako názvy tříd CSS, klíče vlastností a názvy proměnných.

Měly by mít předponu, 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 v LESS k oddělení argumentů středník. To vám umožní používat čárky v doslovné hodnotě.



Vestavěné mixiny
je knihovna LESS udržovaná jako součást MediaWiki, která je automaticky dostupná pro jakoukoli šablonu stylů LESS v MediaWiki. Lze jej importovat z libovolné šablony stylů LESS v jádru, vzhledech a rozšířeních.

Od obsahují vestavěné mixiny nástroje pro použití CSS Flexbox. Podpora je k dispozici pro všechny prohlížeče, které implementovaly alespoň jednu ze specifikací, včetně Internet Exploreru 10. Pro starší prohlížeče je třeba zadat vlastní záložní řešení, např. můžete použít plováky pro základnější zážitek. K dispozici mixiny:

Příklad použití: