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

العرض الشجري

احصل على Ritla UI

يعرض محتوى متداخلًا مثل مجلدات الكشوفات أو دليل الحسابات، ويتيح فتح الفروع وطيّها. كل مستوى يزيح خطوة، والملفات تحت مجلدها.

فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:

افتح في Figma

المعاينة

«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.

المعاينةالكود
إنجليزيمعكوسعربي
← RTL

التثبيت

  1. أضف المكوّن

    npx ritla add tree-view

    ويعمل أيضًا مع shadcn: npx shadcn@latest add @ritla/tree-view

  2. الاعتماديات التي يضيفها

    @phosphor-icons/react

  3. أو انسخه يدويًا

    التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.

الاستخدام

tree-view.tsx
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}).

إنجليزيمعكوسعربي
← RTL

مرجع الخصائص

TreeView

الخاصيةالنوعالافتراضيالوصف
items{ id, label, children? }[]لا يوجدالشجرة؛ العنصر الذي له children فرع حتى لو كانت فارغة.
expanded / defaultExpandedstring[]لا يوجدالفروع المفتوحة.
onExpandedChange(ids: string[]) => voidلا يوجديُستدعى عند فتح فرع أو طيّه.
selected / defaultSelectedstring | nullلا يوجدالصف المحدد.
onSelectedChange(id: string) => voidلا يوجديُستدعى عند تحديد صف.
showIconsbooleantrueخاصية Show icon: أيقونات المجلد والملف.
aria-labelstringلا يوجداسم الشجرة لقارئ الشاشة.

إرشادات الاستخدام

العرض الشجري يعرض تسلسلًا هرميًا حقيقيًا يتصفحه الناس ويفتحونه خطوة خطوة. هنا: متى تناسب الشجرة، وعمقها وترتيبها، والاختيار والإجراءات، وكيف تتدرج من اليمين في العربية، والتحميل والفروع الفارغة، وما تتحقق منه قبل التسليم.

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

افعل

  • النسخة العربية، متدرجةً من اليمين.
  • الأسهم المغلقة تشير إلى اليسار، والمفتوحة إلى الأسفل.
  • أيقونات المجلد والملف دون عكس.

تجنّب

  • تدرّج الأشجار العربية من اليسار.
  • إبقاء الأسهم متجهة إلى اليمين في العربية.

الفحوص التي يجتازها

فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.

  • R042نص مقصوص: محتوى أعرض من صندوقه مع overflow مخفي وبلا علامة حذف
  • R043حاوية بعرض ثابت بالبكسل يتجاوز نصها العربي المساحة
  • R050نص عربي يسقط إلى خط غير الخط المعلن (مقيسًا، أو وفق الإعلان، أو لأن خط الويب فشل في التحميل)
  • R051تباعد حروف مطبَّق على نص عربي (يكسر الخط المتصل)