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

نظرة عامة

يجمع SettingsRow بين مظهر ListItem وSwitch. يعرض تسمية أصلية مرتبطة بمفتاح التبديل الخاص به. يوفّر تطبيقك محتوى الصف ويتولى أي تحديثات للتفضيلات.

استخدام

خيارات العرض

قارن أحجام مفاتيح التبديل وحالات التفعيل والتعطيل والقراءة فقط.

تهيئة مفتاح التبديل

مرّر خصائص Switch مباشرةً إلى SettingsRow. تُهيّئ حالة التحديد وتفاصيل الحدث وسلوك التعطيل والقراءة فقط والحجم وإعدادات النموذج الأصلية والمعالجات والمراجع وتركيب العرض المفتاح. يوفّر children تسمية الصف المرئية. استخدم checked وonCheckedChange عندما يملك تطبيقك القيمة. يتلقى المعالج حالة التحديد التالية وتفاصيل حدث Base UI. يؤدي النقر على التسمية أو المفتاح إلى استدعائه مرة واحدة. استدعِ eventDetails.cancel() لرفض تغيير، وأبقِ قيمتك المتحكَّم بها دون تغيير عند إلغاء التغيير.
استخدم defaultChecked لإعداد غير متحكَّم به. يركّز مستخدمو لوحة المفاتيح على المفتاح ويضغطون مفتاح المسافة. يعطّل disabled عنصر التحكم ويطبّق مظهر الصف المعطّل. يمنع readOnly التغييرات مع إبقاء المفتاح قابلاً للتركيز.

محتوى الصف والنص المتاح

تقبل children وstartElement وdescription العُقد التي يملكها المستدعي. يوفّر العنصران الفرعيان الاسم المتاح للمفتاح، ويوفّر الوصف وصفه المتاح. أبقِ المحتوى داخل التسمية غير تفاعلي. استخدم ListItemButton لصفوف الإجراءات، أو أنشئ ListItem مع رابط للتنقل.
عيّن aria-label أو aria-labelledby أو aria-describedby لتوفير النص المتاح الخاص بك للمفتاح. يستبدل aria-label الصريح ارتباط الاسم المُنشأ؛ وتستبدل قيمتا aria-labelledby وaria-describedby الصريحتان الارتباطات المُنشأة المقابلة.

الأهداف الأصلية والتركيب

تُهيّئ الخصائص الأصلية العادية عنصر التحكم. لتخصيص التسمية اسمان صريحان: تتم إدارة htmlFor الخاصة بالتسمية داخليًا وتتبع id، أو معرّف عنصر تحكم مُنشأ عند عدم توفير أي معرّف. باستخدام تركيب Switch الافتراضي، يحدد هذا المعرّف مربع الاختيار الأساسي. باستخدام nativeButton، يحدد الزر المرئي. يستهدف ref الجذر المرئي في كلتا الحالتين. استخدم labelRender لتخصيص التسمية الأصلية للصف. احتفظ بعنصر تسمية ومرّر خصائص رد نداء العرض إلى عنصرك. تحتوي props.children الخاصة به على الصف الكامل، بما في ذلك المفتاح. يدمج تركيب العنصر فئاته وأنماطه مع الإعدادات الافتراضية للصف.
يتلقى onClick نقرات عنصر التحكم. تتلقى المعالجات الأصلية المتوفرة عبر labelRender أحداث التسمية وأحداث عنصر التحكم الفقاعية. يمنع استدعاء preventDefault() عند النقر على تسمية تفعيل عنصر التحكم الأصلي الخاص بها. استخدم onCheckedChange لتحديثات التفضيلات، بدلاً من استنتاج الحالة من نقرة على تسمية. يكون حجم المفتاح افتراضيًا size="sm"؛ استخدم "md" لمفتاح أكبر. يبقى ارتفاع الصف كما هو. يطبّق focused مظهر الصف المميز دون نقل تركيز لوحة المفاتيح. تقبل className وstyle وrender ردود نداء حالة Switch وتخصص عنصر التحكم. وفّر فئات التسمية وأنماطها عبر labelRender لتخصيص الصف.

