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 ترجیح دهید.