الزر المنقسم
إجراء رئيسي ومعه نصف ثانٍ يفتح قائمة بإجراءات قريبة منه، مثل «حفظ» مع «حفظ كمسودة». لكل نصف تركيزه الخاص، وفي العربية ينتقل نصف القائمة إلى اليسار.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add split-buttonويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/split-buttonالاعتماديات التي يضيفها
@base-ui/react@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
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 ولا نسخة خطرة: الإجراء الخطر لا يُخفى في قائمة.
الأحجام
كل حجم بارتفاع الزر من الحجم نفسه، ونصف القائمة مربع. مساحة النقر 48 بكسل على الأقل في sm وxs.
مرجع الخصائص
SplitButton
خصائص Base UI Button الأخرى (onClick، type…) تذهب إلى نصف الإجراء الرئيسي.
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
children | ReactNode | لا يوجد | خاصية Label: نص الإجراء الرئيسي. |
menuLabel | string | لا يوجد | مطلوب. اسم نصف القائمة لقارئات الشاشة («خيارات حفظ أخرى»). |
menu | ReactNode | لا يوجد | عناصر SplitButtonItem للإجراءات القريبة. |
variant | "filled" | "tonal" | "outline" | "ghost" | "filled" | خاصية Style. |
size | "lg" | "md" | "sm" | "xs" | "lg" | خاصية Size: 56 و48 و40 و32 بكسل. |
iconLeading | IconComponent | لا يوجد | Icon leading: أيقونة قبل النص. |
trailingIcon | IconComponent | CaretDownIcon | Trailing btn icon. لا ينعكس أبدًا. |
disabled | boolean | false | State = Disabled للنصفين. |
className | string | لا يوجد | أصناف للمجموعة الخارجية. |
SplitButtonItem
عنصر من Base UI Menu، يقبل onClick وdisabled. شكل القائمة مؤقت حتى تجهز صفحة القوائم في Figma.
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
children | ReactNode | لا يوجد | نص الإجراء. |
onClick | (event) => void | لا يوجد | يُستدعى عند الاختيار، ثم تُغلق القائمة. |
disabled | boolean | false | يعطّل العنصر ويبقيه ظاهرًا. |
البنية
أجزاء الزر المنقسم، وأين يوجد كل جزء في Figma وفي الكود.
- 1. المجموعة
role="group"نصفان بينهما فراغspace-2، مرتبان على السطر. في نمط Outline يتشارك النصفان حدًّا واحدًا بلا فراغ. - 2. الزر الرئيسي
children, iconLeadingالتسمية وأيقونة اختيارية في البداية، وزواياه عند بداية السطر. له موضع تركيز خاص به، وتمرّ إليه خصائص الزر الأخرى. - 3. نصف القائمة
trailingIconنصف مربع للقائمة بأيقونةCaretDownقابلة للتبديل: يفتح القائمة، ويحملaria-haspopupوaria-expanded. لا ينعكس أبدًا. - 4. اسم نصف القائمة (لا يظهر)
menuLabelخاصية نصية مخفية ومطلوبة: الاسم الذي تسمعه قارئات الشاشة لنصف القائمة. - 5. القائمة
menuعناصر قائمة Ritla UI على بعد 12 بكسل تحت الزر، عند بداية سطره، بدورrole="menu". - 6. مساحة اللمس
size/touch-targetيحتفظ المقاسانsmوxsبمساحة لمس 48 بكسل لكل نصف، دون أن تأخذ مساحة من التخطيط.
إرشادات الاستخدام
الزر المنقسم إجراء معتاد واحد مع بدائل قريبة منه في قائمة. هنا: متى تستخدمه، وكيف تسمّي نصفيه، وما تتحقق منه قبل التسليم.
1. إجراء معتاد واحد وبدائل قريبة
النصف الرئيسي ينفّذ ما يفعله الناس غالبًا، والقائمة تجمع بدائل الإجراء نفسه.
حفظ مستند
«حفظ»، وبدائله في القائمة.
افعل
- ضع الإجراء الأرجح في النصف الرئيسي، والبدائل في القائمة.
- اجعل القائمة خمسة عناصر أو أقل.
تجنّب
- استخدام الزر المنقسم حين تتساوى الإجراءات كلها؛ استخدم مجموعة الأزرار.
- تغيير الإجراء الرئيسي حسب آخر اختيار دون إخبار المستخدم.
3. اجعل التسمية قصيرة
التسمية هي الإجراء الرئيسي، والتفاصيل مكانها القائمة.
شريط تصدير
تصدير تقرير.
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 بكسل.
| المقاس | الارتفاع والحشوة ونصف القطر | التسمية والأيقونات |
|---|---|---|
lg | 56 · space-24 · radius/10 | body-16/Semibold · 24 |
md | 48 · space-24 · radius/10 | body-16/Semibold · 20 |
sm | 40 · space-16 · radius/8 | body-16/Semibold · 20 |
xs | 32 · space-12 · radius/6 | body-14/Semibold · 20 |
الألوان
لون التعبئة والحدّ والتسمية لكل نمط في الحالة الافتراضية، وهي متغيرات الزر نفسها على النصفين. ويأتي الوضعان الفاتح والداكن من وضع 1. Colors.
| النمط | التعبئة والحدّ | التسمية والأيقونات |
|---|---|---|
filled | background/brand/solid | text/brand/on-brand |
tonal | background/brand/faint | text/brand/subtle |
outline | background/surface/lowest · border/gray/soft | text/gray/subtle |
ghost | alpha/tint-12 | text/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>.
افعل
- صُفّ القائمة مع بداية الزر في الاتجاهين: اليسار في الإنجليزية، واليمين في العربية.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.