Visaidizi vya mapendeleo

Utakachojenga

Paneli ya mipangilio ambapo watumiaji huchagua lugha na ukubwa wa maandishi — chaguo zinazotumika kwenye hati nzima, hudumu kati ya ziara, na zinagharimu vipengele viwili na mistari michache ya CSS. Takriban dakika 15.

Kabla ya kuanza

Maliza mafunzo ya mfumo wa kazi kwa teknolojia yako. Mifano iliyo hapa chini ni ya Svelte; visaidizi vya React, Vue, Angular, HTML, Nunjucks, na Blazor vinalingana mkataba kwa mkataba.

Umbo wanaloshiriki

• Kitufe cha ikoni kisicho na mwonekano kinachofungua kisanduku cha orodha cha WAI-ARIA APG (au, kwa date-time-picker, dirisha la kuchagua tarehe) — bila <select>asilia, hivyo kila mfumo wa kazi hupata tabia ileile ya kibodi na vishikio vya mitindo.
• Kishikio kimoja cha darasa kwa kila kifurushi (.locale-picker, .text-size-picker, .share-picker, .date-time-picker), hakuna CSS inayosafirishwa.
• Salama kwa SSR: uandishi wa DOM hutokea tu katika mzunguko wa maisha wa kupachika/athari.
• Safi kwa i18n: kila maandishi ya mtumiaji ni sifa.
• Zinapatikana kwa Svelte (msingi), React, Vue, Angular, kipengele maalum cha HTML, Nunjucks, na Blazor — mkataba uleule katika kila moja.

theme-picker, locale-picker, na text-size-picker kila kimoja humiliki pendeleo moja la mtumiaji kuanzia mwanzo hadi mwisho (uchaguzi, utumiaji kwenye DOM, localStorage uhifadhi wa hiari kupitia storageKey sifa). share-picker na date-time-picker ni tofauti kwa aina: share-picker humiliki kitendo — hakitumii chochote kwenye hati wala hakihifadhi chochote — na date-time-picker humiliki thamani ya fomu, kwa kuwa tarehe kwenye fomu ni data, si pendeleo.

locale-picker — lugha na mwelekeo

Humwezesha mtumiaji kuchagua lugha-eneo, kisha huandika lang na dir kwenye mzizi wa hati ili maktaba yako ya i18n, CSS yako, na teknolojia saidizi zifuate. RTL hutambuliwa kiotomatiki kwa Kiarabu, Kiebrania, na maandishi mengine ya kulia-kwenda-kushoto. Hujikita kwenye kuashiria tu — maktaba yako ya i18n hushughulikia tafsiri.

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

Chaguo huwekewa lebo kutoka jedwali lililojengewa ndani la majina ya lugha-eneo (linaweza kubatilishwa kupitia localeLabels), kila chaguo lina sifa yake ya lang ili visomaji skrini vitamke "Français" kwa Kifaransa, na misimbo yenye mstari wa chini kama en_US hubadilishwa kwenda BCP 47 na kurudi bila hasara en-US. Unganisha onChange (au thamani iliyofungwa) kwenye i18next, Paraglide, vue-i18n, au chochote unachotumia.

text-size-picker — ukubwa unaodhibitiwa na msomaji

Ushindi wa ufikivu unaochukua dakika chache: kisaidizi huweka data-text-size="{slug}" kwenye mzizi wa hati na CSS yako huunganisha kila thamani na ukubwa.

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

Panga mpangilio wako kwa rem na programu nzima hupanuka au kupungua kulingana na chaguo la mtumiaji. Lebo hutengenezwa kwa herufi kubwa za kichwa kutoka kwenye slug ("X Large") au hubatilishwa kwa sizeLabels.

share-picker — tuma ukurasa huu

Kitufe cha alama moja kinachofungua karatasi ya kushiriki ya kifaa pale ilipo, na vinginevyo hurudi kwenye orodha ya maeneo unayotoa, pamoja na kitendo cha kunakili URL. Hakisafirishi URL za mitandao ya kijamii — ni mitandao ipi inafaa bidhaa yako ni uamuzi wako, si wa mfumo wa usanifu.

<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 chaguo-msingi lake ni location.href, hivyo hali ya kawaida haihitaji uunganishaji wowote. Lazimisha njia kwa strategy="list" au strategy="native" unapohitaji tabia thabiti katika majukwaa kwa ajili ya majaribio au picha za skrini.

