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

Tato stránka popisuje kódovací konvence používané v souborech MediaWiki codebase napsané v SVG. Viz také obecné konvence, které platí pro všechny programovací a značkovací jazyky, včetně SVG.

Jako optimalizační nástroj používáme SVGO, viz automatizovaná optimalizace níže.

Struktura kódu

Předpokladem je co nejjednodušší kód s ohledem na čitelnost.

Příklad jednoduchého optimalizovaného souboru – subtract.svg od OOUI:

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20">
	<title>
		subtract
	</title>
	<path d="M4 9h12v2H4z"/>
</svg>

Pro minimalisty lze kreslit úplně stejně

<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20">
    <path d="m4,9h12v2H4"/>
</svg>

Příklad trochu složitějšího, optimalizovaného souboru – BetaFeatures šablona snímku obrazovky:

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="264" height="162" viewBox="0 0 264 162">
    <title>
        BetaFeatures screenshot template
    </title>
    <defs>
        <clipPath id="jagged-edge">
            <path d="M0 0v152l12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10 12 10 12-10V0z"/>
        </clipPath>
    </defs>
    <g fill="#eaecf0" clip-path="url(#jagged-edge)">
        <path id="background" fill="#fff" d="M0 0h264v162H0"/>
        <path id="logo" d="M11 22c0-8 6-14 14-14s14 6 14 14-6 14-14 14-14-6-14-14M38 45v-5H13v5h25"/>
        <path id="sidebar" d="M38 163V58H13v106h25"/>
        <path id="personal-tools" d="M233 5h26v6h-26V5zM209 5h22v6h-22zM185 5h22v6h-22zM162 5h13v6h-13zM177 5h6v6h-6zM154 5h6v6h-6z"/>
        <path id="search-input" d="M258 16v4h-92v-4h92m1-1h-94v6h94v-6z"/>
        <path id="search-icon" d="M168 17h2v2h-2z"/>
        <path id="article" d="M252 162V29H48v133z"/>
        <path id="border" d="M0 0v162h264V0zm1 1h262v150.533l-11 9.166-12-10-12 10-12-10-12 10-12-10-12 10-12-10-12 10-12-10-12 10-12-10-12 10-12-10-12 10-12-10-12 10-12-10-12 10-12-10-12 10-11-9z"/>
    </g>
</svg>

V následující části vysvětlíme různé konvence kódování.

Automatická optimalizace (SVGO)

SVGO spravovali Kir Belevich (deepsweet ) a Lev Solntsev (GreLI ) od srpna 2012 až 2016 a od roku 2021 Bogdan Chadkin (TrySound ).

Jak používat

Je doporučeno instalovat svgo z https://github.com/svg/svgo nebo z npm pro příkazový řádek. K dispozici je také demo v prohlížeči, které vám pomůže s náhledem a obecným pochopením nástroje na https://jakearchibald.github.io/svgomg/. Toto by se však nemělo používat k vytváření produkčních souborů.

Bezpečné pluginy:

Protože některé výchozí zásuvné moduly (možnosti) SVGO mohou mít za následek neočekávaný vzhled u složitějších zásuvných modulů SVG, rozlišujeme mezi bezpečnými, podstatně méně bezpečnými a nebezpečnými zásuvnými moduly. Nastavte "transformPrecision" alespoň na 7, abyste snížili riziko poškození souborů. Při používání nebezpečných zásuvných modulů se doporučuje ověřit před a po rozdílu na soubor, aby byla zajištěna vizuální kvalita.

Uvádíme pouze pluginy, které jsou změněny z výchozího nastavení nebo které mohou být neintuitivní:

• Atributy řazení sortAttrs.
  Povolit nastavením na true. Ve výchozím nastavení zakázáno
• Pokud je to možné, odstraňte nebo vyčistěte atribut enable-background.
  Zastaralý atribut, podporován pouze IE/Edge; ve výchozím nastavení povoleno

