إنشاء شريط تقدُّم منسَّق

ميزات الويب: accent-color <progress> revert-rule طلبات البحث عن الحاويات (الحجم) خصائص التحويل الفردية

العنصر <progress> هو الطريقة الدلالية لتمثيل مستوى تقدّم إكمال مهمة، مثل تنزيل المعلومات أو تحميلها أو إكمال جزء من عملية متعدّدة الخطوات. يساعد استخدام العنصر الأصلي في تسهيل الاستخدام، لأنّ برامج قراءة الشاشة تحتوي على سمة role="progressbar" ضمنية ويمكنها الإعلان عن القيم.

يستخدم هذا الدليل شريط تقدّم أفقيًا منسَّقًا بالكامل مع تخصيصات الأنماط.

شريط التقدّم أم حلقة التقدّم؟

  • إذا كانت المساحة محدودة أو كانت نسبة العرض إلى الارتفاع المربّعة مفضّلة، ننصحك باستخدام شريط تقدّم دائري (حلقة التقدّم): حلقة التقدّم
  • يُفضَّل استخدام مؤشرات سريان العمل في معظم سيناريوهات تقدّم العمل غير المحدّد (مؤشر سريان عملية التحميل). استخدِم أشرطة التقدّم غير المحدّدة عندما تكون الحالة غير المحدّدة مؤقتة وسيتم استبدالها قريبًا بشريط تقدّم محدّد (على سبيل المثال، انتظار البيانات الوصفية حول عملية تحميل قبل عرض نسبة مئوية للتقدّم)

Markup

  1. استخدام عنصر <progress> أصلي: يوفّر هذا العنصر ميزات تسهيل الاستخدام المضمّنة وسلوكًا متسقًا مع المنصة.
  2. استخدِم السمة max إذا كنت بحاجة إلى مقياس مختلف عن المقياس التلقائي من 0 إلى 1.
  3. للحصول على قيمة تقدّم محدّدة، اضبط سمة value. يمكنك حذف value في حال كانت الحالة غير محدّدة (على سبيل المثال، قبل بدء تقديم ملاحظات أكثر تحديدًا).
  4. استخدِم <label for="..."> أو aria-labelledby أو aria-label لربط عنصر مستوى التقدّم بتصنيف.

ما هو نوع التخصيص المطلوب؟

لإجراء تنسيق محدود، تكفي السمات التالية:

  • ‫accent-color لتغيير لون شريط التقدم
  • ‫width / inline-size لتغيير عرض شريط التقدم
  • يتم تطبيق height/block-size بشكل غير متسق، لذا يُرجى إجراء اختبار أولاً
  • ‫writing-mode: vertical-lr للأشرطة العمودية
  • التأثيرات التي يتم تطبيقها بعد الرسم: opacity وfilter وclip-path والأقنعة وعمليات التحويل وbox-shadow وما إلى ذلك

إذا كان التنسيق المحدود كافيًا، يمكنك تخطّي القسم التالي.

تحذير: ستؤدي بعض السمات (مثل border-radius وbackground وborder) إلى إيقاف نمط شريط التقدم التلقائي بدون إشعار. إذا كنت بحاجة إلى تصميم يتجاوز السمات المذكورة أعلاه، عليك تنفيذ تصميم مخصّص بالكامل كما هو موضّح في القسم التالي. لا تطبِّق أنماطًا أكثر شمولاً "على أمل أن تنجح".

أنماط مخصّصة بالكامل

1. الإعداد الأساسي

  • ملاحظة إلزامية: يجب استخدام appearance: none لتفعيل الأنماط المخصّصة.
  • إعادة ضبط حدود أوكرانيا باستخدام border: 0 solid
  • لاقتصاص الشريط النشط وفقًا لسمة border-radius للعنصر، استخدِم overflow: clip أو طبِّق سمة border-radius نفسها على الشريط. لا تستخدِم border-radius: inherit على الشريط، لأنّ ذلك يعتمد على البنية المحدّدة للعناصر في shadow DOM.
progress {
  /* Reset default browser styles */
  appearance: none;
  border: 0 solid;
  /* Clip bar to element’s border-radius  */
  overflow: clip;
}

