Svelte Scoped

Postavi generirani CSS za slogovne pripomočke vsake Svelte komponente neposredno v <style> blok Svelte komponente namesto v globalno CSS datoteko.

Ta komponenta:

<div class="mb-1" />

je transformirana v:

<div class="uno-ei382o" />

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

Kdaj uporabiti

Primer uporabe		Opis	Paket za uporabo
Manjše aplikacije	❌	Imeti 1 globalno CSS datoteko je bolj priročno. Uporabite običajni Vite vtičnik za Svelte/SvelteKit.	unocss/vite
Večje aplikacije	✅	Svelte Scoped vam lahko pomaga preprečiti nenehno rastočo globalno CSS datoteko.	@unocss/svelte-scoped/vite
Knjižnica komponent	✅	Generirani slogi so postavljeni neposredno v grajene komponente brez potrebe po uporabi UnoCSS v gradbenem cevovodu aplikacije.	@unocss/svelte-scoped/preprocess

Kako deluje

Običajna postavitev UnoCSS/Tailwind CSS postavi slogovne pripomočke v globalno CSS datoteko z ustreznim vrstnim redom. Nasprotno pa Svelte Scoped distribuira vaše sloge po mnogih poljubno urejenih Svelte komponentnih CSS datotekah. Vendar pa mora ohraniti slogovne pripomočke globalne, da omogoči, da so kontekstno ozaveščeni, kot je potrebno za stvari, kot so desno-proti-levemu in drugi primeri uporabe, navedeni spodaj. To predstavlja izziv, ki je rešen z uporabo Svelteovega :global() ovoja za izklop privzete Svelte CSS hashing metode in namesto tega uporabo hasha, ki temelji na imenu datoteke + imenu razreda, za kompajliranje edinstvenih imen razredov, ki so lahko globalni brez konfliktov slogov.

Uporaba

Ker Svelte Scoped prepisuje vaša imena razredov pripomočkov, ste omejeni, kje jih lahko zapišete:

Podprta sintaksa	Primer
Atribut razreda	<div class="mb-1" />
Direktiva razreda	<div class:mb-1={condition} />
Okrajšana direktiva razreda	<div class:logo />
Prop razreda	<Button class="mb-1" />

Svelte Scoped je zasnovan kot nadomestek za projekt, ki uporablja slogovne pripomočke. Kot tak so podprti tudi izrazi, najdeni znotraj atributov razreda (npr. <div class="mb-1 {foo ? 'mr-1' : 'mr-2'}" />), vendar priporočamo, da vnaprej uporabite sintaksno direktivo razreda. Upoštevajte tudi, da če ste uporabili imena razredov na druge načine, kot je njihovo postavljanje v blok <script> ali uporaba načina atributivnosti, boste morali pred uporabo Svelte Scoped sprejeti dodatne korake. Lahko uporabite možnost safelist in preverite razdelek prednastavitve spodaj za več nasvetov.

Kontekstno ozaveščeni

Čeprav so slogi distribuirani po Svelte komponentah vaše aplikacije, so še vedno globalni razredi in bodo delovali v odnosu do elementov, najdenih zunaj njihovih specifičnih komponent. Tukaj je nekaj primerov:

Odvisni od starša

Razredi, ki so odvisni od atributov, najdenih v starševski komponenti:

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

se spremenijo v:

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

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

Vpliv otrok

Lahko dodate prostor med 3 otroškimi elementi, od katerih so nekateri v ločenih komponentah:

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

se spremeni v:

<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>

Posredovanje razredov podrejenim komponentam

Lahko dodate prop class komponenti, da omogočite posredovanje prilagojenih razredov kjerkoli se ta komponenta uporablja.

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

se spremeni v:

<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>

Lahek način za implementacijo razreda v sprejemni komponenti je, da jih postavite na element z uporabo {$$props.class} kot v div class="{$$props.class} foo bar" />.

Uporaba direktiv apply

Lahko uporabite direktive apply znotraj vaših <style> blokov z uporabo --at-apply ali @apply ali prilagojene vrednosti, nastavljene z možnostjo applyVariables.

Svelte Scoped pravilno obravnava tudi kontekstno odvisne razrede, kot je dark:text-white, ki jih običajni paket @unocss/transformer-directives ne more pravilno obravnavati, ker ni bil zgrajen specifično za Svelte style bloke. Na primer, s Svelte Scoped ta komponenta:

<div />

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

bo transformirana v:

