العرض الشجري
يعرض محتوى متداخلًا مثل مجلدات الكشوفات أو دليل الحسابات، ويتيح فتح الفروع وطيّها. كل مستوى يزيح خطوة، والملفات تحت مجلدها.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add tree-viewويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/tree-viewالاعتماديات التي يضيفها
@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { TreeView } from "@/components/ui/tree-view";<TreeView aria-label="Documents" items={[ { id: "statements", label: "Statements", children: [{ id: "q1", label: "Q1 2026" }] }, { id: "invoices", label: "Invoices", children: [] }, ]} defaultExpanded={["statements"]}/>أمثلة
تحديد متحكَّم به
selected وexpanded من الصفحة: اختيار ملف يفتحه بجانب الشجرة. والأيقونات مخفية (showIcons={false}).
مرجع الخصائص
TreeView
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
items | { id, label, children? }[] | لا يوجد | الشجرة؛ العنصر الذي له children فرع حتى لو كانت فارغة. |
expanded / defaultExpanded | string[] | لا يوجد | الفروع المفتوحة. |
onExpandedChange | (ids: string[]) => void | لا يوجد | يُستدعى عند فتح فرع أو طيّه. |
selected / defaultSelected | string | null | لا يوجد | الصف المحدد. |
onSelectedChange | (id: string) => void | لا يوجد | يُستدعى عند تحديد صف. |
showIcons | boolean | true | خاصية Show icon: أيقونات المجلد والملف. |
aria-label | string | لا يوجد | اسم الشجرة لقارئ الشاشة. |
إرشادات الاستخدام
العرض الشجري يعرض تسلسلًا هرميًا حقيقيًا يتصفحه الناس ويفتحونه خطوة خطوة. هنا: متى تناسب الشجرة، وعمقها وترتيبها، والاختيار والإجراءات، وكيف تتدرج من اليمين في العربية، والتحميل والفروع الفارغة، وما تتحقق منه قبل التسليم.
1. متى تناسب الشجرة
استخدم الشجرة لتسلسل هرمي حقيقي يتصفحه الناس ويفتحونه خطوة خطوة: مجلدات المستندات، أو دليل الحسابات، أو فئات المنتجات. وإن كانت البنية مسطّحة، أو كان الناس يبحثون أكثر مما يتصفحون، فالقائمة أو الجدول أو البحث يخدمهم أفضل.
| تحتاج إلى | استخدم | السبب |
|---|---|---|
| تصفح مجلدات أو فئات متداخلة | العرض الشجري | افتح الفروع التي تحتاجها فقط. |
| عرض قائمة مسطّحة من العناصر | قائمة أو جدول | لا تسلسل هرمي لفتحه. |
| تجميع بضعة أقسام من المحتوى في صفحة واحدة | الأكورديون | عناوين بمحتوى، لا ملفات. |
| التنقل بين أقسام التطبيق | الدرج الجانبي أو التنقل الجانبي أو التبويبات | الشجرة للتنقل تُخفي أين أنت. |
| العثور على عنصر في تسلسل هرمي كبير | البحث مع الشجرة | الكتابة أسرع من فتح خمسة مستويات. |
2. العمق والترتيب
أبقِ الشجرة في أربعة مستويات على الأكثر. ويتدرج كل مستوى خطوة (16 بكسل للأول، و48 أخرى لكل مستوى)، وتُظهر الفروع سهمًا ومجلدًا، والأوراق ملفًا أعمق بخطوة. اعرض المجلدات قبل الملفات، ثم رتّب بالاسم وفق لغة الصفحة.
افعل
- أربعة مستويات أو أقل.
- الفروع قبل الأوراق، ثم الترتيب بالاسم.
- أبقِ التسميات قصيرة؛ والاسم الكامل يمكن أن يكون في تلميح.
- افتح الفرع الذي يحوي العنصر الحالي افتراضيًا.
تجنّب
- التداخل لأعمق من أربعة مستويات؛ سطّح البنية أو أضف بحثًا.
- اختلاف مقدار التدرج بين المستويات.
- فتح كل الفروع دفعة واحدة.
3. الاختيار والإجراءات
يُختار صف واحد في كل مرة ويُظهر تعبئة الاختيار، وتحتفظ التسمية بتباينها الكامل. وإجراءات الصف (إعادة التسمية، النقل، الحذف) مكانها زر قائمة على الصف أو شريط أدوات فوق الشجرة، لا أزرار داخل كل صف.
افعل
- صف مختار واحد بتعبئة الاختيار وتسمية مقروءة.
- ضع إجراءات الصف في قائمة أو شريط أدوات.
- اجعل النقر على السهم يفتح الفرع دون اختياره.
تجنّب
- جعل الصف المختار يبدو معطّلًا.
- وضع عدة أزرار في كل صف.
4. العربية والاتجاه من اليمين إلى اليسار
تتدرج النسخة العربية من اليمين. ويشير سهم الفرع المغلق إلى اليسار، نحو المحتوى داخله، ويتجه إلى الأسفل حين يُفتح. ولا تنعكس أيقونات المجلد والملف. وفي الكود تتبع مفاتيح الأسهم الاتجاه: السهم الأيسر يفتح الفرع في العربية، والأيمن يغلقه.
الشجرة تتدرج من اليمين
مستندات الحساب بالعربية.
5. التحميل والفروع الفارغة
الأشجار الكبيرة تحمّل أبناء الفرع حين يُفتح. اعرض مؤشر تحميل على الصف أثناء التحميل، ورسالة قصيرة في الفرع الفارغ («لا مستندات بعد») بدل سهم يفتح على لا شيء.
افعل
- حمّل الأبناء حين يُفتح الفرع، مع مؤشر تحميل على الصف.
- اعرض رسالة في الفروع الفارغة.
- احفظ حالة الفتح حين يعود الناس.
تجنّب
- تجميد الشجرة كلها أثناء تحميل فرع واحد.
- عرض سهم على فرع بلا أبناء.
قبل التسليم
- تسلسل هرمي حقيقي من أربعة مستويات أو أقل.
- الترتيب والفروع المفتوحة افتراضيًا والاختيار محسومة.
- التحميل والفروع الفارغة مصمّمة.
- الشاشات العربية تستخدم النسخة العربية، متدرجةً من اليمين.
إمكانية الوصول
لوحة المفاتيح
المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.
| المفتاح | ما يفعله |
|---|---|
| Tab | يدخل الشجرة مرة واحدة على الصف المحدد. |
| ArrowDownArrowUp | بين الصفوف الظاهرة. |
| ArrowRight | يفتح الفرع المطوي أو ينتقل إلى أول أبنائه. في العربية ArrowLeft. |
| ArrowLeft | يطوي الفرع المفتوح أو ينتقل إلى الأب. في العربية ArrowRight. |
| HomeEnd | إلى أول صف أو آخره. |
| EnterSpace | يحدد الصف. |
ARIA
-
role="tree"باسم، وكل صفtreeitemمعaria-levelوaria-setsizeوaria-posinset، وaria-expandedللفروع وaria-selected. - لا تتجاوز أربعة مستويات، ولا تستخدم الشجرة للتنقل بين أقسام التطبيق.
افعل
-
role="tree"وtreeitem، معaria-expandedعلى الفروع وaria-selectedعلى الصف المختار. - السهمان الأعلى والأسفل يتنقلان؛ والأيمن يفتح أو يدخل (الأيسر في العربية)، والأيسر يغلق أو يخرج (الأيمن في العربية).
- Home وEnd، والبحث بالحرف الأول.
تجنّب
- جعل كل صف محطة Tab مستقلة.
- الاكتفاء بأيقونة المجلد لإظهار أن الفرع مفتوح.
ملاحظات العربية والاتجاه
ينعكس
- الإزاحة من اليمين، والسهم المطوي يتجه لليسار، وشريط التحديد على اليمين.
- مفتاحا الفتح والطي ينعكسان: ArrowLeft يفتح وArrowRight يطوي.
لا ينعكس
- أيقونات المجلد والملف.
- الأرقام
- الأرقام في التسميات كما كُتبت.
- الخط العربي
-
label-14عادي، والتسمية الطويلة تُقص بنقاط. - النص ثنائي الاتجاه
- امتدادات الملفات مثل .pdf تنقلب داخل تسمية عربية؛ احذفها أو ضعها في
<bdi>.
افعل
- النسخة العربية، متدرجةً من اليمين.
- الأسهم المغلقة تشير إلى اليسار، والمفتوحة إلى الأسفل.
- أيقونات المجلد والملف دون عكس.
تجنّب
- تدرّج الأشجار العربية من اليسار.
- إبقاء الأسهم متجهة إلى اليمين في العربية.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.