الانتقال إلى المحتوى الرئيسي

نظرة عامة

يتولى RadioGroup تنسيق القيمة والتنقل باستخدام لوحة المفاتيح وإرسال النموذج لعناصره الفرعية Radio.

استخدام

الحالة غير المتحكَّم بها.

استخدم defaultValue لتعيين وتيرة الفوترة الأولية. تمتلك المجموعة التغييرات اللاحقة.
يحدّد name الخاص بالمجموعة القيمة المحددة عند إرسال النموذج. امنح المجموعة اسمًا متاحًا، بالإضافة إلى تسمية كل زر اختيار.

تخطيط أفقي

تستخدم المجموعات عمودًا رأسيًا افتراضيًا. عيّن orientation="horizontal" لصف. تتحكم الخاصية في التخطيط المرئي عبر data-orientation؛ ولا تضبط aria-orientation أو تغيّر التنقل عبر لوحة المفاتيح. يحتفظ مفتاحا السهمين الأفقي والرأسي بسلوك Base UI الحالي، بما في ذلك التنقل من اليمين إلى اليسار عبر DirectionProvider.
تظل الفجوة الافتراضية كما هي في أي من الاتجاهين.

البنية

ضع كل Radio أو Radio.Root داخل المجموعة واربطه بتسمية. استخدم Radio.Indicator لإنشاء مؤشر مخصص. RadioGroup وRadio تصديران منفصلان.
امنح المجموعة اسمًا خاصًا بها يمكن الوصول إليه باستخدام aria-label أو aria-labelledby. في الأمثلة أدناه، يربط aria-labelledby المجموعة بوسيلة الإيضاح. يحتاج كل زر اختيار أيضًا إلى اسمه الخاص. ضع خصائص التحديد على RadioGroup وقيم الخيارات على Radio.

الحالة المتحكم بها

مرّر value وحدّثه باستخدام onValueChange لامتلاك وتيرة الفوترة نفسها في حالة React. الاختيار تابع للمجموعة، وليس لعناصر التحكّم الفردية من نوع radio.
يتلقى onValueChange القيمة التالية وتفاصيل الحدث. يُستنتج نوع القيمة العام من الخصائص. استخدم disabled على المجموعة لتعطيل كل خيار، أو على زر اختيار فردي لتعطيل اختيار واحد. تتنقل مفاتيح الأسهم بين الخيارات المفعّلة وتحددها؛ وينقل المفتاح Tab التركيز خارج المجموعة. يدعم إصدار Base UI المثبّت مفاتيح الأسهم الأفقية والعمودية كليهما. تضيف RadioGroup الخاصية orientation للعرض المرئي فقط دون تغيير اتفاقية لوحة المفاتيح تلك.

تفاصيل التكامل الأصلي والأحداث

يعرض RadioGroup عنصر div افتراضيًا. تستهدف الخصائص الأصلية وref ذلك العنصر؛ بينما ينشئ render عنصرًا آخر ويغيّر هدف المرجع الفعلي. يستهدف inputRef حقل الإدخال المخفي الممثل لزر اختيار فرعي، باستخدام الخيار المفعّل المحدد أو خيار احتياطي مفعّل. تتضمن الأنواع العامة RadioGroupProps وRadioGroupState وRadioGroupChangeEventReason وRadioGroupChangeEventDetails. تتلقى دالة رد الاتصال تفاصيل الحدث الأصلية، بما في ذلك event وreason وcancel() وallowPropagation(). ألغِ تغييرًا مقترحًا قبل تحديث الحالة المتحكَّم بها عندما ينبغي رفض الاختيار. أبقِ name وform وrequired وdisabled وreadOnly في المجموعة للحفاظ على عقد نموذج Base UI الحالي. تُرسل القيمة المحددة ضمن name؛ وتُستبعد المجموعات المعطلة، بينما تحتفظ المجموعات للقراءة فقط باختيارها. يدعم form مجموعة خارج النموذج الذي يملكها. لا يستعيد الإصدار المثبّت حالة المجموعة تلقائيًا عند إعادة تعيين النموذج الأصلي. أعد تعيين الحالة المتحكَّم بها من معالج onReset الخاص بالنموذج عندما يتطلب سير العمل ذلك. في مكونات الواجهة الأمامية المعزولة، ضع المجموعة داخل النموذج الذي يملكها. يمرر العارض عملية التحقق required ويحظر مراجع form الصريحة، التي كانت ستُحلّ بخلاف ذلك عبر مستند المضيف. عنصر التحكم المجزأ إعداد مسبق ملائم مُجمَّع من هذه المكونات الأساسية لاختيار حصري قصير. يستخدم دلالات زر الاختيار ويتطلب اسمًا متاحًا للمجموعة. علامات التبويب والتنقل بين لوحات علامات التبويب عنصرَا تحكم منفصلان.

الخصائص

يُنشأ المرجع من أنواع المكونات العامة. تُقبل أيضًا السمات الأصلية، بما في ذلك الأسماء المتاحة ومعالجات الأحداث، على الأجزاء التي تعرض عناصر.
string | ((state: RadioGroupState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
TValue
The uncontrolled value of the radio button that should be initially selected.To render a controlled radio group, use the value prop instead.
boolean
افتراضي:"false"
Whether the component should ignore user interaction.
string
Identifies the form that owns the radio inputs. Useful when the radio group is rendered outside the form.
Ref<HTMLInputElement>
A ref to access the hidden input element.
string
Identifies the field when a form is submitted.
((value: TValue, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)
Callback fired when the value changes.
"horizontal" | "vertical"
افتراضي:"vertical"
Visual layout direction, reflected in data-orientation. Does not change arrow-key navigation or set aria-orientation.
boolean
افتراضي:"false"
Whether the user should be unable to select a different radio button in the group.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioGroupState>
Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.
boolean
افتراضي:"false"
Whether the user must choose a value before submitting a form.
CSSProperties | ((state: RadioGroupState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
TValue
The controlled value of the radio item that should be currently selected.To render an uncontrolled radio group, use the defaultValue prop instead.