ناوبری بخشی — SegmentedNavigation

ناوبری بخشی برای تغییر نمای همان داده یا انتخاب یک بازهٔ زمانی ساده با دو تا پنج گزینه به کار می‌رود. کامپوننت روی از React Aria ساخته شده، همیشه یک بخش را انتخاب‌شده نگه می‌دارد و وضعیت انتخاب را با پس‌زمینهٔ برجسته و وزن متن نشان می‌دهد، نه فقط با رنگ. ظاهر آن با Tabs یکی است: یک حباب متحرک پشت گزینهٔ فعال که با توکن‌های حرکت جابه‌جا می‌شود. برای بخش‌هایی که محتوای جدا و پنل دارند از Tabs استفاده کنید، نه این کامپوننت.

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

TSX

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

نمونهٔ زنده

کد قابل کپی

TSX

import { SegmentedNavigation } from '@tokapps/tuk';export function ResultsViewSwitch() {  return (    <SegmentedNavigation      aria-label="نمای نتایج"      items={[        { id: 'list', label: 'فهرست' },        { id: 'grid', label: 'شبکه' },        { id: 'timeline', label: 'زمان‌بندی' },      ]}      defaultSelectedKey="list"    />  );}

TSX

import { useState } from 'react';import { Icon } from '@tokapps/icons';import { SegmentedNavigation } from '@tokapps/tuk';const views = [  { id: 'list', label: 'فهرست', icon: <Icon name="ranking" size="sm" /> },  { id: 'grid', label: 'شبکه', icon: <Icon name="docs.templates" size="sm" /> },  { id: 'timeline', label: 'زمان‌بندی', icon: <Icon name="time" size="sm" /> },];export function ControlledViewSwitch() {  const [view, setView] = useState('list');  return (    <SegmentedNavigation      aria-label="نمای نتایج"      items={views}      selectedKey={view}      onSelectionChange={setView}      fullWidth    />  );}

TSX

import { SegmentedNavigation } from '@tokapps/tuk';// حالت کوچک با گزینهٔ غیرفعال؛ گزینهٔ غیرفعال قابل انتخاب نیستexport function CompactDisabledSegmented() {  return (    <SegmentedNavigation      aria-label="وضعیت"      size="sm"      items={[        { id: 'all', label: 'همه' },        { id: 'open', label: 'باز' },        { id: 'archived', label: 'بایگانی', disabled: true },      ]}      defaultSelectedKey="all"    />  );}

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

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

پراپ‌های :

فیلد	نوع	پیش‌فرض	توضیح
		— (الزامی)	شناسهٔ یکتای گزینه؛ مقدار و است.
		— (الزامی)	متن گزینه.
		—	آیکون کنار متن؛ با و نام معنایی داده شود.
			گزینهٔ غیرفعال قابل انتخاب نیست.

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

با
- برای هر گزینه: ( از React Aria)
  - آیکون اختیاری ( با اندازهٔ )

بنیان ثابت: گروه toggle با انتخاب تکی، همیشه یک گزینهٔ فعال، مدیریت کیبورد و ARIA از React Aria.

بخش قابل‌تغییر: متن و آیکون گزینه‌ها، اندازه، عرض کامل و توکن‌های سطح کامپوننت.

همهٔ حالت‌ها

حالت	نشانه	نمایش
پیش‌فرض	بدون data-attribute خاص	متن با رنگ روی پس‌زمینهٔ .
hover	روی بخش	رنگ متن .
selected	روی	پس‌زمینهٔ ، متن با وزن پررنگ‌تر.
focus-visible	روی بخش	حلقهٔ فوکوس .
disabled	روی	کدری با و نشانگر .
sm		ارتفاع .
md		ارتفاع (پیش‌فرض).
full width		گروه تمام عرض والد را می‌گیرد.
چاپ		در چاپ پنهان می‌شود.

کامپوننت حالت‌های loading، invalid و readonly ندارد؛ در کد تعریف نشده‌اند.

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

