Fieldset
گروهبندی معنایی چند فیلد مرتبط (مثلاً «اطلاعات تماس» داخل یک فرم بزرگتر با چند بخش). روی fieldset/legend بومی مرورگر سوار است، نه یک شبیهسازی بصری با div؛ صفحهخوانها legend را قبل از اعلام هر کنترل داخلش میخوانند تا کاربر بداند این ورودی به کدام گروه تعلق دارد.
این کامپوننت فعلاً برای ۱ فریمورک از ۴ فریمورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
نصب
با CLI اختصاصی dig-ui کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگیها و فایلها خودکار اضافه میشوند.
npx dig-ui@latest add https://docs.digdesign.ir/r/fieldset.jsonpnpm dlx dig-ui@latest add https://docs.digdesign.ir/r/fieldset.jsonyarn dlx dig-ui@latest add https://docs.digdesign.ir/r/fieldset.jsonbunx --bun dig-ui@latest add https://docs.digdesign.ir/r/fieldset.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
استفاده
import {
Fieldset,
FieldsetLegend,
FieldsetDescription,
FieldsetGroup,
FieldsetActions,
} from "@/components/ui/fieldset"
<Fieldset>
<FieldsetLegend>عنوان گروه</FieldsetLegend>
<FieldsetGroup>{/* فیلدها */}</FieldsetGroup>
<FieldsetActions>{/* دکمهها */}</FieldsetActions>
</Fieldset>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
ترکیب اجزا
همهٔ محتوای Fieldset: عنوان، توضیح، فیلدها و دکمهها، داخل یک قابِ گردگوشهٔ یکپارچه دیده میشود.
زیرِ پوسته اما یک ترفند لازم است: مرورگر legend واقعی را طبق الگوریتم بومی «Fieldset and Legend Layout» مستقل از padding پدرش روی لبهٔ border جای میدهد، پس اگر legend واقعی داخل همان قاب مینشست، بهجای همراهی با بقیهٔ محتوا بالای قاب معلق میماند.
برای همین Fieldset متنِ FieldsetLegend را همزمان در دو جا میگذارد: یک legend واقعی و نامرئی (sr-only) مستقیماً زیرِ fieldset، که فقط برای صفحهخوان دسترسپذیری گروه را تأمین میکند، و خودِ FieldsetLegend بهعنوان یک عنوان صرفاً بصری، دقیقاً همانجایی که در JSX گذاشتهاید (داخل قاب، کنار توضیح و فیلدها).
- FieldsetGroup فقط چیدمان فیلدهاست؛ پیشفرض یک ستون، با کلاسی مثل
sm:grid-cols-2دوستونه میشود. - FieldsetActions نوار دکمههای پایین قاب است؛ در موبایل دکمهها زیر هم، در صفحهٔ بزرگتر کنار هم مینشینند.
دسترسپذیری
- چون Fieldset خودِ عنصر fieldset بومی است، غیرفعالکردنش (disabled) همهٔ کنترلهای داخلش را یکجا غیرفعال میکند، بدون نیاز به disabled دستی روی تکتک Input/Select/Button.
- Fieldset متنِ FieldsetLegend را خودش به یک legend واقعی و مستقیمِ fieldset تبدیل میکند؛ کافیست یک FieldsetLegend مستقیم داخل Fieldset بگذارید، نیازی به کار دستی برای اتصال دسترسپذیری نیست.
- FieldsetGroup و FieldsetActions فقط ظرف چیدمانیاند (div ساده)، وزن معنایی اضافه به صفحهخوان نمیدهند.
مرجع API
Fieldset
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| disabled | boolean | — | ویژگی بومی fieldset؛ همهٔ کنترلهای داخلش را یکجا غیرفعال میکند. |
| ...props | React.ComponentProps<'fieldset'> | — | همهٔ ویژگیهای بومی fieldset پشتیبانی میشود. |
FieldsetLegend / FieldsetDescription / FieldsetGroup / FieldsetActions
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| className | string | — | کلاسهای اضافه؛ برای مثال sm:grid-cols-2 روی FieldsetGroup برای چیدمان دوستونه. |
| ...props | React.ComponentProps<'div' | 'p' | 'div' | 'div'> | — | بهترتیب div (عنوان بصری، متنش خودکار به legend واقعی هم میرود)، p و دو div بومی؛ همهٔ ویژگیهای استاندارد پشتیبانی میشود. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
نمونهها
با Form ترکیب میشود
FieldsetGroup فقط چیدمان میدهد؛ اعتبارسنجی و خطای هر فیلد کاملاً کار FormField/FormMessage از کامپوننت Form است، این دو مستقل از هم کار میکنند و با هم ترکیب میشوند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
غیرفعالسازی کل گروه
disabled روی خودِ Fieldset: نه یک ویژگی سفارشی، رفتار بومی مرورگر، همهٔ کنترلهای داخلش را یکجا غیرفعال میکند؛ برای وقتیکه مثلاً یک بخش از فرم به انتخاب بخش دیگری وابسته است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار میآید |
|---|---|
| با Form ترکیب میشود | FieldsetGroup فقط چیدمان میدهد؛ اعتبارسنجی و خطای هر فیلد کاملاً کار FormField/FormMessage از کامپوننت Form است، این دو مستقل از هم کار میکنند و با هم ترکیب میشوند. |
| غیرفعالسازی کل گروه | disabled روی خودِ Fieldset: نه یک ویژگی سفارشی، رفتار بومی مرورگر، همهٔ کنترلهای داخلش را یکجا غیرفعال میکند؛ برای وقتیکه مثلاً یک بخش از فرم به انتخاب بخش دیگری وابسته است. |
دستورالعمل استفاده
برای گروههای واقعاً مرتبط از Fieldset استفاده کن، نه یک heading معمولی
انجام بده
Legend قبل از هر فیلد داخل گروه توسط صفحهخوان اعلام میشود؛ کاربر میفهمد «ایمیل» بخشی از «اطلاعات تماس» است.
اطلاعات تماس
انجام نده
یک <h3> بصری هیچ رابطهای بین عنوان و فیلدهای زیرش برای صفحهخوان ثبت نمیکند؛ فقط ظاهراً شبیه گروه است.