شريط التقدم Progress

يُستخدم LhProgress لعرض تقدّم مهمة أو سعة، بشكليه الخطي والدائري، مع إمكانية تخصيص اللون والنص.

الاستخدام الأساسي

شريط تقدم خطي

60%

<script setup lang="ts">
</script>

<template>
  <LhProgress :percentage="60" />
</template>

<script>
export default {}
</script>

<template>
  <LhProgress :percentage="60" />
</template>

الحالة

normal / success / warning / exception، بلوغ 100 يحوّلها تلقائيًا إلى success

100%

80%

40%

<script setup lang="ts">
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <LhProgress :percentage="100" />
    <LhProgress :percentage="80" status="warning" />
    <LhProgress :percentage="40" status="exception" />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <LhProgress :percentage="100" />
    <LhProgress :percentage="80" status="warning" />
    <LhProgress :percentage="40" status="exception" />
  </div>
</template>

لون ونص مخصّصان

color يقبل سلسلة أو دالة، وformat يخصّص النص

55%

70 نقطة

<script setup lang="ts">
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <LhProgress :percentage="55" color="#B8860B" />
    <LhProgress
      :percentage="70"
      :color="(p: number) => `hsl(${p * 1.2}, 60%, 45%)`"
      :format="(p: number) => `${p} نقطة`"
    />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <LhProgress :percentage="55" color="#B8860B" />
    <LhProgress
      :percentage="70"
      :color="(p: number) => `hsl(${p * 1.2}, 60%, 45%)`"
      :format="(p: number) => `${p} نقطة`"
    />
  </div>
</template>

تقدّم دائري

تعيين type إلى circle

75%

100%

<script setup lang="ts">
</script>

<template>
  <div style="display: flex; align-items: center; gap: 24px">
    <LhProgress type="circle" :percentage="75" />
    <LhProgress type="circle" :percentage="100" :width="100" :stroke-width="8" />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; align-items: center; gap: 24px">
    <LhProgress type="circle" :percentage="75" />
    <LhProgress type="circle" :percentage="100" :width="100" :stroke-width="8" />
  </div>
</template>

إخفاء النص

تعيين showText إلى false

<script setup lang="ts">
</script>

<template>
  <LhProgress :percentage="45" :show-text="false" />
</template>

<script>
export default {}
</script>

<template>
  <LhProgress :percentage="45" :show-text="false" />
</template>

API

Props

الخاصية	الوصف	النوع	الافتراضي
percentage	نسبة التقدّم، يُطبَّق عليها clamp تلقائيًا إذا تجاوزت [0, 100]	number	0
type	الشكل	"line" | "circle"	'line'
status	الحالة، عند normal تتحول تلقائيًا إلى success عند بلوغ 100	"normal" | "success" | "warning" | "exception"	'normal'
color	لون شريط التقدّم: سلسلة أو دالة تُرجع لونًا حسب النسبة	string | ((percentage: number) => string)	—
strokeWidth	عرض الخط بالبكسل (ارتفاع في line، عرض حد في circle)	number	6
width	عرض لوحة الرسم في الوضع الدائري بالبكسل	number	126
showText	إظهار النص	boolean	true
format	تنسيق النص مخصص	(percentage: number) => string	—
sx	خصائص التخطيط السريع sx	LhSxProps	—

Slots

اسم الفتحة	الوصف	النطاق
text	محتوى النص المخصص	{ percentage }

إمكانية الوصول

• العنصر الجذري يحمل role="progressbar" مع aria-valuemin / aria-valuemax / aria-valuenow، موافقًا لنمط progressbar في WAI-ARIA
• يُزامِن aria-valuetext النص الظاهر: افتراضيًا النسبة المئوية، وعند تمرير format يُذاع النص المنسَّق (مثل «42 نقطة»)
• القيمة بعد القطع تُزامَن إلى aria-valuenow، فلن يحدث إذاع يتجاوز النطاق

تعريفات الأنواع

بنى TypeScript التي يصدّرها هذا المكوّن للخارج (مستخرجة تلقائيًا من packages/components/progress/src/types.ts و@lh-ui/share/core/*؛ انقر كل عنصر لتوسيع تعريفه الكامل؛ لأوصاف الخصائص انظر جدول Props أعلاه):

LhProgressProps

export interface LhProgressProps {
  /** نسبة التقدّم 0-100 (تُقطع تلقائيًا عند التجاوز) */
  percentage: number
  type?: LhProgressType
  status?: LhProgressStatus
  /** لون شريط التقدّم: سلسلة أو دالة تُرجع لونًا حسب النسبة */
  color?: string | ((percentage: number) => string)
  /** عرض الخط بالبكسل (ارتفاع في line، عرض حد في circle) */
  strokeWidth?: number
  /** عرض لوحة الرسم في الوضع الدائري بالبكسل */
  width?: number
  showText?: boolean
  /** تنسيق النص مخصص */
  format?: (percentage: number) => string
  /** خصائص التخطيط السريع sx */
  sx?: LhSxProps
}

LhProgressType _{(مأخوذ من @lh-ui/share/core/progress)}

export type LhProgressType = 'line' | 'circle'

LhProgressStatus _{(مأخوذ من @lh-ui/share/core/progress)}

export type LhProgressStatus = 'normal' | 'success' | 'warning' | 'exception'