2. التصميم

  • يمكنك تصميم المسار على عنصر progress نفسه.
  • استخدِم العنصر الزائف المناسب الذي يستهدفه المتصفّح لاستهداف شريط التقدّم نفسه: ::-webkit-progress-value لـ WebKit/Blink و::-moz-progress-bar لـ Firefox.
  • MANDATORY: Do NOT group -webkit- and -moz- pseudo-elements in the same rule. سيتم اعتبار القاعدة غير صالحة وسيتم تجاهلها. لا يمكن استخدام :is() و:where() هنا، لأنّهما لا يتيحان استخدام العناصر الزائفة.
  • يجب أن يظهر كل عنصر زائف يستهدف المتصفّح مرة واحدة بالضبط. يجب توجيه عمليات التخصيص الخاصة بالحالة (مثل حجم المقطع غير المحدّد والحركة) من خلال السمات المخصّصة التي تم ضبطها على العنصر progress نفسه.
  • اختياري: يمكنك ضبط انتقال inline-size على التعبئة بحيث يتم تحريك تغييرات القيمة المحدّدة بدلاً من الانتقال السريع. يحدّد Firefox حجم التعبئة في التنسيق ويتجاهلها، وهو أمر غير ضار.
progress {
  --progress-bar-radius: 1e5px;
  border-radius: var(--progress-bar-radius);
  /* Apply color for custom progress track (background) */
  background: var(--progress-bar-track, var(--color-neutral-90));
  /* Subtle depth on the empty part of the track */
  box-shadow: inset 0 1px 2px rgb(0 0 0 / 0.1);
}

/* Let <progress> styling show through */
progress::-webkit-progress-bar {
  background: transparent;
}

/* Webkit, Chrome */
progress::-webkit-progress-value {
  background: var(--progress-bar-fill, var(--accent-color));
  border-radius: var(--progress-bar-radius);
  transition: inline-size 0.3s;
}

/* Firefox */
progress::-moz-progress-bar {
  background: var(--progress-bar-fill, var(--accent-color));
  border-radius: var(--progress-bar-radius);
  transition: inline-size 0.3s;
}

3- نمط الحالة غير المحدّدة

إضافة حركة مخصّصة للحالة غير المحدّدة: يمكنك تحويل العنصر الزائف للتعبئة إلى مقطع قصير وتحريكه على طول المسار.

  • Style the fill itself; do NOT recreate it as a background on progress.
  • لا يتوفّر الملء غير المحدّد إلا من خلال الصورة المتحركة: تحدّد الإطارات الرئيسية طوله باستخدام inline-size حقيقي (يتفوّق على inline-size المضمّن في UA في Chromium) وتحرّكه باستخدام translate. لا تستخدِم scale للطول، لأنّ ذلك يشوّه أي نمط مرسوم على التعبئة.
  • يتم حلّ نِسَب translate مقابل عرض التعبئة، لذا يجب التعبير عن المواضع بوحدات المسار بدلاً من ذلك: اجعل progress حاوية بحجم مضمّن واستخدِم cqi في الإطارات الرئيسية. يجب تضمين margin-right: auto في from, to لكي يضع Chromium الملء في الجزء الأيمن الفعلي في اللغات التي تُكتب من اليمين إلى اليسار أيضًا.
  • استخدِم عمليات التحويل، وليس الهوامش، لنقل التعبئة.
    • تحافظ عمليات التحويل على الصورة المتحركة في أداة التركيب (ما لم يتم أيضًا تحريك inline-size)
    • تتعطّل الهوامش في اللغات التي تُكتب من اليمين إلى اليسار لسببَين منفصلَين:
    • يضع Firefox التعبئة غير المحددة باستخدام الهامش الأيسر الفعلي فقط، لذا ليس لـ margin-inline-start أي تأثير في RTL ولا تتحرك التعبئة أبدًا.
    • في Chromium وWebKit، اللذين يضعان التعبئة ككتلة عادية، بمجرد أن يدفع الهامش التعبئة بعد نهاية المسار، تضاف الهوامش إلى أكثر من المسار. يحلّ CSS العادي هذه المشكلة من خلال تجاهل margin-left في اللغات التي تُكتب من اليمين إلى اليسار، وبالتالي ينتقل الجزء إلى الحافة بدلاً من الانزلاق منها.
    • يتم تطبيق translate بعد التنسيق، لذا لا تنطبق أي من المشكلتين.
  • لعكس الحركة في اللغات التي تُكتب من اليمين إلى اليسار (كما يفعل شريط Chrome الأصلي)، اعكس الحركة ضمن :dir(rtl):
