Cynorthwywyr dewisiadau

Beth fyddwch chi'n ei adeiladu

Panel gosodiadau lle mae defnyddwyr yn dewis eu hiaith a maint eu testun — dewisiadau sy'n berthnasol i'r ddogfen gyfan, yn parhau rhwng ymweliadau, ac yn costio dwy gydran a rhai llinellau o CSS i chi. Tua 15 munud.

Cyn i chi ddechrau

Gorffennwch yn gyntaf y tiwtorial fframwaith ar gyfer eich pentwr. Svelte yw'r samplau isod; mae cynorthwywyr React, Vue, Angular, HTML, Nunjucks a Blazor yn cyfateb contract wrth gontract.

Y ffurf maen nhw'n ei rhannu

• Botwm eicon di-ben sy'n agor blwch rhestr WAI-ARIA APG (neu, ar gyfer date-time-picker, deialog dewis dyddiad) — dim <select>brodorol, fel bod pob fframwaith yn cael yr un ymddygiad bysellfwrdd a bachau steilio.
• Un bachyn dosbarth i bob pecyn (.locale-picker, .text-size-picker, .share-picker, .date-time-picker), sero CSS wedi'i gludo.
• Diogel ar gyfer SSR: dim ond yng nghylch bywyd mount/effect y mae ysgrifennu DOM yn digwydd.
• Glân o ran i18n: mae pob llinyn y mae'r defnyddiwr yn ei weld yn prop.
• Ar gael ar gyfer Svelte (canonaidd), React, Vue, Angular, elfen bersonol HTML, Nunjucks a Blazor — yr un contract ym mhob un.

Mae theme-picker, locale-picker a text-size-picker bob un yn berchen ar un dewis defnyddiwr o'r dechrau i'r diwedd (dewis, cymhwyso i'r DOM, localStorage parhad dewisol drwy'r prop storageKey ). Mae share-picker a date-time-picker yn wahanol o ran math: mae share-picker yn berchen ar weithred — nid yw'n cymhwyso dim i'r ddogfen ac nid yw'n parhau dim — ac mae date-time-picker yn berchen ar werth ffurflen, gan fod dyddiad mewn ffurflen yn ddata, nid yn ddewis.

locale-picker — iaith a chyfeiriad

Yn gadael i'r defnyddiwr ddewis locale, yna'n ysgrifennu lang a dir ar wraidd y ddogfen fel bod eich llyfrgell i18n, eich CSS a thechnolegau cynorthwyol i gyd yn ei ddilyn. Caiff RTL ei ganfod yn awtomatig ar gyfer Arabeg, Hebraeg a sgriptiau eraill o'r dde i'r chwith. Mae'n canolbwyntio'n llwyr ar signalu — eich llyfrgell i18n sy'n trin y cyfieithu.

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

Caiff yr opsiynau eu labelu o dabl adeiledig o enwau locale (gellir ei ddiystyru drwy localeLabels), mae pob opsiwn yn cario ei briodoledd lang ei hun fel bod darllenwyr sgrin yn ynganu "Français" yn Ffrangeg, a chaiff codau â thanlinell fel en_US eu trosi'n ddi-golled i BCP 47 ac yn ôl en-US. Cysylltwch onChange (neu'r gwerth rhwymedig) ag i18next, Paraglide, vue-i18n neu beth bynnag a ddefnyddiwch.

text-size-picker — maint dan reolaeth y darllenydd

Mantais hygyrchedd sy'n cymryd munudau: mae'r cynorthwyydd yn gosod data-text-size="{slug}" ar wraidd y ddogfen ac mae eich CSS yn mapio pob gwerth i faint.

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

Maint eich cynllun yn rem ac mae'r ap cyfan yn graddio gyda dewis y defnyddiwr. Caiff labeli eu ffurfio o'r slugs gyda phrif lythyren ("X Large") neu eu diystyru gyda sizeLabels.

share-picker — anfonwch y dudalen hon

Botwm un glyff sy'n agor taflen rannu brodorol y ddyfais lle mae un, ac fel arall yn disgyn yn ôl i restr o gyrchfannau a ddarparwch, ynghyd â gweithred copïo'r URL. Nid yw'n cludo unrhyw URLau rhwydweithiau cymdeithasol — pa rwydweithiau sy'n perthyn yn eich cynnyrch yw eich penderfyniad chi, nid penderfyniad y system ddylunio.

