Skip to Content
التصميم

زر 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 دائريًا.

ترتيب الاختيار:

  1. حدد الخطوة التالية الأكثر أهمية حاليًا واجعلها primary.
  2. استخدم secondary للإجراءات المساعدة التي لا تزال بحاجة إلى وضوح.
  3. استخدم ghost لإجراءات منخفضة التأكيد في شريط الأدوات أو السياق.
  4. استخدم danger فقط للإجراءات التدميرية الفعلية، مع الحفاظ على سير التأكيد الحالي.

لا تختر variant بناءً على "أي الألوان أجمل".

4. الحجم size

Sizeالارتفاع/القطرحجم الخطالسيناريو الموصى به
sm40px14pxشريط التنقل العلوي، أشرطة الأدوات المدمجة، مناطق العمل الكثيفة
md44px15pxالنماذج الافتراضية و CMS ومربعات الحوار والإجراءات العادية
lg48px16pxCTA الرئيسي في صفحات التسويق، الإجراءات الرئيسية التي تحتاج لمس أفضل

الحجم الافتراضي هو 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 والحالة المستمرة في قاعدة زرقاء فاتحة واحدة.
  • يجب أن تكون أسماء الأزرار مباشرة ومحددة وتوضح ما سيحدث، مثل "حفظ" أو "نشر الموقع" أو "حذف العنصر".
  • يجب أن يوفر IconButton aria-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:

الخاصيةالقيمة الافتراضيةالوصف
variantprimaryالطبقة الدلالية والبصرية
sizemdالارتفاع وحجم الخط والحشو الأفقي
shapepillشكل الاستدارة لـ Button
leadingIconلا يوجدأيقونة قبل النص
trailingIconلا يوجدأيقونة بعد النص
hrefلا يوجدتُعرض كرابط عند التوفير
disabledfalseتعطيل التفاعل
tooltipلا يوجدمحتوى تكميلي لـ Tooltip المشترك؛ لا يمكن أن يحل محل المعلومات المرئية المهمة أو aria-label
tooltipPlacementbottomالاتجاه المفضل؛ يمكن لـ Tooltip المشترك الانعكاس للبقاء داخل إطار العرض
tooltipPortaltrueالعرض خارج حاوية القطع دون إضافة طبقة تخطيط مغلفة
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

عند وجود اختلاف بين الوثيقة والتنفيذ، يجب مزامنة المكوّن والرموز والأنماط وهذه الوثيقة في نفس التغيير.

في هذه الصفحة