المفتاح

نظرة عامة

استخدم Switch لتفضيل التشغيل أو الإيقاف. امنح عنصر التحكم تسمية مرئية أو اسمًا يمكن الوصول إليه.

استخدام

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

استخدم defaultChecked لتعيين حالة التحديد الأولية. يمتلك المفتاح التبديل التغييرات اللاحقة.

import { useId } from 'react';
import { Switch } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';

export const NotificationsPreference = () => {
  const switchId = useId();

  return (
    <label
      htmlFor={switchId}
      style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}
    >
      <Switch id={switchId} name="notifications" />
      <Text render={<span />}>Email notifications</Text>
    </label>
  );
};

الخيارات المرئية

قارن بين الحجمين في حالات التشغيل والإيقاف والتعطيل والقراءة فقط والتركيز. استخدم الأمثلة المفعّلة لتجربة التبديل.

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

مرّر checked وحدّثه باستخدام onCheckedChange لامتلاك التفضيل نفسه في حالة React.

import { useId, useState } from 'react';
import { Switch } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';

export const NotificationsPreference = () => {
  const switchId = useId();
  const [checked, setChecked] = useState(false);

  return (
    <label
      htmlFor={switchId}
      style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}
    >
      <Switch
        id={switchId}
        name="notifications"
        checked={checked}
        onCheckedChange={setChecked}
      />
      <Text render={<span />}>Email notifications</Text>
    </label>
  );
};

يتلقى onCheckedChange القيمة المنطقية التالية وتفاصيل الحدث. تقبل الخاصية size القيمة sm أو md، وتكون قيمتها الافتراضية md. لصف بعرض كامل ومتسق يتضمن أيقونة ووصفًا ومفتاح تبديل، استخدم SettingsRow.

لوحة المفاتيح والنماذج

ينقل مفتاح Tab التركيز إلى المفتاح، ويبدّله مفتاح Space. يؤدي النقر على التسمية المرتبطة به أيضًا إلى تبديله. استخدم disabled لمنع التفاعل أو readOnly للإبقاء على عنصر تحكم قابل للتركيز لا يمكن تغيير قيمته. يرسل المفتاح المُسمّى قيمته عند تحديده. استخدم value لتخصيص تلك القيمة، واستخدم uncheckedValue إذا كان يجب أن يرسل النموذج أيضًا قيمة عندما يكون في وضع الإيقاف.

الأجزاء والمحتوى المخصص

يجمع Switch الجذر المصمم ومقبضه الافتراضي. استخدم Switch.Root مع Switch.Thumb لتملك محتوى المقبض. يدير Root الحالة ومظهر المسار؛ ويعرض Thumb المحتوى الذي توفره.

import { Switch } from 'twenty-ui/primitives/input';

export const CustomPreference = () => (
  <Switch.Root aria-label="Updates" defaultChecked>
    <Switch.Thumb></Switch.Thumb>
  </Switch.Root>
);

SwitchRootProps وSwitchThumbProps نوعان عامان مُصدَّران من twenty-ui/primitives/input. يقبل كلا الجزأين السمات الأصلية والمعالجات والمراجع وrender وعمليات الاستدعاء className وstyle المستندة إلى الحالة. يستهدف ref الخاص بـ Root عنصر التحكم المرئي؛ ويستهدف inputRef حقل الإدخال الأصلي. يستهدف مرجع الجزء العنصر الذي يعرضه. مرر nativeButton مع render={<button />} عند استبدال Root بزر. تنتمي خصائص المظهر إلى Root؛ وتُدمج الفئات والأنماط الصريحة مع الإعدادات الافتراضية. يتلقى Thumb حالة checked وdisabled وreadOnly وrequired وField الحالية. يتبع موضعه اتجاه القراءة. تظل التجميعة القابلة للاستدعاء ونوع SwitchProps الخاص بها مدعومين. استبدل التجميعة بـ Root وجزئه عند توفير محتوى مقبض مخصص بدلًا من إلحاق جزء آخر بأبناء التجميعة. لإعادة تعيين نموذج متحكم به، عالج onReset الخاص بالنموذج وأعد checked إلى قيمتك الأولية. لا يستعيد Base UI 1.8 حالة المكونات غير المتحكم بها عند إعادة تعيين النموذج الأصلية. تحافظ required وform وvalue وuncheckedValue على سلوك حقل الإدخال الأصلي المصدر.

الإزاحة

يتضمن المرجع خصائص خاصة بالمكوّن وخصائص Base UI الموروثة. تُقبل أيضًا السمات الأصلية مثل aria-label وdata-*.

boolean

Whether the switch is currently active.To render an uncontrolled switch, use the defaultChecked prop instead.

string | ((state: SwitchRootState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

افتراضي:"false"

Whether the switch is initially active.To render a controlled switch, use the checked prop instead.

boolean

افتراضي:"false"

Whether the component should ignore user interaction.

string

Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form.

string

The id of the hidden input element.When nativeButton is true, the id is applied to the root element.

Ref<HTMLInputElement>

A ref to access the hidden <input> element.

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)

Event handler called when the switch is activated or deactivated.

boolean

افتراضي:"false"

Whether the user should be unable to activate or deactivate the switch.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchRootState>

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 activate the switch before submitting a form.

"md" | "sm"

افتراضي:"md"

Visual size of the switch.

CSSProperties | ((state: SwitchRootState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

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.

Switch.Root

boolean

Whether the switch is currently active.To render an uncontrolled switch, use the defaultChecked prop instead.

string | ((state: SwitchRootState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

boolean

افتراضي:"false"

Whether the switch is initially active.To render a controlled switch, use the checked prop instead.

boolean

افتراضي:"false"

Whether the component should ignore user interaction.

string

Identifies the form that owns the hidden input. Useful when the switch is rendered outside the form.

string

The id of the hidden input element.When nativeButton is true, the id is applied to the root element.

Ref<HTMLInputElement>

A ref to access the hidden <input> element.

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.

Event handler called when the switch is activated or deactivated.

boolean

افتراضي:"false"

Whether the user should be unable to activate or deactivate the switch.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchRootState>

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 activate the switch before submitting a form.

"md" | "sm"

افتراضي:"md"

Visual size of the switch.

CSSProperties | ((state: SwitchRootState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

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.

Switch.Thumb

string | ((state: SwitchThumbState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SwitchThumbState>

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.

CSSProperties | ((state: SwitchThumbState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

المطورون

التطبيقات

واجهة برمجة التطبيقات

الاستضافة الذاتية

المساهمة

مكتبة واجهة المستخدم

نظرة عامة

استخدام

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

الخيارات المرئية

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

لوحة المفاتيح والنماذج

الأجزاء والمحتوى المخصص

الإزاحة

Switch.Root

Switch.Thumb

​نظرة عامة

​استخدام

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

​الخيارات المرئية

​حالة متحكَّم بها

​لوحة المفاتيح والنماذج

​الأجزاء والمحتوى المخصص

​الإزاحة

​Switch.Root

​Switch.Thumb

نظرة عامة

استخدام

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

الخيارات المرئية

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

لوحة المفاتيح والنماذج

الأجزاء والمحتوى المخصص

الإزاحة

Switch.Root

Switch.Thumb