Viz SVGO Readme pro další povolené, bezpečné pluginy.

Pluginy, které je třeba pečlivě zvážit: 

cleanupIDs	Odstraňte nepoužívaná a minifikujte použitá ID Může negativně ovlivnit čitelnost a porušit některé soubory. Ve výchozím nastavení povoleno
removeRasterImages	Obecné pravidlo je nebezpečné, může způsobit ztrátu dat, některé rastrové obrázky je obtížné rozpoznat; ve výchozím nastavení zakázáno
inlineStyles	Někteří uživatelé dávají přednost použití CSS než inlineStyles, což může snížit upravitelnost
removeDoctype	Pro SVG 1.1 není důvod jej odstraňovat, nicméně pro nadcházející SVG2-draft bude odepsán

Nebezpečná pravidla k deaktivaci (nepoužívejte!):

convertPathData	Může způsobit (i) nepřesné zobrazení, (ii) nesprávné zobrazení pomocí librsvg, (iii) porušení souborů. Ve výchozím nastavení povoleno
cleanupListOfValues	Zaokrouhlit/přepsat číselné seznamy přerušení Wikimedia-renderin
convertShapeToPath	Může snížit čitelnost a rozbije soubory
removeXMLProcInst	Odebrat pokyny pro zpracování XML, neboli deklarace XML <?xml version="1.0" encoding="UTF-8"?> Problémy při zobrazení jako samostatný soubor v některých editorech, také možné problémy s interpretací typu MIME Příklad: Pokud SVG nezačíná deklarací XML, pak bude jeho MIME typ detekován jako text/plain spíše než image/svg+xml pomocí libmagic a následně CSSMin CSS minifikátoru MediaWiki. Výchozí databáze libmagic aktuálně vyžaduje, aby SVG obsahovaly deklaraci XML. Deaktivovat nastavením na false. Ve výchozím nastavení povoleno
removeTitle	Odstranit ‎<title> Problematické z důvodů přístupnosti. Nastaveno na false. Ve výchozím nastavení povoleno
removeDesc	Odstranit ‎<desc> Problematické z důvodu dostupnosti. Nastaveno na false. Ve výchozím nastavení povoleno
removeViewBox	Odebrat atribut viewBox V některých prohlížečích má za následek obtížný vzhled, a proto by měly být uvedeny oba, width/height a viewbox. Nastaveno na false. Ve výchozím nastavení povoleno
removeDimensions	Odebere rozměry width/height, když bude dostupné viewbox Jak je uvedeno výše. Nastaveno na false. Ve výchozím nastavení zakázáno
removeMetadata	Možné informace o autorských právech
removeHiddenElems	Možné referenční čáry, data editoru, skutečný text před převodem, informace o autorských právech
removeUnknownsAndDefaults	odstraňuje Flow-Text
cleanupNumericValues	rozbíje některé soubory
minifyStyles	rozbíje některé soubory
removeComments	snižuje čitelnost a případně odstraňuje referenční řádky, data editoru, skutečný text před převodem, informace o autorských právech
removeEditorsNSData	snižuje upravitelnost pomocí editorů GUI-SVG
collapseGroups	reduced readability and editability and breaks some files
removeStyleElement	rozbíje některé soubory
removeOffCanvasPaths	rozbíje některé soubory
removeEmptyContainers	rozbíje některé soubory
removeElementsByAttr	rozbíje některé soubory
convertStyleToAttrs	rozbíje některé soubory
convertTransform	rozbíje některé soubory
cleanupNumericValues	rozbíje některé soubory
inlineStyles	porušuje některé funkce CSS
reusePaths	rozbíje některé soubory

Příklad bezpečné konfigurace

Všimněte si, že toto je pro svgo v1.x; v2.x přebírá různé argumenty CLI:

$ svgo path/to/image.svg --disable={cleanupIDs,convertPathData,removeDesc,removeTitle,removeViewBox,removeXMLProcInst} --enable='sortAttrs' --pretty --final-newline

