Svelte Scoped

Umiestnite vygenerované CSS pre štýly utilít každého Svelte komponentu priamo do bloku <style> Svelte komponentu namiesto do globálneho CSS súboru.

Tento komponent:

<div class="mb-1" />

sa transformuje na:

<div class="uno-ei382o" />

<style>
  :global(.uno-ei382o) {
    margin-bottom: 0.25rem;
  }
</style>

Kedy použiť

Use Case		Description	Package to Use
Menšie aplikácie	❌	Mať 1 globálny CSS súbor je pohodlnejšie. Použite bežný Vite plugin pre Svelte/SvelteKit.	unocss/vite
Väčšie aplikácie	✅	Svelte Scoped vám môže pomôcť vyhnúť sa neustále rastúcemu globálnemu CSS súboru.	@unocss/svelte-scoped/vite
Knižnica komponentov	✅	Vygenerované štýly sa umiestnia priamo do zostavených komponentov bez potreby používať UnoCSS v build pipelíne aplikácie.	@unocss/svelte-scoped/preprocess

Ako to funguje

Bežné nastavenie UnoCSS/Tailwind CSS umiestňuje štýly utilít do globálneho CSS súboru so správnym poradím. Na rozdiel od toho, Svelte Scoped distribuuje vaše štýly do mnohých ľubovoľne usporiadaných CSS súborov Svelte komponentov. Musí však udržať štýly utilít globálne, aby boli kontextovo uvedomelé podľa potreby pre veci ako right-to-left a iné prípady použitia uvedené nižšie. To predstavuje výzvu, ktorá je vyriešená použitím Svelte :global() wrapperu na odhlásenie sa z predvolenej metódy hashovania CSS Svelte a namiesto toho použitie hashu založeného na názve súboru + názve triedy na kompiláciu jedinečných názvov tried, ktoré môžu byť globálne bez konfliktov štýlov.

Použitie

Pretože Svelte Scoped prepisuje názvy vašich tried utilít, ste obmedzení v tom, kde ich môžete písať:

Supported Syntax	Example
Atribút triedy	<div class="mb-1" />
Direktíva triedy	<div class:mb-1={condition} />
Skratka direktívy triedy	<div class:logo />
Prop triedy	<Button class="mb-1" />

Svelte Scoped je navrhnutý tak, aby bol náhradou za projekt, ktorý používa štýly utilít. Ako také, výrazy nájdené v atribútoch triedy sú tiež podporované (napr. <div class="mb-1 {foo ? 'mr-1' : 'mr-2'}" />), ale odporúčame vám používať syntax direktívy triedy. Všimnite si tiež, že ak ste použili názvy tried inými spôsobmi, ako je ich umiestnenie v bloku <script> alebo používanie režimu attributify, budete musieť podniknúť ďalšie kroky pred použitím Svelte Scoped. Môžete využiť možnosť safelist a tiež skontrolovať sekciu presets nižšie pre ďalšie tipy.

Context aware

Aj keď sú štýly distribuované naprieč Svelte komponentmi vašej aplikácie, stále sú to globálne triedy a budú fungovať vo vzťahu k prvkom nájdeným mimo ich špecifických komponentov. Tu sú niektoré príklady:

Parent dependent

Triedy, ktoré závisia od atribútov nájdených v rodičovskom komponente:

<div class="dark:mb-2 rtl:right-0"></div>

sa zmení na:

<div class="uno-3hashz"></div>

<style>
  :global(.dark .uno-3hashz) {
    margin-bottom: 0.5rem;
  }
  :global([dir="rtl"] .uno-3hashz) {
    right: 0rem;
  }
</style>

Children influencing

Môžete pridať medzeru medzi 3 dcérske prvky, z ktorých niektoré sú v samostatných komponentoch:

<div class="space-x-1">
  <div>Status: online</div>
  <Button>FAQ</Button>
  <Button>Login</Button>
</div>

sa zmení na:

<div class="uno-7haszz">
  <div>Status: online</div>
  <Button>FAQ</Button>
  <Button>Login</Button>
</div>

