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

نظرة عامة

استخدم Button لإجراء ما وقدّم تسميته المرئية كعناصر فرعية. استخدم IconButton لعناصر التحكم التي تحتوي على أيقونة فقط، مع اسم يمكن الوصول إليه من aria-label أو aria-labelledby. لإعدادات التصميم الافتراضية المتكررة، استخدم MainButton أو LightButton من twenty-ui/components. كلاهما يشتركان في خصائص Button الأصلية ومراجعها وحالتها وسلوك العرض الخاص بها.

استخدام

المظهر

قارن المتغيرات والألوان الدلالية والأحجام والحالات الشائعة بشكل منفصل. تغيّر كل مجموعة خيارًا واحدًا مع إبقاء الخيارات الأخرى ثابتة.
اختر solid أو outline أو soft أو ghost أو link بشكل مستقل عن اللون neutral أو accent أو danger أو success. الأحجام هي sm وmd؛ والقيم الافتراضية هي outline وneutral وmd. يملأ fullWidth العرض المتاح. يقبل startIcon وendIcon العناصر ويكونان للزينة. يضيف elevated ظلاً وتمويهًا للخلفية. تكتسب أزرار المخطط المحايدة أيضًا سطحًا ذا حدود بألوان نص وتفاعل متطابقة. تحتفظ المتغيرات الأخرى والألوان الدلالية بلوحتها الحالية. قيمته الافتراضية هي false ولا يغيّر الحجم أو الموضع. يعرض shortcut تلميحات لوحة المفاتيح على الشاشات الأكبر؛ اربط الاختصارات في تطبيقك. استخدم color="inherit" لعناصر التحكم على سطح ملوّن. يتبع التصنيف والأيقونات ومؤشر التحميل والحد الخارجي لون النص المحيط. تستخدم تعبئات التفاعل اللون الأسود الشفاف. تستقر الأزرار ذات الحدود الخارجية على سطح شفاف بحد currentColor بنسبة 25%، وتستخدم تعبئات سوداء بنسبة 10% و20% عند التمرير والضغط. يستخدم Ghost تعبئات سوداء شفافة وبنسب 10% و20%؛ ويستخدم Soft نسب 10% و20% و30%. يبقى Link بلا تعبئة. يدعم inherit كلاً من outline وghost وsoft وlink. يؤدي الجمع المحلول بين solid وinherit إلى ظهور خطأ وقت التشغيل، بما في ذلك القيم الافتراضية التي يوفرها ButtonGroup أو غلاف. تكون القيمة الافتراضية لـMainButton هي solid، لذا وفّر متغيرًا غير solid عند توريث اللون.
يستخدم link نصًا مضغوطًا من دون حد أو خلفية مملوءة. يتبع ارتفاع محتواه في كلا الحجمين، مع خط أصغر وحشوة أضيق. يستخدم لونه المحايد نصًا أقوى عند التمرير. لا يحدد المظهر الدلالات: استخدم onClick للإجراءات وhref للتنقل. يمنع disabled وloading التنشيط. يحافظ التحميل على إمكانية الوصول إلى التسمية ويشير إلى حالة انشغال. بشكل افتراضي، يؤدي loadingPosition="center" إلى إخفاء المحتوى مع الحفاظ على مساحة تخطيطه وتوسيط مؤشر التحميل. عيّن loadingPosition إلى start أو end للإبقاء على العناصر الفرعية والأيقونة المقابلة مرئية، مع استبدال الأيقونة المقابلة بمؤشر التحميل. يتولى تطبيقك تنسيق التقدم والتسمية المترجمة. مرّر عبارة الحالة الكاملة كعناصر فرعية، على سبيل المثال Installing (42%).

ملكية الحالة

يُشغّل Button إجراءً ولا يدير قيمة محددة، لذا ليس له وضع تحديد متحكَّم به أو غير متحكَّم به. توفّر خاصية value الأصلية الخاصة به بيانات النموذج، وليس حالة التحديد. يتحكم تطبيقك في loading وdisabled، وتكون قيمتهما الافتراضية false. لا يؤدي النقر على زر إلى تغيير هذه الخصائص أو إظهار التحميل تلقائيًا أثناء تشغيل معالج غير متزامن. مرّر حالة التطبيق الحالية صراحةً.
يبدأ التطبيق التحميل ويمسحه حول عملية الحفظ. يمنع الزر التفعيل أثناء التحميل ويصبح متاحًا مجددًا عند انتهاء العملية، بما في ذلك بعد حدوث خطأ. يستخدم MainButton وLightButton نموذج الحالة نفسه.

مشغلات النوافذ المنبثقة

أنشئ مشغّل نافذة منبثقة باستخدام Button أو LightButton أو غلاف Button آخر عبر render. يوفّر المشغّل data-popup-open، لذا يحتفظ الزر بخلفية التمرير الخاصة به أثناء فتح النافذة المنبثقة ويستخدم خلفيته النشطة عند التمرير أو الضغط. يحتفظ كل متغير ولون بلوحة الألوان الخاصة به. تظل خلفيات الروابط شفافة، وتحافظ الأزرار المعطلة أو قيد التحميل على مظهرها المعطل. تحتفظ الأزرار التي تحتوي على aria-pressed="true" بتنسيق التبديل الحالي الخاص بها. لا تضبط حالة النافذة المنبثقة aria-pressed ولا تمثل قيمة محددة.

