Beállítási segédek

Mit fogsz építeni

Egy beállítási panel, ahol a felhasználók kiválasztják a nyelvüket és a szövegméretüket — a választások az egész dokumentumra vonatkoznak, látogatások között megmaradnak, és két komponensbe meg néhány sor CSS-be kerülnek. Nagyjából 15 perc.

Mielőtt elkezdenéd

Előbb fejezd be a keretrendszer-oktatóanyagot a saját technológiai készletedhez. Az alábbi minták Svelte-ben vannak; a React, Vue, Angular, HTML, Nunjucks és Blazor segédek szerződésről szerződésre megfelelnek nekik.

A közös forma

• Egy fej nélküli ikongomb, amely WAI-ARIA APG listboxot nyit (vagy a date-time-picker esetében dátumválasztó párbeszédablakot) — nincs natív <select>, így minden keretrendszer ugyanazt a billentyűzet-viselkedést és stílusozási kampókat kapja.
• Csomagonként egy osztálykampó (.locale-picker, .text-size-picker, .share-picker, .date-time-picker), nulla szállított CSS.
• SSR-biztonságos: a DOM-írások csak a mount/effect életciklusban történnek.
• i18n-tiszta: minden, a felhasználónak látható karakterlánc egy prop.
• Elérhető Svelte (kanonikus), React, Vue, Angular, HTML egyedi elem, Nunjucks és Blazor számára — mindegyikben ugyanaz a szerződés.

A theme-picker, a locale-picker és a text-size-picker mindegyike egy felhasználói beállítást birtokol elejétől a végéig (kiválasztás, alkalmazás a DOM-ra, opcionális localStorage tartósság a storageKey propon keresztül). A share-picker és a date-time-picker más természetű: a share-picker egy műveletet birtokol — semmit sem alkalmaz a dokumentumra és semmit sem tart meg — a date-time-picker pedig egy űrlapértéket, mert az űrlapban lévő dátum adat, nem beállítás.

locale-picker — nyelv és irány

Lehetővé teszi a felhasználónak, hogy területi beállítást válasszon, majd kiírja a lang és dir értéket a dokumentum gyökerére, hogy az i18n-könyvtárad, a CSS-ed és a kisegítő technológiák mind kövessék. Az RTL automatikusan felismerhető arab, héber és más jobbról balra író írásrendszereknél. Kizárólag jelzésre koncentrál — a fordítást az i18n-könyvtárad végzi.

<script>
  import LocalePicker from "@lilydesignsystem/svelte-locale-picker";

  let locale = $state("en-US");
</script>

<LocalePicker
  label="Language"
  locales={["en-US", "fr", "ar", "he", "ja"]}
  bind:value={locale}
  storageKey="my-app-locale"
/>

A lehetőségek címkéi egy beépített területi beállítás-névtáblából származnak (felülírható a localeLabelspropon keresztül), minden lehetőség saját lang attribútumot hordoz, hogy a képernyőolvasók a „Français” szót franciául ejtsék, és az aláhúzásos kódok, például en_US veszteség nélkül oda-vissza alakíthatók BCP 47-re en-US. Kösd a onChange értéket (vagy a kötött értéket) az i18next-hez, a Paraglide-hoz, a vue-i18n-hez vagy bármihez, amit használsz.

text-size-picker — az olvasó által vezérelt méret

Percek alatt elérhető akadálymentességi nyereség: a segéd beállítja a data-text-size="{slug}" értéket a dokumentum gyökerén, a CSS-ed pedig minden értéket mérethez rendel.

<script>
  import TextSizePicker from "@lilydesignsystem/svelte-text-size-picker";
</script>

<TextSizePicker
  label="Text size"
  sizes={["small", "medium", "large", "x-large"]}
  storageKey="my-app-text-size"
/>

:root[data-text-size="small"]   { font-size: 87.5%; }
:root[data-text-size="medium"]  { font-size: 100%; }
:root[data-text-size="large"]   { font-size: 112.5%; }
:root[data-text-size="x-large"] { font-size: 125%; }

Méretezd az elrendezésedet rem egységben, és az egész alkalmazás a felhasználó választásával skálázódik. A címkék a slugokból készülnek nagy kezdőbetűvel („X Large”), vagy a sizeLabels.

share-picker — küldd el ezt az oldalt

Egyetlen jelet tartalmazó gomb, amely megnyitja az eszköz natív megosztólapját, ahol van ilyen, máskülönben az általad megadott célok listájára esik vissza, plusz egy URL-másoló művelet. Nem szállít közösségi hálózati URL-eket — hogy mely hálózatok illenek a termékedhez, az a te döntésed, nem a tervezési rendszeré.

<script>
  import SharePicker from "@lilydesignsystem/svelte-share-picker";

  const targets = [
    { id: "mastodon", label: "Mastodon",
      href: (url, title) => `https://mastodon.social/share?text=${encodeURIComponent(title)}%20${encodeURIComponent(url)}` },
    { id: "email", label: "Email",
      href: (url, title) => `mailto:?subject=${encodeURIComponent(title)}&body=${encodeURIComponent(url)}`, newTab: false },
  ];
</script>

<SharePicker
  label="Share this page"
  title="An article worth reading"
  {targets}
  copyLabel="Copy link"
  copiedLabel="Link copied"
/>

url alapértéke location.hrefígy a gyakori eset nem igényel bekötést. Kényszeríts egy útvonalat a strategy="list" vagy a strategy="native" értékkel, ha platformok közötti következetes viselkedésre van szükséged tesztekhez vagy képernyőképekhez.

date-time-picker — dátum, időpont vagy mindkettő

