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.
 * Annotation for and  should be on their own line, above the CSS declaration they're for.
 * 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  . It draws   as black.)

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.

Read further at 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  ).

CSS variables example:

LESS variables example:



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. Hence you can use this class in your selector to conditionally show, hide, or customize 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 vzory
Anti-patterns are mostly covered by use of central 'stylelint-config-wikimedia' already. 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.

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

!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. Since CSS cascades, this works naturally (styles applied later override styles applied earlier, selectors don't need to be of higher specificity).

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
Starting with MediaWiki 1.22, there is native support in ResourceLoader for using LESS (with file extension ) in place of 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.
 * If the extension was omitted, in a folder with 'foo.css' and 'foo.less' LESS would import the latter.
 * 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.
 * 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.



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


 * Does your code contain ? See this question on Stack Overflow about how to use @font-face with 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.

Since, the built-in mixins contain utilities for using 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í: