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

نظرة عامة

يُركّب IconButton زر مع سطح مربع أو دائري. مرّر الأيقونة كعناصر فرعية وقدّم اسمًا متاحًا باستخدام aria-label أو aria-labelledby. محتوى الرمز زخرفي ومخفي عن التقنية المساعدة.

استخدام

الأحجام هي xs ‏(20px) وsm ‏(24px) وmd ‏(32px). القيم الافتراضية هي md وoutline وneutral. تتطابق الأنماط والألوان مع Button. استخدم shape="round" لزر دائري؛ الشكل الافتراضي هو square.

خيارات مرئية

قارن خيارًا مرئيًا واحدًا في كل مرة. استخدم أمثلة تلميح الأدوات المسمى والمرتفع والمجمّع للتركيب.

الأسماء المتاحة

استخدم aria-label لاسم يُقدَّم مباشرةً على عنصر التحكم. عندما يَسمّي النص المرئي الإجراء بالفعل، استخدم aria-labelledby للإشارة إليه بدلًا من ذلك. مطلوب وجود خاصية تسمية واحدة على الأقل.

تلميح

أضف tooltip لإظهار النص عند التمرير والتركيز باستخدام لوحة المفاتيح. احتفظ بـ aria-label أو aria-labelledby باعتباره الاسم المتاح للإجراء. تحتفظ الأزرار المعطلة وأزرار التحميل بتلميحات التمرير.
يظهر التلميح في الأسفل افتراضيًا، مع تأخير قدره 1000ms وإزاحة قدرها 5px. استخدم tooltipPlace وtooltipDelay وtooltipOffset لضبطه. يؤدي حذف tooltip إلى عرض الزر مباشرةً.

ملكية الحالة

يوفر تطبيقك loading وdisabled. كلاهما يمنع التفعيل. تحافظ حالة التحميل على الأبعاد المربعة والتسمية التي يمكن الوصول إليها. لا يتتبع الزر قيمة محددة ولا يضبط حالة التحميل تلقائيًا بعد النقر. يتبع تركيز لوحة المفاتيح الأصلي المتصفح؛ استخدم aria-pressed عندما يمتلك تطبيقك حالة تبديل.

إجراءات مرتفعة

استخدم elevated لإضافة ظل وتمويه للخلفية. يكتسب زر المخطط المحايد الافتراضي أيضًا سطحًا ذا حدود بألوان أيقونة وتفاعل متطابقة. تحتفظ المتغيرات الأخرى والألوان الدلالية بلوحة الألوان الحالية. القيمة الافتراضية لـ elevated هي false. لا يغيّر الموضع أو الظهور أو الحجم. يبقى الحجم md ‏(32px) افتراضيًا؛ عيّن size="sm" لعنصر تحكم بحجم 24px.
احذف elevated أو عيّنه إلى false لاستعادة المظهر القياسي. تدعم الأزرار البارزة تلميحات الأدوات وحالات التحميل والروابط وتفاعلات لوحة المفاتيح نفسها. استبدل عناصر التحكم FloatingIconButton الحالية بـ IconButton elevated. مرّر الأيقونة باعتبارها children، واستخدم aria-label الأصلي، وحوّل small إلى sm وmedium إلى md. وفّر size="sm" عندما كان عنصر التحكم السابق يستخدم حجمه الافتراضي. يستبدل التركيز الأصلي وaria-pressed التركيز الاصطناعي وعلامات الحالة النشطة. تمت إزالة FloatingIconButtonGroup. ركّب ButtonGroup مع IconButton للإجراءات المجمّعة، واحتفظ بأي سطح عائم مشترك في تخطيطك.

إجراءات مجمعة

يوفّر ButtonGroup قيمًا افتراضية للحجم والمتغير واللون، بالإضافة إلى الزوايا المتجاورة. تتقدم خصائص العناصر الفرعية الصريحة بشكل مستقل، بما في ذلك size="xs". لا تحتاج الأزرار الفردية إلى خاصية موضع. أبقِ الأزرار المتصلة بالحجم نفسه لكي تصطف حوافها. عيّن الحجم للمجموعة ودَع كل زر يرثه.

الروابط والنماذج

من دون render مخصص، يعرض href رابط ارتساء ما لم تكن قيمة nativeButton هي true صراحةً. لرابط ارتساء تنقل مخصص أو رابط موجه، اضبط nativeButton={false} وrole="link". يمكن لأداة التصيير امتلاك وجهتها دون href لـ IconButton. أبقِ nativeButton بقيمة true لزر أصلي مخصص، واستخدم false لعنصر إجراء غير أصلي. تُحفظ خصائص nativeButton وrole الصريحة. لا يمكن للروابط المعطلة والتي قيد التحميل أن تُفعَّل. يبقى التوجيه داخل التطبيق. تُمرَّر سمات الزر الأصلي ورابط الارتساء، ومعالجات الأحداث، وتفاصيل الأحداث، والمراجع، وتركيب التصيير إلى Button. يتلقى المرجع عنصر الجذر الفعلي. يحافظ تركيب تلميح الأداة على ذلك الجذر واسمه المتاح. القيمة الافتراضية هي type="button"؛ اضبط type="submit" صراحةً لإرسال النموذج.

عناصر تحكم صغيرة ومستديرة

استخدم size="xs" لعنصر تحكم بحجم 20px وshape="round" لزوايا دائرية. تصبح عناصر التحكم RoundedIconButton الحالية IconButton مع shape="round" وvariant="solid" وcolor="accent". عيّن الحجم القديم small إلى xs والحجم medium إلى sm. وفّر عناصر فرعية للأيقونة واسمًا متاحًا.

الإزاحة

string
Accessible name describing the action. Required unless aria-labelledby supplies the name.
string
ID of the element supplying the accessible name. Can be used instead of aria-label.
ReactNode
مطلوب
Icon content. Decorative and hidden from assistive technology.
string | ((state: ButtonState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
"accent" | "danger" | "inherit" | "neutral" | "success"
افتراضي:"neutral"
Semantic color of the button. inherit uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults.
boolean
Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors.
boolean
افتراضي:"false"
Whether the button should be focusable when disabled.
string
Destination URL. Renders a native anchor when render is omitted unless nativeButton is explicitly true. Custom renderers retain their own element contract.
boolean
Shows a loading indicator and disables activation.
boolean
افتراضي:"true (false for the built-in href anchor)"
Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in href anchor defaults to false; an explicit value takes precedence.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ButtonState>
Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use nativeButton={false} and role="link" for a custom navigation anchor. Router integration belongs to the caller.
AriaRole
Role of the root element. Use link for custom navigation renderers.
"round" | "square"
افتراضي:"square"
Square or round icon control.
"md" | "sm" | "xs"
افتراضي:"md"
Button size: xs (20px), sm (24px), or md (32px).
CSSProperties | ((state: ButtonState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
string
Text displayed when hovering or focusing the button.
number
افتراضي:"1000"
Delay before showing the tooltip.
number
افتراضي:"5"
Distance in pixels between the button and the tooltip.
"bottom" | "inline-end" | "inline-start" | "left" | "right" | "top"
افتراضي:"bottom"
Preferred placement of the tooltip relative to the button.
"ghost" | "link" | "outline" | "soft" | "solid"
افتراضي:"outline"
Visual treatment of the button surface. link uses compact text styling without a filled surface or border; render composition determines native semantics.