<style>
  :global(.uno-7haszz > :not([hidden]) ~ :not([hidden])) {
    --un-space-x-reverse: 0;
    margin-left: calc(0.25rem * calc(1 - var(--un-space-x-reverse)));
    margin-right: calc(0.25rem * var(--un-space-x-reverse));
  }
</style>

Passing classes to child components

Môžete pridať prop class do komponentu na umožnenie odovzdania vlastných tried všade, kde sa tento komponent používa.

<Button class="px-2 py-1">Login</Button>

sa zmení na:

<Button class="uno-4hshza">Login</Button>

<style>
  :global(.uno-4hshza) {
    padding-left:0.5rem;
    padding-right:0.5rem;
    padding-top:0.25rem;
    padding-bottom:0.25rem;
  }
</style>

Jednoduchý spôsob implementácie triedy v prijímajúcom komponente by bolo umiestniť ich na prvok pomocou {$$props.class} ako v div class="{$$props.class} foo bar" />.

Apply directives

Môžete použiť apply direktívy vo vašich blokoch <style> buď s --at-apply alebo @apply alebo vlastnou hodnotou nastavenou pomocou možnosti applyVariables.

Svelte Scoped dokonca správne spracováva triedy závislé od kontextu ako dark:text-white, ktoré bežný balík @unocss/transformer-directives nedokáže správne spracovať, pretože nebol postavený špecificky pre Svelte bloky štýlov. Napríklad, so Svelte Scoped tento komponent:

<div />

<style>
  div {
    --at-apply: rtl:ml-2;
  }
</style>

sa transformuje na:

<div />

<style>
  :global([dir=\\"rtl\\"]) div {
    margin-right: 0.5rem;
  }
</style>

Aby rtl:ml-2 fungovalo správne, selektor [dir="rtl"] je zabalený s :global(), aby sa zabránilo automatickému odstráneniu Svelte kompilátorom, keďže komponent nemá žiadny prvok s týmto atribútom. Avšak, div nemôže byť zahrnutý v :global() wrapperi, pretože by tento štýl ovplyvnil každý div vo vašej aplikácii.

Other style block directives

Použitie theme() je tiež podporované, ale @screen nie je.

Vite Plugin

V aplikáciách Svelte alebo SvelteKit vstreknite vygenerované štýly priamo do vašich Svelte komponentov, pričom umiestnite minimálne potrebné štýly do globálneho stylesheetu. Pozrite si SvelteKit example v Stackblitz:

Inštalácia

pnpm

pnpm add -D unocss @unocss/svelte-scoped

yarn

yarn add -D unocss @unocss/svelte-scoped

npm

npm install -D unocss @unocss/svelte-scoped

bun

bun add -D unocss @unocss/svelte-scoped

Pridať plugin

Pridajte @unocss/svelte-scoped/vite do vášho Vite configu:

import { sveltekit } from '@sveltejs/kit/vite'
import UnoCSS from '@unocss/svelte-scoped/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UnoCSS({
      // injectReset: '@unocss/reset/normalize.css', // pozrite definíciu typu pre všetky zahrnuté možnosti resetu alebo ako odovzdať vlastný
      // ...ostatné možnosti Svelte Scoped
    }),
    sveltekit(),
  ],
})

Pridať konfiguračný súbor

Nastavte váš súbor uno.config.ts ako je popísané nižšie.

Globálne štýly

Aj keď sú takmer všetky štýly umiestnené do jednotlivých komponentov, stále je niekoľko, ktoré musia byť umiestnené do globálneho stylesheetu: preflights, safelist a voliteľný reset (ak použijete možnosť injectReset).

Pridajte placeholder %unocss-svelte-scoped.global% do vášho tagu <head>. V Svelte je to index.html. V SvelteKit to bude v app.html pred %sveltekit.head%:

<head>
  <!-- ... -->
  <title>SvelteKit using UnoCSS Svelte Scoped</title>
  %unocss-svelte-scoped.global%
  %sveltekit.head%
</head>

Ak používate SvelteKit, musíte tiež pridať nasledujúce do hooku transformPageChunk vo vašom súbore src/hooks.server.js:

