العدّاد

نظرة عامة

link

Web

tanrei-meter

clock_loader_40

SwiftUI

TanreiMeter

radio_button_unchecked

Jetpack Compose

TanreiMeter

radio_button_unchecked

Flutter

TanreiMeter

radio_button_unchecked

React Native

Meter

radio_button_unchecked

مولَّد من docs/status/status.json, specs/meter.spec.json

خطي ودائري

الاستخدام

link

عيّنتا Web و React تعرضان المواصفة الحالية. أما SwiftUI و Compose و Flutter و React Native فمخطَّط لها: لا تقدّم عدّادًا بعد.

<tanrei-meter value="0.62" label="مساحة التخزين المستخدمة" value-text="9.3 غيغابايت من 15 غيغابايت"></tanrei-meter>
<tanrei-meter value="37" max="50" label="المقاعد المحجوزة" value-text="37 من 50 مقعدًا"></tanrei-meter>

<!-- المنتج يقرر ما تعنيه القيمة، ويقوله بالكلمات أيضًا. -->
<tanrei-meter value="0.85" status="warning" label="مساحة التخزين المستخدمة" value-text="ممتلئة تقريبًا: 12.8 غيغابايت من 15 غيغابايت"></tanrei-meter>

<tanrei-meter variant="circular" size="small" value="0.62" label="البطارية"></tanrei-meter>

<script type="module">
  import '@tanrei/web/components/meter';
  const meter = document.querySelector('tanrei-meter');
  meter.value = used / quota;
  meter.status = used / quota > 0.8 ? 'warning' : 'default';
</script>

import { Meter } from '@tanrei/react';

<Meter value={used / quota} label="مساحة التخزين المستخدمة" valueText={`${usedText} من ${quotaText}`} />
<Meter value={seats} max={50} label="المقاعد المحجوزة" valueText={`${seats} من 50 مقعدًا`} />
<Meter
  value={used / quota}
  status={used / quota > 0.8 ? 'warning' : 'default'}
  label="مساحة التخزين المستخدمة"
  valueText={used / quota > 0.8 ? `ممتلئة تقريبًا: ${usedText} من ${quotaText}` : `${usedText} من ${quotaText}`}
/>
<Meter variant="circular" size="small" value={charge} label="البطارية" />

المواصفات

link

الحالات: default و info و success و warning و error

الأحجام، وطرفا المدى، ومدى مخصَّص

الفصل: divider (اختيار النظام الافتراضي) و gap

البنية

البنية

مرسوم فوق نموذج الاختبار linear كما ترسمه حزمة الويب.

الجزء	الوصف
1 track	The full length of the bar, or the full circle of the ring: the whole range from min to max.
2 indicator	The part of the track drawn in the indicator color of the meter's status: the fraction of the range up to the value. It meets the rest of the track, or stands a gap from it (separation).
3 stop-indicator · اختياري	A dot at the end of a bar's track that marks where the range ends, drawn whenever its size is above 0.

الخصائص

الخاصية	النوع	القيمة الافتراضية	الوصف
variant	linear | circular	"linear"	Linear is a bar that fills the width its layout gives it; circular is a ring of a fixed size, for tight places and beside text. A structural choice drawn by code, not a token axis, as the progress indicator's is.
size	small | medium | large	"medium"	The bar's thickness or the ring's box, the progress indicator's three sizes by default (2 / 4 / 8 and 16 / 24 / 40). A design system may add values.
separation	auto | divider | gap	"auto"	How the indicator is told from the rest of its track. divider: drawn on the track with no space between them. gap: empty space between them. Auto takes comp.meter.track.separation, which follows the design system's choice.
value	number	0	Where the measured quantity stands, between min and max. Always a number: a meter has no unknown value, and a task under way is a progress indicator.
min	number	0	The low end of the range.
max	number	1	The high end of the range.
status	default | info | success | warning | error	"default"	What the product says the value means, in the names the tag and the snackbar use: default draws the indicator in the meter's own color; info, success, warning and error in that status's color. The product decides it — the meter has no thresholds of its own — and it changes colors only: the words that say so are valueText's and the product's.
label	string	""	The accessible name: what is measured ("Storage used"). Required: a bar alone is not a name.
valueText	string	""	How assistive technology reads the value when a percentage is not the natural reading ("12.4 GB of 15 GB", "Strong"). Empty reads the platform's percentage. Where status means something, say it here too ("Almost full: 14.2 GB of 15 GB").

الحالات

السلوك

متطلبات بصيغة EARS. يُختبر تنفيذ كل منصة مقابل هذه المعرّفات. يُعرض نص المتطلبات كما ورد في ملف المواصفة، بالإنجليزية.

