Guia de Uso - Pagination (Paginação)

Status: Implementado (Design System 1.1 • 05/11/2025) – integra com tabelas e listas SSR.

📋 Índice

1. Introdução
2. Estrutura Base
3. Variantes
4. Estados
5. JavaScript API
6. Acessibilidade
7. Dark Mode
8. Responsividade
9. Exemplos Práticos

---

Introdução

O componente Pagination permite navegar entre páginas de resultados. É ideal para:

• Listagens de dados
• Tabelas com muitos registros
• Resultados de busca
• Qualquer conteúdo paginado

Quando Usar Pagination

✅ Use pagination quando:

• Você tem muitos itens para exibir (>20-30)
• Quer melhorar performance (carregar menos dados)
• Precisa de navegação clara entre páginas
• O usuário precisa encontrar itens específicos

❌ Evite usar pagination quando:

• Você tem poucos itens (<20)
• Todos os itens precisam ser vistos de uma vez
• A navegação é linear (use Stepper)

---

Estrutura Base

HTML Básico (Auto-inicialização)

<div class="pagination" 
     data-pagination="auto"
     data-current-page="3"
     data-total-pages="10">
</div>

HTML Manual

<div class="pagination" id="my-pagination">
    <ul class="pagination-list">
        <li class="pagination-item">
            <a href="#" class="pagination-link pagination-link--disabled">
                <span class="pagination-icon">‹</span>
                <span>Anterior</span>
            </a>
        </li>
        <li class="pagination-item">
            <a href="#" class="pagination-link pagination-link--active" aria-current="page">1</a>
        </li>
        <li class="pagination-item">
            <a href="#" class="pagination-link">2</a>
        </li>
        <li class="pagination-item">
            <a href="#" class="pagination-link">
                <span>Próxima</span>
                <span class="pagination-icon">›</span>
            </a>
        </li>
    </ul>
</div>

---

Variantes

1. Pagination Padrão

<div class="pagination" id="pagination-1"></div>

new PaginationManager(document.getElementById('pagination-1'), {
    currentPage: 3,
    totalPages: 10
});

2. Pagination Compact

<div class="pagination pagination--compact" id="pagination-2"></div>

Características:

• Botões menores
• Ideal para espaços reduzidos

3. Pagination Simple (Apenas Prev/Next)

<div class="pagination pagination--simple" id="pagination-3"></div>

Características:

• Apenas botões Previous/Next
• Ideal para navegação simples

---

Estados

Default

<a href="#" class="pagination-link">2</a>

Active (Página Atual)

<a href="#" class="pagination-link pagination-link--active" aria-current="page">3</a>

Disabled

<a href="#" class="pagination-link pagination-link--disabled" aria-disabled="true">Anterior</a>

---

JavaScript API

Auto-inicialização

<div class="pagination" 
     data-pagination="auto"
     data-current-page="3"
     data-total-pages="10"
     data-total-items="100"
     data-items-per-page="10"
     data-show-info="true"
     data-show-first-last="true">
</div>

Inicialização Manual

const pagination = new PaginationManager(container, {
    currentPage: 3,
    totalPages: 10,
    totalItems: 100,
    itemsPerPage: 10,
    maxVisible: 7, // Máximo de páginas visíveis
    showPrevNext: true,
    showFirstLast: false,
    showInfo: false,
    showEllipsis: true,
    onPageChange: (page, manager) => {
        console.log('Página mudou para:', page);
        // Carregar dados da nova página
        loadPageData(page);
    }
});

Métodos Disponíveis

// Ir para uma página específica
pagination.goToPage(5);

// Definir página atual
pagination.setCurrentPage(5);

// Definir total de páginas
pagination.setTotalPages(20);

// Definir total de itens (recalcula páginas)
pagination.setTotalItems(200);

// Obter página atual
const currentPage = pagination.getCurrentPage();

// Obter total de páginas
const totalPages = pagination.getTotalPages();

---

Acessibilidade

ARIA Attributes

O componente inclui automaticamente:

• aria-label nos botões
• aria-current="page" na página ativa
• aria-disabled="true" nos botões desabilitados

