ناوبری بالا — TopNavigation

نوار ناوبری اصلی سایت یا بخش را در بالای صفحه می‌سازد: برند در ابتدای خط، مقصدهای اصلی در میانه و کنش‌ها (جستجو، پروفایل) در انتها. ساختار > > و لندمارک ناوبری ثابت‌اند؛ ظاهر شیشه‌ای و حرکت فقط از توکن‌ها و هویت می‌آیند. برای موبایل، مقصدهای اصلی در داک شیشه‌ای ثابت پایین صفحه (Dock) قرار می‌گیرند.

وضعیت: beta · لایه: ۳ () · کد:

TSX

import { TopNavigation } from '@tokapps/tuk';

نمونهٔ زنده

توکاپس

کد قابل کپی

نوار پایه با برند و کنش

TSX

import { Icon } from '@tokapps/icons';import { Button, TopNavigation } from '@tokapps/tuk';const items = [  { id: 'home', label: 'خانه', href: '/', current: true },  { id: 'forum', label: 'انجمن', href: '/forum' },  { id: 'funding', label: 'سرمایه‌گذاری', href: '/funding', badge: '۳' },  { id: 'stories', label: 'روایت‌ها', href: '/stories' },];<TopNavigation  items={items}  brand="توکاپس"  actions={<Button variant="ghost" aria-label="جستجو" icon={<Icon name="search" />} />}/>

نوار چسبان با پیوند روتر و تنظیم کامل

TSX

import Link from 'next/link';import { TopNavigation } from '@tokapps/tuk';<TopNavigation  items={items}  brand="توکاپس"  variant="solid"  sticky  aria-label="ناوبری اصلی سایت"  renderLink={(props) => <Link {...props} />}  className="site-header"/>

آیتم غیرفعال و آیتم بدون مقصد (دکمه)

TSX

import { TopNavigation } from '@tokapps/tuk';<TopNavigation  items={[    { id: 'home', label: 'خانه', href: '/', current: true },    { id: 'soon', label: 'به‌زودی', href: '/soon', disabled: true },    { id: 'help', label: 'راهنما', onPress: () => openHelp() },  ]}  brand="توکاپس"  print="show"/>

همهٔ پیکربندی‌ها

نوع	پیش‌فرض	توضیح
	— (الزامی)	مقصدهای ناوبری به ترتیب نمایش.
	— (الزامی)	کلید یکتا هر آیتم ( فهرست).
	— (الزامی)	برچسب قابل‌مشاهده.
	—	با آیتم لینک می‌شود؛ بدون آن .
	—	آیکون قبل از برچسب (با ).
	—	نشان عددی یا متنی کنار برچسب.
		غیرفعال؛ کلیک نادیده گرفته می‌شود.
		صفحهٔ فعلی؛ .
	—	اجرا هنگام کلیک (برای آیتم بدون یا همراه آن).
	—	لوگو یا نام محصول در ابتدای خط.
	—	کنش‌ها (جستجو، پروفایل، …) در انتهای خط.
·		ماده شیشه‌ای یا سطح تخت.
		چسبیدن به بالای صفحه هنگام اسکرول.
		برچسب landmark ناوبری.
·		نمایش نوار در چاپ.
	—	رندر لینک با روتر (مثلاً Next Link).
		جایگزین تگ لینک؛ اگر باشد نادیده گرفته می‌شود.
	—	کلاس روی ریشهٔ .

اندازه‌ای () برای این کامپوننت در کد تعریف نشده؛ اندازه ثابت است و ارتفاع از توکن می‌آید.

ساختار و اسلات‌ها

بخش	نشانه	وضعیت
ریشه	، ، ،	بنیان ثابت
برند	(فقط اگر باشد)	محتوا قابل‌تغییر
ناحیهٔ ناوبری	با	بنیان ثابت
فهرست	>	بنیان ثابت
آیتم	روی یا	بنیان ثابت
نشان	(فقط اگر باشد)	محتوا قابل‌تغییر
کنش‌ها	(فقط اگر باشد)	محتوا قابل‌تغییر

ترتیب DOM: > برند؟ > > > > لینک یا دکمه (با آیکون، برچسب، نشان؟) > کنش‌ها؟.

همهٔ حالت‌ها

حالت	نشانه (data-attribute یا prop)	نمایش
پیش‌فرض	بدون	متن ، پس‌زمینه شفاف
hover		پس‌زمینه ، متن
فشردن		پس‌زمینه
صفحهٔ فعلی	⇒	پس‌زمینه ، متن ، وزن نیمه‌پررنگ (رنگ تنها نشانه نیست)
focus-visible		حلقهٔ فوکوس با offset توکنی
غیرفعال (لینک)	⇒ ،	متن ، بدون کلیک و بدون hover
غیرفعال (دکمه)	روی	همان ظاهر؛ حذف از ترتیب Tab
شیشه‌ای	⇒	بلور و لبهٔ شیشه‌ای
سطح تخت	⇒	سطح بدون بلور
چسبان	⇒	در بالای صفحه
کاهش حرکت		بدون transition

تغییرات مجاز برای توسعه‌دهنده

variant: یا .
اندازه: فقط (بدون پراپ اندازه).
چیدمان: افقی؛ جهت عمودی در کد تعریف نشده است.
چسبیدن: (بولی).
چاپ: یا .
لینک: یا برای روتر (مثلاً Next Link)؛ پیش‌فرض .
آیتم: یا ، ، ، ، .
اسلات‌ها: و (هر ).
کلاس: روی .
برچسب landmark: (قابل ترجمه).
توکن سطح کامپوننت: (فهرست بخش توکن‌ها).
صدا و رویداد: این کامپوننت رویداد صوتی ندارد؛ handler اختصاصی صدا در کد تعریف نشده است.

تغییرات ممنوع (بنیان ثابت)

ساختار DOM ( > > > ) و لندمارک با برچسب؛ حذف یا جابه‌جایی آن‌ها ممنوع است.
استایل‌دهی مستقیم به یا از بیرون با تغییر رفتار؛ فقط توکن و مجاز است.
تنظیم دستی روی wrapper یا لینک فرزند به‌جای .
حذف حلقهٔ فوکوس مرئی روی آیتم.
رنگ خام یا گرادیان در کد رابط؛ همه رنگ‌ها از توکن‌های معنایی و می‌آیند.
قرارداد هدف لمسی ۴۴px (از / ).

RTL، کیبورد و صفحه‌خوان

RTL: ویژگی‌های منطقی (inline/block) و برای کنش‌ها؛ در RTL برند از راست، مقصدها و کنش‌ها به انتهای خط (چپ) می‌روند. آیکون‌های جهت‌دار در RTL آینه می‌شوند.
Tab: حرکت بین مقصدها و کنش‌ها؛ آیتم‌های غیرفعال از ترتیب Tab حذف می‌شوند.
Enter: رفتن به مقصد (لینک) یا اجرای (دکمه).
صفحه‌خوان: شامل با (پیش‌فرض «ناوبری اصلی») و فهرست ؛ صفحهٔ فعلی با ؛ آیتم غیرفعال با .
فوکوس: روی لینک یا دکمه؛ آیتم غیرفعال .

صدا، حرکت، چاپ و کاهش حرکت

صدا: این کامپوننت بی‌صدا است؛ پراپ در کد تعریف نشده و معادل بصری لازم نیست.
حرکت: semantic motion با نام روی و . در و فوری (بدون transition) می‌شود.
چاپ: پیش‌فرض (نوار در چاپ حذف می‌شود). با نوار به‌صورت ایستا و بدون پس‌زمینه با خط جداکننده چاپ می‌شود.

توکن‌ها

معنایی مصرفی: ، ، ، ، ، ، .

سطح کامپوننت: ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، .

مسیر تعریف: مقادیر در ؛ فهرست مصرف در . هویت حرکتی هر تم در تعیین می‌شود و ساختار را تغییر نمی‌دهد.

قرارداد ARCH

آیکون‌ها فقط با و نام معنایی (مثل ) داده می‌شوند؛ هرگز مسیر فایل asset.
تم فقط حرکت و توکن را تغییر می‌دهد؛ ابعاد، ترتیب DOM و فاصلهٔ حرکت ثابت‌اند.
این کامپوننت gesture ندارد؛ کنترل کامل با کیبورد (Tab و Enter) ممکن است.
لینک‌ها agnostic هستند؛ برای روتر از یا استفاده کنید.

نکات

برای موبایل، مقصدهای اصلی را در داک شیشه‌ای ثابت پایین صفحه (Dock) قرار دهید؛ برای لمس انگشت مناسب‌تر است.
برای مقصدهای زیاد یا سلسله‌مراتبی از پنل کناری استفاده کنید.
برای نماهای هم‌سطح درون یک صفحه از Tabs استفاده کنید؛ آن‌ها ناوبری سراسری نیستند.
برای رفتن سریع به صفحه‌ها با صفحه‌کلید، ناوبری فرمانی را کنار این نوار بگذارید.