Checkbox

کامپوننت چک‌باکس برای جابه‌جا کردن یک انتخاب روشن/خاموش، با برچسب اختیاری و پشتیبانی از فرم بومی.

کجا به کارش ببرید: وقتی به یک کلید روشن/خاموش با برچسب نیاز دارید که در فرم‌های بومی شرکت کند. <r-checkbox> وضعیت تیک‌خورده‌اش را به FormData می‌رساند و با صفحه‌کلید هم کار می‌کند.

شروع سریع

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

<r-checkbox>مرا به خاطر بسپار</r-checkbox>

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

مرجع API

خصیصه‌ها

ویژگی‌های checked و value همگام نگه داشته می‌شوند: تعیین یکی دیگری را به‌روز می‌کند. وقتی تیک خورده باشد value برابر 'true' و در غیر این صورت 'false' است.

وضعیت تیک checked

<r-checkbox checked="true">تیک‌خورده</r-checkbox> <r-checkbox checked="false">بدون تیک</r-checkbox>

مقدار value

<r-checkbox value="true">مقدار true</r-checkbox> <r-checkbox value="false">مقدار false</r-checkbox>

حالت غیرفعال disabled

<r-checkbox checked="true" disabled>تیک‌خورده</r-checkbox> <r-checkbox checked="false" disabled>بدون تیک</r-checkbox>

استایل دلخواه sheet

ویژگی sheet کد CSS را به shadow DOM تزریق می‌کند تا بتوانید بخش‌های درونی را با نام کلاسشان هدف بگیرید.

<r-checkbox checked="true" sheet=".ran-checkbox-label { color: #006bff; }">برچسب پوسته‌دار</r-checkbox>

رویدادها

change

هنگام جابه‌جا شدن چک‌باکس (با کلیک یا فشردن Space/Enter) رخ می‌دهد. رویداد یک CustomEvent است که detail آن وضعیت تازه را حمل می‌کند:

detail: {
  checked: boolean; // وضعیت تیک چک‌باکس پس از جابه‌جایی
}

چک‌باکس غیرفعال رویداد change نمی‌فرستد.

<r-checkbox onchange="handleChange(event)">مرا جابه‌جا کن</r-checkbox>

<script>
  function handleChange(event) {
    console.log('checked:', event.detail.checked);
  }
</script>

اسلات‌ها

پیوند با فرم

r-checkbox یک عنصر سفارشی پیوندخورده با فرم است (formAssociated = true). وضعیت تیکش را از راه ElementInternals.setFormValue منتقل می‌کند، پس در فرم‌های بومی شرکت می‌کند و وقتی فرزند واقعی یک <form> بومی باشد، new FormData(form) آن را جمع می‌کند. هم‌سو با معنای چک‌باکس بومی، تنها وقتی تیک خورده باشد value خود را می‌دهد.

خود میزبان معنای دسترس‌پذیر چک‌باکس را دارد: role="checkbox"، aria-checked، aria-disabled و کار با صفحه‌کلید (جابه‌جایی با Space یا Enter).

بازنشانی: form.reset() بومی از راه formResetCallback() وضعیت تیکی را برمی‌گرداند که مربع هنگام نخستین اتصال داشت.

اعتبارسنجی: required مربعِ بدون تیک را با ElementInternals.setValidity() نامعتبر می‌کند و این برای form.checkValidity()/form.reportValidity() دیدنی است؛ مربع disabled هرگز جلوی اعتبارسنجی را نمی‌گیرد. checkValidity()، reportValidity()، validity و validationMessage مانند یک فیلد بومی روی عنصر در دسترس‌اند.

<form>
  <r-checkbox name="terms" required>با شرایط موافقم</r-checkbox>
  <button type="submit">ارسال</button>
</form>

Part‌های CSS

با گزینشگر ()::part به ساختار درونی استایل بدهید:

r-checkbox::part(inner) {
  border-radius: 50%;
}
r-checkbox::part(label) {
  font-weight: 600;
}

استایل

<r-checkbox> ۳۲ ویژگی سفارشی CSS از آنِ خود و افزون بر آن توکن‌های معنایی‌ای که از پوسته می‌خواند در اختیار می‌گذارد. آن را هرجا که ارث می‌رسد تعیین کنید: :root، یک نگه‌دارنده، یا خود عنصر.

r-checkbox {
  --ran-checkbox-color: var(--ran-color-text-secondary);
}

Part‌ها: checkbox · inner · input · label · wrapper

فهرست کامل در توکن‌های استایل است و اینکه کدام توکن را برگزینید در سیستم طراحی آمده.

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

• به چک‌باکس‌ها برچسب بدهید: متنی در اسلات بگذارید تا کنترل نامی دسترس‌پذیر داشته باشد.
• checked در برابر value: برای وضعیت بولی از checked استفاده کنید و هنگام جمع‌کردن دادهٔ فرم value را بخوانید ('true' / 'false').
• حالت غیرفعال: وقتی آن انتخاب در دسترس نیست از disabled استفاده کنید.
• به change گوش بدهید: به‌جای پرس‌وجوی دوبارهٔ DOM، event.detail.checked را بخوانید.
• فرم‌ها: r-checkbox را داخل یک <form> بگذارید؛ وقتی تیک خورده باشد مقدارش خودکار جمع می‌شود. دربارهٔ serializeForm() که یک ارسال را به شیئی ساده تبدیل می‌کند، Forms را ببینید.