date-time-picker — tarehe, saa, au vyote viwili

Sehemu ya maandishi unayoweza kuandika ndani yake, pamoja na kitufe cha ikoni kinachofungua dirisha la kuchagua tarehe la WAI-ARIA APG. Sahihi kwa lugha-eneo kwa muundo — majina ya miezi, majina ya siku za wiki, siku ya kwanza ya wiki, na saa za saa 12 au 24 zote hutoka kwenye Intl — na thamani huwa daima ni mfuatano wa ISO unaoweza kupangwa na usio na ukanda wa saa: "2026-03-15" kwa mode="date", "09:30" kwa mode="time", "2026-03-15T09:30" kwa 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",
  }}
/>

Thamani ya ISO ni sawa na ile inayotumwa na <input type="date"> hivyo unaweza kubadilishana na kidhibiti asilia bila kugusa seva yako.

motion-picker — heshimu mwendo uliopunguzwa

Kisaidizi huweka data-motion="{slug}" kwenye mzizi wa hati. Thamani yake ya kwanza hutoka kwenye mpangilio wa mfumo wa uendeshaji wa mgeni wa prefers-reduced-motion — daima, bila bendera ya kuchagua, kwa sababu mwendo ni hitaji halisi la ufikivu (WCAG 2.3.3). CSS na hati zako huamua nini kinazuiwa.

<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 — kisanduku cha utafutaji kisichosumbua

Kitufe cha ikoni kinachofungua sehemu ya utafutaji. Kubonyeza Return, au kitufe cha ⏎ kando ya sehemu hiyo, huelekeza kwa ombi la GET la kawaida kwa /?<text> (maandishi hupunguzwa nafasi na kusimbwa kwa URI; hoja tupu haiendi popote). Majina yake matatu yanayofikika ni ya lazima, kwa sababu kisaidizi hakisafirishi Kiingereza.

<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 hubadilisha njia (/search?foo), na navigate huweka urambazaji ndani ya programu; bila hiyo kisaidizi huita location.assign.

picker-bar — safu nzima ya kichwa kwa mara moja

picker-bar huonyesha utafutaji, mandhari, lugha-eneo, ukubwa wa maandishi na kushiriki katika safu moja, na seti kamili ya mandhari ya marejeo na kipimo cha hatua saba cha maandishi kimeunganishwa awali. Kila jina linalofikika huja katika kitu kimoja cha lazima cha labels kitu.

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

Fikia kichaguzi chochote kilichofungwa kwa searchProps, themeProps, localeProps, textSizeProps na shareProps.

Vidokezo vya zana vimejengewa ndani

Kila kichaguzi huonyesha lebo yake katika kidokezo cha zana kielekezi kinapokaa juu ya kitufe chake au kitufe kina umakini wa kibodi. Kidokezo hubaki kielekezi kinaposogea juu yake, Escape hukifunga popote umakini ulipo, na hakionekani kamwe wakati dirisha ibukizi la kichaguzi liko wazi. Hubeba maandishi yaleyale ya jina linalofikika la kitufe, hivyo hakuna cha kusanidi wala cha kutafsiri mara mbili; mandhari ya marejeo huipamba.

Paneli ya mipangilio mahali pamoja

Visaidizi vinne vya mapendeleo vinaungana kwa kawaida:

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

Mahali pa kuvipata

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

Kila kifurushi kina spec yake, majaribio yaliyounganishwa na vifungu vya spec, mifano inayoweza kuendeshwa (ikiwemo mifumo ya vidakuzi vya SSR), na mfumo wa ujenzi na uchapishaji. Vifurushi vya Svelte ndivyo vya msingi; ukiwa na shaka, mikataba yake hushinda.

Hatua zinazofuata

• Orodha ya vipengele — marejeo kamili ya vipengele 571.
• Msaada — utatuzi wa matatizo na maswali yanayoulizwa mara kwa mara.
• Kwa nini Lily — na jinsi ya kuunga mkono mradi.

Una maswali njiani? Ukurasa wa msaada umejaa majibu — na kama hatua inaweza kuwa wazi zaidi, tuambie na tutafurahi kuboresha mafunzo.