زر Button
مواصفات الدلالات والأحجام والأشكال والحالات وإمكانية الوصول لـ Button و IconButton.
يُعيد زر الذكاء الاصطناعي استخدام أبعاد الزر ودلالاته بينما يضيف حالة ذكاء اصطناعي مميزة وقابلة للإدراك.
حدد زر الذكاء الاصطناعي لمعاينة حالته أثناء العمل.
مواصفات مكون الأزرار في Qokit
تُعرّف هذه الوثيقة قواعد استخدام الأزرار في منصة Qokit و Builder و CMS و Dashboard و Admin وصفحات التسويق والمواقع المُنشأة. الهدف هو توحيد المكونات والدلالات والأشكال والأحجام والأيقونات والحالات وإمكانية الوصول للأزرار، وتجنب إعادة تصميم الأزرار عبر CSS محلي في كل مسار.
1. النموذج الأساسي
لا تُصنَّف الأزرار حسب "البيضاوي والدائري" فحسب، بل تتكوّن من خمسة أبعاد مستقلة:
Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating- نوع المكوّن يحدد ما إذا كان الزر يحتوي على نص مرئي، وما إذا كان يجب الحفاظ على منطقة نقر مربعة.
- أولوية الدلالة تحدد أولوية الزر ولونه في المهمة الحالية.
- الحجم يحدد الارتفاع الثابت وحجم الخط ومنطقة اللمس.
- الشكل يحدد فقط استدارة الزوايا، ولا يعبر عن أولوية أو دلالة عمل.
- الطبقة المكانية توضح فقط ما إذا كان عنصر التحكم ينفصل عن المستوى الحالي، دون تغيير دلالة الإجراء.
لا تُنشئ أنواع أزرار جديدة عبر تركيب أسماء فئات. ابدأ باختيار الخصائص الموجودة في المكوّن المشترك.
2. اختيار المكوّن
Button
يُستخدم لجميع الإجراءات التي تحتوي على نص مرئي، بما في ذلك:
- أزرار النص فقط؛
- أزرار بأيقونة قبل النص؛
- أزرار بأيقونة بعد النص؛
- روابط الصفحات التي تظهر بشكل أزرار.
Button في المنصة تستخدم افتراضيًا pill باستدارة كاملة، وتظهر بشكل بيضاوي بصريًا. طالما يحتوي الزر على نص مرئي، فلا يجب استبداله بزر أيقونة دائري.
variant مفصولة عن الظلال: primary تستخدم افتراضيًا raised، بينما secondary و danger و ghost تستخدم افتراضيًا flat. يجب أن تكون الإجراءات داخل صفوف القوائم والبطاقات وأشرطة الأدوات والكبسولات المركبة من نوع flat؛ يمكن استخدام raised للإجراءات الرئيسية المستقلة؛ ويُستخدم floating فقط للإجراءات العائمة فوق المحتوى. تُرسم الظل مرة واحدة فقط بواسطة الطبقة الخارجية للكبسولات المستقلة أو عناصر التحكم المجزأة، ولا يجوز للمسارات إعادة كتابة الطبقات المشتركة عبر CSS محلي.
import { Button } from '@qokit/components/ui';
<Button type="button" variant="primary">
保存
</Button>
<Button
leadingIcon={<SaveIcon aria-hidden="true" />}
type="button"
variant="primary"
>
保存
</Button>
<Button
href="/projects"
trailingIcon={<ArrowRightIcon aria-hidden="true" />}
variant="secondary"
>
查看项目
</Button>IconButton
يُستخدم لإجراءات الأدوات المدمجة التي تحتوي على أيقونة فقط بدون نص مرئي، مثل الإغلاق والمزيد والرجوع وتبديل القائمة أو الحذف.
IconButton يحافظ على نفس العرض والارتفاع والاستدارة الكاملة في كل حجم، وبالتالي يظهر كزر دائري بصريًا. يستخدم افتراضيًا ghost، ويفرض على مستوى النوع استخدام aria-label.
import { IconButton } from '@qokit/components/ui';
<IconButton aria-label="关闭" tooltip="关闭" type="button">
<CloseIcon aria-hidden="true" />
</IconButton>القواعد:
- تستخدم الأيقونة نفسها
aria-hidden="true"، ويُوفَّر اسم الزر بواسطةaria-label. - يجب أن تستخدم الأيقونات غير المألوفة أو التي قد يكون معناها غير واضح
Tooltipالمشترك أيضًا؛ ولا يمكن لـ tooltip أن يحل محلaria-label. - لا تستخدم خاصية DOM
titleكتلميح منتج، ولا تضبطtooltipوتغلّف Tooltip يدويًا في الوقت نفسه. - Tooltip طبقة معلومات للقراءة فقط، وليست زرًا بيضاويًا. يستخدم استدارة Tooltip المدمجة المشتركة، ولا يجوز إعادة استخدام
pillأو التأثيرات البصرية لـ hover أو pressed أو focus للزر. - لا تستخدم
Buttonبنص فارغ أو مخفي أو عرض ثابت لمحاكاةIconButton. - لا تضبط
shapeلـIconButton؛ الشكل الدائري هو عقد المكوّن.
سيناريوهات عدم استخدام Button
- علامات التبويب تستخدم المكوّنات المقابلة مثل Tabs/PillTabs/Segmented.
- عناصر القائمة تستخدم المكوّنات المقابلة مثل Menu/ActionMenu.
- الحالات والعلامات ونتائج التصفية تستخدم Pill أو مكوّنات الحالة.
- التنقل النصي العادي يستخدم الروابط الدلالية؛ ولا يُستخدم
Buttonمعhrefإلا عند الحاجة إلى تأكيد بصري بمستوى الزر.
3. الطبقة الدلالية variant
| Variant | المعنى | السيناريوهات النموذجية | قيود الاستخدام |
|---|---|---|---|
primary | الإجراء الرئيسي في المنطقة الحالية | حفظ، نشر، إنشاء، جرّب الآن | يُحتفظ عادةً بإجراء رئيسي واحد فقط في منطقة المهمة |
secondary | إجراء واضح لكن ثانوي | معاينة، إلغاء، رجوع، استيراد | لا ينبغي أن ينافس الإجراء الرئيسي على الانتباه البصري |
ghost | إجراء أدوات منخفض التأكيد وسياقي | إغلاق، المزيد، إجراءات شريط الأدوات، رجوع خفيف | شفاف افتراضيًا، ولا يمكن أن يكون CTA حاسمًا وحيدًا |
danger | إجراء يحذف أو يسبب ضررًا واضحًا | حذف عنصر، إزالة محتوى، مسح بيانات | يعبر فقط عن الدلالة التدميرية، ولا يُستخدم كلون تأكيد عادي |
variant يعبر عن الطبقة الدلالية والبصرية، وليس الشكل. على سبيل المثال، يمكن أن يكون ghost زرًا بيضاويًا مع نص، أو IconButton دائريًا.
ترتيب الاختيار:
- حدد الخطوة التالية الأكثر أهمية حاليًا واجعلها
primary. - استخدم
secondaryللإجراءات المساعدة التي لا تزال بحاجة إلى وضوح. - استخدم
ghostلإجراءات منخفضة التأكيد في شريط الأدوات أو السياق. - استخدم
dangerفقط للإجراءات التدميرية الفعلية، مع الحفاظ على سير التأكيد الحالي.
لا تختر variant بناءً على "أي الألوان أجمل".
4. الحجم size
| Size | الارتفاع/القطر | حجم الخط | السيناريو الموصى به |
|---|---|---|---|
sm | 40px | 14px | شريط التنقل العلوي، أشرطة الأدوات المدمجة، مناطق العمل الكثيفة |
md | 44px | 15px | النماذج الافتراضية و CMS ومربعات الحوار والإجراءات العادية |
lg | 48px | 16px | CTA الرئيسي في صفحات التسويق، الإجراءات الرئيسية التي تحتاج لمس أفضل |
الحجم الافتراضي هو md.
- تستخدم مجموعة الأزرار نفسها نفس الحجم.
- لا يقل حجم عناصر التحكم المدمجة عن 40px؛ وتُفضَّل الإجراءات الرئيسية على الأجهزة المحمولة بارتفاع 44px على الأقل.
- يستخدم ارتفاع
ButtonوقطرIconButtonنفس مجموعة رموز الحجم، لذا يمكن محاذاةهما في شريط أدوات واحد؛ وحجم الأيقونة المرئية لـIconButtonموحد عند 18px. - يُحدد حجم خط
Buttonبواسطة الرمز المشترك المقابل لـ size، ولا يرث حجم الخط من Header أو Dialog أو أي حاوية أب أخرى. - يمكن لـ CSS المسار التحكم في ترتيب الأزرار والتباعد والعرض اللازم، لكن لا يمكنه إعادة تعريف ارتفاع أو حجم الخط للزر المشترك.
- عند وجود نص طويل، يُفضَّل تعديل التخطيط أو حاوية الزر، ولا تُحل المشكلة عبر ضغط الارتفاع أو الخط أو التباعد الجانبي.
5. الشكل shape
| Shape | المظهر | نطاق الاستخدام |
|---|---|---|
pill | استدارة كاملة؛ بيضاوي عند وجود نص | الافتراضي في المنصة، مناسب لصفحات التسويق و Dashboard و Builder و CMS و Admin |
rounded | استدارة 12px | فقط عندما يطلب سمة الموقع المُنشأ صراحةً استدارة أصغر |
Button افتراضيًا shape="pill". لا تضبط rounded صراحةً في الواجهة الأمامية للمنصة، ولا تتجاوز الاستدارة في CSS محلي.
// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>
// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
预约咨询
</Button>IconButton دائري دائمًا، ولا يشارك في اختيار pill / rounded الدلالي.
6. قواعد الأيقونات
- تستخدم الأيقونة قبل النص
leadingIcon، والأيقونة بعد النص تستخدمtrailingIcon. - يستخدم الزر عادةً أيقونة مساعدة واحدة فقط.
- يمكن استخدام الأيقونات لتعزيز التعرف على الإجراءات المألوفة مثل الحفظ والإضافة والرجوع، لكن لا يمكن للأيقونة أن تحل محل النص المرئي للأزرار المهمة.
- توضع الأسهم التي تعبر عن المتابعة أو الدخول أو التوسع عادةً بعد النص؛ وتوضع أيقونة الرجوع عادةً قبل النص.
- لا تكتب تخطيط الأيقونة والنص يدويًا في
children، فالمكوّن يوفر بالفعل فتحات icon و label. - استخدم الأيقونات المشتركة وارث
currentColor، ولا تُشفّر ألوان أو أحجام الأيقونات بشكل ثابت في CSS المسار. - يجب أن تحافظ حالة التحميل على أبعاد الزر الأصلية، وتوفر نصًا قصيرًا مفهومًا أو ملاحظات تحميل موجودة؛ ولا تدع تبديل النص يسبب اهتزاز شريط الأدوات.
7. الأزرار والروابط
يجب استخدام الدلالات الصحيحة للإجراءات والتنقل:
- إجراءات الصفحة الحالية مثل الإرسال والحفظ وفتح الطبقة وتبديل الحالة تستخدم
Buttonبدونhref، وتُعرض نهائيًا كـ<button>. - للانتقال إلى مسار أو مورد آخر، استخدم
Buttonمعhref، وتُعرض نهائيًا كـ Next.js<Link>. - يجب أن تكتب الأزرار غير المرسلة في النماذج
type="button"صراحةً؛ وأزرار الإرسال تكتبtype="submit"صراحةً. - لا تستخدم
onClickلمحاكاة التنقل العادي في الصفحة.
الروابط المعطلة تستخدم aria-disabled وتخرج من ترتيب Tab؛ والأزرار الأصلية المعطلة تستخدم disabled. لا يمكن التعبير عن حالة التعطيل فقط عبر تقليل الشفافية، بل يجب أن تمنع منطق العمل الإجراء أيضًا.
8. الحالات وإمكانية الوصول
تتحكم المكوّنات المشتركة بشكل موحد في حالات hover و focus-visible و disabled والألوان. لا يزال يتعين على كود العمل تحقيق:
- يستخدم hover للأزرار العادية غير المحددة
--control-surface-hover؛ والضغط والتحديد والتوسع يستخدم--control-surface-active. يحتفظfocus-visibleبـ--focus-ringعلى الأسطح المحايدة، ولا يجوز لأنماط المسار دمج hover والحالة المستمرة في قاعدة زرقاء فاتحة واحدة. - يجب أن تكون أسماء الأزرار مباشرة ومحددة وتوضح ما سيحدث، مثل "حفظ" أو "نشر الموقع" أو "حذف العنصر".
- يجب أن يوفر
IconButtonaria-labelمترجمًا محليًا. - تستخدم الأيقونات الزخرفية
aria-hidden="true"لتجنب تكرار القراءة بواسطة قارئ الشاشة. - يجب أن يكون تركيز لوحة المفاتيح مرئيًا؛ ولا يجوز لـ CSS المسار إزالة حلقة focus المشتركة.
- لا تعتمد على hover كتلميح وحيد، يجب أن يدعم التفاعل لوحة المفاتيح واللمس في الوقت نفسه.
- تُستخدم الأزرار المعطلة فقط للإجراءات التي لا يمكن للمستخدم تنفيذها مؤقتًا؛ إذا كانت هناك حاجة لشرح السبب، يجب توفير شرح قريب أو tooltip.
- يجب أن تظل معلومات الأخطاء والأذونات والمخاطر والتكاليف وغيرها من المعلومات الحاسمة للمهمة مرئية؛ يمكن لـ Tooltip فقط补充 المعلومات، ولا يمكن أن يكون الطريقة الوحيدة لاكتشاف هذه المعلومات.
- يجب أن تمنع العمليات غير المتزامنة الإرسال المتكرر، وتحتفظ بملاحظات قابلة للفهم أثناء التنفيذ.
- تستخدم الإجراءات الخطرة
danger، وتعيد استخدام نمط تأكيد الخطر الحالي؛ لا تعتمد فقط على اللون الأحمر للتعبير عن المخاطر. - لا يجوز اقتطاع نص الزر باللغة الصينية أو أي لغة أخرى إلى حد عدم الفهم. يجب التحقق من النصوص الطويلة وعرض الأجهزة المحمولة.
9. حدود مسؤوليات الأنماط
تتحكم Button / IconButton في بنية الأزرار المشتركة ودلالاتها وحالاتها؛ وتتحكم حزمة المكوّنات في رموز التصميم و CSS المشترك؛ والمسارات مسؤولة فقط عن التخطيط.
مسؤوليات الطبقة المشتركة
- DOM، دلالات الروابط/الأزرار، سلوك disabled؛
- فتحات icon/label وقيود أنواع إمكانية الوصول؛
- فئات variant و size و shape؛
- الارتفاع والاستدارة والحشو وحجم الخط ووزن الخط؛
- الخلفية ولون النص والظل وحالات hover و focus-visible و disabled.
يمكن أن تكون الطبقة مسؤولة عن
- اتجاه مجموعة الأزرار والتباعد والمحاذاة والالتفاف؛
- الترتيب المتجاوب؛
width: 100%أو عرض الحاوية المطلوب لسير عمل معين؛- أسماء فئات التموضع التي لا تغير المظهر الأساسي.
لا يجوز للطبقة أن تكون مسؤولة عن
- إعادة كتابة ارتفاع الزر أو حجم الخط أو الاستدارة أو الخلفية أو لون النص أو الظل أو حلقة focus؛
- إعادة تنفيذ الزر المشترك باستخدام ألوان ثابتة أو
border-radius: 999px؛ - إضافة متغيرات بصرية محلية مثل
primary-altوoutline-blueوicon-round؛ - المنافسة مع عقد الزر المشترك عبر
!important؛ - نسخ الأنماط الأساسية لـ
.qk-ui-buttonمباشرةً.
إذا ظهرت بالفعل متغيرات دلالية جديدة مطلوبة في عدة صفحات، يجب أولاً إنشاء عقد موحد في ButtonVariant المشترك والرموز و primitives.css، بدلاً من إضافة أنماط في المسارات.
10. مرجع API السريع
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';الخصائص الرئيسية لـ Button:
| الخاصية | القيمة الافتراضية | الوصف |
|---|---|---|
variant | primary | الطبقة الدلالية والبصرية |
size | md | الارتفاع وحجم الخط والحشو الأفقي |
shape | pill | شكل الاستدارة لـ Button |
leadingIcon | لا يوجد | أيقونة قبل النص |
trailingIcon | لا يوجد | أيقونة بعد النص |
href | لا يوجد | تُعرض كرابط عند التوفير |
disabled | false | تعطيل التفاعل |
tooltip | لا يوجد | محتوى تكميلي لـ Tooltip المشترك؛ لا يمكن أن يحل محل المعلومات المرئية المهمة أو aria-label |
tooltipPlacement | bottom | الاتجاه المفضل؛ يمكن لـ Tooltip المشترك الانعكاس للبقاء داخل إطار العرض |
tooltipPortal | true | العرض خارج حاوية القطع دون إضافة طبقة تخطيط مغلفة |
skin | لا يوجد | يوفر فتحات class وتكييف المتغيرات وفقًا لعقد skeleton/skin |
IconButton يرث خصائص Button المعمول بها، لكنه لا يوفر shape أو leadingIcon أو trailingIcon؛ ويتطلب aria-label، والافتراضي variant="ghost".
يُنصح بكتابة variant و type الزر الأصلي صراحةً في كود العمل، لتكون دلالة الإجراء واضحة في مراجعة الكود.
11. التركيبات الشائعة
// 主要操作:椭圆形文字按钮
<Button type="submit" variant="primary">
保存
</Button>
// 次要操作
<Button type="button" variant="secondary" onClick={onPreview}>
预览
</Button>
// 低强调文字操作
<Button type="button" variant="ghost" onClick={onCancel}>
取消
</Button>
// 图标 + 文字,仍然使用 Button
<Button
leadingIcon={<PlusIcon aria-hidden="true" />}
type="button"
variant="primary"
>
新建内容
</Button>
// 纯图标:圆形按钮
<IconButton aria-label="更多操作" tooltip="更多操作" type="button">
<MoreIcon aria-hidden="true" />
</IconButton>
// 危险操作
<Button type="button" variant="danger" onClick={openDeleteConfirm}>
删除项目
</Button>12. قائمة مراجعة المراجعة
قبل إرسال واجهة المستخدم المتعلقة بالأزرار، تأكد من:
- هل تم إعطاء الأولوية لإعادة استخدام
ButtonأوIconButton؟ - هل تم اختيار المكوّن الصحيح للأزرار مع النص والأيقونات فقط؟
- هل يوجد
primaryواضح واحد فقط في منطقة المهمة الحالية؟ - هل يتم استخدام
secondaryوghostوdangerحسب الدلالة وليس تفضيل اللون؟ - هل يحافظ
Buttonفي المنصة علىpillالافتراضي، وهل يبقىIconButtonدائريًا؟ - هل لا يزال كل Tooltip طبقة معلومات باستدارة مدمجة، وليس مثل زر بيضاوي قابل للنقر؟
- هل تم إزالة
titleالأصلي للمتصفح وفقاعاتdata-tooltipلـ CSS والتلميحات المكررة و Tooltips المرادفة لأزرار النص؟ - هل تستخدم الأحجام فقط
smوmdوlg، وهل الارتفاع وحجم الخط متسقان في نفس المجموعة؟ - هل تم ضبط
typeالصحيح صراحةً للأزرار الأصلية؟ - هل تخفي الأيقونات معلومات القراءة المكررة، وهل يحتوي
IconButtonعلىaria-labelمترجم محليًا؟ - هل حالات focus-visible و disabled وغير المتزامنة وتأكيد الخطر مكتملة؟
- هل يتعامل CSS المسار مع التخطيط فقط دون تجاوز المظهر الأساسي للزر؟
- هل تم التحقق من النصوص الطويلة وأحجام اللمس وترتيب مجموعة الأزرار على عرض سطح المكتب والأجهزة المحمولة؟
13. مصدر التنفيذ
- API المكوّن:
packages/components/src/ui/Button/Button.tsx - تصدير المكوّن:
packages/components/src/ui/Button/index.ts - رموز الحجم واللون:
packages/components/src/styles/foundations.css - أنماط الأزرار المشتركة:
packages/components/src/styles/primitives.css - عقد الوصول للمكوّنات العامة:
docs/public/design/component-integration.md
عند وجود اختلاف بين الوثيقة والتنفيذ، يجب مزامنة المكوّن والرموز والأنماط وهذه الوثيقة في نفس التغيير.