@tokapps/tuk · Layer 3 · Navigation
کارت بالای همه صفحه‌ها: لوگو در بالای صفحه روی سطح می‌نشیند و با اسکرول روی شیشه برجسته می‌شود. کنارش، مسیر فعلی مثل شاخه‌ای از درخت دانش رشد می‌کند؛ کلید گسترش، کارت را بزرگ‌تر و مسیرهای مشابه را نشان می‌دهد.
عمق مسیر، سطح، گسترش، پردازش و ماده را ترکیب کنید. تم و حالت روز/شب از تنظیمات سریع Dock گرفته می‌شود.
کلید گسترش را بزنید و یکی از صفحه‌های درختواره را انتخاب کنید: کارت نرم به اندازه اول برمی‌گردد، تا لود شدن صفحه حلقه هفت‌رنگ می‌چرخد، سپس شاخه جدید رشد می‌کند و حاشیه هفت‌رنگ برگ انتخاب‌شده یک دور می‌گردد و آرام محو می‌شود. (بارگذاری اینجا ۱٫۱ ثانیه شبیه‌سازی شده است.)
با کلید گسترش، درخت ناوبری حول صفحه فعال دوباره ریشه‌دار می‌شود و به‌صورت درختواره شعاعی نمایش می‌یابد: صفحه فعال در مرکز، والد و فرزندها در حلقه ۱، هم‌شاخه‌ها و پدربزرگ/نوه‌ها در حلقه ۲ و ... . فرزندهای هر گره دور خودش باز می‌شوند، پس یال‌ها همدیگر را قطع نمی‌کنند. تعداد سطح‌ها را کاربر از کلیدهای ۱ تا ۳ بالای نمودار عوض می‌کند. در هر نمونه کلیدهای سطح را امتحان کنید.
| تنظیم | نوع / پیش‌فرض | توضیح |
|---|---|---|
| trail | TrailNode[] | مسیر فعلی از ریشه تا صفحه؛ آخری «برگ جاری» است. بدون آن شاخه رسم نمی‌شود. |
| graph | (levels) => PageGraph | سازنده درختواره؛ با graphFor(path, lang, { levels, maxPerRing }) ساخته می‌شود. بدون آن کلید گسترش نیست. |
| levels | number = 2 | تعداد سطح‌ها = بیشترین فاصله (تعداد یال) از صفحه فعال. سطح ۱: والد و فرزندها؛ ۲: هم‌شاخه‌ها، پدربزرگ و نوه‌ها؛ ۳: عموها/بخش‌های دیگر و نبیره‌ها. |
| maxLevels | number = 3 | بیشترین سطحی که کاربر با کلیدهای ۱…n بالای درختواره می‌تواند انتخاب کند. |
| maxPerRing (graphFor) | number = 14 | سقف گره در هر حلقه. نزدیک‌ترین‌ها به صفحه فعال (در ترتیب درخت) می‌مانند و تعداد بقیه در نوار بالای درختواره اعلام می‌شود. |
| settleKey | string | با عوض شدنش حاشیه هفت‌رنگ برگ جاری یک دور می‌گردد و آرام می‌شود (مسیر نمایش‌داده‌شده). |
| position | 'fixed' | 'contained' | contained فقط برای قاب پیش‌نمایش مستندات. |
| elevated / expanded / busy | boolean | اجبار وضعیت برای ویترین و تست: برجسته، گسترده، حلقه پردازش. |
| onNavigate | (node) => boolean | void | پیش از رفتن صدا زده می‌شود و کارت جمع می‌شود؛ false یعنی ناوبری لینک انجام نشود. |
هر وضعیت یک صفت یا prop مشخص دارد؛ هیچ‌کدام فقط با رنگ متمایز نمی‌شوند.
بنیان ثابت است: لوگو و کلید گسترش در ردیف اول، مسیر در ردیف دوم، هیچ گره‌ای حذف نمی‌شود. هر تم فقط رفتار نمایش نام را از فهرست بسته انتخاب می‌کند (مشخص‌شده در فراداده تم). زیر هر نمونه را با لمس، کیبورد یا کشیدن امتحان کنید.
نام کوتاه‌شده؛ لمس طولانی، فوکوس یا hover نام کامل را زیر کارت نشان می‌دهد و چند ثانیه می‌ماند.
فقط برگ جاری اگر بلندتر از جا باشد، نامش به‌آرامی می‌لغزد؛ کاهش حرکت: ایستا و کامل زیر کارت.
همهٔ نام‌ها کامل و در چند ردیف؛ کارت به اندازهٔ مسیر بلندتر می‌شود.
یک ردیف افقی با کشیدن و نقطه‌گیری؛ برگ جاری همیشه در دید است.
هر تم در فراداده‌اش یکی از این مقادیر را می‌گذارد؛ مقدار ناشناخته به «لمس طولانی» برمی‌گردد:
// packages/theme-<id>/src/meta.tsexport const meta: ProductThemeMeta = { // … mobileBehavior: 'marquee', // 'long-press-popover' | 'marquee' | 'wrap' | 'track'};// TopBar خودش این مقدار را از تم می‌گیرد؛ محصول فقط لوگو و مسیر را می‌دهد:<TopBar trail={trail} graph={(n) => graphFor(path, lang, { levels: n })} mobileBehavior={themeTopBarMobile(theme)}> <Logo /></TopBar>کد کارت برای هیچ محصولی عوض نمی‌شود؛ فقط توکن تم عوض می‌شود.
همه در packages/tokens/src/5-chrome.css. کامپوننت جز این‌ها هیچ مقداری مصرف نمی‌کند.
| توکن | مقدار | نقش |
|---|---|---|
| --tds-topbar-height | var(--tds-space-16) | |
| --tds-topbar-max-width | 100rem | |
| --tds-topbar-inset-inline | var(--tds-space-4) | |
| --tds-topbar-padding-block | var(--tds-space-2) | |
| --tds-topbar-padding-inline | var(--tds-space-3) | |
| --tds-topbar-gap | var(--tds-space-3) | |
| --tds-topbar-radius | var(--tds-radius-lg) | |
| --tds-topbar-bg | var(--tds-glass-bg) | |
| --tds-topbar-bg-fallback | var(--tds-glass-bg-fallback) | |
| --tds-topbar-tint | var(--tds-glass-tint) | |
| --tds-topbar-blur | var(--tds-glass-blur) | |
| --tds-topbar-saturate | var(--tds-glass-saturate) | |
| --tds-topbar-border | var(--tds-glass-border) | |
| --tds-topbar-highlight | var(--tds-glass-highlight) | |
| --tds-topbar-shadow | var(--tds-elevation-float) | |
| --tds-topbar-z | var(--tds-z-dock) | |
| --tds-topbar-elevate-distance | 56 | px اسکرول از بالای صفحه تا برجستگی کامل |
| --tds-topbar-lift | var(--tds-space-1) | جابه‌جایی کارت هنگام جدا شدن از سطح |
| --tds-topbar-branch-stroke | var(--tds-fg-muted) | خط درختواره باید روی شیشهٔ تیره هم دیده شود (غیرمتن: کنتراست ≥ 3:1) |
| --tds-topbar-branch-width | 1.5px | |
| --tds-topbar-branch-grow | 520ms | رشد شاخه هنگام ورود به یک صفحه |
| --tds-topbar-node-size | var(--tds-space-2) | |
| --tds-topbar-crumb-height | var(--tds-space-8) | |
| --tds-topbar-crumb-padding | var(--tds-space-3) | |
| --tds-topbar-crumb-radius | var(--tds-radius-full) | |
| --tds-topbar-expand-duration | var(--tds-dur-slow) | |
| --tds-topbar-expand-width | 32rem | عرض کارت هنگام باز شدن |
| --tds-topbar-graph-height | 20rem | ارتفاع نقشه صفحه‌ها |
| --tds-topbar-graph-edge | var(--tds-fg-subtle) | یال‌های درختواره: روی شیشهٔ تیره هم دیده شوند (مرز پیش‌فرض تیره تقریباً سیاه است) |
| --tds-topbar-graph-orbit | var(--tds-border-strong) | حلقه‌های هم‌مرکز نقشه: نقطه‌چین کم‌رنگ ولی قابل‌دیدن |
| --tds-topbar-graph-pop | 70ms | تأخیر ورود هر حلقه |
| --tds-topbar-marquee-speed | 6s | یک رفت‌وبرگشت نوار متن برگ جاری در موبایل |
| --tds-topbar-settle-duration | 2200ms | گرادیان انتخاب‌شده تا آرام شدن |
import { TopBar } from '@tokapps/tuk/topbar';
<TopBar
trail={[{ key: 'foundations', label: 'بنیان‌ها', href: '#/foundations' },
{ key: 'foundations/motion', label: 'حرکت', href: '#/foundations/motion' }]}
graph={(levels) => graphFor(shownPath, 'fa', { levels, maxPerRing: 14 })}
levels={2} maxLevels={3}
settleKey={shownPath} // با عوض شدنش گرادیان برگ جاری پخش و آرام می‌شود
>
<Logo />
</TopBar>
<div data-topbar-reserve> … </div>