Nuostatų pagalbininkai

Ką sukursite

Nustatymų skydelis, kuriame naudotojai renkasi kalbą ir teksto dydį — pasirinkimai, taikomi visam dokumentui, išliekantys tarp apsilankymų ir kainuojantys jums du komponentus bei kelias CSS eilutes. Maždaug 15 minučių.

Prieš pradedant

Pirmiausia užbaikite sistemos vadovą savo technologijų rinkiniui. Toliau pateikti pavyzdžiai yra „Svelte“; „React“, „Vue“, „Angular“, HTML, „Nunjucks“ ir „Blazor“ pagalbininkai jiems atitinka sutartis po sutarties.

Forma, kurią jie dalijasi

• Bekūnis piktogramos mygtukas, atidarantis WAI-ARIA APG listbox (arba, date-time-picker atveju, datos pasirinkimo dialogą) — be gimtojo <select>, todėl kiekviena sistema gauna tą patį klaviatūros elgesį ir stiliaus kablius.
• Vienas klasės kablys vienam paketui (.locale-picker, .text-size-picker, .share-picker, .date-time-picker), nulis pristatomo CSS.
• Saugu SSR: DOM rašymai vyksta tik mount/effect gyvavimo ciklu.
• Švaru i18n požiūriu: kiekviena naudotojui matoma eilutė yra prop.
• Prieinama „Svelte“ (kanoninė), „React“, „Vue“, „Angular“, HTML pasirinktiniam elementui, „Nunjucks“ ir „Blazor“ — kiekvienoje ta pati sutartis.

theme-picker, locale-picker ir text-size-picker kiekvienas valdo po vieną naudotojo nuostatą nuo pradžios iki pabaigos (pasirinkimas, taikymas DOM, pasirenkamas localStorage išsaugojimas per storageKey prop). share-picker ir date-time-picker yra kitokio pobūdžio: share-picker valdo veiksmą — jis nieko netaiko dokumentui ir nieko neišsaugo — o date-time-picker valdo formos reikšmę, nes data formoje yra duomenys, o ne nuostata.

locale-picker — kalba ir kryptis

Leidžia naudotojui pasirinkti lokalę, tada įrašo lang ir dir į dokumento šaknį, kad jūsų i18n biblioteka, CSS ir pagalbinės technologijos visi ją sektų. RTL aptinkamas automatiškai arabų, hebrajų ir kitoms iš dešinės į kairę rašomoms rašmenų sistemoms. Jis tik signalizuoja — vertimą atlieka jūsų i18n biblioteka.

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

Parinktys pažymimos iš įtaisytos lokalių pavadinimų lentelės (galima pakeisti per localeLabels), kiekviena parinktis turi savo lang atributą, kad ekrano skaitytuvai ištartų „Français“ prancūziškai, o kodai su pabraukimu, tokie kaip en_US be nuostolių konvertuojami į BCP 47 ir atgal en-US. Susiekite onChange (arba susietą reikšmę) su i18next, „Paraglide“, vue-i18n ar kuo tik naudojatės.

text-size-picker — skaitytojo valdomas dydis

Prieinamumo laimėjimas, trunkantis minutes: pagalbininkas nustato data-text-size="{slug}" dokumento šaknyje, o jūsų CSS kiekvieną reikšmę susieja su dydžiu.

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

Matuokite savo išdėstymą rem ir visa programa keičia mastelį pagal naudotojo pasirinkimą. Žymos sudaromos iš slug’ų didžiąja pradine raide („X Large“) arba pakeičiamos per sizeLabels.

share-picker — išsiųskite šį puslapį

Vieno simbolio mygtukas, atidarantis įrenginio gimtąjį bendrinimo lapą, kur jis yra, o kitaip grįžtantis prie jūsų pateikto paskirčių sąrašo, plius URL kopijavimo veiksmas. Jis nepristato jokių socialinių tinklų URL — kokie tinklai tinka jūsų produktui, yra jūsų, o ne dizaino sistemos, sprendimas.

