العرض الشجري
تنقّل بين المجلدات المتداخلة والمحتوى المنظم مع فروع قابلة للتوسيع وانتقالات تمويه سلسة وتنقل بلوحة المفاتيح.
التثبيت
يمكنك إضافة العرض الشجري باستخدام CLI الخاص بنا أو يدويًا:
الوضع الداكن جاهز - هذا مكوّن يتبع رموز التصميم الدلالية لـ BoardUI تلقائياً. إعداد تبديل السمة.
تنسخ CLI مصدر المكوّن (مع تبعياته الداخلية) إلى مشروعك وتثبّت أي حزم npm مطلوبة.
npx boardui@latest add tree-viewهل تستخدم حزمة واجهة مستخدم مشتركة أو أسماء استيراد مختصرة مخصصة؟ تهيئة مسارات التثبيت قبل تشغيل CLI. تستخدم أمثلة النسخ واللصق الاستيرادات الافتراضية.
التحكم بالبيانات والحالة
احتفظ بحالة التوسيع والتحديد لديك باستخدام expandedKeys و selectedKeys. استخدم TreeViewCollection لتجسيد البيانات المتداخلة بشكل متكرر. يحتاج كل عنصر إلى معرّف فريد وثابت id.
تتوسع الفروع وتُطوى بانتقال سلس في الارتفاع والتلاشي والتمويه. تخرج الصفوف المغادرة من التنقل بلوحة المفاتيح فورًا، ويعطّل تقليل الحركة الرسوم المتحركة.
import { useState } from "react";import type { Key, Selection } from "react-aria-components";import { TreeView, TreeViewCollection, TreeViewItem } from "@/components/base/tree-view/tree-view";
interface FileNode { id: string; name: string; children?: FileNode[];}
const files: FileNode[] = [ { id: "design", name: "Design", children: [ { id: "logo", name: "Logo.svg" }, { id: "colors", name: "Colors.fig" }, ] }, { id: "notes", name: "Project notes.md" },];
function renderFile(item: FileNode) { return ( <TreeViewItem id={item.id} label={item.name}> <TreeViewCollection items={item.children ?? []}>{renderFile}</TreeViewCollection> </TreeViewItem> );}
export function Example() { const [expandedKeys, setExpandedKeys] = useState<Set<Key>>(new Set(["design"])); const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set(["logo"]));
return ( <TreeView aria-label="Workspace files" items={files} expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys} selectedKeys={selectedKeys} onSelectionChange={setSelectedKeys} > {renderFile} </TreeView> );}التحديد المتعدد
تعيين selectionMode="multiple" لتبديل العناصر بشكل مستقل. اضغط Shift لتحديد نطاق بلوحة المفاتيح. التحديد الفردي هو الافتراضي؛ استخدم selectionMode="none" مع onAction لشجرة تنفّذ الإجراءات فقط.
<TreeView aria-label="Documents to share" selectionMode="multiple" defaultExpandedKeys={["documents"]} defaultSelectedKeys={["overview", "guidelines"]}> <TreeViewItem id="documents" label="Documents" trailingContent="3 files"> <TreeViewItem id="overview" label="Overview.md" /> <TreeViewItem id="guidelines" label="Guidelines.md" /> <TreeViewItem id="changelog" label="Changelog.md" /> </TreeViewItem></TreeView>الأحجام والأيقونات والحالات
استخدام size="sm" للصفوف المضغوطة و showGuides={false} لإخفاء خطوط الإرشاد. تحصل الفروع على أيقونات مجلدات تلقائيًا؛ مرّر مكوّن Remix Icon إلى أيقونة أو expandedIcon لتخصيصها. تمنع العناصر المعطّلة التفاعل، و renderEmptyState يوفّر رسالة عند عدم وجود عناصر.
import { RiFolder3Line } from "@remixicon/react";
<TreeView aria-label="Repository files" size="sm" showGuides={false}> <TreeViewItem id="index" label="index.tsx" /> <TreeViewItem id="private" label="Private files" isDisabled trailingContent="Restricted" /> <TreeViewItem id="archive" label="Archive" icon={RiFolder3Line} trailingContent="Empty" /></TreeView>
<TreeView aria-label="Search results" renderEmptyState={() => "No matching files."}> {[]}</TreeView>من اليمين إلى اليسار
اضبط اللغة والمنطقة باستخدام DirectionProvider. تتبع المسافات البادئة وخطوط الإرشاد وأيقونات التوسيع والتنقل الأفقي بلوحة المفاتيح اتجاه القراءة.
import { DirectionProvider } from "@/components/foundations/direction/direction";import { TreeView, TreeViewItem } from "@/components/base/tree-view/tree-view";
<DirectionProvider locale="ar"> <TreeView aria-label="ملفات المشروع" defaultExpandedKeys={["project"]}> <TreeViewItem id="project" label="المشروع"> <TreeViewItem id="design" label="التصميم"> <TreeViewItem id="logo" label="الشعار.svg" /> </TreeViewItem> <TreeViewItem id="notes" label="الملاحظات.md" /> </TreeViewItem> </TreeView></DirectionProvider>التنقل بلوحة المفاتيح
انتقل إلى الشجرة باستخدام Tab، ثم استخدم السهمين لأعلى ولأسفل للتنقل بين العناصر المرئية. يوسّع السهم لليمين الفرع أو ينتقل إلى أول عنصر فيه؛ ويطوي السهم لليسار الفرع أو يعود إلى الأصل. ينتقل Home وEnd إلى أول عنصر مرئي وآخره. اكتب تسمية للعثور عليها، واضغط Space للتحديد.
امنح كل شجرة aria-label أو aria-labelledby. غلّف مناطق RTL باستخدام مكوّن BoardUI DirectionProvider باللغة والمنطقة المناسبة؛ تتبع أيقونات التوسيع والمسافات البادئة والمفاتيح الأفقية الاتجاه تلقائيًا.