سربرگ صفحه (PageHeader)

معرفی

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

چه زمانی استفاده کنیم:

• در کد خود سیستم طراحی، برای ساختن سرِ یک قالب یا بلوک صفحه‌ای.

چه زمانی استفاده نکنیم:

• در صفحهٔ محصول — هر صفحه یک قالب است و قالب سرِ صفحه را با title، description، back، primaryAction و secondaryActions خودش می‌سازد (حتی CustomPage؛ قاعدهٔ ESLint parto/page-template این جزء را در صفحه نشان می‌دهد).
• داخل modal یا dialog — header در overlay ها معمولاً ساده‌تر است
• برای عنوان بخش‌های صفحه — بخش‌های قالب (DetailSection، SettingsSection، DashboardSection) عنوان خودشان را دارند

زمین بازی

با تغییر تنظیمات زیر، پیش‌نمایش زنده را مشاهده کنید.

استفاده

صفحهٔ محصول این سر را از propهای قالبش می‌گیرد؛ همان سر در کد صفحه این‌طور نوشته می‌شود:

'use client'
import { Button } from '@partodata/ui'
import { DetailPage } from '@partodata/ui/templates'

declare function refresh(): void

export function EngagementReportScreen() {
  return (
    <DetailPage
      title="گزارش تعامل اینستاگرام"
      description="تحلیل نرخ تعامل در بازه زمانی انتخاب‌شده"
      back={{ href: '/reports', label: 'گزارش‌ها' }}
      secondaryActions={<Button variant="default">خروجی</Button>}
      primaryAction={<Button onClick={refresh}>به‌روزرسانی</Button>}
    >
      {/* DetailSectionها */}
    </DetailPage>
  )
}

و قالب آن را با همین جزء می‌سازد (مرجع جزء، برای کد خود سیستم طراحی):

<PageHeader
  title="گزارش تعامل اینستاگرام"
  description="تحلیل نرخ تعامل در بازه زمانی انتخاب‌شده"
  actions={<Button variant="default">خروجی</Button>}
  primaryAction={<Button onClick={refresh}>به‌روزرسانی</Button>}
/>

حالت‌ها و انواع

با Breadcrumb

جای اقدام اصلی صفحه

اقدام اصلی صفحه، یکی در هر صفحه، primaryAction همین سربرگ است: یک Button بدون variant که همیشه آخرِ خوشهٔ اقدام‌ها رندر می‌شود. مگر اینکه صفحه PageToolbar داشته باشد، یعنی جست‌وجو یا فیلتر؛ آن‌وقت اقدام اصلی primaryAction نوارابزار است و سربرگ primaryAction ندارد.

اقدام‌های دیگر در actions می‌آیند. actions همیشه جای اقدام‌های ثانوی است: دکمهٔ بدون variant در آن، مثل همه‌جا، همان default خنثی است، و فقط primaryAction دکمهٔ بدون variant را اصلی رندر می‌کند؛ پس صفحه دو دکمهٔ اصلی پیدا نمی‌کند. قانون ESLint parto/page-primary-action فقط variant="primary" صریح در actions را گزارش می‌کند. (تا 3٫x، سربرگی که primaryAction نداشت دکمهٔ بدون variant در actions را اصلی رندر می‌کرد؛ اگر آن دکمه اقدام اصلی صفحه است، به primaryAction ببریدش.)

کنترل‌های actions و primaryAction که size ندارند یک ارتفاع می‌گیرند، sm (30 پیکسل)، فیلد هم (که تنها 38 پیکسل است) و به اندازهٔ محتوایشان؛ یک ControlSizeProvider بیرونی هنوز تصمیم می‌گیرد.

<PageHeader
  title="هشدارها"
  actions={<Button variant="default">خروجی</Button>}
  primaryAction={
    <Button onClick={createAlert} iconStart={<Plus />}>
      ساخت هشدار
    </Button>
  }
/>

اقدام اصلی‌ای که کاربر اجازه‌اش را ندارد پنهان نمی‌شود: همان‌جا غیرفعال با دلیلش می‌ماند، با GatedAction دور Button (<GatedAction allowed={canCreate} reason="…">)؛ نه canCreate && <Button/> (قاعدهٔ ESLint parto/page-primary-action آن را نشان می‌دهد). false و null هیچ خوشه‌ای رندر نمی‌کنند؛ actions در هر حال ثانوی است. دکمهٔ اصلی را به actions نبرید: آن‌جا دکمهٔ بدون variant خنثی است، نه اصلی. primaryAction همیشه یک Button است، نه fragment؛ در محیط توسعه fragment هشدار می‌دهد.

در عرض کم (موبایل، یا یک PeriodSelector پهن در actions) عنوان جای خودش را نگه می‌دارد: اقدام‌ها تا وقتی کل عنوان کنارشان جا می‌شود کنار آن می‌مانند (عنوان کوتاه با یک دکمه، حتی روی موبایل)، و وقتی جا نمی‌شود به خط خودشان زیر عنوان می‌روند و اگر از عرض صفحه پهن‌تر باشند، درون همان خط می‌شکنند. توضیح (description) در این حساب نیست و در عرض باقی‌مانده می‌شکند.

داخل ProductFrame

قالب‌ها PageHeader را با عنوان صفحه (تنها h1 آن) بالای محتوای خودشان رندر می‌کنند. داخل ProductFrame فاصلهٔ 48 پیکسلی تا نوار بالا (--layout-page-top) را خودش می‌گذارد، چون ناحیهٔ محتوای قاب padding ندارد؛ بیرون از قاب فاصله‌ای اضافه نمی‌کند. فاصلهٔ سرِ صفحه تا اولین بلوک را بخش بعدی قالب می‌دهد، نه className روی سر.

PageHeader فقط برای عنوان صفحه است. داخل Dialog، Sheet، Drawer یا Popover که از صفحه باز شود، این فاصله اعمال نمی‌شود (این سطوح دیگر «صفحهٔ قاب» نیستند)؛ عنوان بخش‌های صفحه را بخش‌های قالب (DetailSection، …) می‌دهند.

Props

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

دسترسی‌پذیری

• دکمه برگشت دارای aria-label است که از locale سیستم خوانده می‌شود
• عنوان صفحه با تگ <h1> رندر می‌شود که برای ساختار صفحه مهم است

اجزای سرِ صفحه (PageHeaderRoot)

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

کامپوننت‌های مرتبط

• Breadcrumb — اغلب در کنار PageHeader استفاده می‌شود تا مسیر ناوبری کاربر مشخص باشد
• PageToolbar — صفحه‌ای که جست‌وجو یا فیلتر دارد اقدام اصلی‌اش را به primaryAction نوارابزار می‌دهد، نه به این سربرگ
• ProductFrame — نوار بالای برنامه (هویت محصول و اقدام‌های سراسری)، نه سربرگ صفحه
• داربست صفحه (Page*) — سربرگ ترکیبی PageHeaderRoot، جزء سطح پایین کد خود سیستم طراحی؛ صفحه‌ای که زبانه، متا یا راه بازگشت در سرش لازم دارد DetailPage است (tabs، meta، back)
• چیدمان (الگو) — اسکلتی که قالب‌های صفحه رویش ساخته شده‌اند: PageContainer › PageHeader › PageSection