progress:dir(rtl) {
  --progress-bar-indeterminate-animation: progress-bar-indeterminate var(--progress-bar-indeterminate-animation-duration) infinite linear reverse;
}
  • حدِّد سمات --progress-bar-indeterminate-* العامة في progress (يحدّد اسمها نطاقها في الحالة) ليتمكّن المستهلكون من إلغائها بدون معرفة :indeterminate.
  • لتغيير طول الجزء (على سبيل المثال، يتقدّم الطرف الأمامي ويتجاوز الطرف الخلفي)، اضبط --progress-bar-indeterminate-animation على حركتَين متزامنتَين: حركة تحرّك إطاراتها الرئيسية translate في cqi (الموضع) وحركة تحرّك إطاراتها الرئيسية inline-size (الطول)، بحيث يحصل كل منهما على إطاراته الرئيسية وتأثيره السلس. لا تحاول تشكيل كلا الحافتَين في قائمة إطارات رئيسية واحدة، لأنّ السمة animation-timing-function لكل إطار رئيسي تنطبق على كل سمة في هذا الإطار الرئيسي.
  • ينطبق --progress-bar-animation في كلتا الحالتَين ويمكن استخدامه لتأثيرات مثل اللمعان المحدّد. تُستخدَم السمة revert-rule للتجاوز فقط عند ضبطها، وذلك لزيادة إمكانية التركيب إلى أقصى حد.
  • لا توقف أبدًا الصورة المتحركة غير المحددة (يترك animation: none تعبئة بعرض صفر في Chromium). لتقليل الحركة، يمكنك إبطاؤها بدلاً من ذلك.
progress {
  /* Lets the fill position itself in track units (cqi) */
  container-type: inline-size;
  /* Segment length relative to the track */
  --progress-bar-indeterminate-size: 30%;
  --progress-bar-indeterminate-animation-duration: 1.5s;

  /* Respect prefers-reduced-motion */
  @media (prefers-reduced-motion: reduce) {
    --progress-bar-indeterminate-animation-duration: 10s;
  }
}

progress:indeterminate {
  --progress-bar-animation: var(
      --progress-bar-indeterminate-animation,
      progress-bar-indeterminate var(--progress-bar-indeterminate-animation-duration) infinite linear
    );
}

/* Add to the existing pseudo-element rules */
progress::-webkit-progress-value {
  animation: var(--progress-bar-animation, revert-rule);
}

progress::-moz-progress-bar {
  animation: var(--progress-bar-animation, revert-rule);
}

/* Physical: left to right regardless of direction (reverse under :dir(rtl) to mirror). */
@keyframes progress-bar-indeterminate {
  from, to {
    inline-size: var(--progress-bar-indeterminate-size);
    /* Pin to the physical left; Chromium would otherwise lay the fill out at the inline start */
    margin-right: auto;
  }
  from { translate: -100%; } /* Own width: fully outside the left edge */
  to { translate: 100cqi; }  /* Track width: fully outside the right edge */
}

اعتبارات إضافية لتسهيل الاستخدام

بالإضافة إلى الإرشادات المذكورة أعلاه:

  • الإعلان عن اكتمال العملية بدون سرقة التركيز: لا تضبط tabindex أو تستدعي .focus() على <progress>، لأنّه غير تفاعلي ونقل التركيز إليه يؤدي إلى تشتيت مستخدمي لوحة المفاتيح. للإعلان عن انتهاء مهمة في الخلفية، عدِّل عنصر الحالة polite (role="status" أو aria-live="polite").
  • لا تضِف نصًا احتياطيًا داخل <progress>: تتجاهل المتصفحات الحديثة النص داخل <progress> ولا تستخدمه التكنولوجيات المساعِدة.
  • تجنَّب استخدام aria-busy + aria-describedby على <div> عام بدون تصنيف. لا يتوافق aria-busy مع قارئ الشاشة بشكل متسق، ويتم تجاهل aria-describedby في <div> غير مسمّى بدون دور من خلال التكنولوجيا المساعِدة. إذا لم يكن محتوى منطقة معيّنة جاهزًا أثناء التحميل، يمكنك إخفاؤه باستخدام hidden أو aria-hidden="true".
  • يجب التأكّد من وجود تباين مناسب بين شريط التقدّم والمسار عند إضافة أنماط مخصّصة.
  • البحث عن بدائل لتمثيل الحالة غير المحدّدة: قد تشتّت انتباه بعض المستخدمين الصور المتحركة لشريط التقدم غير المحدّد التي يتم عرضها بالتوازي مع محتوى آخر.

استراتيجيات احتياطية

الخيارات الاحتياطية وتوافق المتصفّح مع السمة accent-color

سمة accent-color هي تحسين تدريجي. وستتجاهل المتصفّحات التي لا تتوافق مع هذه السمة هذه السمة وتستخدم ألوان واجهة المستخدم التلقائية.

إذا لم يكن accent-color متاحًا وكان من الضروري تصميم شريط التقدّم، استخدِم طريقة النمط المخصّص لتطبيق التصميم المفضّل على شريط التقدّم.

الخيارات الاحتياطية وتوافق المتصفّح مع revert-rule

إذا لم يكن revert-rule متاحًا، يعود animation: var(--progress-bar-animation, revert-rule) إلى animation-name: revert-rule بمدة 0s عندما لا يتم ضبط --progress-bar-animation، وهي عملية غير ضارة ولا تؤدي إلى أي إجراء في حال عدم توفّر @keyframes revert-rule.