Eelistuste abilised

Mida sa ehitad

Seadete paneel, kus kasutajad valivad keele ja teksti suuruse — valikud, mis kehtivad kogu dokumendile, püsivad külastuste vahel ja maksavad sulle kaks komponenti ja paar rida CSS-i. Umbes 15 minutit.

Enne alustamist

Lõpeta esmalt raamistiku õpetus oma tehnoloogiapaki jaoks. Allolevad näited on Svelte'is; Reacti, Vue, Angulari, HTML-i, Nunjucksi ja Blazori abilised vastavad neile lepingu haaval.

Kuju, mida nad jagavad

• Peata ikoonnupp, mis avab WAI-ARIA APG listboxi (või date-time-pickeri puhul kuupäevavalija dialoogi) — pole natiivset <select>-i, nii et iga raamistik saab sama klaviatuurikäitumise ja kujunduskonksud.
• Üks klassikonks paketi kohta (.locale-picker, .text-size-picker, .share-picker, .date-time-picker), null tarnitud CSS-i.
• SSR-ohutu: DOM-i kirjutamised toimuvad ainult mount-/effect-elutsüklis.
• i18n-puhas: iga kasutajale nähtav string on prop.
• Saadaval Svelte'ile (kanooniline), Reactile, Vuele, Angularile, HTML-i kohandatud elemendile, Nunjucksile ja Blazorile — igaühes sama leping.

theme-picker, locale-picker ja text-size-picker omavad igaüks ühte kasutaja eelistust algusest lõpuni (valik, rakendamine DOM-ile, valikuline localStorage püsivus storageKey propi kaudu). share-picker ja date-time-picker on olemuselt teistsugused: share-picker omab tegevust — see ei rakenda dokumendile midagi ega salvesta midagi — ja date-time-picker omab vormi väärtust, sest vormi kuupäev on andmed, mitte eelistus.

locale-picker — keel ja suund

Laseb kasutajal valida lokaadi ja kirjutab seejärel lang ja dir dokumendi juurele, et sinu i18n-teek, CSS ja abitehnoloogiad kõik järgiksid. RTL tuvastatakse automaatselt araabia, heebrea ja teiste paremalt vasakule kirjutatavate kirjade jaoks. See keskendub puhtalt signaliseerimisele — tõlke teeb sinu i18n-teek.

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

Valikud märgistatakse sisseehitatud lokaadinimede tabelist (alistatav propiga localeLabels), igal valikul on oma lang atribuut, et ekraanilugejad hääldaksid "Français" prantsuse keeles, ja alakriipsuga koodid nagu en_US teisendatakse BCP 47-ks ja tagasi kadudeta en-US. Ühenda onChange (või seotud väärtus) i18nexti, Paraglide'i, vue-i18n-i või millega iganes sa töötad.

text-size-picker — lugeja juhitav suurus

Ligipääsetavuse võit, mis võtab minuteid: abiline seab data-text-size="{slug}" dokumendi juurele ja sinu CSS seob iga väärtuse suurusega.

<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õõtmesta oma paigutus ühikuga rem ja kogu rakendus skaleerub kasutaja valikuga. Sildid moodustatakse slugidest suure algustähega ("X Large") või alistatakse propiga sizeLabels.

share-picker — saada see leht

Ühe sümboliga nupp, mis avab seadme natiivse jagamislehe, kus see on olemas, ja muidu langeb tagasi sinu antud sihtkohtade loendile, pluss URL-i kopeerimise tegevus. See ei tarni ühtegi sotsiaalvõrgustiku URL-i — millised võrgustikud sinu tootesse kuuluvad, on sinu otsus, mitte disainisüsteemi oma.

<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 vaikeväärtus on location.href, nii et tavajuhtum ei vaja ühendamist. Sunni tee propiga strategy="list" või strategy="native" kui vajad järjepidevat käitumist platvormide vahel testide või ekraanipiltide jaoks.

date-time-picker — kuupäev, kellaaeg või mõlemad

Tekstiväli, kuhu saab kirjutada, pluss ikoonnupp, mis avab WAI-ARIA APG kuupäevavalija dialoogi. Lokaadile õige juba ülesehituselt — kuude nimed, nädalapäevade nimed, nädala esimene päev ja 12- või 24-tunnine kell tulevad kõik moodulist Intl — ja väärtus on alati sorteeritav, ajavööndita ISO-string: "2026-03-15" elemendile mode="date", "09:30" elemendile mode="time", "2026-03-15T09:30" elemendile 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",
  }}
/>

ISO väärtus on identne sellega, mida <input type="date"> saadab, nii et saad natiivse juhtelemendi sisse või välja vahetada, backendi puutumata.

motion-picker — austa vähendatud liikumist

Abiline seab data-motion="{slug}" dokumendi juurele. Selle esimene väärtus tuleb külastaja operatsioonisüsteemi prefers-reduced-motion seadest — alati, ilma lubamislipuata, sest liikumine on tõeline ligipääsetavuse vajadus (WCAG 2.3.3). Sinu CSS ja skriptid otsustavad, mida alla surutakse.

<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 — otsingukast, mis ei jää ette

Ikoonnupp, mis avab otsinguvälja. Return-klahvi või välja kõrval oleva ⏎-nupu vajutamine navigeerib tavalise GET-päringuga aadressile /?<text> (tekst kärbitakse ja URI-kodeeritakse; tühi päring ei vii kuhugi). Selle kolm ligipääsetavat nime on kohustuslikud, sest abiline ei tarni inglise keelt.

<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 muudab teed (/search?foo) ja navigate hoiab navigeerimise rakenduse sees; ilma selleta kutsub abiline location.assign.

picker-bar — kogu päisejada korraga

picker-bar renderdab otsingu, teema, keele, teksti suuruse ja jagamise ühes reas, täieliku viiteteemade komplekti ja seitsmeastmelise tekstiskaalaga eelnevalt ühendatud. Iga ligipääsetav nimi tuleb ühes kohustuslikus labels objektis.

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

Jõua mis tahes mähitud valijani propiga searchProps, themeProps, localeProps, textSizeProps ja shareProps.

Tööriistavihjed on sisse ehitatud

Iga valija näitab oma silti tööriistavihjes, kui kursor puhkab selle nupul või nupul on klaviatuurifookus. Tööriistavihje jääb nähtavale, kui kursor liigub sellele, Escape sulgeb selle, kus iganes fookus on, ja see ei ilmu kunagi, kui valija hüpikaken on avatud. See kannab sama teksti mis nupu ligipääsetav nimi, nii et pole midagi seadistada ega kaks korda tõlkida; viiteteemad kujundavad selle.

Seadete paneel ühes kohas

Neli eelistuste abilist sobivad loomulikult kokku:

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

Kust neid saada

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

Igal paketil on oma spec, speci klauslitega seotud testid, käivitatavad näited (sh SSR-küpsisemustrid) ning ehitus- ja avaldamistoru. Svelte paketid on kanoonilised; kahtluse korral võidavad nende lepingud.

Järgmised sammud

• Komponentide kataloog — kõigi 571 komponendi täielik viide.
• Abi — tõrkeotsing ja KKK.
• Miks Lily — ja kuidas projekti toetada.

Küsimusi teel? Abileht on täis vastuseid — ja kui mõni samm saaks olla selgem, anna meile teada ja me parandame õpetust hea meelega.