Progress

<r-progress>API Tokens de estilo Prueba interactiva Código fuente

Barra de progreso para mostrar el avance de una tarea, con un tirador arrastrable opcional.

Úsalo cuando necesites una barra que muestre el avance de una tarea. Usa <r-progress> tal cual para un progreso de solo lectura, o type="drag" cuando el usuario deba fijar el valor con un tirador arrastrable.

Inicio rápido

<r-progress percent="40%"></r-progress>

💡 Consejo: r-progress es un elemento de bloque sin ancho intrínseco. Dentro de una fila flex puede colapsar a ancho cero; dale un ancho explícito (por ejemplo style="width:100%") o colócalo en un contexto de bloque.

Referencia de la API

Propiedades

Propiedad	Tipo	Por defecto	Descripción
`percent`	`string`	`'0'`	Progreso actual; admite un número o un porcentaje. Se limita a `total`.
`total`	`string`	`'100'`	Progreso total; admite un número o un porcentaje.
`type`	`string`	`'primary'`	Tipo de barra: `primary` (estática) o `drag` (clicable y arrastrable).
`dot`	`string`	`'true'`	Si se muestra el tirador de arrastre: `true` o `false`.
`sheet`	`string`	`''`	CSS inyectado en el shadow DOM del componente.

Define el progreso actual. Admite un número o una cadena de porcentaje y no puede superar total. Cuando total no está definido, vale 100 por defecto (es decir, percent se lee como porcentaje de 100).

<r-progress percent="30%"></r-progress>
<r-progress percent="70%"></r-progress>
<r-progress percent="100%"></r-progress>

Progreso total `total`

Define el denominador de percent. Se admiten tanto números como porcentajes, así que percent="30" total="1000" llena la barra al 3%.

<r-progress percent="30" total="1000"></r-progress>
<r-progress percent="70" total="100"></r-progress>
<r-progress percent="10%" total="100%"></r-progress>

Tipo de barra `type`

primary: barra de progreso estática. Es el valor por defecto si no defines type.
drag: barra clicable y arrastrable. Hacer clic en la pista o arrastrar el tirador actualiza percent y dispara un evento change. Arrastrar el tirador requiere dot="true".

<r-progress type="drag" percent="30%"></r-progress> <r-progress type="primary" percent="40%"></r-progress>

Tirador de arrastre `dot`

Activa o desactiva el tirador. Solo se dibuja cuando dot="true" y type="drag"; en una barra primary estática se omite a propósito, así que allí dot no tiene efecto visible.

<r-progress type="drag" percent="30%" dot="true"></r-progress>
<r-progress type="drag" percent="30%" dot="false"></r-progress>

Eventos

`change`

Se despacha en el tipo drag cada vez que el usuario hace clic en la pista o arrastra el tirador, actualizando percent. El objeto detail lleva:

Campo	Tipo	Descripción
`value`	`string`	Progreso actual
`percent`	`string`	Progreso actual
`total`	`string`	Progreso total

<r-progress type="drag" percent="30%"></r-progress>

<script>
  const progress = document.createElement('r-progress');
  progress.type = 'drag';
  progress.percent = '30%';
  progress.addEventListener('change', (e) => {
    console.log(e.detail.value, e.detail.percent, e.detail.total);
  });
  container.append(progress);
</script>

Partes CSS

Parte	Descripción
`track`	La pista del progreso (el fondo).
`fill`	La porción llena de la pista.
`dot`	El tirador de arrastre.

r-progress::part(fill) {
  background: var(--ran-color-primary);
}

Buenas prácticas

Barras estáticas: usa el type="primary" por defecto para mostrar un progreso de solo lectura.
Barras interactivas: usa type="drag" cuando el usuario deba poder fijar el valor, y escucha el evento change.
Porcentaje o número: mezcla percent y total con libertad; pasa números crudos cuando correspondan a un total conocido, o porcentajes para un control directo.
Ancho en la maqueta: envuelve la barra en un contenedor de bloque o dale un ancho explícito para que no colapse en maquetas flex.

Prueba interactiva

<r-progress>

Marcado