<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 yw ei ragosodiad location.hreffelly nid oes angen unrhyw wifrau ar y cyflwr cyffredin. Gorfodwch lwybr gyda strategy="list" neu strategy="native" pan fo angen ymddygiad cyson ar draws llwyfannau ar gyfer profion neu sgrinluniau.

date-time-picker — dyddiad, amser, neu'r ddau

Maes testun y gallwch deipio ynddo, ynghyd â botwm eicon sy'n agor deialog dewis dyddiad WAI-ARIA APG. Cywir o ran locale yn ôl cynllun — daw enwau misoedd, enwau diwrnodau'r wythnos, diwrnod cyntaf yr wythnos a chloc 12 neu 24 awr i gyd o Intl — ac mae'r gwerth bob amser yn llinyn ISO trefnadwy heb barth amser: "2026-03-15" ar gyfer mode="date", "09:30" ar gyfer mode="time", "2026-03-15T09:30" ar gyfer 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",
  }}
/>

Mae'r gwerth ISO yn union yr un fath â'r hyn y mae <input type="date"> yn ei anfon, felly gallwch gyfnewid y rheolydd brodorol i mewn neu allan heb gyffwrdd â'ch ôl-wyneb.

motion-picker — parchwch symudiad llai

Mae'r cynorthwyydd yn gosod data-motion="{slug}" ar wraidd y ddogfen. Daw ei werth cyntaf o osodiad prefers-reduced-motion system weithredu'r ymwelydd — bob amser, heb faner optio i mewn, oherwydd bod symudiad yn angen hygyrchedd go iawn (WCAG 2.3.3). Eich CSS a'ch sgriptiau sy'n penderfynu beth a gaiff ei fygu.

<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 — blwch chwilio nad yw'n rhwystro

Botwm eicon sy'n agor maes chwilio. Mae pwyso Return, neu'r botwm ⏎ wrth ymyl y maes, yn llywio gyda chais GET syml i /?<text> (caiff y testun ei docio a'i amgodio fel URI; nid yw ymholiad gwag yn mynd i unman). Mae ei dri enw hygyrch yn ofynnol, oherwydd nid yw'r cynorthwyydd yn cludo Saesneg.

<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 yn newid y llwybr (/search?foo), ac mae navigate yn cadw'r llywio y tu mewn i'r ap; hebddo mae'r cynorthwyydd yn galw location.assign.

picker-bar — y rhes pennawd gyfan ar unwaith

picker-bar yn rendro chwilio, thema, locale, maint testun a rhannu mewn un rhes, gyda'r set lawn o themâu cyfeirio a'r raddfa testun saith cam wedi'u gwifro ymlaen llaw. Mae pob enw hygyrch yn cyrraedd mewn un gwrthrych labels gofynnol.

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

Cyrhaeddwch unrhyw ddewisydd wedi'i lapio gyda searchProps, themeProps, localeProps, textSizeProps a shareProps.

Mae awgrymiadau offer wedi'u hadeiladu i mewn

Mae pob dewisydd yn dangos ei label mewn awgrym offer pan fo'r pwyntydd yn gorffwys ar ei fotwm neu pan fo ffocws bysellfwrdd ar y botwm. Mae'r awgrym offer yn aros tra bo'r pwyntydd yn symud arno, mae Escape yn ei gau ble bynnag y bo'r ffocws, ac nid yw byth yn dangos tra bo naidlen y dewisydd ar agor. Mae'n cario'r un testun ag enw hygyrch y botwm, felly nid oes dim i'w ffurfweddu na'i gyfieithu ddwywaith; mae'r themâu cyfeirio yn ei steilio.

Panel gosodiadau mewn un lle

Mae'r pedwar cynorthwyydd dewisiadau yn cyfansoddi'n naturiol:

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

Ble i'w cael

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

Mae gan bob pecyn ei spec ei hun, profion wedi'u mapio i gymalau'r spec, enghreifftiau y gellir eu rhedeg (gan gynnwys patrymau cwcis SSR) a phibell adeiladu + cyhoeddi. Y pecynnau Svelte yw'r rhai canonaidd; os oes amheuaeth, eu contractau sy'n ennill.

Y camau nesaf

• Catalog cydrannau — cyfeirnod llawn y 571 cydran.
• Cymorth — datrys problemau a chwestiynau cyffredin.
• Pam Lily — a sut i gefnogi'r prosiect.

Cwestiynau ar y ffordd? Mae'r dudalen gymorth yn llawn atebion — ac os gellid gwneud cam yn gliriach, dywedwch wrthym a byddwn yn falch o wella'r tiwtorial.