Navegação por Teclado

• Arrow Left: Botão anterior
• Arrow Right: Próximo botão
• Home: Primeiro botão
• End: Último botão
• Enter/Space: Ativar botão focado
• Tab: Navegar para fora do componente

---

Dark Mode

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

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

---

Responsividade

Mobile

Em telas menores que 768px:

• Botões ajustam tamanho automaticamente
• Informações podem ser escondidas (opcional)
• Pagination continua funcional

---

Exemplos Práticos

Exemplo 1: Pagination Básica

const pagination = new PaginationManager(document.getElementById('pagination'), {
    currentPage: 1,
    totalPages: 10,
    onPageChange: (page) => {
        // Carregar dados da página
        loadData(page);
    }
});

Exemplo 2: Com Informações de Total

const pagination = new PaginationManager(document.getElementById('pagination'), {
    currentPage: 2,
    totalPages: 15,
    totalItems: 150,
    itemsPerPage: 10,
    showInfo: true,
    onPageChange: (page) => {
        loadData(page);
    }
});

Resultado: "Mostrando 11-20 de 150"

Exemplo 3: Com First/Last

const pagination = new PaginationManager(document.getElementById('pagination'), {
    currentPage: 5,
    totalPages: 20,
    showFirstLast: true,
    onPageChange: (page) => {
        loadData(page);
    }
});

Exemplo 4: Muitas Páginas (com Ellipsis)

const pagination = new PaginationManager(document.getElementById('pagination'), {
    currentPage: 10,
    totalPages: 50,
    maxVisible: 7, // Mostra 7 páginas por vez
    showFirstLast: true,
    onPageChange: (page) => {
        loadData(page);
    }
});

Resultado: 1 ... 7 8 9 [10] 11 12 13 ... 50

Exemplo 5: Integração com AJAX

const pagination = new PaginationManager(document.getElementById('pagination'), {
    currentPage: 1,
    totalPages: 1,
    totalItems: 0,
    itemsPerPage: 10,
    showInfo: true,
    onPageChange: async (page) => {
        // Mostrar loading
        showLoading();
        
        try {
            // Buscar dados
            const response = await fetch(`/api/data?page=${page}&limit=10`);
            const data = await response.json();
            
            // Atualizar pagination
            pagination.setTotalItems(data.total);
            pagination.setCurrentPage(page);
            
            // Renderizar dados
            renderData(data.items);
        } catch (error) {
            console.error('Erro ao carregar dados:', error);
        } finally {
            hideLoading();
        }
    }
});

// Carregar primeira página
pagination.goToPage(1);

---

Tamanhos

Small

<div class="pagination pagination--sm" id="pagination"></div>

Large

<div class="pagination pagination--lg" id="pagination"></div>

---

Alinhamento

Left

<div class="pagination pagination--left" id="pagination"></div>

Center (Padrão)

<div class="pagination pagination--center" id="pagination"></div>

Right

<div class="pagination pagination--right" id="pagination"></div>

---

Boas Práticas

1. Use ellipsis: Para muitas páginas (>10)
2. Mostre informações: Total de itens ajuda o usuário
3. Mantenha estado: Salve página atual na URL ou estado
4. Carregue dados: Use callback onPageChange para carregar dados
5. Teste acessibilidade: Sempre teste navegação por teclado
6. Considere mobile: Em mobile, pode esconder números e mostrar apenas Prev/Next

---

Integração com Backend

PHP (Laminas Paginator)

use Laminas\Paginator\Paginator;

$paginator = new Paginator($adapter);
$paginator->setItemCountPerPage(10);
$paginator->setCurrentPageNumber($page);

// No template
$pagination = new PaginationManager('#pagination', [
    'currentPage' => $paginator->getCurrentPageNumber(),
    'totalPages' => $paginator->count(),
    'totalItems' => $paginator->getTotalItemCount(),
    'itemsPerPage' => $paginator->getItemCountPerPage(),
    'showInfo' => true,
    'onPageChange' => 'loadPage'
]);

---

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