انتقل إلى المحتوى

الزر المنقسم

احصل على Ritla UI

إجراء رئيسي ومعه نصف ثانٍ يفتح قائمة بإجراءات قريبة منه، مثل «حفظ» مع «حفظ كمسودة». لكل نصف تركيزه الخاص، وفي العربية ينتقل نصف القائمة إلى اليسار.

فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:

افتح في Figma

المعاينة

«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.

المعاينةالكود
إنجليزيمعكوسعربي
← RTL

التثبيت

  1. أضف المكوّن

    npx ritla add split-button

    ويعمل أيضًا مع shadcn: npx shadcn@latest add @ritla/split-button

  2. الاعتماديات التي يضيفها

    @base-ui/react@phosphor-icons/react

  3. أو انسخه يدويًا

    التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.

الاستخدام

split-button.tsx
import { SplitButton, SplitButtonItem } from "@/components/ui/split-button";<SplitButton  onClick={save}  menuLabel="More save options"  menu={    <>      <SplitButtonItem onClick={saveDraft}>Save as draft</SplitButtonItem>      <SplitButtonItem onClick={publish}>Save and publish</SplitButtonItem>    </>  }>  Save</SplitButton>

أمثلة

الأنماط

أنماط الزر filled وtonal وoutline وghost، والنصفان بالنمط نفسه دائمًا. لا يوجد inverted-ghost ولا نسخة خطرة: الإجراء الخطر لا يُخفى في قائمة.

إنجليزيمعكوسعربي
← RTL

الأحجام

كل حجم بارتفاع الزر من الحجم نفسه، ونصف القائمة مربع. مساحة النقر 48 بكسل على الأقل في sm وxs.

إنجليزيمعكوسعربي
← RTL

القائمة ولوحة المفاتيح

Tab ينتقل بين النصفين. نصف القائمة يفتح بـEnter أو Space أو السهم للأسفل، والقائمة تصطف مع بداية الزر كله: اليمين في العربية. جرّب الوضع العربي.

إنجليزيمعكوسعربي
← RTL

غير متاح

disabled يوقف النصفين معًا.

إنجليزيمعكوسعربي
← RTL

مرجع الخصائص

SplitButton

خصائص Base UI Button الأخرى (onClick، type…) تذهب إلى نصف الإجراء الرئيسي.

الخاصيةالنوعالافتراضيالوصف
childrenReactNodeلا يوجدخاصية Label: نص الإجراء الرئيسي.
menuLabelstringلا يوجدمطلوب. اسم نصف القائمة لقارئات الشاشة («خيارات حفظ أخرى»).
menuReactNodeلا يوجدعناصر SplitButtonItem للإجراءات القريبة.
variant"filled" | "tonal" | "outline" | "ghost""filled"خاصية Style.
size"lg" | "md" | "sm" | "xs""lg"خاصية Size: ‏56 و48 و40 و32 بكسل.
iconLeadingIconComponentلا يوجدIcon leading: أيقونة قبل النص.
trailingIconIconComponentCaretDownIconTrailing btn icon. لا ينعكس أبدًا.
disabledbooleanfalseState = Disabled للنصفين.
classNamestringلا يوجدأصناف للمجموعة الخارجية.

SplitButtonItem

عنصر من Base UI Menu، يقبل onClick وdisabled. شكل القائمة مؤقت حتى تجهز صفحة القوائم في Figma.

الخاصيةالنوعالافتراضيالوصف
childrenReactNodeلا يوجدنص الإجراء.
onClick(event) => voidلا يوجديُستدعى عند الاختيار، ثم تُغلق القائمة.
disabledbooleanfalseيعطّل العنصر ويبقيه ظاهرًا.

البنية

أجزاء الزر المنقسم، وأين يوجد كل جزء في Figma وفي الكود.

  1. 1. المجموعةrole="group"نصفان بينهما فراغ space-2، مرتبان على السطر. في نمط Outline يتشارك النصفان حدًّا واحدًا بلا فراغ.
  2. 2. الزر الرئيسيchildren, iconLeadingالتسمية وأيقونة اختيارية في البداية، وزواياه عند بداية السطر. له موضع تركيز خاص به، وتمرّ إليه خصائص الزر الأخرى.
  3. 3. نصف القائمةtrailingIconنصف مربع للقائمة بأيقونة CaretDown قابلة للتبديل: يفتح القائمة، ويحمل aria-haspopup وaria-expanded. لا ينعكس أبدًا.
  4. 4. اسم نصف القائمة (لا يظهر)menuLabelخاصية نصية مخفية ومطلوبة: الاسم الذي تسمعه قارئات الشاشة لنصف القائمة.
  5. 5. القائمةmenuعناصر قائمة Ritla UI على بعد 12 بكسل تحت الزر، عند بداية سطره، بدور role="menu".
  6. 6. مساحة اللمسsize/touch-targetيحتفظ المقاسان sm وxs بمساحة لمس 48 بكسل لكل نصف، دون أن تأخذ مساحة من التخطيط.

إرشادات الاستخدام

الزر المنقسم إجراء معتاد واحد مع بدائل قريبة منه في قائمة. هنا: متى تستخدمه، وكيف تسمّي نصفيه، وما تتحقق منه قبل التسليم.

1. إجراء معتاد واحد وبدائل قريبة

النصف الرئيسي ينفّذ ما يفعله الناس غالبًا، والقائمة تجمع بدائل الإجراء نفسه.

حفظ مستند

«حفظ»، وبدائله في القائمة.

افعل: بدائل «حفظ»كل عنصر طريقة للحفظ، فيُقرأ الزر المنقسم إجراءً واحدًا.
تجنّب: إجراءات لا علاقة بينهاالمشاركة والحذف والإعدادات ليست بدائل للحفظ. استخدم زر القائمة.

افعل

  • ضع الإجراء الأرجح في النصف الرئيسي، والبدائل في القائمة.
  • اجعل القائمة خمسة عناصر أو أقل.

تجنّب

  • استخدام الزر المنقسم حين تتساوى الإجراءات كلها؛ استخدم مجموعة الأزرار.
  • تغيير الإجراء الرئيسي حسب آخر اختيار دون إخبار المستخدم.

2. سمِّ نصف القائمة

menuLabel مطلوب في الكود، فلا يُنشر سهم القائمة بلا اسم. وفي Figma املأ خاصية Menu label المخفية («خيارات حفظ أخرى»)، بلغة الصفحة.

3. اجعل التسمية قصيرة

التسمية هي الإجراء الرئيسي، والتفاصيل مكانها القائمة.

شريط تصدير

تصدير تقرير.

افعل: «تصدير»فعل واحد، والصيغ في القائمة.
تجنّب: «تصدير بصيغة PDF للطباعة»التسمية الطويلة تبعد نصف القائمة وتكرّر ما فيها.

4. زر filled واحد في كل شاشة

الزر المنقسم بنمط filled هو الإجراء الرئيسي في شاشته، مثل الزر بنمط filled.

تذييل محرّر

«إلغاء» و«حفظ».

افعل: «إلغاء» outline و«حفظ» filledيبرز الإجراء الرئيسي.
تجنّب: زرّا filledوزنان متساويان يتنافسان.

5. لا تُخفِ الإجراءات الخطرة في قائمة

لا توجد نسخة danger من الزر المنقسم. ضع الإجراء الخطر في زر بنص مستقل مع danger، حيث يراه المستخدم قبل أن يضغط.

تجنّب

  • إخفاء إجراء خطر في قائمة الزر المنقسم دون خطوة تأكيد.

6. إجراء التداول ليس زرًا منقسمًا

نصفا إجراء التداول إجراءان رئيسيان، فليس زرًا منقسمًا. يبقى «شراء» في بداية السطر، ولا تتبادل الألوان أبدًا.

7. العربية والاتجاه من اليمين إلى اليسار

في الإطارات العربية استخدم RTL (عربي) = Yes، فيقع نصف القائمة على اليسار. وفي الكود لا خاصية لذلك: الاتجاه يكفي.

محرّر عربي

«حفظ» بالعربية.

افعل: RTL = Yesتُقرأ التسمية أولًا، ويختم نصف القائمة السطر على اليسار.
تجنّب: RTL = No مع نص عربييقع السهم قبل التسمية ويُقرأ الترتيب معكوسًا.

قبل التسليم

  • خاصيتا Label وMenu label مملوءتان بلغة الصفحة.
  • عناصر القائمة بدائل للإجراء الرئيسي.
  • زر filled واحد في كل شاشة.
  • الإطارات العربية تستخدم RTL = Yes.
  • لا إجراء خطر داخل القائمة.

رموز التصميم والمواصفات

كل قيمة في الزر المنقسم متغيّر أو نمط نص، وهي متغيرات الزر نفسها على النصفين. هذه هي القيم المربوطة بالمكوّن، حسب المقاس وحسب النمط.

المقاسات