عارض مكوّن الواجهة الأمامية

داخل مكوّن واجهة أمامية، استخدم تركيب الزر الأصلي لمفتاح متداخل في تسمية الصف:
يُفعّل هذا التركيب مرة واحدة عند النقر على التسمية أو عنصر التحكم. لا يمكن لجسر الأحداث غير المتزامن للعارض إلغاء التفعيل الافتراضي لتسمية المضيف في الوقت المناسب لعنصر تحكم قائم على span، مما قد ينتج عنه ردود نداء تغيير مكررة عند النقر المباشر على عنصر التحكم. تُرشَّح أيضًا سمات التحقق من النموذج الأصلية مثل required بواسطة العارض الحالي. يحتفظ SettingsRow المستقل بعقد نموذج Switch الكامل.

النماذج وإعادة التعيين

تُهيّئ name وvalue وrequired مربع الاختيار الأساسي لإرسال النموذج والتحقق منه. يرسل المفتاح المحدد قيمته. يهمل المفتاح غير المحدد القيمة ما لم يتم توفير uncheckedValue. استخدم form لربط الإدخال بنموذج خارج شجرة أصل الصف. لإعادة تعيين نموذج متحكَّم به، استعد قيمة التحديد التي يملكها التطبيق في معالج onReset الخاص بالنموذج. لا يستعيد Base UI 1.8 حالة المفتاح غير المتحكَّم بها عند إعادة تعيين النموذج الأصلية. يحافظ SettingsRow على هذا السلوك السابق.

الخصائص

boolean
Whether the switch is currently active.To render an uncontrolled switch, use the defaultChecked prop instead.
ReactNode
مطلوب
Visible label and default accessible name of the switch. Use non-interactive node content.
string | ((state: SwitchRootState) => string | undefined)
Customizes the visible Switch root and accepts a Switch state callback.
boolean
افتراضي:"false"
Whether the switch is initially active.To render a controlled switch, use the checked prop instead.
ReactNode
Non-interactive supporting node content, used as the default accessible description of the switch.
boolean
افتراضي:"false"
Whether the component should ignore user interaction.
boolean
افتراضي:"false"
Applies the highlighted row style without moving keyboard focus.
string
Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form.
string
Identifies the associated checkbox, or the visible root with nativeButton. The label association follows this ID.
Ref<HTMLInputElement>
Targets the underlying native checkbox.
Ref<HTMLLabelElement>
Targets the outer native label.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>
Customizes the outer native label with its complete composed row children. Preserve a label element and forward its props to retain control association.
string
Identifies the field when a form is submitted.
boolean
افتراضي:"false"
Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.
((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)
Receives the next checked value and Base UI event details. Controlled callers own accepted state updates; cancellation prevents a change.
((event: BaseUIEvent<MouseEvent<HTMLSpanElement, MouseEvent>>) => void)
Native click handler for the visible Switch root.
boolean
افتراضي:"false"
Whether the user should be unable to activate or deactivate the switch.
Ref<HTMLSpanElement>
Targets the visible Switch root, which defaults to a span.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchRootState>
Customizes the visible Switch root with control props and Switch state. Use nativeButton when composing a button.
boolean
افتراضي:"false"
Whether the user must activate the switch before submitting a form.
"md" | "sm"
افتراضي:"sm"
Visual size of the switch. Defaults to sm.
ReactNode
Non-interactive node content before the label.
CSSProperties | ((state: SwitchRootState) => CSSProperties | undefined)
Customizes the visible Switch root and accepts a Switch state callback.
string
The value submitted with the form when the switch is off. By default, unchecked switches do not submit any value, matching native checkbox behavior.
string
The value submitted with the form when the switch is on. By default, switch submits the “on” value, matching native checkbox behavior.