> ## 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 في تطبيق React واستخدم مكوناته وسماته.

## نظرة عامة

Twenty UI هي مكتبة واجهة مستخدم React مفتوحة المصدر الخاصة بـ Twenty. توفر عناصر أساسية ومكونات مشتركة وأيقونات ورموز مميزة للسمة مع CSS مُعد مسبقًا، لذلك لا يحتاج تطبيقك إلى مترجم CSS-in-JS.

## تثبيت

بالنسبة إلى تطبيق React موجود، ثبّت المكتبة. React 19 مطلوب.

```bash theme={null}
yarn add twenty-ui
```

يحتوي [محرر التعليمات البرمجية](https://docs.twenty.com/ar/ui/components/code-editor/code-editor.md) على نقطة إدخال منفصلة، `twenty-ui/components/code-editor`. لا تتطلب المكونات الأخرى Monaco. لاستخدام محرر التعليمات البرمجية، ثبّت تبعيات النظير الاختيارية الخاصة به واضبط عمال Monaco لحزمتك قبل تركيبه:

```bash theme={null}
yarn add @monaco-editor/react monaco-editor
```

إذا كنت تبني تطبيق Twenty، فاتبع [استخدام مكونات Twenty UI](https://docs.twenty.com/ar/developers/extend/apps/layout/front-components.md#using-twenty-ui-components). يوفر عارض المكونات الأمامية سمة مساحة العمل، ويختلف إعداده عن تطبيق متصفح مستقل. أبقِ `twenty-ui` و`twenty-sdk` و`twenty-client-sdk` على الإصدار نفسه.

## حمّل الأنماط ووفّر سمة

استورد ورقة أنماط المكونات وورقة أنماط سمة مرة واحدة عند نقطة دخول تطبيقك. يطبّق `ThemeProvider` فئة السمة النشطة ويجعل قيم السمة متاحة للمكونات.

```tsx theme={null}
import { Field, Input } from 'twenty-ui/primitives/input';
import { ThemeProvider } from 'twenty-ui/theme';

import 'twenty-ui/style.css';
import 'twenty-ui/theme-light.css';

export const App = () => (
  <ThemeProvider colorScheme="light">
    <Field.Root>
      <Field.Label>Email</Field.Label>
      <Input name="email" type="email" placeholder="you@example.com" />
      <Field.Description>Use your work email address.</Field.Description>
    </Field.Root>
  </ThemeProvider>
);
```

تتضمن ورقة أنماط المكونات إعادة تعيين عامة. راجع تأثيرها عند إضافة Twenty UI إلى تطبيق موجود.

## تجاوز الأنماط

تضع Twenty UI أنماط المكونات وإعادة الضبط في طبقة التسلسل `twenty-ui`. تتجاوز الأنماط التي تكتبها خارج طبقة، مثل `className` أو وحدة CSS أو قاعدة CSS-in-JS، تلك القواعد ذات الطبقات بغض النظر عن خصوصية المحدد أو ترتيب الاستيراد. تظل أوراق أنماط السمة وقواعد Monaco العامة للمحرر الاختيارية دون طبقات.

إعادات ضبط العناصر العامة في تطبيقك دون طبقات أيضًا، لذا ستتجاوز مكونات Twenty UI. أعلن طبقة لها قبل تحميل ورقة أنماط Twenty UI:

```css theme={null}
@layer reset, twenty-ui;

@layer reset {
  button {
    font: inherit;
  }
}
```

مع Tailwind CSS v4، ضع Twenty UI بين طبقتي الأساس والأدوات المساعدة في Tailwind:

```css theme={null}
@layer theme, base, twenty-ui, components, utilities;
```

## اختر نقطة إدخال

استورد المكونات من مسارها الفرعي العام للحفاظ على تركيز الاستيرادات:

العناصر الأساسية هي عناصر تحكم تأسيسية، بما في ذلك عناصر التحكم المركبة مثل Select،
Popover، وAlertDialog. تجمع المكونات المشتركة العناصر الأساسية في إعدادات
تصميم متكررة ولبنات بناء تطبيقات قابلة لإعادة الاستخدام. يتلقى كلاهما البيانات واستدعاءات الرجوع
من التطبيق.

استخدم [MainButton](https://docs.twenty.com/ar/ui/components/input/main-button.md) للإجراءات البارزة و
[LightButton](https://docs.twenty.com/ar/ui/components/input/light-button.md) للإجراءات البسيطة. كلاهما
يأتي من `twenty-ui/components/input` ويتشاركان عقد تفاعل
[Button](https://docs.twenty.com/ar/ui/primitives/input/button.md) الأساسي. يبقى التوجيه وتخطيط
الصفحة في التطبيق.

لكل عائلة من العناصر الأساسية والمكونات المشتركة نقطة إدخال عامة مطابقة، مثل
`twenty-ui/primitives/input` و`twenty-ui/components/settings`. تصدّر إدخالات
`twenty-ui/primitives` و`twenty-ui/components` المجمّعة عائلاتها المعنية.
تعيد نقطة الإدخال الجذرية `twenty-ui` تصدير العناصر الأساسية والمكونات المشتركة والأيقونات ورموز السمة المميزة
والأدوات المساعدة. للأصول ومساعدات الاختبار ومحرر التعليمات البرمجية الاختياري نقاط إدخال منفصلة.

| استيراد | المحتويات |
| - | - |
| `twenty-ui/assets` | الشعارات والأصول الثابتة |
| `twenty-ui/components` | جميع مجموعات المكونات المشتركة باستثناء المحرر الاختياري |
| `twenty-ui/components/data-display` | مجموعات الصور الرمزية، وكتل الأوامر، وأشجار JSON، والمقاييس، ومربعات الأيقونات |
| `twenty-ui/components/feedback` | وسائل الشرح، واللافتات المضمنة، والإشعارات |
| `twenty-ui/components/input` | إعدادات الأزرار المسبقة، وحقول الإدخال المتخصصة، والمنتقيات، وعناصر التحكم المجزأة |
| `twenty-ui/components/layout` | الأقسام، والقوائم المتجاوزة، وانتقالات الأيقونات |
| `twenty-ui/components/navigation` | القوائم المنسدلة، وتركيبات القوائم، وإجراءات علامات التبويب |
| `twenty-ui/components/settings` | صفوف الإعدادات مع عناصر تحكم مُسمّاة |
| `twenty-ui/components/code-editor` | محرر التعليمات البرمجية، ورأس المحرر، ومساعدات سمة المحرر |
| `twenty-ui/primitives` | جميع عائلات العناصر الأساسية |
| `twenty-ui/primitives/accessibility` | العناصر المخفية ومساعدات التفاعل بلوحة المفاتيح |
| `twenty-ui/primitives/data-display` | الصور الرمزية والشارات والرقائق والوسوم وعينات الألوان ومؤشرات الحالة |
| `twenty-ui/primitives/feedback` | اللافتات ومؤشرات التقدم وأدوات التحميل والعناصر النائبة |
| `twenty-ui/primitives/input` | الأزرار وعناصر التحكم في النماذج |
| `twenty-ui/primitives/layout` | التوسيع، والفواصل، والاتجاه، وتغيير الحجم |
| `twenty-ui/primitives/navigation` | مسارات التنقل وعناصر القوائم وعلامات التبويب |
| `twenty-ui/primitives/surfaces` | البطاقات ومربعات الحوار والنوافذ المنبثقة وتلميحات الأدوات |
| `twenty-ui/primitives/typography` | النصوص والعناوين والاختصارات والنصوص المتجاوزة |
| `twenty-ui/icon` | [الأيقونات والبحث الديناميكي](https://docs.twenty.com/ar/ui/icons.md) |
| `twenty-ui/testing` | [مُزيّنات وتخطيطات Storybook](https://docs.twenty.com/ar/ui/testing.md) |
| `twenty-ui/theme` | موفر السمة والخطافات ومراجع متغيرات CSS |
| `twenty-ui/utilities` | الخطافات والأدوات المساعدة المشتركة |

استورد الأيقونات الفردية، مثل `IconCheck`، من `twenty-ui/icon`. يتضمن موفر الأيقونات الديناميكي كتالوج الأيقونات الكامل، لذا خصصه للواجهات التي تحتاج إلى البحث عن الأيقونات في وقت التشغيل.

## خطافات الاستجابة

استورد `useIsMobile` و`useIsTouchDevice` و`useMediaQuery` من `twenty-ui/utilities`.

| الخطّاف | الاستعلام | استخدام |
| - | - | - |
| `useIsMobile()` | `MOBILE_MEDIA_QUERY`، حتى `MOBILE_VIEWPORT` وبما في ذلك | اختر تخطيطًا مضغوطًا. |
| `useIsTouchDevice()` | `TOUCH_DEVICE_MEDIA_QUERY`، `(hover: none) and (pointer: coarse)` | اختر سلوك التفاعل باللمس بشكل مستقل عن العرض. |
| `useMediaQuery(query)` | أي استعلام وسائط يدعمه `window.matchMedia` | اشترك في استعلام وسائط مخصص. |

تأتي ثوابت الاستعلام من `twenty-ui/utilities`؛ ويأتي `MOBILE_VIEWPORT` من `twenty-ui/theme`. تتشارك الاشتراكات قائمة `MediaQueryList` واحدة لكل استعلام، وتُحدَّث عند تغير تطابقها. تعيد الخطافات `false` أثناء العرض على الخادم، وأول عرض للترطيب، وعندما يكون `window.matchMedia` غير متاح.

في [مكون واجهة أمامية لـ Twenty](https://docs.twenty.com/ar/developers/extend/apps/layout/front-components.md#current-limitations)، تتبع استعلامات العرض مربع الأداة. لذلك يتبع `useIsMobile` عرض الأداة، بينما يتبع `useIsTouchDevice` الإدخال الأساسي للجهاز. استخدم [تجاوزات القصص](https://docs.twenty.com/ar/ui/testing.md#media-query-overrides) لاختبار هذه الحالات في Storybook.

## استمر

* [السمات](https://docs.twenty.com/ar/ui/theming.md): استخدم الرموز الدلالية والتجاوزات المحصورة.
* [الوضع الداكن](https://docs.twenty.com/ar/ui/dark-mode.md): بدّل بين لوحات الألوان الفاتحة والداكنة.

## استعرض المكتبة

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


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