Egy szövegmező, amelybe gépelhetsz, plusz egy ikongomb, amely WAI-ARIA APG dátumválasztó párbeszédablakot nyit. Szerkezetéből adódóan területi beállítás szerint helyes — a hónapnevek, a hétköznapnevek, a hét első napja és a 12 vagy 24 órás óra mind innen jön: Intl — az érték pedig mindig rendezhető, időzóna nélküli ISO karakterlánc: "2026-03-15" a mode="date", "09:30" a mode="time", "2026-03-15T09:30" a mode="datetime".

<script>
  import DateTimePicker from "@lilydesignsystem/svelte-date-time-picker";

  let appointment = $state("");
</script>

<DateTimePicker
  inputId="appointment"
  name="appointment"
  label="Choose an appointment date"
  locale="en-GB"
  bind:value={appointment}
  labels={{
    previousYear: "Previous year",
    previousMonth: "Previous month",
    nextMonth: "Next month",
    nextYear: "Next year",
    confirm: "OK",
    cancel: "Cancel",
  }}
/>

Az ISO-érték azonos azzal, amit a <input type="date"> elküld, így a natív vezérlőt a háttérrendszer érintése nélkül cserélheted be vagy ki.

motion-picker — tartsd tiszteletben a csökkentett mozgást

A segéd beállítja a data-motion="{slug}" értéket a dokumentum gyökerén. Az első érték a látogató operációs rendszerének prefers-reduced-motion beállításából jön — mindig, bekapcsolási jelző nélkül, mert a mozgás valós akadálymentességi igény (WCAG 2.3.3). A CSS-ed és a szkriptjeid döntik el, mi kerül elnyomásra.

<script>
  import MotionPicker from "@lilydesignsystem/svelte-motion-picker";
</script>

<MotionPicker
  label="Motion"
  motions={["no-preference", "reduce"]}
  storageKey="my-app-motion"
/>

:root[data-motion="reduce"] *,
:root[data-motion="reduce"] *::before,
:root[data-motion="reduce"] *::after {
  animation: none !important;
  transition: none !important;
  scroll-behavior: auto !important;
}

search-picker — egy keresőmező, amely nem áll útban

Egy ikongomb, amely keresőmezőt nyit. A Return vagy a mező melletti ⏎ gomb megnyomása egyszerű GET-kéréssel navigál ide: /?<text> (a szöveg le van vágva és URI-kódolva; üres lekérdezés sehová sem vezet). A három hozzáférhető név kötelező, mert a segéd nem szállít angol szöveget.

<script>
  import SearchPicker from "@lilydesignsystem/svelte-search-picker";
  import { goto } from "$app/navigation";
</script>

<SearchPicker
  label="Search this site"
  inputLabel="Search terms"
  submitLabel="Search"
  placeholder="Search…"
  action="/search"
  navigate={(href) => goto(href)}
/>

action módosítja az útvonalat (/search?foo), a navigate pedig az alkalmazáson belül tartja a navigációt; nélküle a segéd hívja: location.assign.

picker-bar — az egész fejlécsor egyszerre

picker-bar egy sorban rendereli a keresést, a témát, a területi beállítást, a szövegméretet és a megosztást, a referenciatémák teljes készletével és a hétfokozatú szövegskálával előre bekötve. Minden hozzáférhető név egyetlen kötelező labels objektumban érkezik.

<script>
  import PickerBar from "@lilydesignsystem/svelte-picker-bar";
</script>

<PickerBar
  labels={{
    search: "Search", searchInput: "Search terms", searchSubmit: "Search",
    theme: "Theme", locale: "Language", textSize: "Text size", share: "Share",
  }}
  themesUrl="/themes/"
  locales={["en", "fr", "es"]}
  shareTargets={targets}
/>

Bármely becsomagolt választót elérhetsz a searchProps, themeProps, localeProps, textSizeProps és shareProps.

A buboréksúgók be vannak építve

Minden választó buboréksúgóban mutatja a címkéjét, ha a mutató a gombján pihen, vagy a gombnak billentyűzetfókusza van. A buboréksúgó megmarad, amíg a mutató rámozdul, az Escape bezárja, bárhol is van a fókusz, és soha nem jelenik meg, amíg a választó felugró ablaka nyitva van. Ugyanazt a szöveget hordozza, mint a gomb hozzáférhető neve, így nincs mit beállítani, és nincs mit kétszer lefordítani; a referenciatémák stílusozzák.

Egy beállítási panel egy helyen

A négy beállítási segéd természetesen összeáll:

<fieldset class="fieldset">
  <legend>Preferences</legend>
  <ThemePicker    label="Theme"     themesUrl="/themes/" themes={themes} storageKey="pref-theme" />
  <LocalePicker   label="Language"  locales={locales}    storageKey="pref-locale" />
  <TextSizePicker label="Text size" sizes={sizes}        storageKey="pref-text-size" />
  <MotionPicker   label="Motion"    motions={motions}    storageKey="pref-motion" />
</fieldset>

Hol szerezheted be

# one directory per package in the monorepo, e.g.
git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-svelte-theme-picker
# or lily-design-system-react-theme-picker, -vue- / -angular- / -html- / -web-components- / -nunjucks- / -blazor-

Minden csomagnak saját specje, a spec-szakaszokhoz rendelt tesztjei, futtatható példái (az SSR sütimintákat is beleértve) és build- és közzétételi csővezetéke van. A Svelte csomagok kanonikusak; kétség esetén az ő szerződéseik döntenek.

További lépések

• Komponenskatalógus — mind az 571 komponens teljes referenciája.
• Súgó — hibaelhárítás és GYIK.
• Miért a Lily — és hogyan támogathatod a projektet.

Kérdésed akad útközben? A súgóoldal tele van válaszokkal — és ha egy lépés érthetőbb lehetne, szólj nekünk és szívesen javítjuk az oktatóanyagot.