نظرة عامة
يكشفProgress عن أجزاء Base UI المثبتة: Root وTrack وIndicator وLabel وValue. استوردها من twenty-ui/primitives/feedback. استخدم شريط التقدم أو حلقة التقدم للحصول على مظهر ملائم مع العقد الدلالي نفسه.
استخدام
يمتلكRoot القيمة المتحكَّم بها ودلالات شريط التقدم المتاح. يوفر Label اسمه المتاح. يعرض Value القيمة المنسقة. يصف Track وIndicator التعبئة المرئية؛ ويأتي عرض المؤشر من النطاق المطبع للجذر. لا تفرض الأجزاء مظهرًا.
50% بينما تكون قيمة aria-valuenow هي 70، وقيمة aria-valuemin هي 20، وقيمة aria-valuemax هي 120. يمتلك التطبيق الطلبات والتوقيت وتحديثات التقدم. لا توجد defaultValue ولا زيادة تلقائية.
القيم والنطاقات والتقدم غير المحدد
القيمة الافتراضية لـmin هي 0، والقيمة الافتراضية لـ max هي 100. وفّر حدودًا منتهية باستخدام min \< max. تُقيَّد القيم المنتهية خارج النطاق للقيمة الدلالية والقيمة المنسقة والتعبئة المرئية. يكتمل التقدم عند القيمة القصوى. يؤدي تغيير النطاق إلى إعادة حساب النسبة المئوية دون تغيير القيمة الأولية التي يوفرها التطبيق.
مرّر value={null} عندما يكون مقدار التقدم غير معروف. يكون للجذر عندئذٍ حالة غير محددة، ويُغفل aria-valuenow، ويستخدم indeterminate progress كنص قيمة متاح افتراضيًا. تظل القيم غير المنتهية غير محددة أيضًا؛ ولا تُحوَّل إلى صفر. لا يحتوي Indicator الأولي على عرض نسبة مئوية محسوب في تلك الحالة، لذا يختار التركيب مظهره غير المحدد.
التسميات والتنسيق
أنشئProgress.Label داخل Root، أو عيّن aria-label أو aria-labelledby الأصليين. استخدم aria-valuetext لبديل قابل للقراءة البشرية عندما لا تكون النسبة المئوية كافية.
يعرض المنسق الافتراضي النسبة المئوية المطبعة. يحتفظ locale وformat بعقد Intl.NumberFormat المثبت؛ ويقوم format الصريح بتنسيق القيمة الرقمية المقيّدة. تتلقى getAriaValueText(formattedValue, value) ذلك النص المنسق وقيمة التطبيق الأولية، بما في ذلك null. يغيّر نص القيمة المتاح دون تغيير التعبئة.
Progress.Value كلًا من القيمة المنسقة والقيمة الأولية من خلال رد نداء الطفل الاختياري الخاص به. بالنسبة إلى التقدم غير المحدد، يتلقى رد النداء indeterminate كنص منسق؛ وبدون رد نداء، لا يعرض جزء القيمة أي محتوى. لا يصبح محتوى العرض تلقائيًا الاسم المتاح أو نص القيمة المتاح.
الخصائص الأصلية والمراجع والتركيب
يحافظ كل جزء على الخصائص الأصلية والمراجع وعقد تركيب
render المثبت. مرّر الخصائص والمرجع المزوَّدين عند استبدال عنصر. تتلقى ردود النداء className وstyle وrender الحالة العامة مع status: progressing أو complete أو indeterminate. تجعل سمات الحالة الحالة نفسها متاحة للأنماط.
تصدّر نقطة الإدخال ProgressStatus وأنواع Props وState لكل جزء، بما في ذلك ProgressRootProps وProgressRootState وProgressIndicatorProps وProgressIndicatorState. يمرر كل جزء معالجات الأحداث الأصلية. تمتلك التطبيقات تنسيق الميزات وردود نداء الإكمال.
الخصائص
Progress.Root
string
Accessible name identifying the measured operation.
string
ID of the visible label that names the operation.
string
Human-readable progress value overriding the default formatted value.
ReactNode
Composed Progress parts and supporting content.
string | ((state: ProgressRootState) => string | undefined)
Class applied to this part, or a callback receiving its progress status.
NumberFormatOptions
Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage.
((formattedValue: string, value: number | null) => string)
Receives the formatted value and raw value, including null, and returns an accessible value description.
LocalesArgument
Locale or locale list used to format the value. Defaults to the runtime locale.
number
افتراضي:"100"
Inclusive maximum. Defaults to 100.
number
افتراضي:"0"
Inclusive minimum. Defaults to 0.
Ref<HTMLDivElement>
Ref to the root div, or the element composed through Root.render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its progress status.
number | null
مطلوب
Controlled value in the min/max range. Use null for indeterminate progress.
Progress.Track
ReactNode
The indicator and optional supporting content.
string | ((state: ProgressTrackState) => string | undefined)
Class applied to this part, or a callback receiving its progress status.
Ref<HTMLDivElement>
Ref to the track div, or the element composed through Track.render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressTrackState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: ProgressTrackState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its progress status.
Progress.Indicator
string | ((state: ProgressIndicatorState) => string | undefined)
Class applied to this part, or a callback receiving its progress status.
Ref<HTMLDivElement>
Ref to the indicator div, or the element composed through Indicator.render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressIndicatorState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: ProgressIndicatorState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its progress status.
Progress.Value
((formattedValue: string | null, value: number | null) => ReactNode) | null
Optional callback receiving the formatted value and raw value. Indeterminate progress passes indeterminate as formatted text. Without a callback, indeterminate progress displays no content.
string | ((state: ProgressValueState) => string | undefined)
Class applied to this part, or a callback receiving its progress status.
Ref<HTMLSpanElement>
Ref to the value span, or the element composed through Value.render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressValueState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: ProgressValueState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its progress status.
Progress.Label
ReactNode
Visible text that supplies the accessible name of the root.
string | ((state: ProgressLabelState) => string | undefined)
Class applied to this part, or a callback receiving its progress status.
Ref<HTMLSpanElement>
Ref to the label span, or the element composed through Label.render.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressLabelState>
Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
CSSProperties | ((state: ProgressLabelState) => CSSProperties | undefined)
Inline styles applied to this part, or a callback receiving its progress status.