نظرة عامة
يوفرListItem التخطيط المرئي المشترك بين صفوف القوائم والقوائم المنسدلة. يعرض عنصر div افتراضيًا للمحتوى غير التفاعلي. استخدم ListItemButton لصفوف الإجراءات العادية. كوّن ListItem باستخدام رابط للتنقل أو باستخدام عنصر دلالي مخصص عند الحاجة. استخدم Dropdown أو Select عندما تحتاج إلى مالك كامل للنافذة المنبثقة أو التحديد.
استخدام
البنية التشريحية
يكشفListItem عن فتحات محتوى عبر الخصائص. ترتب هذه الفتحات المحتوى داخل صف واحد؛ وهي ليست مكونات مُصدَّرة بشكل منفصل.
يوفر الصف التخطيط. يقبل
render عنصراً أو دالة استدعاء تتلقى الخصائص الأصلية والحالة المرئية. انشر تلك الخصائص على الجذر الفعلي عند استخدام دالة استدعاء. تصل السمات الأصلية، ومعالجات الأحداث، وclassName، وstyle، وref إلى ذلك الجذر. بالنسبة إلى صف يحتوي على أزرار إجراءات مستقلة، أبقِ الصف نفسه غير تفاعلي لكي تظل تلك الأزرار عناصر تحكم منفصلة.
صفوف متعددة الأسطر
عيّنdescriptionPlacement="below" لوضع المحتوى الداعم أسفل التسمية. يحتفظ العنوان بسلوك الاقتطاع الحالي، ويلتف المحتوى الداعم وفقًا للعرض المتاح. يحتفظ الموضع الافتراضي inline وموضع end بمظهرهما الحالي.
truncate أو lineClamp بوصفه description. يتحكم المحتوى المخصص في تخطيطه وتسمياته المتاحة بنفسه.
حالات مرئية مستقلة
تعود جميع الحالات المرئية إلى المستدعي. يحددactive الصف المفتوح أو الحالي من دون تحديده. يمثل selected التحديد، ويمثل focused تمييز التنقل بلوحة المفاتيح من دون نقل تركيز DOM. يطبق active خلفية الصف الحالي. عيّن selectionAppearance="accent" للحصول على تعبئة بارزة في الصفوف المحددة، بشكل مستقل عن موضع الوصف. يحافظ المظهر الافتراضي على تنسيق التحديد الحالي المعتمد على المؤشر. يطبق focused الخلفية المميزة المشتركة، بما في ذلك عندما يستخدمها مالك للتمييز بالمؤشر. يتبع مخطط التركيز المرئي تركيز لوحة المفاتيح الفعلي على الجذر أو عناصر التحكم التابعة له.
لا تضيف هذه الخصائص حالات متاحة. زوّد المالك الدلالي المناسب بحالة aria-current أو aria-selected أو checked الخاصة بعنصر تحكم. يحتفظ التركيز الفعلي للوحة المفاتيح أيضًا بمخطط التركيز المرئي الأصلي.
عناصر تحكم مستقلة
احتفظ بجذرdiv الافتراضي عندما يحتوي الصف على مربع اختيار حقيقي أو أزرار إجراءات مستقلة. استخدم startIcon لمربع الاختيار وactions للأزرار. لا حاجة إلى indicator الزخرفي عندما يعرض مربع اختيار حقيقي التحديد بالفعل.
ListItem.disabled المظهر فقط؛ مرّر disabled إلى كل عنصر تحكم حقيقي لمنع تنشيطه.
ينطبق سلوك رؤية الإجراءات الحالي على الصفوف متعددة الأسطر: يكشف actionsVisibility="hover" عن الإجراءات عند التمرير أو التركيز داخل الصف، ويبقيها مرئية على أجهزة اللمس. عيّنه إلى always للإجراءات المستمرة، بما في ذلك أثناء فتح نافذة منبثقة يملكها المستدعي. عند عرض صف يبلغ 480px أو أقل، تنتقل الإجراءات متعددة الأسطر إلى سطر خاص بها وتلتف حسب الحاجة.
صف الإجراء
استخدم ListItemButton لدمج تنسيق الصف مع تفاعل الزر الأصلي. مرّرdisabled مرة واحدة للتحكم في كل من المظهر والتفعيل.
ListItem عبر render. يوفر ذلك المالك التركيز الأصلي، والتفعيل بمفتاحي Enter وSpace، وسلوك التعطيل. يوفر ListItem.disabled النمط المرئي المطابق فقط. يعرض shortcut التلميحات؛ ويسجل تطبيقك الاختصارات.
التنقل والروابط الصريحة
مرّر رابط ارتساء عبرrender عندما ينتقل الصف بأكمله. ضع سمات رابط الارتساء، بما في ذلك href وtarget وrel، على ذلك العنصر.
div لتجنب الروابط أو الأزرار المتداخلة. تحتفظ تسميات السلاسل النصية باقتطاعها وتلميح الأدوات عند التجاوز؛ ويمكن للمحتوى المخصص استخدام OverflowingTextWithTooltip مع رابط ارتساء معروض صراحةً.
لا تحتوي الروابط على سمة disabled أصلية. إذا كانت الوجهة غير متاحة، فيجب على مالك الرابط توفير الدلالات المناسبة وترتيب التنقل بالضغط على Tab وسياسة التنقل. لا يمنع تنسيقه باستخدام ListItem.disabled وحده التنقل.
مالك عنصر النافذة المنبثقة
استخدمDropdown.ActionItem أو Dropdown.OptionItem داخل مالك النافذة المنبثقة الخاص بهما. تكوّن هذه الأجزاء بالفعل تخطيط ListItem وتكشف فتحاته المرئية. يوفر مالك النافذة المنبثقة الأدوار والتركيز والتنقل بلوحة المفاتيح والتفعيل وسلوك التعطيل.
سياسة الأحداث الأصلية
يمرر ListItem كائنات الأحداث الأصلية ومعالجاتها. تنتشر النقرات بشكل طبيعي، بما في ذلك النقرات على عناصر تحكم الإجراءات اللاحقة. ضع أي حد مقصود على المالك التفاعلي أو معالج المستدعي.preventDefault()، مثل منع تنقل الرابط. تمرير onClick لا يضيف دوراً، ولا يجعل div قابلاً للتشغيل بلوحة المفاتيح، ولا يغير الانتشار.
السحب والتنقل في المحرر المملوكان للتطبيق
أنشئ صفوفًا قابلة لإعادة الترتيب باستخدامListItem داخل مضيف السحب في تطبيقك. ضع سمات السحب ومستمعيه الخاصة بالمضيف على مقبضه، ومرر المقبض أو أداة الإمساك عبر startIcon. احتفظ بعناصر تحكم مستقلة للرؤية والتحرير والحذف في actions. يتولى مضيف السحب إعادة الترتيب بالمؤشر ولوحة المفاتيح، وتعطيل السحب، وتسميات المقابض المتاحة.
بالنسبة إلى اقتراحات المحرر، احتفظ بمربع القائمة الحالي للمحرر ومالك الخيار النشط. اعرض كل ListItem باستخدام role="option" وaria-selected، واستخدم focused لمظهر الصف النشط. يتولى المحرر التنقل بالأسهم والتفعيل باستخدام Enter بينما يبقى التركيز في سطح التحرير. امنع تغييرات التركيز عند الضغط بالمؤشر عندما يتطلبها المحرر، وتعامل مع تحديد المؤشر في معالج الصف الخاص بالتطبيق.
بالنسبة إلى الاقتراحات في صفحة Dropdown، استخدم Dropdown.OptionItem أو Dropdown.ActionItem لكي تتولى تلك الصفحة التنقل والتفعيل. لا تضف معالجًا ثانيًا لـ Enter أو Space إلى مالك يتم تفعيله بالفعل من لوحة المفاتيح.
صف الإعدادات
استخدم SettingsRow لصف مفتاح تبديل مُسمّى. يُنشئ تركيبًا منListItem وSwitch، ويدير ارتباطهما المتاح، ويستخدم حالة التعطيل الخاصة بالمفتاح لمظهر الصف.
مؤشر التحديد
active وselected وfocused وdisabled بشكل مستقل في تنسيق الصف. لا تسجل إجراءات، ولا تنقل تركيز DOM، ولا تضيف أدواراً أو حالات يمكن الوصول إليها، ولا تمنع الأحداث. مؤشرا check وcheckbox زخرفيان؛ استخدم Checkbox حقيقياً لعنصر تحكم في نموذج. عيّن aria-pressed أو aria-selected أو دلالات حالة أخرى على المالك الذي يحتاج إليها.
صفوف المنتقي
التحديد تابع للعنصر الأصل. لا يحتويListItem على حالة تحديد غير مضبوطة: مرّر selected وحدّثه من onClick. استخدم indicator="check" لخيار واحد وindicator="checkbox" لخيارات متعددة. كلا المؤشرين زخرفي؛ ويتولى المالك التفاعلي التفعيل.
في مربع قائمة موجود، مرّر role="option" وaria-selected، وأبقِ التركيز ومعالجة مفاتيح الأسهم في مربع القائمة. للحصول على عنصر واجهة اختيار كامل، استخدم Select. يمكن لأزرار الاختيار المستقلة استخدام aria-pressed، كما في هذه الأمثلة.
اختيار واحد
ضع Avatar فيstartIcon لتعريف سجل. استخدم description للنص الداعم، وdescriptionPlacement="end" لقيمة لاحقة.
اختيار متعدد
استخدم Tag كمحتوى الصف للقيم ذات العلامات، أو ضع ColorSample فيstartIcon لاختيار لون. يمكن أن يحتوي الصف أيضاً على نص عادي أو صورة رمزية.
disabled الأصلي على الزر المعروض لمنع التفعيل وإزالته من ترتيب التنقل بالضغط على Tab. مرّر أيضاً ListItem.disabled لمظهره المرئي.
فتحات
استخدمstartIcon وendIcon للأيقونات أو المحتوى الذي يملكه المستدعي، وdescription للنص الداعم، وactions للمحتوى اللاحق، وhasSubmenu لمؤشر قائمة فرعية. يقبل descriptionPlacement القيم inline أو end أو below. ينسق color="danger" إجراءً إتلافيًا. تجنب تداخل عناصر التحكم التفاعلية داخل صف معروض كزر.
التسميات العربية
استخدمshortcutJoinLabel لتخصيص النص بين خطوات الاختصار المتسلسلة. تكون قيمته الافتراضية then؛ وتزيل السلسلة الفارغة نص الربط. تتوفر الخاصية نفسها في أجزاء عنصر Dropdown.
الإزاحة
يُنشأ المرجع من الأنواع العامة للمكوّنات. تُقبل سمات ومعالجاتdiv الأصلية، بما في ذلك الأسماء القابلة للوصول والأحداث الأصلية. ضع السمات الخاصة بالزر أو رابط الارتساء على العنصر الموفّر عبر render. يستهدف كل من ref ومرجع العنصر المعروض الجذر الفعلي لـ DOM.
ReactNode
Trailing content, such as buttons, rendered after the content.
"auto" | "end"
افتراضي:"auto"
Keeps actions beside the content at every width when set to
end. The default auto preserves responsive wrapping. Hidden end actions do not reserve width on devices without touch."always" | "hover"
افتراضي:"hover"
When trailing actions are visible: on hover and focus, or always.
boolean
افتراضي:"false"
Marks the open or current item independently of selection and focus. Does not add accessible state or activate the item.
"danger" | "neutral"
افتراضي:"neutral"
Color of the text and icons.
danger marks a destructive action.ReactNode
Supporting text, placed according to
descriptionPlacement."below" | "end" | "inline"
افتراضي:"inline"
Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.
boolean
افتراضي:"false"
Applies disabled styling only. Set native disabled behavior and accessible semantics on the button, link, or popup item owner.
ReactNode
Icon rendered after the content.
boolean
افتراضي:"false"
Applies highlighted styling without moving DOM focus or handling keyboard navigation.
Shows a chevron indicating that the item opens a submenu.
"check" | "checkbox" | "none"
افتراضي:"none"
Selection indicator: a check icon after the content or a checkbox before
it.
Ref<HTMLElement>
Ref to the actual DOM root, including a composed native button or link.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ListItemState>
Composes the row with an element or render callback. The owner supplies interaction semantics, native attributes, and behavior.
boolean
افتراضي:"false"
Applies selected styling and the configured decorative indicator. Selection state and accessible semantics belong to the owner.
"accent" | "default"
افتراضي:"default"
Selection styling independent of description placement.
default preserves indicator-based styling; accent fills selected rows with the accent background.ShortcutDefinition
Keyboard shortcut keys displayed at the end of the row. Registering the
shortcut is up to the application.
string
Text between sequential shortcut steps. Defaults to
then; pass an empty string to omit it.ReactNode
Icon rendered before the content.
shortcut={['Mod', 'Enter']} للمفاتيح المتزامنة أو shortcut={[['G'], ['P']]} للضغطات المتتالية. راجع Shortcut للتعرف على التركيبات المتداخلة ومنسق السلاسل المشترك.