<div />

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

Da bi rtl:ml-2 pravilno deloval, je selektor [dir="rtl"] ovit z :global(), da se prepreči, da bi ga Svelte kompajler samodejno odstranil, saj komponenta nima elementa s tem atributom. Vendar pa div ne more biti vključen v :global() ovoj, ker bi ta slog vplival na vsak div v vaši aplikaciji.

Druge direktive style bloka

Uporaba theme() je prav tako podprta, vendar @screen ni.

Vite vtičnik

V aplikacijah Svelte ali SvelteKit vbrizgajte generirane sloge neposredno v vaše Svelte komponente, medtem ko postavite najmanj potrebne sloge v globalno stylesheet. Oglejte si primer SvelteKit v Stackblitz:

Namestitev

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

Dodaj vtičnik

Dodajte @unocss/svelte-scoped/vite v vašo Vite konfiguracijo:

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', // glejte definicijo tipa za vse vključene možnosti ponastavitve ali kako posredovati svoje
      // ...druge možnosti Svelte Scoped
    }),
    sveltekit(),
  ],
})

Dodaj konfiguracijsko datoteko

Nastavite vašo datoteko uno.config.ts, kot je opisano spodaj.

Globalni slogi

Čeprav so skoraj vsi slogi postavljeni v posamezne komponente, je še vedno nekaj, ki morajo biti postavljeni v globalni stylesheet: preflights, safelist in izbirna ponastavitev (če uporabljate možnost injectReset).

Dodajte nadomestni znak %unocss-svelte-scoped.global% v vašo <head> oznako. V Svelte je to index.html. V SvelteKit bo to v app.html pred %sveltekit.head%:

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

Če uporabljate SvelteKit, morate tudi dodati naslednje v hook transformPageChunk v vaši datoteki 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
}

Ta transformacija mora biti v datoteki, katere pot vključuje hooks in server (npr. src/hooks.server.js, src/hooks.server.ts), saj bo svelte-scoped iskal v vaši server hooks datoteki za zamenjavo unocss_svelte_scoped_global_styles z vašimi globalnimi slogi. Poskrbite, da ne boste uvozili te transformacije iz druge datoteke, kot pri uporabi sequence iz @sveltejs/kit/hooks.

V običajnem Svelte projektu bo Viteov hook transformIndexHtml to storil samodejno.

Svelte Preprocesor

Uporabite slogovne pripomočke za izgradnjo knjižnice komponent, ki ni odvisna od vključitve spremljajoče CSS datoteke, z uporabo preprocesorja za postavitev generiranih slogov neposredno v grajene komponente. Oglejte si primer SvelteKit Library v Stackblitz:

Namestitev

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

Dodaj preprocesor

Dodajte @unocss/svelte-scoped/preprocess v vašo Svelte konfiguracijo:

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 preprocesorja
    }),
  ],
  // druga Svelte konfiguracija
}

Ne združuj imen razredov v razvoju

Pri uporabi Svelte Scoped v običajni aplikaciji bo Vite vtičnik samodejno zaznal dev nasproti build. V razvoju bodo razredi ohranjeni ločeni in hashirani na mestu za lažje vklop/izklop v brskalnikovih orodjih za razvijalce. class="mb-1 mr-1" se bo spremenilo v nekaj kot class="_mb-1_9hwi32 _mr-1_84jfy4. V produkciji bodo ti kompajlirani v eno ime razreda z uporabo vaše želene predpone, uno- privzeto, in hasha, ki temelji na imenu datoteke + imenih razredov, npr. class="uno-84dke3.

Če želite enako vedenje pri uporabi preprocesorja, morate ročno nastaviti možnost combine glede na okolje. Eden od načinov je namestitev cross-env in posodobitev vaše dev skripte v to:

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

Nato prilagodite vaš svelte.config.js:

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

Dodaj konfiguracijsko datoteko

Nastavite vašo datoteko uno.config.ts, kot je opisano spodaj.

Preflights

Pri uporabi preprocesorja imate možnost vključitve preflights v specifične komponente, kjer so potrebni, z dodajanjem uno-preflights kot atributa sloga.

<style uno-preflights></style>

Vsi specialni preflights, ki se začnejo s piko, kot so .prose :where(a):not(:where(.not-prose, .not-prose *)), bodo oviti z :global(), da se prepreči samodejno odstranitev s strani Svelte kompajlerja.

