Asetusapuvälineet

Mitä rakennat

Asetuspaneeli, jossa käyttäjät valitsevat kielensä ja tekstikokonsa — valinnat, jotka koskevat koko dokumenttia, säilyvät käyntien välillä ja maksavat sinulle kaksi komponenttia ja muutaman rivin CSS:ää. Noin 15 minuuttia.

Ennen kuin aloitat

Suorita ensin kehysopas omalle pinollesi. Alla olevat esimerkit ovat Sveltellä; React-, Vue-, Angular-, HTML-, Nunjucks- ja Blazor-apuvälineet vastaavat niitä sopimus sopimukselta.

Muoto, jonka ne jakavat

• Headless-kuvakepainike, joka avaa WAI-ARIA APG -listboxin (tai date-time-pickerin tapauksessa päivämäärän valintaikkunan) — ei natiivia <select>-elementtiä, joten jokainen kehys saa saman näppäimistökäyttäytymisen ja tyylikoukut.
• Yksi luokkakoukku pakettia kohden (.locale-picker, .text-size-picker, .share-picker, .date-time-picker), nolla toimitettua CSS:ää.
• SSR-turvallinen: DOM-kirjoitukset tapahtuvat vain mount-/effect-elinkaaressa.
• i18n-puhdas: jokainen käyttäjälle näkyvä merkkijono on prop.
• Saatavilla Sveltelle (kanoninen), Reactille, Vuelle, Angularille, HTML-mukautetulle elementille, Nunjucksille ja Blazorille — sama sopimus jokaisessa.

theme-picker, locale-picker ja text-size-picker omistavat kukin yhden käyttäjän asetuksen alusta loppuun (valinta, soveltaminen DOMiin, valinnainen localStorage pysyvyys storageKey -propin kautta). share-picker ja date-time-picker ovat luonteeltaan erilaisia: share-picker omistaa toiminnon — se ei sovella mitään dokumenttiin eikä säilytä mitään — ja date-time-picker omistaa lomakkeen arvon, koska lomakkeen päivämäärä on dataa, ei asetus.

locale-picker — kieli ja suunta

Antaa käyttäjän valita kieliasetuksen ja kirjoittaa sitten lang ja dir dokumentin juureen, jotta i18n-kirjastosi, CSS:äsi ja apuvälineteknologiat seuraavat kaikki mukana. RTL tunnistetaan automaattisesti arabialle, heprealle ja muille oikealta vasemmalle kirjoitettaville kirjoitusjärjestelmille. Se keskittyy pelkkään signalointiin — i18n-kirjastosi hoitaa käännöksen.

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

Valinnat nimetään sisäänrakennetusta kieliasetusnimien taulukosta (ohitettavissa localeLabels-propilla), jokaisella valinnalla on oma lang -attribuuttinsa, jotta ruudunlukijat ääntävät "Français" ranskaksi, ja alaviivakoodit kuten en_US muunnetaan häviöttä BCP 47:ksi ja takaisin en-US. Yhdistä onChange (tai sidottu arvo) i18nextiin, Paraglideen, vue-i18n:ään tai mitä ikinä käytätkin.

text-size-picker — lukijan hallitsema koko

Saavutettavuusvoitto, joka vie minuutteja: apuväline asettaa data-text-size="{slug}" dokumentin juureen, ja CSS:äsi yhdistää jokaisen arvon kokoon.

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

Mitoita asettelusi yksiköllä rem ja koko sovellus skaalautuu käyttäjän valinnan mukana. Nimiöt muodostetaan slugeista isoin alkukirjaimin ("X Large") tai ohitetaan propilla sizeLabels.

share-picker — lähetä tämä sivu

Yhden merkin painike, joka avaa laitteen natiivin jakoarkin, jos sellainen on, ja muuten palaa antamaasi kohdeluetteloon sekä URL:n kopiointitoimintoon. Se ei toimita sosiaalisten verkostojen URL-osoitteita — mitkä verkostot kuuluvat tuotteeseesi, on sinun päätöksesi, ei suunnittelujärjestelmän.

