Għajnuniet tal-preferenzi

X'se tibni

Pannell tal-issettjar fejn l-utenti jagħżlu l-lingwa u d-daqs tat-test — għażliet li japplikaw għad-dokument kollu, jibqgħu bejn żjarat u jiswewk żewġ komponenti u ftit linji CSS. Madwar 15-il minuta.

Qabel ma tibda

Lesti l-ewwel it-tutorja tal-framework għall-istack tiegħek. L-eżempji hawn taħt huma Svelte; l-għajnuniet għal React, Vue, Angular, HTML, Nunjucks u Blazor jaqblu kuntratt b'kuntratt.

Il-forma li jaqsmu

• Buttuna-ikona headless li tiftaħ listbox WAI-ARIA APG (jew, għal date-time-picker, djalogu għall-għażla tad-data) — l-ebda <select>nattiv, biex kull framework jieħu l-istess mġiba tat-tastiera u ganċijiet tal-istil.
• Ganċ tal-klassi wieħed għal kull pakkett (.locale-picker, .text-size-picker, .share-picker, .date-time-picker), żero CSS mibgħut.
• Sigur għal SSR: il-kitbiet fid-DOM isiru biss fmiċ-ċiklu tal-ħajja mount/effect.
• Nadif għal i18n: kull string li jara l-utent huwa prop.
• Disponibbli għal Svelte (kanoniku), React, Vue, Angular, element personalizzat HTML, Nunjucks u Blazor — l-istess kuntratt f'kull wieħed.

theme-picker, locale-picker u text-size-picker kull wieħed igawdi preferenza waħda tal-utent mill-bidu sal-aħħar (għażla, applikazzjoni għad-DOM, localStorage persistenza fakultattiva permezz tal-prop storageKey ). share-picker u date-time-picker huma differenti fit-tip: share-picker igawdi azzjoni — ma japplika xejn għad-dokument u ma jżomm xejn — u date-time-picker igawdi valur ta' formola, peress li data f'formola hija data u mhux preferenza.

locale-picker — lingwa u direzzjoni

Iħalli lill-utent jagħżel lokal, imbagħad jikteb lang u dir fuq l-għerq tad-dokument biex il-librerija i18n tiegħek, is-CSS tiegħek u t-teknoloġiji ta' assistenza kollha jsegwuh. L-RTL jinkixef awtomatikament għall-Għarbi, l-Ebrajk u kitbiet oħra mill-lemin għax-xellug. Jiffoka biss fuq is-sinjalar — il-librerija i18n tiegħek tieħu ħsieb it-traduzzjoni.

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

L-għażliet jinkitbu minn tabella mibnija bl-ismijiet tal-lokali (tista' tissostitwixxi permezz ta' localeLabels), kull għażla għandha l-attribut tagħha lang biex il-qarrejja tal-iskrin jippronunzjaw "Français" bil-Franċiż, u kodiċijiet b'sottolinja bħal en_US jinbidlu mingħajr telf lejn BCP 47 u lura en-US. Qabbad onChange (jew il-valur marbut) ma' i18next, Paraglide, vue-i18n jew dak li tuża.

text-size-picker — daqs ikkontrollat mill-qarrej

Rebħa għall-aċċessibbiltà li tieħu minuti: l-għajnuna tiffissa data-text-size="{slug}" fuq l-għerq tad-dokument u s-CSS tiegħek jaqsam kull valur ma' daqs.

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

Dimensjona l-layout tiegħek bi rem u l-app kollha tiskala mal-għażla tal-utent. It-tikketti jinbnew mill-slugs bl-ewwel ittra kapitali ("X Large") jew jinbidlu permezz ta' sizeLabels.

share-picker — ibgħat din il-paġna

Buttuna b'karattru wieħed li tiftaħ il-folja nattiva tal-qsim tal-apparat fejn teżisti, u inkella terġa' lura għal lista ta' destinazzjonijiet li inti tipprovdi, flimkien ma' azzjoni biex tikkopja l-URL. Ma tibgħatx l-ebda URL ta' netwerks soċjali — liema netwerks jappartjenu fil-prodott tiegħek hija d-deċiżjoni tiegħek, mhux tas-sistema tad-disinn.

<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 b'mod awtomatiku huwa location.hrefgħalhekk il-każ komuni ma jeħtieġ l-ebda wajering. Ġiegħel triq b' strategy="list" jew strategy="native" meta teħtieġ mġiba konsistenti bejn il-pjattaformi għal testijiet jew screenshots.

