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

نظرة عامة

العناصر الأساسية هي عناصر التحكم التأسيسية في Twenty UI. تتضمن عناصر إدخال وعناصر عرض وتنقّل وعناصر تحكم مركبة مثل Select وPopover وAlertDialog. يتلقى كل عنصر أساسي البيانات ودوال الاستدعاء الخلفي من تطبيقك. استورد العناصر الأساسية من نقطة إدخال عائلة، مثل twenty-ui/primitives/input. يُصدّر الإدخال المجمّع twenty-ui/primitives أيضًا كل مجموعة من العناصر الأولية. راجع بدء الاستخدام للتثبيت وإعداد النسق. تجمع المكوّنات هذه العناصر الأساسية في إعدادات تصميم مشتركة ووحدات بناء قابلة لإعادة الاستخدام للتطبيقات.

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

استخدم الحالة غير المتحكم بها عندما يتمكن المكوّن من إدارة تفاعلاته الخاصة. توفر الخاصية الافتراضية الحالة الأولية. استخدم الحالة المتحكم بها عندما يحتاج التطبيق إلى تنسيق تلك الحالة مع عناصر التحكم الأخرى أو التنقل أو بيانات التطبيق. في الوضع المتحكم به، مرر الحالة الحالية وحدّثها في دالة رد الاتصال الخاصة بالتغيير. في الوضع غير المتحكم به، لا يزال بإمكانك الاستماع إلى التغييرات دون تولي ملكية الحالة. إضافة دالة رد اتصال وحدها لا تجعل المكوّن متحكمًا به. اختر وضعًا لكل حالة والتزم به طوال عمر المكوّن. تهيئ الخصائص الافتراضية الحالة؛ ولا يؤدي تغييرها لاحقًا إلى استبدال الحالة الحالية. تجنب تمرير الخاصية الافتراضية والخاصية المتحكم بها معًا للحالة نفسها. تحتوي بعض المكوّنات على أكثر من حالة مستقلة واحدة. على سبيل المثال، يمكن أن يحتوي تحديد على قيمة متحكم بها وظهور نافذة منبثقة غير متحكم به. تنتمي الحالة إلى الجزء الذي يدير التفاعل. هيئ تحديد زر الاختيار في مجموعة أزرار الاختيار، وليس في كل Radio. لا تحتوي مكوّنات العرض مثل Text على وضع متحكم به أو غير متحكم به. يفوض Toast ظهوره وإزالته إلى التطبيق.

التركيب

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

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

توفّر Select وPopover وAutocomplete أجزاءً منفصلة هي Portal وPositioner وPopup: ضمّن Popup داخل Positioner وPositioner داخل Portal. ضع المحتوى داخل Popup وأضف Arrow صراحةً عند الحاجة. قد تنقل البوابة DOM المعروض إلى حاوية أخرى مع الحفاظ على تسلسل المكوّنات والسياق. راجع تخصيص المظهر للتعرّف على حاويات البوابة ذات النطاق المحدد. يحافظ كل جزء معروض على سماته الأصلية الخاصة به، وهدف ref، وتركيب العرض. يحافظ Autocomplete أيضًا على أجزاء المجموعة والتجميع والشبكة والتصفية والحالة المثبّتة من المصدر الأساسي. يعرض Dialog وAlertDialog أجزاء Portal وBackdrop وViewport وPopup منفصلة. اضبط التركيب والوجهة في Portal، ومظهر التراكب في Backdrop وViewport، وحجم المحتوى والتركيز في Popup. يحافظ كل جزء على سماته الأصلية وهدف المرجع وتركيب العرض الخاص به. واجهات برمجة تطبيقات مربع الحوار هذه مخصصة لواجهة المستخدم المستقلة ومضيف Twenty. تستخدم مكونات Front واجهة برمجة تطبيقات مربع حوار مضيف SDK.

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

بالنسبة إلى الأجزاء التي تدعم render، مرّر عنصرًا أو مكوّنًا متوافقًا لاستبدال العنصر الافتراضي. على سبيل المثال، يمكن لـ Popover.Trigger استخدام Button من واجهة Twenty مع الاحتفاظ بسلوك المشغّل الخاص به. يجب أن يمرّر الغلاف المخصص الخصائص وref المزوّدين إلى العنصر التفاعلي. يحافظ هذا على معالجات الأحداث، وسمات إمكانية الوصول، والتموضع، واستعادة التركيز. يمرّرها هذا المثال عبر Button، الذي يربطها بزره الأصلي.
مرّر الزر عبر render واجعل كل إجراء عنصر تحكم تفاعليًا واحدًا. حافظ على المعالجات وref المزوّدين إلى غلافك عند إضافة سلوكك الخاص. يجب أن يصل ref إلى العنصر الذي يتلقى التركيز. استخدم زرًا أصليًا للأجزاء الشبيهة بالأزرار. في الأجزاء التي تعرض nativeButton، عيّن nativeButton={false} فقط عندما لا يكون العنصر المعروض زرًا أصليًا. يحتفظ المكوّن المخصص الذي يعرض زرًا في النهاية، مثل HelpButton، بسلوك الزر الافتراضي.

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

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