<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 oletusarvo on location.href, joten tavallinen tapaus ei vaadi johdotusta. Pakota polku propilla strategy="list" tai strategy="native" kun tarvitset johdonmukaista käyttäytymistä eri alustoilla testejä tai kuvakaappauksia varten.

date-time-picker — päivämäärä, kellonaika tai molemmat

Tekstikenttä, johon voi kirjoittaa, sekä kuvakepainike, joka avaa WAI-ARIA APG -päivämäärävalitsimen. Kieliasetuksen mukainen rakenteensa puolesta — kuukausien nimet, viikonpäivien nimet, viikon ensimmäinen päivä ja 12 tai 24 tunnin kello tulevat kaikki kohteesta Intl — ja arvo on aina lajiteltavissa oleva, aikavyöhykkeetön ISO-merkkijono: "2026-03-15" elementille mode="date", "09:30" elementille mode="time", "2026-03-15T09:30" elementille 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-arvo on identtinen sen kanssa, minkä <input type="date"> lähettää, joten voit vaihtaa natiivin ohjaimen sisään tai ulos koskematta taustajärjestelmääsi.

motion-picker — kunnioita vähennettyä liikettä

Apuväline asettaa data-motion="{slug}" dokumentin juureen. Sen ensimmäinen arvo tulee vierailijan käyttöjärjestelmän prefers-reduced-motion -asetuksesta — aina, ilman käyttöönottolippua, koska liike on todellinen saavutettavuustarve (WCAG 2.3.3). CSS:äsi ja skriptisi päättävät, mitä tukahdutetaan.

<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 — hakukenttä, joka pysyy poissa tieltä

Kuvakepainike, joka avaa hakukentän. Return-näppäimen tai kentän vieressä olevan ⏎-painikkeen painaminen siirtyy tavallisella GET-pyynnöllä osoitteeseen /?<text> (teksti trimmataan ja URI-koodataan; tyhjä haku ei vie minnekään). Sen kolme saavutettavaa nimeä ovat pakollisia, koska apuväline ei toimita englantia.

<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 muuttaa polkua (/search?foo), ja navigate pitää siirtymän sovelluksen sisällä; ilman sitä apuväline kutsuu location.assign.

picker-bar — koko ylätunnisterivi kerralla

picker-bar renderöi haun, teeman, kielen, tekstikoon ja jaon yhdelle riville, ja täysi viiteteemojen joukko sekä seitsenportainen tekstiasteikko on valmiiksi kytketty. Jokainen saavutettava nimi tulee yhdessä pakollisessa labels -oliossa.

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

Tavoita mikä tahansa kääritty valitsin propilla searchProps, themeProps, localeProps, textSizeProps ja shareProps.

Työkaluvihjeet ovat valmiina

Jokainen valitsin näyttää nimiönsä työkaluvihjeessä, kun osoitin lepää sen painikkeen päällä tai painikkeella on näppäimistökohdistus. Työkaluvihje pysyy, kun osoitin siirtyy sen päälle, Escape sulkee sen missä tahansa kohdistus onkaan, eikä se näy koskaan, kun valitsimen ponnahdusikkuna on auki. Se kantaa saman tekstin kuin painikkeen saavutettava nimi, joten ei ole mitään konfiguroitavaa eikä mitään käännettävää kahdesti; viiteteemat tyylittelevät sen.

Asetuspaneeli yhdessä paikassa

Neljä asetusapuvälinettä sopivat luontevasti yhteen:

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

Mistä ne saa

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

Jokaisella paketilla on oma specinsä, spec-lausekkeisiin kytketyt testit, ajettavat esimerkit (mukaan lukien SSR-evästemallit) sekä build- ja julkaisuputki. Svelte-paketit ovat kanonisia; epäselvässä tapauksessa niiden sopimukset ratkaisevat.

Seuraavat askeleet

• Komponenttiluettelo — kaikkien 571 komponentin täysi viite.
• Ohje — vianmääritys ja usein kysytyt kysymykset.
• Miksi Lily — ja miten tuet projektia.

Kysymyksiä matkan varrella? Ohjesivu on täynnä vastauksia — ja jos jokin vaihe voisi olla selkeämpi, kerro meille ja parannamme opasta mielellämme.