Medidor
Muestra dónde está un valor conocido dentro de un intervalo conocido (el almacenamiento usado, la carga de una batería, una cuota, la seguridad de una contraseña) en forma de barra o de anillo con el aspecto del indicador de progreso, sin decir que haya nada en curso.
- Categoría
- Comunicación
- Tokens
comp.meter- Nivel
- Base
- Web
tanrei-meterclock_loader_40 - SwiftUI
TanreiMeterradio_button_unchecked - Jetpack Compose
TanreiMeterradio_button_unchecked - Flutter
TanreiMeterradio_button_unchecked - React Native
Meterradio_button_unchecked
Generado a partir de docs/status/status.json, specs/meter.spec.json
Lineal y circular
Los ejemplos de Web y React muestran la especificación actual. SwiftUI, Compose, Flutter y React Native están previstos: todavía no ofrecen un medidor.
<tanrei-meter value="0.62" label="Almacenamiento usado" value-text="9,3 GB de 15 GB"></tanrei-meter>
<tanrei-meter value="37" max="50" label="Plazas ocupadas" value-text="37 de 50 plazas"></tanrei-meter>
<!-- El producto decide qué significa el valor, y también lo dice con palabras. -->
<tanrei-meter value="0.85" status="warning" label="Almacenamiento usado" value-text="Casi lleno: 12,8 GB de 15 GB"></tanrei-meter>
<tanrei-meter variant="circular" size="small" value="0.62" label="Batería"></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="Almacenamiento usado" valueText={`${usedText} de ${quotaText}`} />
<Meter value={seats} max={50} label="Plazas ocupadas" valueText={`${seats} de 50 plazas`} />
<Meter
value={used / quota}
status={used / quota > 0.8 ? 'warning' : 'default'}
label="Almacenamiento usado"
valueText={used / quota > 0.8 ? `Casi lleno: ${usedText} de ${quotaText}` : `${usedText} de ${quotaText}`}
/>
<Meter variant="circular" size="small" value={charge} label="Batería" />Estados: default, info, success, warning, error
Tamaños, extremos del intervalo y un intervalo propio
Separación: divider (la elección del sistema predeterminado) y gap
Anatomía
Anatomía
linear, tal como lo dibuja el paquete web.| Parte | Descripción |
|---|---|
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 · opcional | A dot at the end of a bar's track that marks where the range ends, drawn whenever its size is above 0. |
Propiedades
| Propiedad | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
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"). |
Estados
Comportamiento
Requisitos en formato EARS. Cada implementación de plataforma se prueba contra estos identificadores. El texto de los requisitos se muestra tal como está en la especificación, en inglés.
| ID | Requisito |
|---|---|
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. |
Correspondencia de nombres por plataforma
Paridad no significa API idénticas. Cada plataforma expresa el mismo contrato con su propio estilo.
| Especificación | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| Componente | tanrei-meter | TanreiMeter | TanreiMeter | TanreiMeter | Meter |
variant · Propiedad | variant | variant | variant | variant | variant |
size · Propiedad | size | size | size | size | size |
separation · Propiedad | separation | separation | separation | separation | separation |
value · Propiedad | value | value | value | value | value |
min · Propiedad | min | bounds.lowerBound | valueRange.start | min | min |
max · Propiedad | max | bounds.upperBound | valueRange.endInclusive | max | max |
status · Propiedad | status | status | status | status | status |
label · Propiedad | label | label | label | label | label |
valueText · Propiedad | valueText | valueText | valueText | valueText | valueText |
| Notas | 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. |
Tokens
| Token | Alias de | Valor resuelto (claro) |
|---|---|---|
--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 | |
--tanrei-comp-meter-indicator-color | comp.progress-indicator.indicator.color | |
--tanrei-comp-meter-info-indicator-color | sys.color.info | |
--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 | |
--tanrei-comp-meter-track-color | comp.progress-indicator.track.color | |
--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 |
Fixtures
Representaciones canónicas. Todas las plataformas capturan cada fixture con el mismo identificador para poder comparar los resultados.
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 Generado a partir de specs/meter.spec.json, tokens/comp/meter.tokens.json, design/tokens/
Usa un medidor para mostrar dónde está una cantidad dentro de un intervalo que tiene un mínimo y un máximo reales: el almacenamiento usado de una cuota, la carga de una batería, las plazas ocupadas de una sala, la seguridad de una contraseña nueva. Muestra un nivel; no hay nada en curso y nada va a terminar.
Para una tarea que se está ejecutando (una subida, una importación, un guardado largo), usa en su lugar un indicador de progreso. Tiene el mismo aspecto, pero la tecnología de apoyo le dice a la persona que algo está en curso, y un medidor no debe decirlo. Un valor sin un máximo con sentido, como el número de mensajes, no es ni lo uno ni lo otro: muéstralo como texto.
| Variante | Úsala para |
|---|---|
| Lineal | Un nivel que pertenece a una página o a una sección: el almacenamiento en una página de ajustes, una cuota dentro de una tarjeta, una fila de una lista de planes. La barra ocupa el ancho que le da su diseño. |
| Circular | Lugares estrechos y un nivel junto a un texto: una batería en una barra de estado, una fila de una lista de dispositivos. El anillo tiene un tamaño fijo. |
| Tamaño | Grosor de la barra / tamaño del anillo en el sistema predeterminado | Úsalo para |
|---|---|---|
| Small | 2 / 16 | Filas densas, junto a un texto pequeño. |
| Medium | 4 / 24 | La mayoría de los lugares. Es el predeterminado. |
| Large | 8 / 40 | El único nivel del que trata una vista, como la página de almacenamiento de una cuenta. |
Los tamaños, la pista y el color predeterminado son los del indicador de progreso, así que un medidor y un indicador de progreso uno junto al otro coinciden. Un sistema de diseño puede distinguir el medidor mediante sus propios tokens.
El medidor no decide qué significa un valor. Si más es mejor o peor lo sabe tu producto: un almacenamiento casi lleno es un warning, una contraseña casi en su máxima seguridad es un success. Calcula tú el estado y pásalo. Los estados tienen los nombres que usan el tag y el snackbar.
| Estado | Úsalo para |
|---|---|
| Default | Un nivel que no necesita comentario. La mayoría de los medidores se quedan aquí. |
| Info | Un nivel que conviene conocer y que no pide nada, como una cuota que se renueva pronto. |
| Success | Un nivel que está donde debe estar, como una contraseña segura. |
| Warning | Un nivel que pronto necesitará atención, como un almacenamiento casi lleno o una batería baja. |
| Error | Un nivel que ya impide algo, como un almacenamiento lleno. |
Un estado cambia el color del indicador y nada más. Di también con palabras qué significa: en el texto de valor y en el texto junto al medidor.
- Dale una etiqueta que diga qué se mide: «Almacenamiento usado», no «Medidor». Si junto a él se muestra una leyenda, usa las mismas palabras.
- Usa un texto de valor cuando un porcentaje no sea la lectura natural: «9,3 GB de 15 GB», «37 de 50 plazas», «Segura».
- Cuando el estado signifique algo, ponlo también en el texto de valor: «Casi lleno: 12,8 GB de 15 GB».
- No lo uses para una tarea que se está ejecutando. Eso es un indicador de progreso.
- No te apoyes solo en el color de un estado. Quien no puede ver el color también tiene que enterarse de que el almacenamiento está casi lleno.
- No muestres un valor fuera del intervalo. El medidor lo dibuja y lo expone limitado al intervalo, así que el número que oiría la persona no sería el que tienes.
- Rol
meter- Etiquetado
- 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.
- Objetivo mínimo
- El área de pulsación cumple el tamaño mínimo de objetivo aunque el tamaño visual sea menor. minimum 32px · pointer 44px · spacing 8px · touch 48px
Teclado
| Teclas | Acción |
|---|
Notas
- 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.
Generado a partir de specs/meter.spec.json, tokens/sys/measure.tokens.json
- Expone el rol de medidor (meter) con la etiqueta como nombre, el intervalo, el valor actual (limitado al intervalo) y el texto de valor cuando lo hay. Nunca dice que esté ocupado ni que haya una tarea en curso.
- Nunca recibe el foco y no anuncia sus cambios. La tecnología de apoyo lee el valor actual cuando la persona llega a él.
- Un estado nunca se anuncia por sí solo: solo cambia el color.
- Un cambio de valor mueve el extremo del indicador y un cambio de estado funde su color. Cuando se pide reducir movimiento, el extremo se mueve de inmediato y solo se funde el color.
- Con colores forzados, la pista pasa a ser un borde fino y el indicador se rellena, ambos en el color del texto, sea cual sea el estado, de modo que el valor se sigue leyendo donde termina el indicador.
- Las compilaciones de depuración notifican una etiqueta vacía, un valor fuera del intervalo, un valor que no es un número y un
size,variant,separationostatusdesconocido.
- Di con palabras qué significa un estado: en el texto de valor y en el texto junto al medidor.
- Anuncia tú un cambio que importe, como que el almacenamiento se ha llenado: un mensaje en una región activa (live region) o un aviso que la persona vaya a ver. El medidor no lo dirá.
- Si los cambias, mantén cada color del indicador (el predeterminado y los cuatro estados) con un contraste de al menos 3:1 frente a la pista y frente a la superficie que tiene detrás. El valor se lee allí donde el indicador se encuentra con la pista. El sistema predeterminado mantiene los cinco por encima de 4,6:1 en claro y de 7,3:1 en oscuro.