> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# صف الإعدادات

> صف مفتاح تبديل مُسمّى بخصائص عناصر تحكم مسطّحة وتكوين تسمية أصلي.

## نظرة عامة

يجمع `SettingsRow` بين مظهر [ListItem](https://docs.twenty.com/ar/ui/primitives/navigation/list-item.md) و[Switch](https://docs.twenty.com/ar/ui/primitives/input/switch.md). يعرض تسمية أصلية مرتبطة بمفتاح التبديل الخاص به. يوفّر تطبيقك محتوى الصف ويتولى أي تحديثات للتفضيلات.

**Light**

[مثال على صف الإعدادات (light)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[مثال على صف الإعدادات (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-settingsrow--display)

## استخدام

```tsx theme={null}
import { SettingsRow } from 'twenty-ui/components/settings';
import { IconBell } from 'twenty-ui/icon';

export const NotificationSetting = () => (
  <SettingsRow startElement={<IconBell aria-hidden />}>
    Notifications
  </SettingsRow>
);
```

## خيارات العرض

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

**Light**

[أحجام وحالات صف الإعدادات (light)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--catalog\&viewMode=story\&globals=colorScheme:light)

**Dark**

[أحجام وحالات صف الإعدادات (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--catalog\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-settingsrow--catalog)

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

مرّر [خصائص Switch](https://docs.twenty.com/ar/ui/primitives/input/switch.md) مباشرةً إلى `SettingsRow`. تُهيّئ حالة التحديد وتفاصيل الحدث وسلوك التعطيل والقراءة فقط والحجم وإعدادات النموذج الأصلية والمعالجات والمراجع وتركيب العرض المفتاح. يوفّر `children` تسمية الصف المرئية.

استخدم `checked` و`onCheckedChange` عندما يملك تطبيقك القيمة. يتلقى المعالج حالة التحديد التالية وتفاصيل حدث Base UI. يؤدي النقر على التسمية أو المفتاح إلى استدعائه مرة واحدة. استدعِ `eventDetails.cancel()` لرفض تغيير، وأبقِ قيمتك المتحكَّم بها دون تغيير عند إلغاء التغيير.

```tsx theme={null}
import { useState } from 'react';
import { SettingsRow } from 'twenty-ui/components/settings';
import { IconBell } from 'twenty-ui/icon';

export const NotificationSetting = () => {
  const [enabled, setEnabled] = useState(false);

  return (
    <SettingsRow
      startElement={<IconBell aria-hidden />}
      checked={enabled}
      onCheckedChange={setEnabled}
    >
      Notifications
    </SettingsRow>
  );
};
```

استخدم `defaultChecked` لإعداد غير متحكَّم به. يركّز مستخدمو لوحة المفاتيح على المفتاح ويضغطون مفتاح المسافة. يعطّل `disabled` عنصر التحكم ويطبّق مظهر الصف المعطّل. يمنع `readOnly` التغييرات مع إبقاء المفتاح قابلاً للتركيز.

```tsx theme={null}
import { SettingsRow } from 'twenty-ui/components/settings';

export const WorkspaceSettings = () => (
  <>
    <SettingsRow disabled>Notifications</SettingsRow>
    <SettingsRow readOnly defaultChecked>
      Activity history
    </SettingsRow>
  </>
);
```

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

تقبل `children` و`startElement` و`description` العُقد التي يملكها المستدعي. يوفّر العنصران الفرعيان الاسم المتاح للمفتاح، ويوفّر الوصف وصفه المتاح. أبقِ المحتوى داخل التسمية غير تفاعلي. استخدم [ListItemButton](https://docs.twenty.com/ar/ui/components/navigation/list-item-button.md) لصفوف الإجراءات، أو أنشئ [ListItem](https://docs.twenty.com/ar/ui/primitives/navigation/list-item.md) مع رابط للتنقل.

**Light**

[صف إعدادات مع وصف (light)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--with-description\&viewMode=story\&globals=colorScheme:light)

**Dark**

[صف إعدادات مع وصف (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-settingsrow--with-description\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-settingsrow--with-description)

```tsx theme={null}
import { SettingsRow } from 'twenty-ui/components/settings';

export const WeeklyDigestSetting = () => (
  <SettingsRow defaultChecked description="Sent every Monday" name="digest">
    Weekly digest
  </SettingsRow>
);
```

عيّن `aria-label` أو `aria-labelledby` أو `aria-describedby` لتوفير النص المتاح الخاص بك للمفتاح. يستبدل `aria-label` الصريح ارتباط الاسم المُنشأ؛ وتستبدل قيمتا `aria-labelledby` و`aria-describedby` الصريحتان الارتباطات المُنشأة المقابلة.

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

تُهيّئ الخصائص الأصلية العادية عنصر التحكم. لتخصيص التسمية اسمان صريحان:

| الخصائص | الهدف |
| - | - |
| السمات الأصلية والمعالجات و`className` و`style` و`ref` و`render` | جذر Switch المرئي |
| `inputRef` و`name` و`value` و`uncheckedValue` و`required` و`form` | مربع الاختيار الأصلي الأساسي لـ Switch |
| `labelRef` والسمات والمعالجات والفئات والأنماط المتوفرة عبر `labelRender` | التسمية الأصلية الخارجية |

تتم إدارة `htmlFor` الخاصة بالتسمية داخليًا وتتبع `id`، أو معرّف عنصر تحكم مُنشأ عند عدم توفير أي معرّف. باستخدام تركيب Switch الافتراضي، يحدد هذا المعرّف مربع الاختيار الأساسي. باستخدام `nativeButton`، يحدد الزر المرئي. يستهدف `ref` الجذر المرئي في كلتا الحالتين.

استخدم `labelRender` لتخصيص التسمية الأصلية للصف. احتفظ بعنصر تسمية ومرّر خصائص رد نداء العرض إلى عنصرك. تحتوي `props.children` الخاصة به على الصف الكامل، بما في ذلك المفتاح. يدمج تركيب العنصر فئاته وأنماطه مع الإعدادات الافتراضية للصف.

```tsx theme={null}
import { useRef } from 'react';
import { SettingsRow } from 'twenty-ui/components/settings';

export const ComposedNotificationSetting = () => {
  const labelRef = useRef<HTMLLabelElement>(null);
  const controlRef = useRef<HTMLElement>(null);
  const inputRef = useRef<HTMLInputElement>(null);

  return (
    <SettingsRow
      id="notification-control"
      ref={controlRef}
      inputRef={inputRef}
      nativeButton
      render={<button />}
      labelRef={labelRef}
      labelRender={<label id="notification-row" data-setting="notifications" />}
    >
      Notifications
    </SettingsRow>
  );
};
```

يتلقى `onClick` نقرات عنصر التحكم. تتلقى المعالجات الأصلية المتوفرة عبر `labelRender` أحداث التسمية وأحداث عنصر التحكم الفقاعية. يمنع استدعاء `preventDefault()` عند النقر على تسمية تفعيل عنصر التحكم الأصلي الخاص بها. استخدم `onCheckedChange` لتحديثات التفضيلات، بدلاً من استنتاج الحالة من نقرة على تسمية.

يكون حجم المفتاح افتراضيًا `size="sm"`؛ استخدم `"md"` لمفتاح أكبر. يبقى ارتفاع الصف كما هو. يطبّق `focused` مظهر الصف المميز دون نقل تركيز لوحة المفاتيح. تقبل `className` و`style` و`render` ردود نداء حالة Switch وتخصص عنصر التحكم. وفّر فئات التسمية وأنماطها عبر `labelRender` لتخصيص الصف.

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

داخل مكوّن واجهة أمامية، استخدم تركيب الزر الأصلي لمفتاح متداخل في تسمية الصف:

```tsx theme={null}
import { SettingsRow } from 'twenty-ui/components/settings';

export const FrontComponentNotificationSetting = () => (
  <SettingsRow nativeButton render={<button />}>
    Notifications
  </SettingsRow>
);
```

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

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

تُهيّئ `name` و`value` و`required` مربع الاختيار الأساسي لإرسال النموذج والتحقق منه. يرسل المفتاح المحدد قيمته. يهمل المفتاح غير المحدد القيمة ما لم يتم توفير `uncheckedValue`. استخدم `form` لربط الإدخال بنموذج خارج شجرة أصل الصف.

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

```tsx theme={null}
import { useState } from 'react';
import { SettingsRow } from 'twenty-ui/components/settings';
import { Button } from 'twenty-ui/primitives/input';

export const NotificationPreferences = () => {
  const [enabled, setEnabled] = useState(true);

  return (
    <form onReset={() => setEnabled(true)}>
      <SettingsRow
        checked={enabled}
        onCheckedChange={setEnabled}
        name="notifications"
        value="enabled"
        uncheckedValue="disabled"
      >
        Notifications
      </SettingsRow>
      <Button type="reset">Reset</Button>
    </form>
  );
};
```

## الخصائص

**checked** `boolean`

Whether the switch is currently active.

To render an uncontrolled switch, use the `defaultChecked` prop instead.

**children** `ReactNode` *required*

Visible label and default accessible name of the switch. Use non-interactive node content.

**className** `string | ((state: SwitchRootState) =\> string | undefined)`

Customizes the visible Switch root and accepts a Switch state callback.

**defaultChecked** `boolean` (default: false)

Whether the switch is initially active.

To render a controlled switch, use the `checked` prop instead.

**description** `ReactNode`

Non-interactive supporting node content, used as the default accessible description of the switch.

**disabled** `boolean` (default: false)

Whether the component should ignore user interaction.

**focused** `boolean` (default: false)

Applies the highlighted row style without moving keyboard focus.

**form** `string`

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

**id** `string`

Identifies the associated checkbox, or the visible root with nativeButton. The label association follows this ID.

**inputRef** `Ref\<HTMLInputElement\>`

Targets the underlying native checkbox.

**labelRef** `Ref\<HTMLLabelElement\>`

Targets the outer native label.

**labelRender** `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.

**name** `string`

Identifies the field when a form is submitted.

**nativeButton** `boolean` (default: 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.

**onCheckedChange** `((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.

**onClick** `((event: BaseUIEvent\<MouseEvent\<HTMLSpanElement, MouseEvent\>\>) =\> void)`

Native click handler for the visible Switch root.

**readOnly** `boolean` (default: false)

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

**ref** `Ref\<HTMLSpanElement\>`

Targets the visible Switch root, which defaults to a span.

**render** `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.

**required** `boolean` (default: false)

Whether the user must activate the switch before submitting a form.

**size** `"md" | "sm"` (default: sm)

Visual size of the switch. Defaults to sm.

**startElement** `ReactNode`

Non-interactive node content before the label.

**style** `CSSProperties | ((state: SwitchRootState) =\> CSSProperties | undefined)`

Customizes the visible Switch root and accepts a Switch state callback.

**uncheckedValue** `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.

**value** `string`

The value submitted with the form when the switch is on.
By default, switch submits the "on" value, matching native checkbox behavior.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.