BuscarCtrl K

Appearance

Extensões

Guia de Uso - Progress Bar ​

Status: Implementado (Design System 1.1 • 05/11/2025) – cobre barras lineares e circulares.

📋 Índice ​

  1. Introdução
  2. Estrutura Base
  3. Tipos
  4. Estados
  5. Tamanhos
  6. Animações
  7. Progress Circular
  8. Dark Mode
  9. Exemplos Práticos

Introdução ​

O componente Progress Bar mostra o progresso de uma operação. É ideal para:

  • Uploads de arquivos
  • Processamento de dados
  • Carregamento de páginas
  • Etapas de formulários
  • Qualquer operação assíncrona

Quando Usar Progress Bar ​

✅ Use progress bar quando:

  • Você tem uma operação que leva tempo
  • Quer mostrar o progresso visual
  • Precisa de feedback ao usuário
  • A operação tem um valor percentual conhecido

❌ Evite usar progress bar quando:

  • A operação é instantânea
  • Não há como medir o progresso
  • Use Skeleton Loader para carregamento de conteúdo

Estrutura Base ​

HTML Básico ​

html
<div class="progress">
    <div class="progress-bar" style="width: 50%"></div>
</div>

Com Label ​

html
<div>
    <div class="progress-label">
        <span class="progress-label-text">Upload de arquivo</span>
        <span class="progress-label-value">50%</span>
    </div>
    <div class="progress">
        <div class="progress-bar" style="width: 50%"></div>
    </div>
</div>

Tipos ​

1. Linear (Padrão) ​

html
<div class="progress">
    <div class="progress-bar" style="width: 60%"></div>
</div>

2. Circular ​

html
<div class="progress-circular">
    <svg viewBox="0 0 64 64">
        <circle class="progress-circular-track" cx="32" cy="32" r="28"></circle>
        <circle class="progress-circular-bar" cx="32" cy="32" r="28" 
                stroke-dasharray="175.9" stroke-dashoffset="87.95"></circle>
    </svg>
    <span class="progress-circular-text">50%</span>
</div>

Estados ​

Default ​

html
<div class="progress">
    <div class="progress-bar" style="width: 60%"></div>
</div>

Success ​

html
<div class="progress">
    <div class="progress-bar progress-bar--success" style="width: 100%"></div>
</div>

Warning ​

html
<div class="progress">
    <div class="progress-bar progress-bar--warning" style="width: 75%"></div>
</div>

Error ​

html
<div class="progress">
    <div class="progress-bar progress-bar--error" style="width: 30%"></div>
</div>

Tamanhos ​

Small ​

html
<div class="progress progress--sm">
    <div class="progress-bar" style="width: 50%"></div>
</div>

Medium (Padrão) ​

html
<div class="progress">
    <div class="progress-bar" style="width: 50%"></div>
</div>

Large ​

html
<div class="progress progress--lg">
    <div class="progress-bar" style="width: 50%"></div>
</div>

Extra Large ​

html
<div class="progress progress--xl">
    <div class="progress-bar" style="width: 50%"></div>
</div>

Animações ​

Striped ​

html
<div class="progress">
    <div class="progress-bar progress-bar--striped" style="width: 60%"></div>
</div>

Animated ​

html
<div class="progress">
    <div class="progress-bar progress-bar--animated" style="width: 60%"></div>
</div>

Striped + Animated ​

html
<div class="progress">
    <div class="progress-bar progress-bar--striped progress-bar--animated" style="width: 60%"></div>
</div>

Progress Circular ​

Estrutura ​

html
<div class="progress-circular">
    <svg viewBox="0 0 64 64">
        <circle class="progress-circular-track" cx="32" cy="32" r="28"></circle>
        <circle class="progress-circular-bar" cx="32" cy="32" r="28" 
                stroke-dasharray="175.9" stroke-dashoffset="87.95"></circle>
    </svg>
    <span class="progress-circular-text">50%</span>
</div>

Cálculo do Progresso ​

javascript
// Circunferência = 2 * π * raio
const radius = 28;
const circumference = 2 * Math.PI * radius; // ~175.9

// Progresso = (100 - percentual) / 100 * circunferência
const percent = 50;
const offset = ((100 - percent) / 100) * circumference; // ~87.95

Tamanhos ​

html
<!-- Small -->
<div class="progress-circular progress-circular--sm">...</div>

<!-- Large -->
<div class="progress-circular progress-circular--lg">...</div>

Dark Mode ​

O Dark Mode é aplicado automaticamente quando a classe .dark, .dark-mode ou [data-theme="dark"] está presente no elemento raiz.

html
<html class="dark">
    <!-- Progress Bar automaticamente em dark mode -->
</html>

Exemplos Práticos ​

Exemplo 1: Upload de Arquivo ​

html
<div>
    <div class="progress-label">
        <span class="progress-label-text">Enviando arquivo...</span>
        <span class="progress-label-value" id="upload-progress">0%</span>
    </div>
    <div class="progress">
        <div class="progress-bar progress-bar--animated" id="upload-bar" style="width: 0%"></div>
    </div>
</div>
javascript
function updateUploadProgress(percent) {
    document.getElementById('upload-progress').textContent = percent + '%';
    document.getElementById('upload-bar').style.width = percent + '%';
    
    if (percent === 100) {
        document.getElementById('upload-bar').classList.remove('progress-bar--animated');
        document.getElementById('upload-bar').classList.add('progress-bar--success');
    }
}

Exemplo 2: Processamento de Dados ​

html
<div>
    <div class="progress-label">
        <span class="progress-label-text">Processando dados</span>
        <span class="progress-label-value" id="process-progress">0%</span>
    </div>
    <div class="progress progress--lg">
        <div class="progress-bar progress-bar--striped progress-bar--animated" 
             id="process-bar" style="width: 0%"></div>
    </div>
</div>

Exemplo 3: Progress Circular ​

html
<div class="progress-circular" id="circular-progress">
    <svg viewBox="0 0 64 64">
        <circle class="progress-circular-track" cx="32" cy="32" r="28"></circle>
        <circle class="progress-circular-bar" id="circular-bar" 
                cx="32" cy="32" r="28" 
                stroke-dasharray="175.9" stroke-dashoffset="175.9"></circle>
    </svg>
    <span class="progress-circular-text" id="circular-text">0%</span>
</div>
javascript
function updateCircularProgress(percent) {
    const radius = 28;
    const circumference = 2 * Math.PI * radius;
    const offset = ((100 - percent) / 100) * circumference;
    
    document.getElementById('circular-bar').style.strokeDashoffset = offset;
    document.getElementById('circular-text').textContent = percent + '%';
}

Boas Práticas ​

  1. Use labels descritivos: Seja claro sobre o que está carregando
  2. Mostre percentual: Quando possível, exiba o valor numérico
  3. Use animação: Para operações sem progresso conhecido
  4. Mude cor no sucesso: Use progress-bar--success quando completo
  5. Considere circular: Para espaços compactos ou dashboards

Versão: 1.0.0
Data: 2025-01-27
Documentação: /public/css/design-system/GUIA_PROGRESS.md
Exemplos: /public/css/design-system/exemplos-progress.html

Design System interno do GALES

IpeWeb