Dodajanje preflights v posamezne komponente je nepotrebno, če vaši razredi niso odvisni od preflights ali če so vaše grajene komponente uporabljene le v aplikacijah, ki že vključujejo preflights.

Safelist

Pri uporabi preprocesorja imate možnost vključitve safelist razredov v komponento z dodajanjem uno-safelist kot atributa sloga.

<style uno-safelist></style>

Vaši safelist slogi bodo oviti z :global(), da se prepreči samodejno odstranitev s strani Svelte kompajlerja.

Konfiguracija

Postavite vaše UnoCSS nastavitve v datoteko uno.config.ts:

import { defineConfig } from 'unocss'

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

Ekstraktorji niso podprti zaradi razlik v običajni globalni uporabi UnoCSS in uporabi Svelte Scoped. Prednastavitve in Transformerji so podprti, kot je opisano v naslednjih razdelkih. Za vse ostale podrobnosti si oglejte Konfiguracijska datoteka in Referenca konfiguracij.

Podpora prednastavitvam

Zaradi narave, da imamo nekaj potrebnih slogov v globalnem stylesheetu in vse ostalo vsebovano v vsaki komponenti, kjer je potrebno, je treba prednastavitve obravnavati posebej:

Prednastavitev	Podprto	Opombe
@unocss/preset-uno, @unocss/preset-mini, @unocss/preset-wind3, @unocss/preset-icons, @unocss/web-fonts	✅	Te in vse community vtičnike, npr. unocss-preset-forms, ki se zanašajo le na rules/variants/preflights, bodo delovale.
@unocss/preset-typography	✅	Zaradi načina, kako ta prednastavitev dodaja rule sete vašim preflights, morate dodati razred prose v vaš safelist pri uporabi te prednastavitve, sicer preflights nikoli ne bodo sproženi. Vsi drugi razredi iz te prednastavitve, npr. prose-pink, so lahko komponentno scoped.
@unocss/preset-rem-to-px	✅	To in vse prednastavitve, kot je ta, ki le modificirajo izhod slogov, bodo delovale.
@unocss/preset-attributify	-	Prednastavitev ne bo delovala. Namesto tega uporabite Vite vtičnik unplugin-attributify-to-class (attributifyToClass({ include: [/\.svelte$/]})) pred Svelte Scoped Vite vtičnikom
@unocss/preset-tagify	-	Prednastavitve, ki dodajajo custom ekstraktorje, ne bodo delovale. Ustvarite preprocesor za pretvorbo <text-red>Hi</text-red> v <span class="text-red">Hi</span>, nato ustvarite PR za dodajanje povezave tukaj.

Za druge prednastavitve, če se ne zanašajo na običajno uporabo class="...", boste morali najprej preprocesirati ta imena razredov v atribut class="...". Če dodajo prednastavitve kot je typographyjev razred .prose, boste morali postaviti razrede, ki sprožijo dodatke prednastavitev, v vaš safelist.

Podpora transformerjem

Transformerji so podprti za vaše CSS datoteke (css|postcss|sass|scss|less|stylus|styl). Za njihovo uporabo dodajte transformer v možnost cssFileTransformers v vaši vite.config.ts:

import transformerDirectives from '@unocss/transformer-directives'

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

INFO

Transformerji niso podprti v Svelte komponentah zaradi načina delovanja Svelte Scoped.

Scoped slogovni pripomočki sproščajo ustvarjalnost

Nekaj nasvetov, kdaj boste morda želeli uporabiti scoped sloge: Če ste prišli do točke v življenju velikega projekta, ko vsakič, ko uporabite razred, kot je .md:max-w-[50vw], za katerega veste, da je uporabljen le enkrat, se zdrznete, ko čutite, da se velikost vaše globalne stylesheet datoteke povečuje, potem poskusite ta paket. Oklevanje pri uporabi točno tistega razreda, ki ga potrebujete, zavira ustvarjalnost. Seveda lahko uporabite --at-apply: md:max-w-[50vw] v style bloku, vendar to postane dolgočasno in slogi v kontekstu so uporabni. Poleg tega, če želite vključiti veliko različnih ikon v vaš projekt, boste začutili težo dodajanja v globalni stylesheet. Ko vsaka komponenta nosi težo svojih lastnih slogov in ikon, lahko nadaljujete s širitvijo vašega projekta, ne da bi morali analizirati stroške in koristi vsakega novega dodatka.

Licenca

• MIT Licenca © 2022-PRESENT Jacob Bowdoin