الارتفاع والحشوة على امتداد السطر ونصف قطر الزوايا لكل نصف، وبين النصفين space-2 (وفي Outline حدّ مشترك بعرض border-width/thicker بدل الفراغ). ونصف القطر في md وsm وxs أعلى بدرجة من الزر، ويطابقه في lg. وكل مقاس يحتفظ بمساحة لمس 48 بكسل.

المقاسالارتفاع والحشوة ونصف القطرالتسمية والأيقونات
lg56 · space-24 · radius/10body-16/Semibold · 24
md48 · space-24 · radius/10body-16/Semibold · 20
sm40 · space-16 · radius/8body-16/Semibold · 20
xs32 · space-12 · radius/6body-14/Semibold · 20

الألوان

لون التعبئة والحدّ والتسمية لكل نمط في الحالة الافتراضية، وهي متغيرات الزر نفسها على النصفين. ويأتي الوضعان الفاتح والداكن من وضع 1. Colors.

النمطالتعبئة والحدّالتسمية والأيقونات
filledbackground/brand/solidtext/brand/on-brand
tonalbackground/brand/fainttext/brand/subtle
outlinebackground/surface/lowest · border/gray/softtext/gray/subtle
ghostalpha/tint-12text/gray/subtle

التركيز

تُرسم حالتا التركيز (على النصف الرئيسي أو على نصف القائمة) بنمط التأثير Focus/focus-ring حول نصف واحد. وفي الكود يحدث ذلك تلقائيًا مع :focus-visible.

إمكانية الوصول

لوحة المفاتيح

المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.

المفتاحما يفعله
Tabينتقل من الإجراء الرئيسي إلى نصف القائمة؛ لكل نصف حلقة تركيزه.
EnterSpaceعلى الإجراء الرئيسي ينفّذه، وعلى نصف القائمة يفتحها.
ArrowDownArrowUpيفتح القائمة وينتقل بين عناصرها.
Escapeيغلق القائمة ويعيد التركيز إلى نصف القائمة.

ARIA

  • زران أصليان داخل role="group"، ونصف القائمة يحمل aria-haspopup="menu" وaria-expanded.
  • menuLabel مطلوب في النوع، فلا يُنشر سهم بلا اسم. اكتبه بلغة الصفحة.
  • القائمة role="menu" وعناصرها menuitem من Base UI، مع تنقل الأسهم والكتابة للبحث.

افعل

  • زران أصليان داخل role="group"، ولكل نصف حلقة تركيزه.
  • Enter أو Space ينفّذ الإجراء الرئيسي أو يفتح القائمة؛ والسهمان للأسفل وللأعلى يفتحانها وينتقلان فيها؛ وEscape يغلقها ويعيد التركيز إلى نصف القائمة.
  • مساحة لمس 48 بكسل على الأقل لكل نصف في كل مقاس.

ملاحظات العربية والاتجاه

ينعكس

  • نصف القائمة في نهاية السطر: اليسار في العربية، دون خاصية RTL.
  • القائمة تصطف مع بداية الزر (اليمين في العربية) وتأخذ اتجاه الزر ولغته، حتى داخل جزيرة عربية في صفحة إنجليزية.

لا ينعكس

  • السهم CaretDown يشير إلى الأسفل، فلا ينعكس، حتى لو استُبدل بأيقونة اتجاهية.
الأرقام
الأرقام داخل النص أو عناصر القائمة («تصدير 3 ملفات») تُنسّق بـformatNumber.
الخط العربي
النص body-16 (وbody-14 في xs) بوزن Semibold كالزر، وعناصر القائمة body-16 بصفوف 48 بكسل تتسع للنص العربي.
النص ثنائي الاتجاه
اسم صيغة أو منتج لاتيني داخل عنصر عربي («تصدير بصيغة PDF») يبقى صحيحًا في نهاية النص؛ في وسطه ضعه في <bdi>.

افعل

  • صُفّ القائمة مع بداية الزر في الاتجاهين: اليسار في الإنجليزية، واليمين في العربية.

الفحوص التي يجتازها

فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.

  • R050نص عربي يسقط إلى خط غير الخط المعلن (مقيسًا، أو وفق الإعلان، أو لأن خط الويب فشل في التحميل)
  • R051تباعد حروف مطبَّق على نص عربي (يكسر الخط المتصل)
  • R042نص مقصوص: محتوى أعرض من صندوقه مع overflow مخفي وبلا علامة حذف
  • R043حاوية بعرض ثابت بالبكسل يتجاوز نصها العربي المساحة