Card

نگه‌دارنده‌ای ساختارمند برای محتوا با ناحیه‌های سربرگ، بدنه و پاورقی که محتوای مرتبط را کنار هم می‌آورد. کارت‌ها سطح‌هایی حاشیه‌دار در سبک Geist‌اند (زمینهٔ صفحه به‌علاوهٔ حاشیهٔ ۱ پیکسلی، نه پُرکردن خاکستری) و تا وقتی hoverable را خودتان روشن نکنید، با نگه‌داشتن نشانگر واکنشی نشان نمی‌دهند.

کجا به کارش ببرید: وقتی می‌خواهید محتوای مرتبط را در سطحی حاشیه‌دار با ناحیه‌های عنوان، توضیح، بدنه و پاورقی گروه کنید. <r-card> همان اسلات‌ها را به‌علاوهٔ حالت تعاملی اختیاری hoverable می‌دهد.

شروع سریع

استفادهٔ پایه

tag

محتوای بدنه در اسلات پیش‌فرض قرار می‌گیرد.

دیدن یادداشت‌ها

<r-card heading="عنوان کارت" description="زیرعنوان اختیاری">
  <span slot="extra">tag</span>
  <p>محتوای بدنه در اسلات پیش‌فرض قرار می‌گیرد.</p>
  <a slot="footer" href="#">دیدن یادداشت‌ها</a>
</r-card>

مرجع API

خصیصه‌ها

خصیصه	نوع	پیش‌فرض	توضیح
`heading`	`string`	`''`	عنوان کارت که بالای سربرگ می‌آید. خالی که باشد پنهان است.
`description`	`string`	`''`	زیرعنوانی که زیر عنوان کشیده می‌شود. خالی که باشد پنهان است.
`hoverable`	`boolean`	`false`	کارت تعاملی: با نگه‌داشتن نشانگر، حاشیه تیره‌تر و کارت کمی بلند می‌شود.
`sheet`	`string`	`''`	CSS تزریق‌شده به shadow DOM کارت.

عنوان `heading`

عنوان کارت که بالای سربرگ نشان داده می‌شود. خالی که باشد پنهان است.

محتوای بدنه.

<r-card heading="فقط یک عنوان">
  <p>محتوای بدنه.</p>
</r-card>

توضیح `description`

زیرعنوانی که زیر عنوان کشیده می‌شود. خالی که باشد پنهان است. اگر نه title و نه description تعیین شده باشد، کل سربرگ پنهان می‌شود.

محتوای بدنه.

<r-card heading="عنوان" description="زیرعنوانی کوتاه و پشتیبان">
  <p>محتوای بدنه.</p>
</r-card>

کارت تعاملی `hoverable`

کارت‌ها به‌طور پیش‌فرض به نشانگر واکنش نشان نمی‌دهند. ویژگی hoverable را تنها روی کارت‌هایی بگذارید که واقعاً کلیک‌شدنی‌اند: با نگه‌داشتن نشانگر، حاشیه یک پله روی نردبان خاکستری تیره‌تر می‌شود (--ran-color-border ← --ran-color-border-hover) و سطح، سایهٔ بلندشدهٔ آرام (--ran-shadow-elevated) را می‌گیرد.

حاشیه تیره‌تر می‌شود و کارت کمی بالا می‌آید.

<r-card hoverable heading="کارت با hover" description="نشانگر را روی من ببرید">
  <p>حاشیه تیره‌تر می‌شود و کارت کمی بالا می‌آید.</p>
</r-card>

hoverable تنها جنبهٔ ظاهری دارد: آن را برای کارت‌هایی نگه دارید که به کلیک پاسخ می‌دهند و کارت‌های غیرتعاملی را بی‌واکنش بگذارید.

استایل بیرونی `sheet`

کد CSS که به shadow DOM کارت تزریق می‌شود و از همان قرارداد sheet پیروی می‌کند که همهٔ کامپوننت‌های دیگر ranui دارند.

<r-card heading="کارت پوسته‌دار" sheet=".ran-card { background: #f6ffed; }">
  <p>محتوای بدنه.</p>
</r-card>

اسلات‌ها

اسلات	توضیح
(پیش‌فرض)	محتوای بدنه که در بدنهٔ کارت رندر می‌شود.
`extra`	سمت راست سربرگ: نشان‌ها، پیوندها یا کنش‌ها.
`footer`	محتوای پاورقی. تا وقتی این اسلات گره‌ای نگیرد پاورقی پنهان است.

Part‌های CSS

کارت این دستگیره‌های ()::part را برای استایل‌دهی از بیرون در اختیار می‌گذارد:

Part	توضیح
`card`	نگه‌دارندهٔ بیرونی کارت.
`header`	ردیف سربرگ.
`title`	متن عنوان.
`description`	متن زیرعنوان.
`extra`	اسلات `extra` در سربرگ.
`body`	ناحیهٔ بدنه (اسلات پیش‌فرض).
`footer`	ناحیهٔ پاورقی (اسلات `footer`).

این متغیرهای CSS را می‌توان بازنویسی کرد: --ran-card-display، --ran-card-min-height، --ran-card-gap، --ran-card-padding، --ran-card-radius، --ran-card-background، --ran-card-border-color، --ran-card-shadow، --ran-card-hover-border-color، --ran-card-hover-shadow (دو تای آخر با hoverable اثر دارند)، --ran-card-title-color، --ran-card-title-font-size، --ran-card-title-font-weight، --ran-card-description-color، --ran-card-description-font-size.

r-card {
  --ran-card-background: var(--surface-2);
  --ran-card-radius: 12px;
  --ran-card-min-height: 148px;
}
r-card::part(header) {
  border-bottom: 1px solid var(--line);
}

رویدادها

کارت نگه‌دارنده‌ای منفعل است و هیچ رویداد سفارشی‌ای ارسال نمی‌کند.

بهترین شیوه‌ها

عنوان و توضیح: برای سرتیتر از title و برای زیرعنوان کوتاه پشتیبان از description استفاده کنید؛ حذف هر دو، سربرگ را یکسره پنهان می‌کند.
محتوای بدنه: محتوای اصلی را در اسلات پیش‌فرض بگذارید.
کنش‌های سربرگ: برای نشان‌ها، پیوندها یا کنش‌هایی که سمت راست سربرگ می‌نشینند از اسلات extra استفاده کنید.
پاورقی: برای کنش‌ها یا پیوندهای فرعی از اسلات footer استفاده کنید؛ تا محتوایی در آن نگذارید پنهان می‌ماند.
بازخورد hover: hoverable را تنها به کارت‌های کلیک‌شدنی بدهید؛ کارت غیرتعاملی نباید به نشانگر واکنش نشان دهد.
پوسته‌دهی: برای استایل قابل استفادهٔ مجدد، متغیرهای CSS و ()::part را به ویژگی sheet ترجیح دهید.