Použijte výstup pretty pro kód čitelný pro člověka a v procesu odsazení kódu po tabulátorech.

Příklad bezpečné konfigurace (.svgo.config.js)

června 2023 - Kompatibilita s SVGO v3.0.0+, změna názvu nového pluginu cleanupIds. (phab:T324899)

ledna 2022 - Spouštěcí skripty NPM umožnily konfiguraci SVGO. (phab:T246321)

/**
 * SVGO Configuration
 * Compatible to v3.0.0+
 * Doporučené možnosti od:
 * https://www.mediawiki.org/wiki/Manual:Coding_conventions/SVG#Exemplified_safe_configuration
 */

'use strict';

module.exports = {
	plugins: [
		{
			// Set of built-in plugins enabled by default.
			name: 'preset-default',
			params: {
				overrides: {
					cleanupIds: false,
					removeDesc: false,
					removeTitle: false,
					removeViewBox: false,
					// Pokud SVG nezačíná deklarací XML, pak bude jeho MIME typ detekován jako "text/plain" spíše než "image/svg+xml" pomocí libmagic a následně i CSSMin CSS minifikátor MediaWiki.
					// Výchozí databáze libmagic aktuálně vyžaduje, aby soubory SVG obsahovaly deklaraci XML:
					// https://github.com/threatstack/libmagic/blob/master/magic/Magdir/sgml#L5
					removeXMLProcInst: false // https://phabricator.wikimedia.org/T327446
					convertPathData: false // https://github.com/svg/svgo/issues/880 https://github.com/svg/svgo/issues/1487
					removeMetadata: false // Copyright-Violation
					removeHiddenElems: false // source for converted text2path
					removeUnknownsAndDefaults: false // removes Flow-Text: https://commons.wikimedia.org/wiki/User:JoKalliauer/RepairFlowRoot
					cleanupNumericValues: false // https://github.com/svg/svgo/issues/1080
					minifyStyles: false //https://github.com/svg/svgo/issues/888
					removeComments: false //reduces readability
					removeEditorsNSData: false // https://github.com/svg/svgo/issues/1096
					collapseGroups: false // https://github.com/svg/svgo/issues/1057
					removeOffCanvasPaths: false //https://github.com/svg/svgo/issues/1732
					removeEmptyContainers: false // https://github.com/svg/svgo/issues/1194 https://github.com/svg/svgo/issues/1618
					convertTransform: fasle // https://github.com/svg/svgo/issues/988 https://github.com/svg/svgo/issues/1021
					cleanupNumericValues: false // https://github.com/svg/svgo/issues/1080
					inlineStyles: false // https://github.com/svg/svgo/issues/1486
				}
			}
		},
		'removeRasterImages',
		'sortAttrs'
	],
	// Set whitespace according to Wikimedia Coding Conventions.
	// @see https://github.com/svg/svgo/blob/main/lib/stringifier.js#L39 for available options.
	js2svg: {
		eol: 'lf',
		finalNewline: true,
		// Zde nakonfigurujte odsazení tabulátorů (výchozí 4 mezery), které používá '--pretty'.
		indent: "\t",
		pretty: true
	},
	multipass: true
}

Příklad bezpečné konfigurace (Gruntfile.js)