date-time-picker — data, ħin jew it-tnejn

Qasam tat-test fejn tista' tiktep, flimkien ma' buttuna-ikona li tiftaħ djalogu għall-għażla tad-data WAI-ARIA APG. Korrett għal-lokal b'mod strutturali — l-ismijiet tax-xhur, l-ismijiet tal-jiem, l-ewwel jum tal-ġimgħa u arloġġ ta' 12 jew 24 siegħa kollha jiġu minn Intl — u l-valur huwa dejjem string ISO li jista' jiġi ordnat u mingħajr żona tal-ħin: "2026-03-15" għal mode="date", "09:30" għal mode="time", "2026-03-15T09:30" għal 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",
  }}
/>

Il-valur ISO huwa identiku għal dak li <input type="date"> jibgħat, biex tkun tista' tbiddel il-kontroll nattiv ġewwa jew barra mingħajr ma tmiss il-backend tiegħek.

motion-picker — irrispetta l-moviment imnaqqas

L-għajnuna tiffissa data-motion="{slug}" fuq l-għerq tad-dokument. L-ewwel valur tiegħu jiġi mill-issettjar prefers-reduced-motion tas-sistema operattiva tal-viżitatur — dejjem, mingħajr flag ta' opt-in, għax il-moviment huwa bżonn reali ta' aċċessibbiltà (WCAG 2.3.3). Is-CSS u l-iskripts tiegħek jiddeċiedu x'jiġi mrażżan.

<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 — kaxxa tal-ġħażla li ma tiġix fit-triq

Buttuna-ikona li tiftaħ qasam tat-tfittxija. Meta tagħfas Return, jew il-buttuna ⏎ maġenb il-qasam, tinnaviga b'talba GET sempliċi lejn /?<text> (it-test jitnaqqas mill-ispazji u jiġi kodifikat bħala URI; mistoqsija vojta ma tmur imkien). It-tliet ismijiet aċċessibbli tagħha huma meħtieġa, għax l-għajnuna ma tibgħatx l-Ingliż.

<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 tbiddel it-triq (/search?foo), u navigate iżomm in-navigazzjoni ġewwa l-app; mingħajru l-għajnuna tsejjaħ location.assign.

picker-bar — ir-ringiela sħiħa tal-header f'daqqa

picker-bar tirrendi t-tfittxija, it-tema, il-lokal, id-daqs tat-test u l-qsim f'ringiela waħda, bis-sett sħiħ ta' temi ta' referenza u l-iskala ta' seba' passi tat-test imqabbdin minn qabel. Kull isem aċċessibbli jaslu f'oġġett wieħed meħtieġ labels .

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

Wasal għal kwalunkwe għażiel mgeżwer b' searchProps, themeProps, localeProps, textSizeProps u shareProps.

It-tooltips huma inkorporati

Kull għażiel juri t-tikketta tiegħu f'tooltip meta l-pointer jistrieħ fuq il-buttuna tiegħu jew il-buttuna jkollha focus tat-tastiera. It-tooltip jibqa' waqt li l-pointer jiċċaqlaq fuqu, Escape jagħlqu fejn jinsab il-focus, u qatt ma jidher waqt li l-popup tal-għażiel ikun miftuħ. Iġorr l-istess test bħall-isem aċċessibbli tal-buttuna, għalhekk m'hemm xejn xi tikkonfigura jew titraduċi darbtejn; it-temi ta' referenza jagħtuh l-istil.

Pannell tal-issettjar f'post wieħed

L-erba' għajnuniet tal-preferenzi jikkomponu b'mod naturali:

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

Fejn tikseb

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

Kull pakkett għandu l-ispec tiegħu, testijiet immappjati mal-klawżoli tal-ispec, eżempji li jistgħu jitmexxew (inklużi mudelli ta' cookies għal SSR) u pipeline tal-bini u tal-pubblikazzjoni. Il-pakketti Svelte huma kanoniċi; fil-każ ta' dubju, il-kuntratti tagħhom jirbħu.

Passi li jmiss

• Katalogu tal-komponenti — ir-referenza sħiħa tal-571 komponent.
• Għajnuna — issolvi l-problemi u mistoqsijiet frekwenti.
• Għaliex Lily — u kif tappoġġja l-proġett.

Mistoqsijiet matul it-triq? Il-paġna tal-għajnuna hija mimlija tweġibiet — u jekk pass jista' jkun iktar ċar, għidilna u nħossuna kuntenti ntejbu t-tutorja.