/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
  const response = await resolve(event, {
    transformPageChunk: ({ html }) =>
      html.replace(
        '%unocss-svelte-scoped.global%',
        'unocss_svelte_scoped_global_styles'
      ),
  })
  return response
}

Táto transformácia musí byť v súbore, ktorého cesta obsahuje hooks a server (napr. src/hooks.server.js, src/hooks.server.ts), keďže svelte-scoped bude hľadať vo vašom súbore server hooks na nahradenie unocss_svelte_scoped_global_styles vašimi globálnymi štýlmi. Uistite sa, že neimportujete túto transformáciu z iného súboru, napríklad pri používaní sequence z @sveltejs/kit/hooks.

V bežnom Svelte projekte, Vite hook transformIndexHtml to urobí automaticky.

Svelte Preprocessor

Používajte štýly utilít na zostavenie knižnice komponentov, ktorá nie je závislá na zahrnutí sprievodného CSS súboru použitím preprocesora na umiestnenie vygenerovaných štýlov priamo do zostavených komponentov. Pozrite si SvelteKit Library example v Stackblitz:

Inštalácia

pnpm

pnpm add -D unocss @unocss/svelte-scoped

yarn

yarn add -D unocss @unocss/svelte-scoped

npm

npm install -D unocss @unocss/svelte-scoped

bun

bun add -D unocss @unocss/svelte-scoped

Pridať preprocesor

Pridajte @unocss/svelte-scoped/preprocess do vášho Svelte configu:

import adapter from '@sveltejs/adapter-auto'
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte'
import UnoCSS from '@unocss/svelte-scoped/preprocess'

const config = {
  preprocess: [
    vitePreprocess(),
    UnoCSS({
      // ... možnosti preprocesora
    }),
  ],
  // ostatný Svelte config
}

Nekombinovať názvy tried vo vývoji

Pri používaní Svelte Scoped v bežnej aplikácii, Vite plugin automaticky deteguje dev vs build. Vo vývoji budú triedy ponechané odlišné a hashované na mieste pre jednoduché zapínanie/vypínanie v nástrojoch vývojára vášho prehliadača. class="mb-1 mr-1" sa zmení na niečo ako class="_mb-1_9hwi32 _mr-1_84jfy4. V produkcii budú tieto skompilované do jedného názvu triedy pomocou vášho požadovaného prefixu, predvolene uno-, a hashu založeného na názve súboru + názvoch tried, napr. class="uno-84dke3.

Ak chcete toto isté správanie pri používaní preprocesora, musíte manuálne nastaviť možnosť combine na základe prostredia. Jeden spôsob, ako to urobiť, je nainštalovať cross-env a aktualizovať váš dev script na toto:

"dev": "cross-env NODE_ENV=development vite dev"

Potom upravte váš svelte.config.js:

+const prod = process.env.NODE_ENV !== 'development'
const config = {
  preprocess: [
    vitePreprocess(),
    UnoCSS({
+      combine: prod,
    }),
  ],
}

Pridať konfiguračný súbor

Nastavte váš súbor uno.config.ts ako je popísané nižšie.

Preflights

Pri používaní preprocesora máte možnosť zahrnúť preflights do špecifických komponentov, kde sú potrebné, pridaním uno-preflights ako atribútu štýlu.

<style uno-preflights></style>

Akékoľvek špeciálne preflights, ktoré začínajú bodkou, napríklad .prose :where(a):not(:where(.not-prose, .not-prose *)), budú zabalené s :global(), aby sa zabránilo automatickému odstráneniu Svelte kompilátorom.

Pridávanie preflights do jednotlivých komponentov je zbytočné, ak vaše triedy nezávisia na preflights alebo ak sú vaše zostavené komponenty používané iba v aplikáciách, ktoré už zahŕňajú preflights.

Safelist

Pri používaní preprocesora máte možnosť zahrnúť triedy safelist do komponentu pridaním uno-safelist ako atribútu štýlu.

<style uno-safelist></style>

Vaše štýly safelist budú zabalené s :global(), aby sa zabránilo automatickému odstráneniu Svelte kompilátorom.