variant: یک ظاهر؛ variant جداگانه در کد تعریف نشده است.
size: و .
عرض: برای کشیدن به عرض کامل.
کنترل انتخاب: با (کنترل‌شده) یا (غیرکنترل‌شده).
محتوای گزینه: و (هر ).
نقاط توسعه: ، و برای استایل، توکن‌های ، ، .
صدا و handler: رویداد صوتی ندارد (انتخاب فقط بصری است)؛ handler انتخاب است.

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

تغییر گروه به چند انتخابی یا اجازهٔ خالی‌بودن انتخاب (در کد و ثابت‌اند).
حذف از گروه (الزامی است).
تکیه بر رنگ برای نشان‌دادن بخش فعال؛ باید وزن متن و پس‌زمینه هم باشد.
حذف فوکوس مرئی یا فعال‌کردن گزینهٔ غیرفعال.
کوچک‌کردن ارتفاع بخش‌ها زیر مقدار توکن کنترل () بدون بازبینی دسترس‌پذیری.

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

RTL: ترتیب بخش‌ها بر پایهٔ جهت خوانش است و در RTL از راست به چپ می‌چیند.
کیبورد: وارد گروه و خارج می‌شود؛ کلیدهای فلش جابه‌جا می‌کنند (در RTL جهت فلش‌ها معکوس است)؛ یا بخش را انتخاب می‌کنند.
صفحه‌خوان: گروه با معرفی می‌شود و هر بخش وضعیت انتخاب ( از ) را اعلام می‌کند.
هدف لمسی: ارتفاع بخش‌ها از توکن کنترل می‌آید؛ قرارداد عدد حداقل لمسی مشخصی ندارد و بازبینی انسانی لازم است.

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

صدا: بی‌صدا (). انتخاب بخش با تغییر حالت بصری همراه است (). prop صدا در سطح Provider در کد تعریف نشده است.
حرکت: نام معنایی با تغییر (). با یا تغییر بدون انتقال و فوری است.
چاپ: در فایل پنهان ثبت شده است؛ پیش‌فرض کد اما است. برای پنهان‌کردن در چاپ بدهید.

توکن‌ها

فایل توکن: و مقدارهای مرجع در .
توکن‌های معنایی مصرفی: ، ، ، ، ، ، ، ، ، .
توکن‌های سطح کامپوننت (): ، ، ، ، ، ، ، ، ، ، ، ، ، .

قرارداد ARCH

آیکون گزینه فقط با و نام معنایی رندر می‌شود؛ مسیر asset در کد مصرف‌کننده نمی‌آید.
تم فقط حرکت و توکن را تغییر می‌دهد؛ ساختار گروه، انتخاب تکی و ARIA ثابت است.
gesture ندارد؛ انتخاب با کیبورد و pointer یکسان است.

نکات

برای بخش‌های با محتوای جدا و پنل از Tabs استفاده کنید.
برای گزینه‌های بیشتر از پنج مورد از Select استفاده کنید.
برای اعمال یک‌باره (نه انتخاب وضعیت) از Button استفاده کنید.
اگر در کد برچسب گروه را فراموش کنید، TypeScript خطا می‌دهد؛ مقدار آن باید متن معنادار فارسی باشد.

باید و نباید

باید

برای انتخاب یک مقدار یا نمای همان داده (جهت، تراکم، ارقام، فهرست/شبکه) از این کامپوننت استفاده کنید.
معنادار بدهید؛ این برچسب گروه برای صفحه‌خوان است.
گزینه‌ها را بین دو تا پنج نگه دارید.
در تنظیمات داک () و شیت، از همین کامپوننت استفاده کنید تا ظاهر یکسان بماند.

نباید

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

موارد استفاده در سامانه

محل	استفاده
، تنظیمات داک	جهت، تراکم، حرکت، کنتراست، ارقام
، شیت «تنظیمات سریع»	همان پنج ردیف (با )
	باقی‌مانده: هنوز محلی؛ باید تبدیل شود

فهرست کامل و وضعیت موارد باقی‌مانده در ARCH.md بند ۱۶ آمده است.