> ## 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.

# العناصر الأساسية

> عناصر التحكم الأساسية لبناء واجهات باستخدام Twenty UI.

## نظرة عامة

العناصر الأساسية هي عناصر التحكم التأسيسية في Twenty UI. تتضمن عناصر إدخال وعناصر عرض وتنقّل وعناصر تحكم مركبة مثل Select وPopover وAlertDialog. يتلقى كل عنصر أساسي البيانات ودوال الاستدعاء الخلفي من تطبيقك.

استورد العناصر الأساسية من نقطة إدخال عائلة، مثل `twenty-ui/primitives/input`. يُصدّر الإدخال المجمّع `twenty-ui/primitives` أيضًا كل مجموعة من العناصر الأولية. راجع [بدء الاستخدام](https://docs.twenty.com/ar/ui/getting-started.md) للتثبيت وإعداد النسق.

تجمع [المكوّنات](https://docs.twenty.com/ar/ui/components/overview) هذه العناصر الأساسية في إعدادات تصميم مشتركة ووحدات بناء قابلة لإعادة الاستخدام للتطبيقات.

## ملكية الحالة العربية

استخدم الحالة غير المتحكم بها عندما يتمكن المكوّن من إدارة تفاعلاته الخاصة. توفر الخاصية الافتراضية الحالة الأولية. استخدم الحالة المتحكم بها عندما يحتاج التطبيق إلى تنسيق تلك الحالة مع عناصر التحكم الأخرى أو التنقل أو بيانات التطبيق.

| الحالة | الحالة الأولية غير المتحكم بها | الحالة المتحكم بها | دالة رد الاتصال الخاصة بالتغيير |
| - | - | - | - |
| الإدخال أو التحديد أو علامة التبويب النشطة | `defaultValue` | `القيمة` | `onValueChange` |
| مربع اختيار أو مفتاح تبديل | `defaultChecked` | `checked` | `onCheckedChange` |
| ظهور النافذة المنبثقة | `defaultOpen` | `افتح` | `onOpenChange` |

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

اختر وضعًا لكل حالة والتزم به طوال عمر المكوّن. تهيئ الخصائص الافتراضية الحالة؛ ولا يؤدي تغييرها لاحقًا إلى استبدال الحالة الحالية. تجنب تمرير الخاصية الافتراضية والخاصية المتحكم بها معًا للحالة نفسها.

تحتوي بعض المكوّنات على أكثر من حالة مستقلة واحدة. على سبيل المثال، يمكن أن يحتوي [تحديد](https://docs.twenty.com/ar/ui/primitives/input/select.md#open-state) على قيمة متحكم بها وظهور نافذة منبثقة غير متحكم به.

تنتمي الحالة إلى الجزء الذي يدير التفاعل. هيئ تحديد زر الاختيار في [مجموعة أزرار الاختيار](https://docs.twenty.com/ar/ui/primitives/input/radio-group.md)، وليس في كل Radio. لا تحتوي مكوّنات العرض مثل Text على وضع متحكم به أو غير متحكم به. يفوض [Toast](https://docs.twenty.com/ar/ui/components/feedback/toast.md) ظهوره وإزالته إلى التطبيق.

## التركيب

تكشف العناصر الأولية المركبة عن أجزاء مثل `Select.Root` و`Select.Trigger` و`Select.Popup`. أبقِ الأجزاء ذات الصلة تحت الجذر نفسه في شجرة المكوّنات لكي تشترك في الحالة وعلاقات إمكانية الوصول. يحدد قسم البنية التشريحية لكل مكوّن الأجزاء المطلوبة والمحتوى الاختياري.

تقبل الفتحات مثل `InputGroup.startElement` و`ListItem.actions` عُقد React كخصائص. تضيف محتوى ضمن تخطيط المكوّن. الأجزاء والفتحات هما واجهتا برمجة تطبيقات مختلفتان؛ استخدم الأسماء المدرجة في دليل المكوّن.

### تركيب النافذة المنبثقة

توفّر Select وPopover وAutocomplete أجزاءً منفصلة هي `Portal` و`Positioner` و`Popup`:

| الجزء | المسؤولية |
| - | - |
| `Portal` | حاوية الوجهة والتركيب |
| `Positioner` | الموضع، والمرساة، والإزاحات، ومعالجة التصادمات |
| `Popup` | المحتوى، وسلوك التركيز، والسمات الأصلية، وref |
| `Arrow` | سهم اختياري داخل النافذة المنبثقة |

ضمّن Popup داخل Positioner وPositioner داخل Portal. ضع المحتوى داخل Popup وأضف Arrow صراحةً عند الحاجة. قد تنقل البوابة DOM المعروض إلى حاوية أخرى مع الحفاظ على تسلسل المكوّنات والسياق. راجع [تخصيص المظهر](https://docs.twenty.com/ar/ui/theming.md#scope-an-override) للتعرّف على حاويات البوابة ذات النطاق المحدد.

يحافظ كل جزء معروض على سماته الأصلية الخاصة به، وهدف ref، وتركيب العرض. يحافظ [Autocomplete](https://docs.twenty.com/ar/ui/primitives/input/autocomplete) أيضًا على أجزاء المجموعة والتجميع والشبكة والتصفية والحالة المثبّتة من المصدر الأساسي.

يعرض [Dialog](https://docs.twenty.com/ar/ui/primitives/surfaces/dialog.md) و[AlertDialog](https://docs.twenty.com/ar/ui/primitives/surfaces/alert-dialog.md) أجزاء `Portal` و`Backdrop` و`Viewport` و`Popup` منفصلة. اضبط التركيب والوجهة في Portal، ومظهر التراكب في Backdrop وViewport، وحجم المحتوى والتركيز في Popup. يحافظ كل جزء على سماته الأصلية وهدف المرجع وتركيب العرض الخاص به. واجهات برمجة تطبيقات مربع الحوار هذه مخصصة لواجهة المستخدم المستقلة ومضيف Twenty. تستخدم مكونات Front [واجهة برمجة تطبيقات مربع حوار مضيف SDK](https://docs.twenty.com/ar/developers/extend/apps/layout/front-components.md#host-communication-api).

### المكوّنات المخصصة

بالنسبة إلى الأجزاء التي تدعم `render`، مرّر عنصرًا أو مكوّنًا متوافقًا لاستبدال العنصر الافتراضي. على سبيل المثال، يمكن لـ `Popover.Trigger` استخدام `Button` من واجهة Twenty مع الاحتفاظ بسلوك المشغّل الخاص به.

يجب أن يمرّر الغلاف المخصص الخصائص وref المزوّدين إلى العنصر التفاعلي. يحافظ هذا على معالجات الأحداث، وسمات إمكانية الوصول، والتموضع، واستعادة التركيز. يمرّرها هذا المثال عبر `Button`، الذي يربطها بزره الأصلي.

```tsx theme={null}
import { type ComponentPropsWithRef } from 'react';
import { Button } from 'twenty-ui/primitives/input';
import { Popover } from 'twenty-ui/primitives/surfaces';

type HelpButtonProps = ComponentPropsWithRef<typeof Button>;

const HelpButton = ({ ref, ...props }: HelpButtonProps) => (
  <Button {...props} ref={ref} variant="outline" />
);

export const ImportHelp = () => (
  <Popover.Root>
    <Popover.Trigger render={<HelpButton>Import help</HelpButton>} />
    <Popover.Portal>
      <Popover.Positioner>
        <Popover.Popup>
          <Popover.Title>Import a CSV file</Popover.Title>
          <Popover.Description>
            Use a header row to identify your columns.
          </Popover.Description>
          <Popover.Close render={<Button>Got it</Button>} />
        </Popover.Popup>
      </Popover.Positioner>
    </Popover.Portal>
  </Popover.Root>
);
```

مرّر الزر عبر `render` واجعل كل إجراء عنصر تحكم تفاعليًا واحدًا. حافظ على المعالجات وref المزوّدين إلى غلافك عند إضافة سلوكك الخاص. يجب أن يصل ref إلى العنصر الذي يتلقى التركيز.

استخدم زرًا أصليًا للأجزاء الشبيهة بالأزرار. في الأجزاء التي تعرض `nativeButton`، عيّن `nativeButton={false}` فقط عندما لا يكون العنصر المعروض زرًا أصليًا. يحتفظ المكوّن المخصص الذي يعرض زرًا في النهاية، مثل `HelpButton`، بسلوك الزر الافتراضي.

## تصفح العناصر الأولية

تتضمن كل صفحة أمثلة على الاستخدام، وإرشادات للتفاعل، ومرجع API مُنشأ تلقائيًا.

| الفئة | العناصر الأولية |
| - | - |
| إمكانية الوصول | [مخفي بصريًا](https://docs.twenty.com/ar/ui/primitives/accessibility/visually-hidden.md) |
| البيانات المعروضة | [Avatar](https://docs.twenty.com/ar/ui/primitives/data-display/avatar.md)، [Chip](https://docs.twenty.com/ar/ui/primitives/data-display/chip.md)، [ColorSample](https://docs.twenty.com/ar/ui/primitives/data-display/color-sample.md)، [Badge](https://docs.twenty.com/ar/ui/primitives/data-display/badge.md)، [Status](https://docs.twenty.com/ar/ui/primitives/data-display/status.md)، [Tag](https://docs.twenty.com/ar/ui/primitives/data-display/tag.md) |
| التغذية الراجعة | [Banner](https://docs.twenty.com/ar/ui/primitives/feedback/banner.md)، [Loader](https://docs.twenty.com/ar/ui/primitives/feedback/loader.md)، [Progress](https://docs.twenty.com/ar/ui/primitives/feedback/progress.md)، [ProgressBar](https://docs.twenty.com/ar/ui/primitives/feedback/progress-bar.md)، [ProgressRing](https://docs.twenty.com/ar/ui/primitives/feedback/progress-ring.md)، [Skeleton](https://docs.twenty.com/ar/ui/primitives/feedback/skeleton.md) |
| النماذج | [الإكمال التلقائي](https://docs.twenty.com/ar/ui/primitives/input/autocomplete)، [زر](https://docs.twenty.com/ar/ui/primitives/input/button.md)، [مجموعة الأزرار](https://docs.twenty.com/ar/ui/primitives/input/button-group.md)، [مربع اختيار](https://docs.twenty.com/ar/ui/primitives/input/checkbox.md)، [حقل](https://docs.twenty.com/ar/ui/primitives/input/field.md)، [إدخال](https://docs.twenty.com/ar/ui/primitives/input/input.md)، [مجموعة الإدخال](https://docs.twenty.com/ar/ui/primitives/input/input-group.md)، [حقل الأرقام](https://docs.twenty.com/ar/ui/primitives/input/number-field.md)، [زر اختيار](https://docs.twenty.com/ar/ui/primitives/input/radio.md)، [مجموعة أزرار الاختيار](https://docs.twenty.com/ar/ui/primitives/input/radio-group.md)، [تحديد](https://docs.twenty.com/ar/ui/primitives/input/select.md)، [شريط تمرير](https://docs.twenty.com/ar/ui/primitives/input/slider.md)، [مفتاح تبديل](https://docs.twenty.com/ar/ui/primitives/input/switch.md)، [منطقة نص](https://docs.twenty.com/ar/ui/primitives/input/textarea.md) |
| التخطيط | [Collapsible](https://docs.twenty.com/ar/ui/primitives/layout/collapsible.md)، [Separator](https://docs.twenty.com/ar/ui/primitives/layout/separator.md)، [ResizeHandle](https://docs.twenty.com/ar/ui/primitives/layout/resize-handle.md)، [DirectionProvider](https://docs.twenty.com/ar/ui/primitives/layout/direction-provider.md) |
| التنقل | [مسار التنقل](https://docs.twenty.com/ar/ui/primitives/navigation/breadcrumb.md)، [عنصر القائمة](https://docs.twenty.com/ar/ui/primitives/navigation/list-item.md)، [علامات التبويب](https://docs.twenty.com/ar/ui/primitives/navigation/tabs.md) |
| الأسطح | [AlertDialog](https://docs.twenty.com/ar/ui/primitives/surfaces/alert-dialog.md)، [Card](https://docs.twenty.com/ar/ui/primitives/surfaces/card.md)، [Dialog](https://docs.twenty.com/ar/ui/primitives/surfaces/dialog.md)، [Popover](https://docs.twenty.com/ar/ui/primitives/surfaces/popover.md)، [Tooltip](https://docs.twenty.com/ar/ui/primitives/surfaces/tooltip.md) |
| الطباعة | [عنوان](https://docs.twenty.com/ar/ui/primitives/typography/heading.md)، [نص متجاوز مع تلميح](https://docs.twenty.com/ar/ui/primitives/typography/overflowing-text-with-tooltip.md)، [موفر وضع تلميح النص المتجاوز](https://docs.twenty.com/ar/ui/primitives/typography/overflowing-text-tooltip-mode-provider)، [اختصار](https://docs.twenty.com/ar/ui/primitives/typography/shortcut.md)، [نص](https://docs.twenty.com/ar/ui/primitives/typography/text.md) |


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