Configuration

Umiestnite nastavenia UnoCSS do súboru uno.config.ts:

import { defineConfig } from 'unocss'

export default defineConfig({
  // ...UnoCSS možnosti
})

Extractors nie sú podporované kvôli rozdielom v bežnom globálnom používaní UnoCSS a používaní Svelte Scoped. Presets a Transformers sú podporované ako je popísané v nasledujúcich sekciách. Pozrite Config File a Config reference pre všetky ostatné detaily.

Presets support

Kvôli povahe mať niekoľko potrebných štýlov v globálnom stylesheete a všetko ostatné obsiahnuté v každom komponente, kde je potrebné, presety musia byť spracované individuálne:

Preset	Supported	Notes
@unocss/preset-uno, @unocss/preset-mini, @unocss/preset-wind3, @unocss/preset-icons, @unocss/web-fonts	✅	Tieto a všetky komunitné pluginy, napr. unocss-preset-forms, ktoré sa spoliehajú iba na rules/variants/preflights budú fungovať.
@unocss/preset-typography	✅	Kvôli tomu, ako tento preset pridáva rulesets do vašich preflights, musíte pridať triedu prose do vášho safelistu pri používaní tohto presetu, inak sa preflights nikdy nespustia. Všetky ostatné triedy z tohto presetu, napr. prose-pink, môžu byť komponentovo scoped.
@unocss/preset-rem-to-px	✅	Toto a všetky presety ako ony, ktoré iba upravujú výstup štýlu budú fungovať.
@unocss/preset-attributify	-	Preset nebude fungovať. Namiesto toho použite unplugin-attributify-to-class Vite plugin (attributifyToClass({ include: [/\.svelte$/]})) pred Svelte Scoped Vite pluginom
@unocss/preset-tagify	-	Presety, ktoré pridávajú vlastné extractory nebudú fungovať. Vytvorte preprocesor na konverziu <text-red>Hi</text-red> na <span class="text-red">Hi</span>, potom vytvorte PR na pridanie odkazu sem.

Pre ostatné presety, ak sa nespoliehajú na tradičné používanie class="...", budete musieť najprv preprocessovať tieto názvy tried do atribútu class="...". Ak pridávajú presety ako typography's .prose trieda, budete musieť umiestniť triedy, ktoré spúšťajú pridania presetu, do vášho safelistu.

Transformers support

Transformers sú podporované pre vaše CSS súbory (css|postcss|sass|scss|less|stylus|styl). Na ich použitie pridajte transformer do možnosti cssFileTransformers vo vašom vite.config.ts:

import transformerDirectives from '@unocss/transformer-directives'

export default defineConfig({
  plugins: [
    UnoCSS({
      cssFileTransformers: [transformerDirectives()],
    }),
    sveltekit(),
  ],
})

INFO

Transformers nie sú podporované v Svelte komponentoch kvôli tomu, ako Svelte Scoped funguje.

Scoped utility classes unleash creativity

Niektoré rady, kedy môžete chcieť použiť scoped štýly: Ak ste dospeli do bodu v živote veľkého projektu, keď zakaždým, keď použijete triedu ako .md:max-w-[50vw], o ktorej viete, že sa používa iba raz, stiahnete sa, pretože cítite, že veľkosť vášho globálneho stylesheetu sa zväčšuje a zväčšuje, potom vyskúšajte tento balík. Váhavosť použiť presne triedu, ktorú potrebujete, inhibuje kreativitu. Samozrejme, mohli by ste použiť --at-apply: md:max-w-[50vw] v bloku štýlu, ale to sa stáva únavným a štýly v kontexte sú užitočné. Navyše, ak by ste chceli zahrnúť veľké množstvo ikon do vášho projektu, začnete cítiť váhu ich pridávania do globálneho stylesheetu. Keď každý komponent nesie váhu svojich vlastných štýlov a ikon, môžete pokračovať v rozširovaní vášho projektu bez potreby analyzovať náklady a výhody každého nového pridania.

License

• MIT License © 2022-PRESENT Jacob Bowdoin