<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 numatytoji reikšmė yra location.href, todėl įprastam atvejui nereikia jokio sujungimo. Priverskite kelią su strategy="list" arba strategy="native" kai reikia nuoseklaus elgesio skirtingose platformose testams ar ekrano nuotraukoms.

date-time-picker — data, laikas arba abu

Teksto laukas, į kurį galima rašyti, plius piktogramos mygtukas, atidarantis WAI-ARIA APG datos pasirinkimo dialogą. Teisingas lokalei pagal konstrukciją — mėnesių pavadinimai, savaitės dienų pavadinimai, pirma savaitės diena ir 12 ar 24 valandų laikrodis visi gaunami iš Intl — o reikšmė visada yra rūšiuojama ISO eilutė be laiko juostos: "2026-03-15" elementui mode="date", "09:30" elementui mode="time", "2026-03-15T09:30" elementui 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 reikšmė tokia pati, kokią siunčia <input type="date"> todėl gimtąjį valdiklį galite įdėti ar išimti nelies serverio dalies.

motion-picker — gerbkite sumažintą judesį

Pagalbininkas nustato data-motion="{slug}" dokumento šaknyje. Jo pirmoji reikšmė imama iš lankytojo operacinės sistemos prefers-reduced-motion nustatymo — visada, be įjungimo vėliavėlės, nes judesys yra tikras prieinamumo poreikis (WCAG 2.3.3). Jūsų CSS ir scenarijai nusprendžia, kas slopinama.

<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 — paieškos laukelis, kuris netrukdo

Piktogramos mygtukas, atidarantis paieškos lauką. Paspaudus Return arba šalia lauko esantį ⏎ mygtuką, einama paprasta GET užklausa į /?<text> (tekstas apkerpamas ir koduojamas kaip URI; tuščia užklausa niekur nenuveda). Jo trys prieinami pavadinimai privalomi, nes pagalbininkas nepristato anglų kalbos.

<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 keičia kelią (/search?foo), o navigate išlaiko naršymą programos viduje; be jo pagalbininkas iškviečia location.assign.

picker-bar — visa antraštės eilutė iš karto

picker-bar atvaizduoja paiešką, temą, lokalę, teksto dydį ir bendrinimą vienoje eilutėje, su visu etalonų temų rinkiniu ir septynių pakopų teksto skale iš anksto sujungtais. Kiekvienas prieinamas pavadinimas ateina viename privalomame labels objekte.

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

Pasiekite bet kurį apgaubtą parinkiklį per searchProps, themeProps, localeProps, textSizeProps ir shareProps.

Patarimai įtaisyti

Kiekvienas parinkiklis rodo savo žymą patarime, kai žymeklis ilsisi ant jo mygtuko arba mygtukas turi klaviatūros fokusą. Patarimas lieka, kol žymeklis juda ant jo, Escape jį uždaro, kad ir kur būtų fokusas, ir niekada nerodomas, kol parinkiklio iškylantysis langas atidarytas. Jis turi tą patį tekstą kaip mygtuko prieinamas pavadinimas, todėl nėra ko konfigūruoti ar versti du kartus; etalonų temos jį apipavidalina.

Nustatymų skydelis vienoje vietoje

Keturi nuostatų pagalbininkai natūraliai dera:

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

Kur juos gauti

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

Kiekvienas paketas turi savo spec, testus, susietus su spec sąlygomis, vykdomus pavyzdžius (įskaitant SSR slapukų šablonus) ir kūrimo bei paskelbimo vamzdyną. „Svelte“ paketai yra kanoniniai; abejojant jų sutartys nugali.

Tolesni žingsniai

• Komponentų katalogas — visas 571 komponento žinynas.
• Pagalba — trikčių šalinimas ir DUK.
• Kodėl „Lily“ — ir kaip paremti projektą.

Klausimų pakeliui? Pagalbos puslapis pilnas atsakymų — o jei kuris nors žingsnis galėtų būti aiškesnis, pasakykite mums ir mielai patobulinsime vadovą.