انتقل إلى المحتوى
TopClass UI

قائمة اختيار

اختيار واحد من قائمة بيانات بسيطة. تبقى القائمة المنبثقة داخل الشاشة وتمرّر نفسها، بارتفاع سبعة صفوف افتراضيًا.

client - الحجم لم يُقَس بعد

قائمة اختيار

client - الحجم لم يُقَس بعد

اختيار واحد من قائمة بيانات بسيطة. تبقى القائمة المنبثقة داخل الشاشة وتمرّر نفسها، بارتفاع سبعة صفوف افتراضيًا.

تثبيت

جرّبه

size
invalid
fullWidth
placement
visibleRows
loadMoreThreshold

الشيفرة

select.tsx
import { Select } from 'topclassui/select'

<div className="grid justify-items-start gap-1.5">
  <label htmlFor="select-playground" className="text-sm text-body">Country</label>
  <Select id="select-playground" items={COUNTRIES} defaultValue="jo" />
</div>

items بيانات بسيطة، فتستطيع صفحة خادم أن تعرض Select: لا تعبر أي دالة إلى المتصفح.

كل الحالات، بدون تمرير الفأرة

4 حالات
Pick a paid plan.

أو استورده من الحزمة

topclassui/select
import { Select } from 'topclassui/select'

ثبّت مرة واحدة:npm i topclassui@beta zod

أمثلة

  • items يأخذ { value, label, disabled? }: القيمة هي ما يستلمه النموذج، والتسمية هي ما يظهر في الصف وعلى الزر.
  • داخل نموذج يرسل القيمة المختارة، وقبل الترطيب يرسل القيمة الافتراضية. وإعادة ضبط النموذج تعيد القيمة الافتراضية.
  • تعرض القائمة سبعة صفوف، أو visibleRows (من 1 إلى 20)، ثم تمرّر داخلها. ولا تعرض الصفوف الظاهرة فقط: للآلاف من الخيارات استخدم Combobox.
  • placement يأخذ القيم المشتركة الاثنتي عشرة، وbottom-start هي الافتراضية؛ تنقلب القائمة عند الحافة وتبقى على بعد 8px داخل الشاشة.
  • العرض هو عرض Input بنفس size؛ fullWidth يملأ الحاوية، وصنف العرض في className يقع على الزر داخل الصندوق.
basic
form
sizes
four-rows
sixty-items
long-content
بالعربية، من اليمين إلى اليسار

الخصائص

خصائص Select
الخاصيةالنوعالافتراضيالحدودالوصف
items*readonly ListOption[]--Plain data, so a Server Component can render a Select: one option per row, in order.
aria-labelstring--The name read out when no visible label names the control.
aria-labelledbystring--The id of the visible text that names the control.
idstring--The id a <label htmlFor> points at.
classNamestring--On the trigger, merged last, so a consumer class wins a conflict with its own.
containerBase.Portal.Props['container']--Where the list mounts; <body> by default.
fullWidthbooleanfalse-Select: the box fills the width of its parent instead of taking the width of an Input.
hasMoreboolean--
invalidbooleanfalse-Select: marks the choice as wrong: sets aria-invalid on the trigger, whose line turns to danger and thickens.
loadMore(() => void | Promise<void>)--Client-only, or a Server Action. Called once when the window nears the end.
loadMoreThresholdinteger, min 0, max 20010min 0, max 200Select: rows from the end of the open list at which loadMore is called, clamped to 0 to 200.
placeholderstring--The text of an empty trigger. Left out, the provider's select.placeholder.
placementtop | top-start | top-end | bottom | bottom-start | bottom-end | start | start-top | start-bottom | end | end-top | end-bottom"bottom-start"-Select: the side and alignment the list opens at; start and end mirror in Arabic.
refRef<HTMLButtonElement>--The trigger, a <button role="combobox">.
sizexs | sm | md | lg | xl | custom"md"-Select: the height, the inline padding and the type step of the trigger, and its width with them; custom emits no size classes.
visibleRowsnumber, min 1, max 207min 1, max 20Select: rows the list shows before it scrolls, clamped; left out, the --tc-list-rows knob applies.

لوحة المفاتيح وإمكانية الوصول

لوحة مفاتيح Select
المفاتيحما يفعله
ArrowDownيفتح القائمة على الخيار المحدد؛ وداخلها ينتقل إلى الأسفل ويتوقف عند النهاية.
ArrowUpيفتح القائمة على الخيار المحدد؛ وداخلها ينتقل إلى الأعلى ويتوقف عند البداية.
Spaceيفتح القائمة على الخيار المحدد.
Enterيفتح القائمة؛ وداخلها يختار الخيار ويغلقها.
Homeينتقل إلى الخيار الأول.
Endينتقل إلى الخيار الأخير.
Escapeيغلق القائمة ويعيد التركيز إلى زر الفتح.
A-Zعلى الزر المغلق، يختار الخيار التالي الذي يبدأ بذلك الحرف.
  • الاسم مطلوب: id لتسمية <label htmlFor>، أو aria-label، أو aria-labelledby. الزر هو <button role="combobox">.
  • ارتفاع الصف 40px، و44px تحت مؤشر لمس، والتسمية الطويلة تنتهي بعلامة حذف في الصف وعلى الزر.
  • invalid يضبط aria-invalid على الزر، فيتحوّل خطه إلى لون الخطر ويزداد سمكًا.

من اليمين إلى اليسار

يقع السهم وعلامة الاختيار على اليسار، وbottom-start تحاذي القائمة مع الحافة اليمنى للزر. مفاتيح الأسهم عمودية، فلا يتغيّر معناها.

الخادم والمتصفح

مكوّن متصفح: يُعرض على الخادم ثم يُرطَّب في المتصفح.

الملفات: index.tsx, client.tsx.

على الشارة: client - الحجم لم يُقَس بعد.