المعرّف	المتطلب
MTR-1	THE meter SHALL draw the indicator over the fraction (value − min) / (max − min) of the track, from the track's start: the inline-start of a bar, the top of a ring, turning clockwise.
MTR-2	THE meter SHALL draw a bar comp.meter.linear.thickness.medium high for medium (and so on for each size) across the full inline size its layout gives it, and a ring whose outer edge fills a comp.meter.circular.size.medium square with a stroke of comp.meter.circular.thickness.medium for medium (and so on for each size).
MTR-3	THE meter SHALL draw the track in comp.meter.track.color and the indicator over it in the indicator color of its status — comp.meter.indicator.color WHILE status is default, comp.meter.info.indicator.color WHILE it is info, comp.meter.success.indicator.color WHILE it is success, comp.meter.warning.indicator.color WHILE it is warning and comp.meter.error.indicator.color WHILE it is error; the ends of a bar's track and indicator SHALL be rounded by comp.meter.track.shape, clamped to half the thickness, and a ring's arcs SHALL have round caps unless comp.meter.track.shape is sys.shape.corner.none.
MTR-4	THE meter SHALL tell the indicator from the rest of its track as its separation names — WHILE separation is auto, as comp.meter.track.separation names; WHILE it is divider or gap, as that value names — and WHILE the separation is gap and value lies strictly between min and max SHALL leave comp.meter.track.gap of empty space, measured along the track, between the indicator and the rest of the track (on a ring, at both ends of the indicator's arc); WHILE it is divider THE meter SHALL draw the indicator on the track with nothing between them.
MTR-5	WHILE comp.meter.stop-indicator.size is above 0 THE meter SHALL draw at the end of a bar's track a round dot of that size, centred across the track, in the indicator color of its status; a ring SHALL draw none.
MTR-6	WHEN value, min, max or status changes after the first frame THE meter SHALL move the indicator's end to the new fraction over comp.meter.motion.value-duration with comp.meter.motion.value-easing, and change the indicator's color over the same duration; WHEN it changes again during that motion THE meter SHALL go on from the place and the color then shown. THE meter SHALL draw its first frame at its value and in its status's color without a motion, and WHERE reduced motion is requested SHALL move the end at once and keep the change of color as a fade over the same duration.
MTR-7	THE meter SHALL expose to assistive technology a meter — the platform's own meter where it has one, and otherwise an element with a value range and no busy state — named by label, with min and max as its range, the clamped value as its current value, and valueText as the value's text WHILE valueText is not empty; it SHALL NOT expose the progressbar role or a busy state, because nothing is under way.
MTR-8	THE meter SHALL NOT be focusable, SHALL take no input and SHALL NOT announce a change of its value or its status by itself; assistive technology SHALL read the current value when it reaches the meter.
MTR-9	THE meter SHALL expose nothing of status by itself: status SHALL change the indicator's color and nothing else, so that what the color means reaches every person only through the words the product gives in valueText, label or the text beside the meter.
MTR-10	IF value is below min or above max THE meter SHALL draw and expose it clamped to that range; IF value is not a finite number THE meter SHALL draw and expose min; IF max is not greater than min THE meter SHALL draw the track with no indicator and expose a current value of 0 in a range of 0 to 1; in each case debug builds SHALL report the values.
MTR-11	WHEN size names a value that the active design system does not have, or variant, separation or status a value the meter does not define, THE meter SHALL render with the default value's tokens (medium, linear, auto, default), and in debug builds report the unknown value.
MTR-12	WHERE the layout direction is right-to-left THE meter SHALL fill a bar from the right and draw its stop indicator at the left; a ring SHALL NOT be mirrored: it starts at the top and turns clockwise in every direction, as a clock does.
MTR-13	THE meter SHALL take its layout direction from where it is used and SHALL have no direction setting of its own; WHEN that direction changes while the meter is shown THE meter SHALL draw itself for the new direction at once, without a motion of its own, keeping its value.
MTR-14	WHILE label is empty THE meter SHALL still render, and in debug builds report that it has no accessible name.
MTR-15	WHERE the platform draws with a person's own forced colors THE meter SHALL draw its track as an edge sys.border.hairline wide in the platform's text color and its indicator filled in the platform's text color, whatever its status, so that the value is still read from where the indicator ends.
MTR-16	WHERE the platform has ARIA attributes (the web), the host carries its meter role (MTR-7) itself, so what the product writes on it is not moved, but for a name: WHILE label is not empty THE meter SHALL hold the product's aria-label and aria-labelledby on that host as their data-aria- twins, so that label is its whole name although the platform gives aria-labelledby the precedence, and WHEN label is emptied SHALL give them back as they were written; WHILE label is empty a name the product gives so — aria-label, or aria-labelledby naming an element — SHALL be its name and SHALL NOT be reported as having none in debug builds (MTR-14). WHEN the product removes one, or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaLabelledByElements) to null, THE meter SHALL take it away.

مطابقة الأسماء بين المنصات

التكافؤ لا يعني واجهات برمجية متطابقة. تعبّر كل منصة عن العقد نفسه بأسلوبها.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
المكوّن	tanrei-meter	TanreiMeter	TanreiMeter	TanreiMeter	Meter
variant · الخاصية	variant	variant	variant	variant	variant
size · الخاصية	size	size	size	size	size
separation · الخاصية	separation	separation	separation	separation	separation
value · الخاصية	value	value	value	value	value
min · الخاصية	min	bounds.lowerBound	valueRange.start	min	min
max · الخاصية	max	bounds.upperBound	valueRange.endInclusive	max	max
status · الخاصية	status	status	status	status	status
label · الخاصية	label	label	label	label	label
valueText · الخاصية	valueText	valueText	valueText	valueText	valueText
ملاحظات	Drawn as the progress indicator is (the two share the drawing code; the meter never runs the indeterminate animation). The host carries role="meter", aria-valuemin, aria-valuemax, aria-valuenow, aria-label and aria-valuetext while value-text is set. separation and status are attributes; auto reads the name in --tanrei-comp-meter-track-separation.	TanreiMeter("Storage used", value: 9.3, in: 0...15). Exposed as SwiftUI exposes a Gauge: an element with the label and an accessibility value, accessibilityValue(valueText) while it is set; no updates-frequently trait.	Semantics progressBarRangeInfo with the range (Android has no separate meter role) and stateDescription from valueText; never the indeterminate range info.	Semantics(label:, value:) with the value text or the percentage; on the web renderer the role is meter.	accessibilityRole="progressbar" is not used; the view carries accessibilityValue={{ min, max, now, text }} with role="meter" where React Native passes it through (web), and the label.

الرموز

الرمز	يشير إلى	القيمة المحلولة (فاتح)
--tanrei-comp-meter-circular-size-large	comp.progress-indicator.circular.size.large	40px
--tanrei-comp-meter-circular-size-medium	comp.progress-indicator.circular.size.medium	24px
--tanrei-comp-meter-circular-size-small	comp.progress-indicator.circular.size.small	16px
--tanrei-comp-meter-circular-thickness-large	comp.progress-indicator.circular.thickness.large	2px
--tanrei-comp-meter-circular-thickness-medium	comp.progress-indicator.circular.thickness.medium	2px
--tanrei-comp-meter-circular-thickness-small	comp.progress-indicator.circular.thickness.small	2px
--tanrei-comp-meter-error-indicator-color	sys.color.error	#cd262f
--tanrei-comp-meter-indicator-color	comp.progress-indicator.indicator.color	#1b1b1b
--tanrei-comp-meter-info-indicator-color	sys.color.info	#3066cb
--tanrei-comp-meter-linear-thickness-large	comp.progress-indicator.linear.thickness.large	8px
--tanrei-comp-meter-linear-thickness-medium	comp.progress-indicator.linear.thickness.medium	4px
--tanrei-comp-meter-linear-thickness-small	comp.progress-indicator.linear.thickness.small	2px
--tanrei-comp-meter-motion-value-duration	comp.progress-indicator.motion.value-duration	300ms
--tanrei-comp-meter-motion-value-easing	comp.progress-indicator.motion.value-easing	cubic-bezier(0.2, 0, 0, 1)
--tanrei-comp-meter-stop-indicator-size	comp.progress-indicator.stop-indicator.size	0px
--tanrei-comp-meter-success-indicator-color	sys.color.success	#077b32
--tanrei-comp-meter-track-color	comp.progress-indicator.track.color	#eeeeee
--tanrei-comp-meter-track-gap	comp.progress-indicator.track.gap	4px
--tanrei-comp-meter-track-separation	comp.progress-indicator.track.separation	0
--tanrei-comp-meter-track-shape	comp.progress-indicator.track.shape	9999px
--tanrei-comp-meter-warning-indicator-color	sys.color.warning	#9b5c00

نماذج الاختبار

عروض مرجعية. تلتقط كل المنصات لقطة لكل نموذج بالمعرّف نفسه حتى يمكن مقارنة النتائج.

size: small (2)

linear-small

size: small value: 0.62 label: Storage used

circular-small

variant: circular size: small value: 0.62 label: Battery

size: medium (14)

linear

value: 0.62 label: Storage used valueText: 9.3 GB of 15 GB

linear-info

value: 0.4 status: info label: Monthly quota

linear-success

value: 0.9 status: success label: Password strength valueText: Strong

linear-warning

value: 0.85 status: warning label: Storage used valueText: Almost full: 12.8 GB of 15 GB

linear-error

value: 0.98 status: error label: Storage used valueText: Full: 14.7 GB of 15 GB

linear-empty

value: 0 label: Storage used

linear-full

value: 1 label: Storage used

linear-range

value: 37 min: 0 max: 50 label: Seats taken valueText: 37 of 50 seats

linear-gap

separation: gap value: 0.62 label: Storage used

linear-divider

separation: divider value: 0.62 label: Storage used

linear-on-container-highest

value: 0.62 label: Storage used

linear-rtl

value: 0.62 label: Storage used direction: rtl

circular

variant: circular value: 0.62 label: Battery

circular-warning

variant: circular value: 0.15 status: warning label: Battery valueText: Low: 15%

size: large (2)

linear-large

size: large value: 0.62 label: Storage used

circular-large

variant: circular size: large value: 0.62 label: Battery

مولَّد من specs/meter.spec.json, tokens/comp/meter.tokens.json, design/tokens/

الإرشادات

link

متى يُستخدم

link

استخدم العدّاد لتبيّن أين تقع كمية في مدى له حدّ أدنى وحدّ أقصى حقيقيان: مساحة التخزين المستخدمة من حصة، أو شحن بطارية، أو المقاعد المحجوزة في قاعة، أو قوة كلمة مرور جديدة. إنه يعرض مستوى؛ لا شيء جارٍ، ولا شيء سينتهي.

للمهمة الجارية — رفع، أو استيراد، أو حفظ طويل — استخدم مؤشر التقدم بدلًا منه. شكله هو نفسه، لكن التقنيات المساعدة تخبر الناس بأن شيئًا جارٍ، والعدّاد يجب ألا يقول ذلك. والقيمة التي ليس لها حدّ أقصى ذو معنى، كعدد الرسائل، ليست هذا ولا ذاك: اعرضها نصًّا.

اختيار الطراز

link

الطراز (variant)	يُستخدم لـ
خطي (linear)	مستوى يخص صفحة أو قسمًا: مساحة التخزين في صفحة الإعدادات، أو حصة داخل بطاقة، أو صف في قائمة الخطط. يملأ الشريط العرض الذي يعطيه إياه تخطيطه.
دائري (circular)	المواضع الضيقة والمستوى بجانب النص: البطارية في شريط الحالة، أو صف في قائمة الأجهزة. للحلقة مقاس ثابت.

اختيار الحجم

link

الحجم	ثخانة الشريط / مقاس الحلقة في النظام الافتراضي	يُستخدم لـ
صغير (small)	2 / 16	الصفوف الكثيفة، بجانب النص الصغير.
متوسط (medium)	4 / 24	معظم المواضع. وهو الافتراضي.
كبير (large)	8 / 40	المستوى الوحيد الذي يدور حوله العرض، كصفحة التخزين في حساب.

الأحجام والمسار واللون الافتراضي هي نفسها التي لمؤشر التقدم، فيتطابق العدّاد ومؤشر التقدم حين يتجاوران. ويستطيع نظام التصميم أن يميّز العدّاد برموزه الخاصة.

اختيار الحالة

link

لا يقرر العدّاد ما تعنيه القيمة. أن يكون الأكثر أفضل أو أسوأ أمرٌ يعرفه منتجك: مساحة تخزين شبه ممتلئة هي warning، وكلمة مرور تقارب أقصى قوتها هي success. احسب الحالة بنفسك ومرّرها. وللحالات الأسماء التي يستخدمها الوسم وشريط الإشعار.

الحالة	تُستخدم لـ
Default	مستوى لا يحتاج إلى تعليق. معظم العدّادات تبقى هنا.
Info	مستوى تحسن معرفته ولا يطلب شيئًا، كحصة تتجدد قريبًا.
Success	مستوى في موضعه الصحيح، ككلمة مرور قوية.
Warning	مستوى سيحتاج إلى انتباه قريبًا، كمساحة تخزين شبه ممتلئة أو بطارية منخفضة.
Error	مستوى يمنع شيئًا الآن، كمساحة تخزين ممتلئة.

الحالة تغيّر لون المؤشر ولا شيء غيره. قل ما تعنيه بالكلمات أيضًا: في نص القيمة، وفي النص بجانب العدّاد.

افعل

link

• أعطِه تسمية تقول ما الذي يُقاس: «مساحة التخزين المستخدمة»، لا «العدّاد». وإن عُرض بجانبه شرح فاستخدم الكلمات نفسها.
• استخدم نص القيمة حين لا تكون النسبة المئوية هي القراءة الطبيعية: «9.3 غيغابايت من 15 غيغابايت»، «37 من 50 مقعدًا»، «قوية».
• حين يكون للحالة معنى، ضعها في نص القيمة أيضًا: «ممتلئة تقريبًا: 12.8 غيغابايت من 15 غيغابايت».

لا تفعل

link

• لا تستخدمه لمهمة جارية. ذاك مؤشر التقدم.
• لا تعتمد على لون الحالة وحده. فمن لا يرى اللون يجب أن يعرف هو أيضًا أن مساحة التخزين شبه ممتلئة.
• لا تعرض قيمة خارج المدى. فالعدّاد يرسمها ويعرضها محصورة في المدى، فلا يكون الرقم الذي يسمعه الشخص هو الرقم الذي لديك.

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

link

الدور

meter

التسمية

label is the accessible name. valueText, when given, replaces the platform's percentage as the spoken value. A visible caption beside the meter is the product's composition; when it exists, use the same words as label. status is never announced: say in valueText what it means.

الحد الأدنى للهدف

تستوفي مساحة اللمس الحد الأدنى لحجم الهدف حتى لو كان الحجم المرئي أصغر. minimum 32px · pointer 44px · spacing 8px · touch 48px

لوحة المفاتيح

المفاتيح	الإجراء

ملاحظات

• Not interactive: the meter takes no input and is never focusable (MTR-8), so the minimum target holds without extending anything.
• A meter shows where a value stands in a known range; it is not progress (WAI-ARIA APG, Meter: not for loading or percent completion) and not for a value without a meaningful maximum. A task under way is a progress indicator.
• The value is read from the boundary between indicator and track, so every indicator color — default and the four statuses — must stay at least 3:1 against comp.meter.track.color and the surface behind it (WCAG 1.4.11). In the default system each is above 4.6:1 in light and 7.3:1 in dark.
• Color is never the only sign of a status (WCAG 1.4.1): MTR-9.
• Web: the host carries role="meter" and the aria-value attributes; the native <meter> element is not drawn, because its look cannot be styled in every engine.

مولَّد من specs/meter.spec.json, tokens/sys/measure.tokens.json

ما يتكفل به المكوّن

link

• يعرض دور العدّاد (meter) والتسمية اسمًا له، ويعرض المدى والقيمة الحالية (محصورة في المدى) ونص القيمة إن وُجد. ولا يقول أبدًا إنه مشغول أو إن مهمة جارية.
• لا يقبل التركيز أبدًا، ولا يُعلِن تغيّراته. تقرأ التقنيات المساعدة القيمة الحالية حين يصل الشخص إليه.
• لا تُعلَن الحالة وحدها أبدًا: إنها تغيّر اللون فقط.
• تغيّر القيمة يحرّك طرف المؤشر، وتغيّر الحالة يبدّل لونه تدريجيًّا. وحين يُطلب تقليل الحركة يتحرك الطرف فورًا ويتبدّل اللون وحده تدريجيًّا.
• في الألوان المفروضة (forced colors) يصير المسار حافة رفيعة ويُملأ المؤشر، كلاهما بلون النص، أيًّا كانت الحالة، فتبقى القيمة مقروءة من حيث ينتهي المؤشر.
• التسمية الفارغة، والقيمة الخارجة عن المدى، والقيمة التي ليست عددًا، وقيم size أو variant أو separation أو status غير المعروفة يُبلَّغ عنها في بنيات التنقيح (debug).

ما عليك فعله

link

• قل بالكلمات ما تعنيه الحالة: في نص القيمة، وفي النص بجانب العدّاد.
• أعلِن بنفسك التغيّر المهم، كامتلاء مساحة التخزين: رسالة في منطقة حيّة (live region) أو إشعار سيراه الشخص. العدّاد لن يقول ذلك.
• إن غيّرت ألوان المؤشر، فأبقِ كل لون منها — الافتراضي والحالات الأربع — بتباين 3:1 على الأقل مقابل المسار ومقابل السطح الذي خلفه. تُقرأ القيمة من حيث يلتقي المؤشر بالمسار. والنظام الافتراضي يُبقي الألوان الخمسة فوق 4.6:1 في الوضع الفاتح وفوق 7.3:1 في الداكن.