Pomočniki za nastavitve

Kaj boste ustvarili

Plošča z nastavitvami, kjer uporabniki izberejo jezik in velikost besedila — izbire, ki veljajo za cel dokument, ostanejo med obiski in vas stanejo dve komponenti in nekaj vrstic CSS. Približno 15 minut.

Preden začnete

Najprej dokončajte vodnik za ogrodje za svoj sklad. Spodnji vzorci so v Svelte; pomočniki za React, Vue, Angular, HTML, Nunjucks in Blazor jim ustrezajo pogodbo za pogodbo.

Oblika, ki si jo delijo

• Brezglavi gumb z ikono, ki odpre listbox WAI-ARIA APG (ali pri date-time-picker pogovorno okno za izbiro datuma) — brez izvornega <select>, tako da vsako ogrodje dobi enako vedenje tipkovnice in stilske kavlje.
• En razredni kavelj na paket (.locale-picker, .text-size-picker, .share-picker, .date-time-picker), nič dobavljenega CSS.
• Varno za SSR: zapisi v DOM se zgodijo le v življenjskem ciklu mount/effect.
• Čisto za i18n: vsak niz, viden uporabniku, je prop.
• Na voljo za Svelte (kanonični), React, Vue, Angular, HTML po meri, Nunjucks in Blazor — v vsakem enaka pogodba.

theme-picker, locale-picker in text-size-picker vsak lastnijo eno uporabnikovo nastavitev od začetka do konca (izbira, uporaba na DOM, neobvezna localStorage trajnost prek propa storageKey ). share-picker in date-time-picker sta drugačne vrste: share-picker lastni dejanje — ničesar ne uporabi na dokumentu in ničesar ne shrani — date-time-picker pa lastni vrednost obrazca, saj je datum v obrazcu podatek, ne nastavitev.

locale-picker — jezik in smer

Uporabniku omogoči izbiro področne nastavitve, nato zapiše lang in dir na koren dokumenta, da ji sledijo vaša knjižnica i18n, vaš CSS in pomožne tehnologije. RTL se samodejno zazna za arabščino, hebrejščino in druge pisave od desne proti levi. Osredotoča se zgolj na signaliziranje — prevod opravi vaša knjižnica i18n.

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

Možnosti so označene iz vgrajene tabele imen področnih nastavitev (preglasi se prek localeLabels), vsaka možnost nosi svoj atribut lang , da bralniki zaslona izgovorijo „Français“ po francosko, in kode s podčrtajem, kot je en_US se brez izgub pretvarjajo v BCP 47 in nazaj en-US. Povežite onChange (ali vezano vrednost) z i18next, Paraglide, vue-i18n ali česar koli že uporabljate.

text-size-picker — velikost, ki jo nadzira bralec

Pridobitev za dostopnost, ki traja minute: pomočnik nastavi data-text-size="{slug}" na korenu dokumenta, vaš CSS pa vsako vrednost preslika v velikost.

<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%; }

Dimenzionirajte postavitev v rem in cela aplikacija se prilagodi uporabnikovi izbiri. Oznake se oblikujejo iz slugov z veliko začetnico („X Large“) ali preglasijo prek sizeLabels.

share-picker — pošljite to stran

Gumb z enim glifom, ki odpre izvorni list za deljenje naprave, kjer obstaja, sicer pa se vrne na seznam ciljev, ki jih dobavite, plus dejanje kopiranja URL-ja. Ne dobavlja nobenih URL-jev družbenih omrežij — katera omrežja sodijo v vaš izdelek, je vaša odločitev, ne odločitev oblikovalskega sistema.

<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 je privzeto location.hrefzato običajen primer ne potrebuje nobenega ožičenja. Izsilite pot z strategy="list" ali strategy="native" kadar potrebujete dosledno vedenje med platformami za teste ali posnetke zaslona.

date-time-picker — datum, čas ali oboje

Besedilno polje, v katerega lahko tipkate, plus gumb z ikono, ki odpre pogovorno okno za izbiro datuma WAI-ARIA APG. Pravilen za področno nastavitev že po zasnovi — imena mesecev, imena dni, prvi dan tedna in 12- ali 24-urna ura vsi prihajajo iz Intl — vrednost pa je vedno razvrstljiv niz ISO brez časovnega pasu: "2026-03-15" za mode="date", "09:30" za mode="time", "2026-03-15T09:30" za 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",
  }}
/>

Vrednost ISO je enaka temu, kar <input type="date"> pošlje, zato lahko izvorni kontrolnik zamenjate noter ali ven, ne da bi se dotaknili zaledja.

motion-picker — spoštujte zmanjšano gibanje

Pomočnik nastavi data-motion="{slug}" na korenu dokumenta. Njegova prva vrednost prihaja iz nastavitve prefers-reduced-motion operacijskega sistema obiskovalca — vedno, brez zastavice za vklop, ker je gibanje resnična potreba po dostopnosti (WCAG 2.3.3). Vaš CSS in skripte odločajo, kaj se zaduši.

<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 — iskalno polje, ki ne moti

Gumb z ikono, ki odpre iskalno polje. Pritisk tipke Return ali gumba ⏎ ob polju krmari z navadno zahtevo GET na /?<text> (besedilo se obreže in kodira kot URI; prazna poizvedba ne vodi nikamor). Njegova tri dostopna imena so obvezna, ker pomočnik ne dobavlja angleščine.

<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 spremeni pot (/search?foo), in navigate ohrani krmarjenje znotraj aplikacije; brez njega pomočnik pokliče location.assign.

picker-bar — cela vrstica glave naenkrat

picker-bar izriše iskanje, temo, področno nastavitev, velikost besedila in deljenje v eni vrstici, s popolnim naborom referenčnih tem in sedemstopenjsko lestvico besedila vnaprej povezanima. Vsako dostopno ime prihaja v enem obveznem labels objektu.

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

Do katerega koli ovitega izbirnika pridete prek searchProps, themeProps, localeProps, textSizeProps in shareProps.

Namigi so vgrajeni

Vsak izbirnik prikaže svojo oznako v namigu, ko kazalec počiva na njegovem gumbu ali ima gumb fokus tipkovnice. Namig ostane, ko se kazalec premakne nanj, Escape ga zapre, kjer koli je fokus, in nikoli se ne prikaže, medtem ko je pojavno okno izbirnika odprto. Nosi isto besedilo kot dostopno ime gumba, zato ni treba nič nastavljati ali dvakrat prevajati; referenčne teme ga oblikujejo.

Plošča z nastavitvami na enem mestu

Štirje pomočniki za nastavitve se naravno sestavijo:

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

Kje jih dobite

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

Vsak paket ima svoj spec, teste, povezane s klavzulami specifikacije, izvedljive primere (vključno z vzorci piškotkov za SSR) in cevovod za gradnjo ter objavo. Paketi Svelte so kanonični; v dvomu zmagajo njihove pogodbe.

Naslednji koraki

• Katalog komponent — popolna referenca 571 komponent.
• Pomoč — odpravljanje težav in pogosta vprašanja.
• Zakaj Lily — in kako podpreti projekt.

Vprašanja na poti? Stran s pomočjo je polna odgovorov — in če bi bil kakšen korak lahko jasnejši, sporočite nam in vodnik bomo z veseljem izboljšali.