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. It will still allow multiple stylesheets to use the same technique and each express their specificity. Better than adding in ancestors classes not related to your code. ( And more maintainable as they won't change. )

LESS
Starting with MediaWiki 1.22, there is native support in ResourceLoader for using LESS (with file extension ) in place of CSS. Most of the LESS syntax can be formatted using the CSS conventions:


 * Indent nested blocks with 1 tab (same as for indenting declarations inside CSS rules).
 * Don't space-align declarations values inside mixins (same as for CSS rules).
 * No spaces on the outside of the parameter lists in function invocations, mixin uses and mixin definitions (same as for  in CSS).
 * No quotes around parameter values (same as for  in CSS).

Example:

There's a few new concepts that don't map to CSS conventions, outlined below.

Struktura

 * Separate nested CSS rules from the parent declarations by 1 empty line.
 * tags must be on the line immediately above the declaration, as shown in the example above.



Import souborů LESS/CSS

 * The filename of an import statement has to include the  file extension.
 * If the extension was omitted, in a folder with 'foo.css' and 'foo.less' LESS would import the latter.
 * If the code is ever used outside MediaWiki context, for example in Webpack as part of storybook, it will throw an error as it will assume it is a package with an index.css or index.js file meaning the code cannot be used.
 * Use  to load mixins and variables so that they may be used by the current LESS stylesheet; these are processed synchronously by LESS and will not be present in the generated CSS output. Load mixins first, variables second. Mixins should be free of variable values and parameters in mixin calls provide values with variables.
 * Don't use  to bundle stylesheets that are related to one another only conceptually; instead, reference the set of files in the   array of a ResourceLoader module.
 * 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
If your LESS  doesn't work please check:


 * Does your code contain ? See this question on Stack Overflow about how to use @font-face with LESS.

Mixins
Mixin names should use hyphen-case, just like CSS class names, property keys and variable names.

They should be prefixed with  to avoid confusing developers who are familiar with CSS, but not LESS and distinguish them from classes, the syntax for which is similar.

As mentioned above, no spaces on the outside of the parameter list and avoid quoting values.

If you need to call a mixin with one or more arguments that contain a comma use a semicolon  in LESS to separate the arguments. This allows you to use commas in the literal value.



Vestavěné mixiny
is a LESS library maintained as part of MediaWiki that is automatically available to any LESS stylesheet in MediaWiki. It can be imported from any LESS stylesheet in core, skins, and extensions.

Since, the built-in mixins contain utilities for using CSS Flexbox. Support is present all browsers that implemented at least one of the specs, including Internet Explorer 10. You need to specify your own fallback for older browsers, e.g. you can use floats for a more basic experience. Mixins available:

Example usage: