En el ecosistema de HarmonyOS, el componente Progress es fundamental para indicar visualmente el estado de avance de operaciones asíncronas, descargas o tareas de larga duración. Este elemento permite a los desarrolladores comunicar de manera clara el progreso actual en relación con un objetivo total dentro de la interfaz de usuario.

Inicialización y Parámetros Base

La instanciación del componente se realiza mediante su constructor, el cual acepta un objeto de configuración con tres parámetros principales:

Progress({ value: valorActual, total: limiteMaximo, type: ProgressType.Linear })

• value: Define el nivel de avance actual numérico.
• total: Establece el límite máximo o la meta total de la operación.
• type: Determina la representación visual o geometría de la barra.

Variantes Visuales y Personalización

El framework ArkUI ofrece cinco tipologías distintas para el componente Progress, accesibles a través de la enumeración ProgressType. A continuación, se detalla su implementación y configuración:

1. Estilo Lineal (Linear)

Es la representación por defecto. Una característica importente es su adaptabilidad: si la dimensión vertical supera a la horizontal, el componante rota automáticamente para mostrarse en posición vertical.

// Configuración horizontal estándar
Progress({ value: 45, total: 100, type: ProgressType.Linear })
  .width(300)
  .height(20)

// Adaptación automática a vertical debido a la altura
Progress({ value: 45, total: 100, type: ProgressType.Linear })
  .width(20)
  .height(300)

2. Anular sin Marcas (Ring)

Representa el progreso mediante un arco circular. Permite ajustar el grosor del trazo y los colores de fondo y primer plano.

// Arco circular básico
Progress({ value: 60, total: 100, type: ProgressType.Ring })
  .width(120)
  .height(120)

// Arco personalizado con grosor y color modificados
Progress({ value: 60, total: 100, type: ProgressType.Ring })
  .width(120)
  .height(120)
  .color('#FF5722')
  .style({ strokeWidth: 12 })

3. Anular con Marcas (ScaleRing)

Similar al anterior, pero incorpora divisiones o marcas a lo largo del perímetro, ideal para indicadores de precisión o medidores.

Progress({ value: 75, total: 100, type: ProgressType.ScaleRing })
  .width(150)
  .height(150)
  .backgroundColor('#F0F0F0')
  .style({
    strokeWidth: 18,
    scaleCount: 25,
    scaleWidth: 4
  })

4. Estilo Circular (Eclipse)

Genera un círculo sólido que se llena progresivamente. A diferencia del estilo Ring, este no tiene un hueco en el centro.

Progress({ value: 30, total: 100, type: ProgressType.Eclipse })
  .width(100)
  .height(100)
  .color('#4CAF50')

5. Estilo Cápsula (Capsule)

Combina los extremos redondeados del estilo Eclipse con el cuerpo rectangular del estilo Linear. También soporta la rotación automática si la altura es mayor que el ancho.

Progress({ value: 85, total: 100, type: ProgressType.Capsule })
  .width(250)
  .height(40)
  .color('#2196F3')
  .backgroundColor('#E3F2FD')

Interactividad y Actualización Dinámica

En escenarios reales, como la descarga de archivos o la instalación de paquetes, el valor del progreso debe actualizarse dinámicamente. Esto se logra enlazando el parámetro value con una variable de estado reactiva (@State). Al modificar esta variable, el framework re-renderiza el componente automáticamente.

@Entry
@Component
struct DescargaArchivosUI {
  @State porcentajeDescarga: number = 10;

  build() {
    Column({ space: 20 }) {
      Text(`${this.porcentajeDescarga}%`)
        .fontSize(24)
        .fontWeight(FontWeight.Bold)

      Progress({
        value: this.porcentajeDescarga,
        total: 100,
        type: ProgressType.Capsule
      })
      .width('80%')
      .height(30)
      .color('#007DFF')
      .backgroundColor('#E5E5E5')

      Button('Simular Avance')
        .width('60%')
        .onClick(() => {
          this.porcentajeDescarga += 15;
          if (this.porcentajeDescarga > 100) {
            this.porcentajeDescarga = 0; // Reinicio cíclico para demostración
          }
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}