زر الأيقونة
زر بأيقونة بدل النص، لأشرطة الأدوات والإجراءات المتكررة. يشارك الزر أنماطه وأحجامه وحالاته، ويحمل دائمًا اسمًا مكتوبًا لقارئات الشاشة.
فحص ريتلا لهذه المعاينة: الفحوص الناجحة: 41 من 41مقاسات العرض: 3تاريخ الفحص:
المعاينة
«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.
التثبيت
أضف المكوّن
npx ritla add icon-buttonويعمل أيضًا مع shadcn:
npx shadcn@latest add @ritla/icon-buttonالاعتماديات التي يضيفها
@base-ui/react@phosphor-icons/reactأو انسخه يدويًا
التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.
الاستخدام
import { MagnifyingGlassIcon } from "@phosphor-icons/react/ssr";import { IconButton } from "@/components/ui/icon-button";<IconButton variant="outline" icon={MagnifyingGlassIcon} label="Search" />أمثلة
الأحجام
كل حجم مربع بارتفاع الزر من الحجم نفسه (56 و48 و40 و32 بكسل)، فيصطفان في سطر واحد. مساحة النقر تبقى 48 بكسل على الأقل في sm وxs.
الأنماط
أنماط الزر الخمسة بألوانها نفسها، والأيقونة بلون النص. danger يحوّل أي نمط إلى الأحمر، وinverted-ghost للأسطح الملونة.
الشكل
square (الافتراضي) يأخذ استدارة الزر في حجمه، وround دائري بالكامل للأزرار العائمة وصور الملفات الشخصية.
الحالات
loading يضع المؤشر مكان الأيقونة ويُبقي التركيز والاسم، وdisabled يوقف الزر. اضغط «حفظ»، وغيّر label أثناء التحميل («جارٍ الحفظ»).
شريط الأدوات في العربية
«رجوع» يستخدم ArrowLeftIcon في اللغتين ويشير إلى اليمين في العربية، لأن الرجوع عكس اتجاه القراءة. البحث والإشعارات والقائمة لا تنعكس، والصف كله يتبع اتجاه الصفحة.
زر الإغلاق
زر الإغلاق عند نهاية السطر، أي اليسار في العربية. الحجم xs يناسب الترويسات الكثيفة ويبقى سهل النقر.
متى تستخدم زرًا بنص
زر الأيقونة للأيقونات المألوفة (تعديل، مشاركة، بحث). الإجراء الخطر يحتاج نصًا صريحًا، فاستخدم زرًا بنص بدل سلة مهملات وحدها، ولا تضع زرين filled متجاورين.
مرجع الخصائص
IconButton
أي خاصية أخرى من Base UI Button تمر كما هي (onClick، type…).
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
icon | IconComponent | لا يوجد | Change icon في Figma: أيقونة Phosphor أو من Ritla UI. الأيقونات الاتجاهية تنعكس في العربية وحدها. |
label | string | لا يوجد | مطلوب. الاسم الذي تسمعه قارئات الشاشة (aria-label)، بلغة الصفحة. |
shape | "square" | "round" | "square" | خاصية Shape: استدارة الزر أو دائرة كاملة. |
variant | "filled" | "tonal" | "outline" | "ghost" | "inverted-ghost" | "filled" | خاصية Style، كما في الزر. |
size | "lg" | "md" | "sm" | "xs" | "lg" | خاصية Size: مربع 56 و48 و40 و32 بكسل. |
danger | boolean | false | خاصية Danger في Figma: الأحمر وحلقة تركيز حمراء. |
loading | boolean | false | State = Loading: المؤشر مكان الأيقونة، aria-busy، والزر يبقى قابلًا للتركيز. |
disabled | boolean | false | State = Disabled. |
render | ReactElement | لا يوجد | عنصر آخر بشكل زر الأيقونة، عادةً رابط. يحتفظ بدلالته ويأخذ label اسمًا. |
className | string | لا يوجد | أصناف إضافية تُدمج عبر cn(). |
البنية
أجزاء زر الأيقونة، وأين يوجد كل جزء في Figma وفي الكود.
- 1. مساحة اللمس
size/touch-target48 بكسل على الأقل في كل المقاسات. يضيف المقاسانsmوxsمربعًا غير مرئي بحجم 48 بكسل دون أن يأخذ مساحة من التخطيط. - 2. المحتوى
sizeمربع لكل مقاس: 56 بكسل فيlg، و48 بكسل فيmd، و40 بكسل فيsm، و32 بكسل فيxs، باستدارة الزر في المقاس نفسه. - 3. الأيقونة
iconأيقونة Phosphor قابلة للتبديل، مقاسها 24 بكسل فيlg، و20 بكسل فيmdوsmوxs، وتأخذ لون التسمية. الأيقونات الاتجاهية تنعكس في العربية. - 4. التسمية (لا تظهر)
labelخاصية نصية مخفية ومطلوبة. تصبحaria-label، وتُخفى الأيقونة عن قارئات الشاشة (aria-hidden). - 5. الشكل
shapesquare(الافتراضي) أوround، الذي يستبدل الاستدارة بـradius/full. - 6. الخطر
dangerالألوان الحمراء وحلقة تركيز حمراء. - 7. مؤشر التحميل
loadingفي حالة التحميل يأخذ المؤشر مكان الأيقونة، ويحمل الزرaria-busyويبقى قابلًا للتركيز.
إرشادات الاستخدام
زر الأيقونة يختصر إجراءً مألوفًا في أيقونة. هنا: أي أيقونة تختار، وكيف تسمّي الزر، وما تتحقق منه قبل التسليم.
1. اختر أيقونات مألوفة
لا يعمل زر الأيقونة إلا حين يقرأ الجميع الأيقونة بالطريقة نفسها: رجوع، بحث، إشعارات، تعديل، مشاركة، تنزيل، إغلاق.
شريط أدوات لمستند
ثلاثة إجراءات فوق مستند.
افعل
- استخدم زر الأيقونة فقط حين تكون الأيقونة واضحة لا لبس فيها: إغلاق، بحث، المزيد، تعديل.
تجنّب
- الاعتماد على أيقونة مخصّصة لم يرها المستخدم من قبل.
2. سمِّ كل زر أيقونة
label مطلوب في الكود، فلا يُنشر زر أيقونة بلا اسم. يصبح aria-label، وتُخفى الأيقونة عن قارئات الشاشة. وفي Figma املأ خاصية Label المخفية كي يظهر الاسم في Dev Mode. سمِّ الإجراء لا الأيقونة («إغلاق» لا «X»)، بلغة الصفحة.
افعل
- أعطِ كل زر أيقونة اسمًا يُقرأ، وتلميحًا في أشرطة الأدوات.
3. زر filled واحد في كل مرة
النمط filled يميّز الإجراء الرئيسي. وبجوار أزرار أيقونات أخرى، اكتفِ بواحد منه.
صف في قائمة مع إجراءاته
تعديل ومشاركة وإضافة في صف واحد.
filled واحد والباقي ghostيبرز الإجراء الرئيسي وتبقى الإجراءات الأخرى هادئة.filled متجاورانوزنان متساويان يجعلان المستخدم يتوقف ليقارن.تجنّب
- استخدام زر أيقونة للإجراء الرئيسي في الشاشة؛ استخدم زرًا بنص.
4. الإجراءات الخطرة تحتاج إلى كلمات
أيقونة سلة المهملات وحدها سهلة الضغط بالخطأ وسهلة الفهم الخاطئ.
حذف مشروع
الإجراء الأخير في صفحة الإعدادات.
dangerالكلمات تقول بالضبط ما الذي سيُحذف.5. طابِق مقاس الصف
كل زر أيقونة بارتفاع الزر من المقاس نفسه، فاختر المقاس نفسه للاثنين.
شريط حفظ
زر أيقونة للقائمة بجوار «حفظ».
md بجوار mdتتطابق الحواف ويُقرأ الصف مجموعة واحدة.lg بجوار smالارتفاعات المختلطة تبدو مكسورة وتزيح خط الأساس.6. التحميل والتعطيل
في التحميل يأخذ المؤشر مكان الأيقونة، ويحتفظ الزر بالتركيز وباسمه، ويتجاهل الضغط؛ حوّل الاسم إلى صيغة «جارٍ …» («جارٍ الحفظ»). واستخدم التعطيل بقلة، وقل بجوار الزر لماذا لا يتوفر الإجراء.
7. العربية والاتجاه من اليمين إلى اليسار
«رجوع» يشير إلى اليمين في العربية. اختر أيقونة ArrowLeft، فهي تنعكس وحدها.
ترويسة صفحة عربية
رجوع وبحث، من اليمين إلى اليسار.
قبل التسليم
- في كل نسخة خاصية
Labelمملوءة بلغة الصفحة. - الأيقونات مألوفة، والاتجاهية منها تستخدم
RTL = Yesفي الإطارات العربية. - زر
filledواحد في كل مجموعة. - المقاسات تطابق الأزرار في الصف نفسه.
- الإجراءات الخطرة أزرار بنص.
رموز التصميم والمواصفات
كل قيمة في زر الأيقونة متغيّر، وهي متغيرات الزر نفسها. هذه هي القيم المربوطة بالمكوّن، حسب المقاس وحسب النمط.
المقاسات
المربع والحشوة الداخلية ونصف قطر الزوايا لإطار المحتوى، مع مقاس الأيقونة. وكل مقاس داخل مساحة لمس size/touch-target (48)، ويضيفها sm وxs دون أن تأخذ مساحة من التخطيط.
| المقاس | المربع والحشوة ونصف القطر | الأيقونة |
|---|---|---|
lg | 56 · space-16 · radius/10 | 24 |
md | 48 · space-14 · radius/8 | 20 |
sm | 40 · space-10 · radius/6 | 20 |
xs | 32 · space-6 · radius/4 | 20 |
shape="round" | radius/full | 24 · 20 |
الألوان
لون التعبئة والحدّ والأيقونة لكل نمط في الحالة الافتراضية، وهي متغيرات الزر نفسها. ويأتي الوضعان الفاتح والداكن من وضع 1. Colors، لا من نسخ منفصلة.
| النمط | التعبئة والحدّ | الأيقونة |
|---|---|---|
filled | background/brand/solid | text/brand/on-brand |
filled · danger | background/danger/solid | text/static/white |
tonal | background/brand/faint | text/brand/subtle |
tonal · danger | background/danger/faint | text/danger/subtle |
outline | background/surface/lowest · border/gray/soft | text/gray/subtle |
outline · danger | background/surface/lowest · border/danger/soft | text/danger/subtle |
ghost | alpha/tint-12 | text/gray/subtle |
ghost · danger | alpha/tint-12 | text/danger/subtle |
inverted-ghost | alpha/tint-12 | text/static/white |
التركيز
في حالة التركيز يُرسم نمط التأثير Focus/focus-ring (effects/focus/main) بسماكة border-width/thicker، وتصبح الحلقة حمراء مع danger. وفي الكود يحدث ذلك تلقائيًا مع :focus-visible.
إمكانية الوصول
لوحة المفاتيح
المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.
| المفتاح | ما يفعله |
|---|---|
| Tab | ينقل التركيز إلى الزر، وتظهر حلقة التركيز (حمراء مع danger). |
| EnterSpace | ينفّذ الإجراء. أثناء التحميل يبقى التركيز ولا يتكرر الإجراء. |
ARIA
labelمطلوب في النوع نفسه، فلا يمكن نشر زر أيقونة بلا اسم. يصبحaria-labelوالأيقونةaria-hidden.- اكتب الاسم بلغة الصفحة («بحث» لا «Search» في العربية)، وصف الإجراء لا الأيقونة («إغلاق» لا «علامة X»).
- التحميل يضبط
aria-busy="true"وaria-disabled="true"بدلdisabled، فلا يضيع التركيز. - مساحة النقر 48 بكسل على الأقل في كل الأحجام (WCAG 2.5.8)، حتى حين يُرسم الزر 32 بكسل.
- في أشرطة الأدوات يحتاج المستخدم المبصر تلميحًا أيضًا. سيأتي مع مكوّن Tooltip.
افعل
- حافظ على مساحة لمس 48 بكسل على الأقل في كل المقاسات، حتى في
xs. - ينقل
Tabالتركيز وتظهر الحلقة (حمراء معdanger)، ويضغطEnterوSpaceالزر. - أثناء التحميل استخدم
aria-busyوaria-disabledبدلdisabled، فلا يضيع التركيز، والكود يفعل ذلك عنك. - في أشرطة الأدوات أضف تلميحًا للمستخدم المبصر أيضًا.
ملاحظات العربية والاتجاه
ينعكس
- الأسهم والأسهم المثلثة تنعكس عبر
<Icon>: «رجوع» بـArrowLeftIconيشير إلى اليمين في العربية. - ترتيب الأزرار في شريط الأدوات ينعكس مع الصفحة، وزر الإغلاق يبقى عند نهاية السطر.
لا ينعكس
- الزر نفسه لا ينعكس ولا يحتاج خاصية RTL؛ الأيقونة وحدها تقرر.
- البحث والإشعارات والقائمة والقلب والتنزيل ومؤشر التحميل تبقى كما هي في اللغتين.
- الأرقام
- لا أرقام في زر الأيقونة. إن أضفت شارة عدد فوقه، نسّقها بـ
formatNumberلتتبع إعداد الأرقام. - الخط العربي
- لا نص مرئي؛ الاسم في
label. اكتبه بالعربية الطبيعية، فقارئ الشاشة ينطقه بصوت عربي حين تكون الصفحةlang="ar". - النص ثنائي الاتجاه
- اسم علامة تجارية لاتيني داخل
labelعربي («مشاركة عبر WhatsApp») يُقرأ صحيحًا دون<bdi>، لأنaria-labelنص لا يُعرض.
افعل
- استخدم أيقونة
ArrowLeftلـ«رجوع»، فتشير إلى اليمين في العربية. - في إطارات Figma العربية استخدم
RTL = Yesللأيقونات الاتجاهية.
تجنّب
- عكس الأيقونات غير الاتجاهية: البحث والإعدادات والمزيد.
الفحوص التي يجتازها
فحوص ريتلا التي يجتازها هذا المكوّن بطريقة بنائه. إن استُخدم كما هو موثّق، لا يحمل هذه الأخطاء إلى صفحتك.