svgmin: {
	options: {
		js2svg: {
			indent: '\t',
			pretty: true
		},
		plugins: [ {
			cleanupIDs: false
		}, {
			removeDesc: false
		}, {
			removeRasterImages: true
		}, {
			removeTitle: false
		}, {
			removeViewBox: false
		}, {
			removeXMLProcInst: false
		}, {
			sortAttrs: true
		}, {
			convertPathData: false // https://github.com/svg/svgo/issues/880
		}, {
			removeMetadata: false // Copyright-Violation
		}, {
			removeHiddenElems: false // source for converted text2path
		}, {
			removeUnknownsAndDefaults: false // removes Flow-Text
		}, {
			cleanupNumericValues: false // https://github.com/svg/svgo/issues/1080
		}, {
			minifyStyles: false //https://github.com/svg/svgo/issues/888
		}, {
			removeComments: false //reduces readability
		}, {
			removeEditorsNSData: false // https://github.com/svg/svgo/issues/1096
		}, {
			collapseGroups: false // https://github.com/svg/svgo/issues/1057
		}, {
			removeOffCanvasPaths: false //https://github.com/svg/svgo/issues/1732
		}, {
			removeEmptyContainers:false // https://github.com/svg/svgo/issues/1194 https://github.com/svg/svgo/issues/1618
		}, {
			convertTransform: fasle // https://github.com/svg/svgo/issues/988 https://github.com/svg/svgo/issues/1021
		}, {
			cleanupNumericValues: false // https://github.com/svg/svgo/issues/1080
		}, {
			inlineStyles: false // https://github.com/svg/svgo/issues/1486
		} ]
	}
}

Ruční optimalizace

Kromě automatické optimalizace SVG je třeba zvážit další kroky:

• Ponechte si následující kód xml:space="preserve", <!--, <title, \n, \r, \t, <g, visibility="hidden", opacity="0", display="none", requiredFeatures=", <?xml version="1.0" encoding="UTF-8"?>, ‎<defs>, <rect, <style type="text/css", class=", data-name=, inkscape:label, <rdf:RDF, aria-label=, <inkscape:grid, <sodipodi:guide, sodipodi:cx=, sodipodi:cy=, sodipodi:rx=, sodipodi:ry=, sodipodi:type="arc", vector-effect=, inkscape:groupmode="layer", inkscape:label=, sodipodi:role="line", viz c:Help:směrnice SVG
• Odeberte standalone="no" z instrukce zpracování XML, protože je výchozí
• Malá písmena (pro lepší gzip) a hex hodnoty barev zkraťte, pokud je to možné, např. #fff místo #FFFFFF.
• Atributy, které jsou stejné pro skupinu prvků, lze místo toho použít na společný rodič ‎<g> nebo někdy dokonce specifikovat příkazem <svg (viz příklad: CHE Bettens COA.svg)
  To může snížit upravitelnost nebo čitelnost
• Spolehněte se na výchozí hodnoty, jako je fill="#000" a stroke-width="1".
• Syntaxe <path d="…"/> je téměř vždy kratší než syntaxe základních tvarů, jako je ‎<polygon> nebo dokonce ‎<rect>, nicméně ‎<circle>, ‎<ellipse>, ‎<rect> jsou obecně snadněji čitelné/upravitelné, a proto je obecně preferováno použití specifičtějších.
• V případě potřeby slučte prvky <path d="…"/>. Nedělejte to, pokud mají být obě cesty upravovány samostatně.
• Neodstraňujte nadbytečný atribut ry="…", pokud je shodný s rx="…", bude obtížnější jej číst/upravovat.
• Odstraňte nepotřebné fill-rule="…" a clip-rule="…". Tato pravidla mají vliv pouze na určité cesty, např. když se cesta protne.
• Hledejte chyby zaokrouhlení IEEE jako 0.999999998 nebo 1.000000003. Taková čísla zabírají místo, aniž by poskytovala další informace. Téměř vždy je lze odříznout, aniž by se cokoli vizuálně změnilo.
• Při kreslení pracujte s nezlomkovou pixelovou mřížkou a zarovnejte co nejvíce bodů na této mřížce. Tyto body mají mnohem vyšší šanci, že budou ve výsledném kódu reprezentovány jako krátká celá čísla.
• Vyberte mřížku bez zlomků tak, aby odpovídala rysům existujícího obrázku, a upravte velikost nebo překreslete tvary tak, aby na mřížku dopadalo co nejvíce bodů. Výsledek může být špatně zarovnaný a lze jej oříznout pomocí viewBox="<left> <top> <width> <height>".

