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

زر الأيقونة

احصل على Ritla UI

زر بأيقونة بدل النص، لأشرطة الأدوات والإجراءات المتكررة. يشارك الزر أنماطه وأحجامه وحالاته، ويحمل دائمًا اسمًا مكتوبًا لقارئات الشاشة.

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

افتح في Figma

المعاينة

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

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

التثبيت

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

    npx ritla add icon-button

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

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

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

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

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

الاستخدام

icon-button.tsx
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.

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

الأنماط

أنماط الزر الخمسة بألوانها نفسها، والأيقونة بلون النص. danger يحوّل أي نمط إلى الأحمر، وinverted-ghost للأسطح الملونة.

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

الشكل

square (الافتراضي) يأخذ استدارة الزر في حجمه، وround دائري بالكامل للأزرار العائمة وصور الملفات الشخصية.

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

الحالات

loading يضع المؤشر مكان الأيقونة ويُبقي التركيز والاسم، وdisabled يوقف الزر. اضغط «حفظ»، وغيّر label أثناء التحميل («جارٍ الحفظ»).

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

شريط الأدوات في العربية

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

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

زر الإغلاق

زر الإغلاق عند نهاية السطر، أي اليسار في العربية. الحجم xs يناسب الترويسات الكثيفة ويبقى سهل النقر.

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

متى تستخدم زرًا بنص

زر الأيقونة للأيقونات المألوفة (تعديل، مشاركة، بحث). الإجراء الخطر يحتاج نصًا صريحًا، فاستخدم زرًا بنص بدل سلة مهملات وحدها، ولا تضع زرين filled متجاورين.

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

مرجع الخصائص

IconButton

أي خاصية أخرى من Base UI Button تمر كما هي (onClick، type…).

الخاصيةالنوعالافتراضيالوصف
iconIconComponentلا يوجدChange icon في Figma: أيقونة Phosphor أو من ⁨Ritla UI⁩. الأيقونات الاتجاهية تنعكس في العربية وحدها.
labelstringلا يوجدمطلوب. الاسم الذي تسمعه قارئات الشاشة (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 بكسل.
dangerbooleanfalseخاصية Danger في Figma: الأحمر وحلقة تركيز حمراء.
loadingbooleanfalseState = Loading: المؤشر مكان الأيقونة، aria-busy، والزر يبقى قابلًا للتركيز.
disabledbooleanfalseState = Disabled.
renderReactElementلا يوجدعنصر آخر بشكل زر الأيقونة، عادةً رابط. يحتفظ بدلالته ويأخذ label اسمًا.
classNamestringلا يوجدأصناف إضافية تُدمج عبر cn().

البنية

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

  1. 1. مساحة اللمسsize/touch-target48 بكسل على الأقل في كل المقاسات. يضيف المقاسان sm وxs مربعًا غير مرئي بحجم 48 بكسل دون أن يأخذ مساحة من التخطيط.
  2. 2. المحتوىsizeمربع لكل مقاس: 56 بكسل في lg، و48 بكسل في md، و40 بكسل في sm، و32 بكسل في xs، باستدارة الزر في المقاس نفسه.
  3. 3. الأيقونةiconأيقونة Phosphor قابلة للتبديل، مقاسها 24 بكسل في lg، و20 بكسل في md وsm وxs، وتأخذ لون التسمية. الأيقونات الاتجاهية تنعكس في العربية.
  4. 4. التسمية (لا تظهر)labelخاصية نصية مخفية ومطلوبة. تصبح aria-label، وتُخفى الأيقونة عن قارئات الشاشة (aria-hidden).
  5. 5. الشكلshapesquare (الافتراضي) أو round، الذي يستبدل الاستدارة بـradius/full.
  6. 6. الخطرdangerالألوان الحمراء وحلقة تركيز حمراء.
  7. 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 دون أن تأخذ مساحة من التخطيط.

المقاسالمربع والحشوة ونصف القطرالأيقونة
lg56 · space-16 · radius/1024
md48 · space-14 · radius/820
sm40 · space-10 · radius/620
xs32 · space-6 · radius/420
shape="round"radius/full24 · 20

الألوان

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

النمطالتعبئة والحدّالأيقونة
filledbackground/brand/solidtext/brand/on-brand
filled · dangerbackground/danger/solidtext/static/white
tonalbackground/brand/fainttext/brand/subtle
tonal · dangerbackground/danger/fainttext/danger/subtle
outlinebackground/surface/lowest · border/gray/softtext/gray/subtle
outline · dangerbackground/surface/lowest · border/danger/softtext/danger/subtle
ghostalpha/tint-12text/gray/subtle
ghost · dangeralpha/tint-12text/danger/subtle
inverted-ghostalpha/tint-12text/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 للأيقونات الاتجاهية.

تجنّب

  • عكس الأيقونات غير الاتجاهية: البحث والإعدادات والمزيد.

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

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

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