الميزات القادمة

يتحكم تطبيقك في توفر الميزة وتسميتها. أنشئ زرًا معطّلًا يحتوي على Badge كعناصر فرعية بحيث يبقى النص جزءًا من الاسم المتاح للزر. وفّر نصًا مترجمًا محليًا من تطبيقك.
يعمل هذا التركيب أيضًا مع MainButton وLightButton. يستبدل الخاصيتين المحذوفتين soon وsoonLabel.

أيقونات متحركة

استخدم AnimatedIconCrossfade مع Button لتغيير أيقونته عند تغيّر حالة التطبيق. مرّر العنصر المتحرك إلى startIcon والتسمية كعناصر فرعية.
عندما تكون الأيقونة إجراءً بحد ذاتها، استخدم IconButton أو LightIconButton وحرّك محتوى أيقونتها. عندما يتحكم رأس الإفصاح في التوسيع، أبقِ سهمه الزاوي للزينة واعرض aria-expanded على عنصر التحكم في الرأس. أبقِ أنماط الحركة مع الميزة واحترم prefers-reduced-motion.

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

من دون render مخصص، يعرض href رابط ارتساء بدلالات الرابط، ما لم تضبط nativeButton صراحةً على true. تصل سمات الارتساء الأصلية، مثل download وhrefLang وping وreferrerPolicy، إلى رابط الارتساء. تحتفظ الخصائص المشتركة مع الأزرار الأصلية بأنواع Base UI الخاصة بها. لتوفير نوع MIME لرابط ارتساء، ضعه على العارض، على سبيل المثال render={<a href="/records.csv" type="text/csv">Download records</a>} مع nativeButton={false} وrole="link". لا يمكن للروابط المعطلة أو قيد التحميل أن تُفعَّل. استخدم render لتكوين عنصر آخر أو رابط موجّه. يصف nativeButton العنصر المعروض، وتكون قيمته الافتراضية true للعارضات المخصصة. اضبط nativeButton={false} وrole="link" لرابط ارتساء للتنقل. يمكن لمكوّن الارتساء أو الموجّه امتلاك وجهته من دون href لـ Button.
لزر \<button> أصلي مخصص، أبقِ nativeButton على true. لعنصر إجراء غير أصلي مثل \<div>، استخدم nativeButton={false}؛ توفّر Base UI سلوك الزر عبر لوحة المفاتيح. يُحافَظ على nativeButton أو role الصريح حتى عند توفير href أيضًا. تكون القيمة الافتراضية للأزرار هي type="button". اضبط type="submit" أو type="reset" صراحةً للنماذج. تصل السمات الأصلية ومعالجات الأحداث وتفاصيل الأحداث والمراجع إلى الجذر المعروض. يتلقى المرجع عنصر الزر أو رابط الارتساء أو عنصر الجذر المخصص الفعلي. تحتفظ معالجات لوحة المفاتيح بأساليب أحداث Base UI، بما في ذلك preventBaseUIHandler() لإلغاء إجراء لوحة المفاتيح المضمّن. يتلقى رد النداء الخاص بالعرض في Base UI كلاً من خصائص الجذر وحالة التعطيل الحالية؛ انشر الخصائص على جذرك للاحتفاظ بسلوك التكوين.

القيم الافتراضية للمجموعة

يوفّر ButtonGroup متغيرًا ولونًا وحجمًا مشتركًا. تكون للخاصية الصريحة في عنصر فرعي أولوية على القيمة الافتراضية للمجموعة. عندما لا يضبط أيٌّ منهما خاصية، تُطبَّق القيمة الافتراضية للمكوّن. استورد Button من twenty-ui/primitives/input واستبدل ClickToActionLink بـ Button variant="link". احتفظ بـ href وtarget وrel للتنقل. تُعرض الإجراءات من دون href الآن كزر أصلي مع التفعيل عبر لوحة المفاتيح. تُمرَّر السمات والأحداث والمراجع الأصلية إلى العنصر الجذر.

الإزاحة

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
افتراضي:"false"
Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors.
ReactNode
Decorative content displayed after the label.
boolean
افتراضي:"false"
Whether the button should be focusable when disabled.
boolean
افتراضي:"false"
Expands the button to fill its container width.
string
Destination URL. Renders a native anchor when render is omitted unless nativeButton is explicitly true. Custom renderers retain their own element contract.
boolean
افتراضي:"false"
Shows a loading indicator and disables activation.
"center" | "end" | "start"
افتراضي:"center"
Where the loading indicator appears. center hides the content while preserving its layout space; start and end keep children and the opposite icon visible and replace the corresponding icon with the spinner.
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.
ShortcutDefinition
Flat key array for simultaneous keys, or nested key arrays for an ordered sequence. Displayed on non-mobile screens.
string
Localized text between sequence steps. Defaults to then.
"md" | "sm"
افتراضي:"md"
Button height: sm (24px) or md (32px). The link variant uses its content height at either size.
ReactNode
Decorative content displayed before the label.
CSSProperties | ((state: ButtonState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
"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.
مرّر shortcut={['Mod', 'Enter']} للمفاتيح المتزامنة أو shortcut={[['G'], ['P']]} للضغطات المتتالية. راجع Shortcut للاطلاع على التركيبات المتداخلة ومنسّق السلاسل المشترك.