Pokud se chcete ponořit ještě hlouběji, existují další optimalizace pro kompresi doručení, například:

• automatické zavírání cest (neboli odebrání z pro určité tvary),
• při vytváření cest používejte relativní příkazy (místo absolutních příkazů, např. "m" pro "move by" (přesunout o), místo "M" pro "move to" (přesunout do)),
• optimalizace pro zpětné reference komprese

Další nástroje

Další nástroje, které mohou být užitečné:

1. SvgWorkAroundBot
2. SVGOMG
3. scour
4. svgcleaner
5. další možnosti naleznete na stránce Nápověda:Pokyny pro SVG#Jak optimalizovat.

scour

Popis a historie

Tento optimalizátor byl jedním z prvních optimalizátorů: Od roku 2009 je součástí instalace Inkscape a lze jej používat ukládání souborů Inkscape pomocí "Optimalizovaného Inkscape SVG" a v roce 2013 oddělené do samostatného projektu dostupného na https://github.com/scour-project/scour. Spravuje jej Inscape-Developer Patrick Storz (Ede123).

Jak používat

Můžete jej použít v prohlížeči za https://svgworkaroundbot.toolforge.org/ nebo jej nainstalovat přes pip install scour z příkazového řádku (Linux-PC/Mac-PC/Windows).

bezpečné pluginy

Scour je velmi opatrný optimalizátor, nicméně některé pluginy stále mohou rozbít soubor nebo odstranit důležité neviditelné části, pro jistotu můžete použít scour -i input.svg -o output.svg --disable-simplify-colors --disable-style-to-xml --disable-group-collapsing --keep-editor-data --keep-unreferenced-defs --protect-ids-noninkscape --disable-embed-rasters --set-precision=8 --set-c-precision=8

svgcleaner

Popis a historie

Tento optimalizátor vyvíjel od ledna 2012 do roku 2022 Yevhenii Reizner. Zaměřuje se na dodržování aktuálních standardů w3c (SVG1.1). Ve srovnání s scour nebo svgo rozbije méně souborů , sníží velikost souboru o více a výkon je mnohem rychlejší.

Jak používat

Můžete jej použít v prohlížeči na https://svgworkaroundbot.toolforge.org/ nebo si jej stáhnout z https://github.com/RazrFalcon/svgcleaner-gui/releases.

bezpečné pluginy

Se soubory bude zacházeno podle standardů, ale někdy se mohou ukládat jiné než svg prvky, které jsou důležité pro čtení a/nebo úpravu souboru, pro jistotu můžete použít svgcleaner input.svg output.svg --allow-bigger-file --indent yes --resolve-use no --apply-transform-to-gradients yes --apply-transform-to-shapes yes --convert-shapes no --group-by-style no --join-arcto-flags no --join-style-attributes no --merge-gradients yes --regroup-gradient-stops yes --remove-comments no --remove-declarations no --remove-default-attributes yes --remove-desc no --remove-dupl-cmd-in-paths yes --remove-dupl-fegaussianblur yes --remove-dupl-lineargradient yes --remove-dupl-radialgradient yes --remove-gradient-attributes yes --remove-invalid-stops yes --remove-invisible-elements no --remove-metadata no --remove-needless-attributes yes --remove-nonsvg-attributes no --remove-nonsvg-elements no --remove-text-attributes no --remove-title no --remove-unreferenced-ids no --remove-unresolved-classes yes --remove-unused-coordinates yes --remove-unused-defs yes --remove-version yes --remove-xmlns-xlink-attribute yes --simplify-transforms yes --trim-colors yes --trim-ids no --trim-paths yes --ungroup-defs yes --ungroup-groups no --use-implicit-cmds yes --list-separator comma --paths-to-relative yes --remove-unused-segments yes --convert-segments yes --apply-transform-to-paths yes --coordinates-precision 2 --paths-coordinates-precision 5 --properties-precision 3 --transforms-precision 7