1. Demo completo

Todos os recursos ativos: busca, ordenação, paginação, exportação CSV/Copiar e visibilidade de colunas.

2. Uso básico

Adicione y2table em qualquer <table> existente. Busca, sort e paginação são ativados por padrão.

3. Ordenação e Busca

Ordenação — automática em todas as colunas. Números são ordenados numericamente. Use y2table-nosort no <th> para desabilitar uma coluna específica. A busca filtra por todas as colunas simultaneamente com debounce de 300ms.

// Busca programática
const tabela = document.querySelector('#minha-tabela');
Y2Table.search(tabela, 'São Paulo');

// Escutar evento de busca
tabela.addEventListener('yd:table:search', e => {
    console.log('Query:', e.detail.query);
});

// Escutar evento de sort
tabela.addEventListener('yd:table:sort', e => {
    console.log('Coluna:', e.detail.col, 'Direção:', e.detail.dir);
});

4. Exportação

O atributo y2table-export aceita csv e copy separados por vírgula. A exportação respeita o filtro de busca atual e as colunas visíveis.

// Exportar programaticamente
const tabela = document.querySelector('#minha-tabela');

Y2Table.export(tabela, 'csv');   // baixa arquivo tabela.csv
Y2Table.export(tabela, 'copy');  // copia para clipboard

5. Seleção de linhas

O atributo y2table-select adiciona uma coluna de checkboxes com "Selecionar tudo". O evento yd:table:select dispara ao mudar a seleção.

const tabela = document.querySelector('#minha-tabela');

tabela.addEventListener('yd:table:select', e => {
    const selecionados = e.detail.selected; // array de índices
    console.log(`${selecionados.length} linha(s) selecionada(s)`);
    console.log('índices:', selecionados);
});

6. Visibilidade de colunas

O atributo y2table-colvis adiciona um botão "Colunas" que permite mostrar/ocultar colunas. Use y2table-novis no <th> para impedir que uma coluna seja ocultada.

7. Server-side AJAX

Use y2table-url para buscar dados do servidor. Paginação, busca e ordenação são delegadas ao servidor. O thead pode ser definido no HTML ou auto-gerado a partir de y2table-cols.

Request enviado ao servidor:

// GET /api/funcionarios?page=1&per=10&search=ana&sort=nome&dir=asc

Response esperado do servidor:

// Mínimo — array simples (sem paginação)
["dado1", "dado2"]

// Completo — com total e filtrado
{
  "data": [
    { "nome": "Ana Silva", "cargo": "Designer", "cidade": "São Paulo" },
    { "nome": "Bruno Santos", "cargo": "Dev Frontend", "cidade": "Curitiba" }
  ],
  "total": 150,      // total de registros sem filtro
  "filtered": 23     // total após filtro de busca
}

Exemplo em PHP (Laravel):

// Route::get('/api/funcionarios', function(Request $r) {
//     $q = Funcionario::query();
//     if ($r->search) $q->where('nome', 'like', "%{$r->search}%");
//     $total    = $q->count();
//     if ($r->sort) $q->orderBy($r->sort, $r->dir ?? 'asc');
//     $filtered = $q->count();
//     $data     = $q->skip(($r->page - 1) * $r->per)->take($r->per)->get();
//     return response()->json(compact('data', 'total', 'filtered'));
// });

8. API JavaScript

Métodos estáticos disponíveis em Y2Table para controle e população programática.

Y2Table.fromData() — popular com dados JS

Cria ou re-popula uma tabela a partir de arrays JS puros. HTML nas células — permitido. Chamadas subsequentes atualizam os dados sem recriar a UI.

// ?"—? 1. Arrays posicionais — mais simples
Y2Table.fromData('#tabela',
    ['Nome', 'Cargo', 'Cidade'],
    [
        ['Ana Silva',    'Designer',  'São Paulo'],
        ['Bruno Santos', 'Dev Front', 'Curitiba'],
        ['Carla Mendes', 'PM',        'São Paulo'],
    ]
);

// ?"—? 2. Objetos com field mapping
Y2Table.fromData('#tabela',
    [
        { label: 'Nome',  field: 'nome'  },
        { label: 'Cargo', field: 'cargo' },
        { label: 'Status', field: 'status', nosort: true },
    ],
    [
        { nome: 'Ana Silva',    cargo: 'Designer',  status: '<span class="bdg is-suc is-sm">Ativo</span>' },
        { nome: 'Bruno Santos', cargo: 'Dev Front', status: '<span class="bdg is-err is-sm">Inativo</span>' },
    ]
);

// ?"—? 3. Com fetch() — carrega JSON e popula
fetch('/api/produtos')
    .then(r => r.json())
    .then(data => {
        Y2Table.fromData('#tabela',
            [
                { label: 'Produto', field: 'nome' },
                { label: 'Preço',   field: 'preco' },
                { label: 'Estoque', field: 'qtd' },
            ],
            data
        );
    });

// ?"—? 4. Re-popular tabela existente (atualiza sem recriar a UI)
// A segunda chamada reutiliza busca, paginação e colunas já configuradas
Y2Table.fromData('#tabela', cols, novosDados);

// ?"—? 5. Opções na primeira chamada (opts ignorados em chamadas seguintes)
Y2Table.fromData('#tabela', cols, rows, {
    per:    10,
    export: 'csv,copy',
    colvis: true,
    stripe: true,
    state:  true,   // salva estado no localStorage (requer id na tabela)
});

Outros métodos

const tabela = document.querySelector('#tabela');

Y2Table.reload(tabela);           // recarrega (útil após mutação externa)
Y2Table.search(tabela, 'SP');     // busca programática (atualiza o campo)
Y2Table.export(tabela, 'csv');    // baixa tabela.csv
Y2Table.export(tabela, 'copy');   // copia para clipboard

// Acesso direto — instância
const inst = tabela._y2TabInst;
console.log(inst.cur);      // página atual
console.log(inst._hidden);  // Set de índices de colunas ocultas

Eventos

tabela.addEventListener('yd:table:page',   e => console.log('Página:', e.detail.page));
tabela.addEventListener('yd:table:sort',   e => console.log('Sort:', e.detail.col, e.detail.dir));
tabela.addEventListener('yd:table:search', e => console.log('Busca:', e.detail.query));

9. PHP — foreach com HTML

O Y2Table lê o conteúdo de cada <td> preservando o HTML interno. Badges, botões de ação, links e qualquer elemento renderizado pelo PHP funcionam normalmente — inclusive no sort e na busca (que usa o texto visível, não o HTML).

Básico — foreach simples:

Com busca e sort respeitando os botões:

Colunas com HTML (badges, botões) devem ter y2table-nosort — o sort usa o textContent visível, que pode ser vazio em colunas só com ícones. A busca global ignora essas colunas automaticamente se não houver texto visível.

Estilo para botões de ação nas células: