# 
> Biblioteca JavaScript moderna para criação de tabelas interativas com filtros cascata, busca normalizada e recursos avançados
[](https://www.npmjs.com/package/skargrid)
[](https://www.npmjs.com/package/skargrid)
[](LICENSE)
[](https://bundlephobia.com/package/skargrid)
**Site:** [https://skargrid.com](https://skargrid.com) •
**🇺🇸 [Read in English](README.md)**
---
## 📋 Sumário
- [✨ Principais Recursos](#-principais-recursos)
- [📸 Exemplos Visuais](#-exemplos-visuais)
- [🚀 Início Rápido](#-início-rápido)
- [📖 Exemplos Completos](#-exemplos-completos)
- [⚡ Benchmarks de Performance](#-benchmarks-de-performance)
- [🎯 Referência da API](#-referência-da-api)
- [🎨 Temas e Estilização](#-temas-e-estilização)
- [🔧 Build e Desenvolvimento](#-build-e-desenvolvimento)
- [📋 Changelog](#-changelog)
- [🤝 Contribuição](#-contribuição)
- [📄 Licença](#-licença)
---
## ✨ Principais Recursos
- 🌐 **Internacionalização (i18n)** - Labels padrão em inglês, totalmente personalizáveis para qualquer idioma
- ⚡ **Rolagem Virtual** - Renderização de alta performance para datasets grandes (100k+ linhas)
- 🎨 **Configuração de Colunas** - Arrastar e soltar para reordenar, mostrar/ocultar colunas com persistência
- 🗄️ **Persistência Inteligente** - Salva preferências do usuário no localStorage automaticamente
- 🌓 **Suporte a Temas** - Tema claro/escuro com transições suaves e variáveis customizáveis
- 🔄 **Filtros Cascata** - Filtros estilo Excel com valores indisponíveis desabilitados
- 🌍 **Busca Sem Acentos** - Trata acentos automaticamente (José = jose)
- ↔️ **Rolagem Horizontal** - Barra de rolagem customizada para tabelas largas
- 📦 **Bundle Único** - Apenas 2 arquivos (JS + CSS) - **27.8KB comprimido**
- 🎯 **Zero Dependências** - JavaScript puro Vanilla, agnóstico a frameworks
- 🧪 **Testes Automatizados** - 21 testes abrangentes cobrindo todas as funcionalidades
- 📊 **Suporte a Exportação** - Exportação CSV e XLSX nativa sem dependências externas
---
## 📸 Exemplos Visuais
Abaixo exemplos visuais dos recursos do SkarGrid, em ordem de aprendizado recomendada:
#### Configuração Básica
Tabela básica: 4 colunas, ordenação, paginação
#### Recursos Completos
Todos os recursos: ordenação, filtros, seleção, exportação, tema escuro, config. de colunas
#### Filtragem Avançada
Filtros cascata estilo Excel com busca
#### Gerenciamento de Colunas
Reordenamento arrastar/soltar e alternância de visibilidade
#### Exportação de Dados
Exportação para formatos CSV e XLSX
#### Tema Escuro
Tema escuro integrado com transições suaves
---
## 🚀 Início Rápido
### Instalação
**Opção 1: CDN (Recomendado)**
```html
```
**Opção 2: NPM**
```bash
npm install skargrid
```
**Opção 3: Download**
```bash
git clone https://github.com/ScarpelliniGilmar/skargrid.git
cp skargrid/dist/* seu-projeto/
```
### Uso Básico
```html
```
---
## 📖 Exemplos Completos
### 🏆 Tabela Completa com Todos os Recursos
```html
Demonstração SkarGrid
```
### 📊 Exemplo de Gerenciamento de Dados
```javascript
// Inicializar tabela
const table = new Skargrid('myTable', {
data: dadosIniciais,
columns: columns,
pagination: true,
searchable: true
});
// Atualizar dados dinamicamente
function atualizarTabela(novosDados) {
table.updateData(novosDados);
}
// Manipular mudanças de seleção
function aoMudarSelecao() {
const linhasSelecionadas = table.getSelectedRows();
console.log('Itens selecionados:', linhasSelecionadas);
// Exportar apenas linhas selecionadas
if (linhasSelecionadas.length > 0) {
table.exportSelectedToCSV('itens-selecionados.csv');
}
}
// Limpar todos os filtros
function resetarFiltros() {
table.clearAllFilters();
}
// Alterar tema
function alternarTema() {
const temaAtual = table.options.theme;
table.setTheme(temaAtual === 'light' ? 'dark' : 'light');
}
```
### 🎨 Estilização Avançada
```css
/* Variáveis de tema customizado */
:root {
--sg-primary: #2563eb;
--sg-accent: #1d4ed8;
--sg-gray: #6b7280;
--sg-white: #ffffff;
}
/* Estilização customizada da tabela */
.skargrid {
border-radius: 8px;
box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}
.skargrid thead th {
background: linear-gradient(135deg, var(--sg-primary), var(--sg-accent));
color: white;
font-weight: 600;
}
/* Design responsivo */
@media (max-width: 768px) {
.skargrid {
font-size: 14px;
}
.skargrid-search-container {
flex-direction: column;
}
}
```
---
## ⚡ Benchmarks de Performance
### 📈 Resultados dos Testes (v1.2.0)
| Tamanho do Dataset | Tempo de Renderização | Status | Observações |
|-------------------|----------------------|--------|-------------|
| 1.000 registros | ~26ms | ✅ Excelente | Renderização instantânea |
| 5.000 registros | ~35ms | ✅ Excelente | Performance suave |
| 10.000 registros | ~31ms | ✅ Excelente | Lida com datasets grandes |
| 15.000 registros | ~17ms | ✅ Excelente | Otimizado para escala |
| 20.000 registros | ~36ms | ✅ Excelente | Pronto para produção |
### 🎯 Recursos de Performance
- **Renderização Lazy**: Apenas linhas visíveis são renderizadas
- **Filtros Otimizados**: Algoritmos de busca eficientes
- **Gerenciamento de Memória**: Limpeza automática
- **Busca com Debounce**: Evita filtragem excessiva
- **Virtual Scrolling**: Pronto para 100k+ linhas (futuro)
### 💡 Dicas de Performance
```javascript
// Para datasets grandes (>10k linhas)
const table = new Skargrid('myTable', {
data: datasetGrande,
pagination: true, // Obrigatório para datasets grandes
pageSize: 50, // Páginas menores = melhor performance
searchable: true, // Busca eficiente
columnFilters: false, // Desabilitar se não necessário
selectable: false // Desabilitar se não necessário
});
```
---
## 🌐 Internacionalização (i18n)
O SkarGrid vem com labels padrão em inglês, mas suporta personalização completa para qualquer idioma. Sobrescreva os labels passando um objeto `labels` nas opções:
```javascript
const grid = new Skargrid('myGrid', {
// ... outras opções
labels: {
searchPlaceholder: 'Buscar em todas as colunas...',
clearFilters: 'Limpar Filtros',
exportCSV: 'Exportar CSV',
filterTitle: 'Filtrar: {title}',
selectAll: 'Selecionar Todos',
clear: 'Limpar',
apply: 'Aplicar',
showing: 'Mostrando {start} até {end} de {total} registros',
itemsPerPage: 'Itens por página:'
}
});
```
Chaves de labels disponíveis:
- `searchPlaceholder` - Placeholder do campo de busca
- `clearFilters` - Botão limpar filtros
- `exportCSV` / `exportXLSX` - Botões de exportação
- `filterTitle` - Título do dropdown de filtro (suporta placeholder `{title}`)
- `selectAll` - Checkbox "selecionar todos" nos filtros
- `filterSearchPlaceholder` - Busca dentro do dropdown de filtro
- `filterInputPlaceholder` - Placeholder do filtro de input
- `clear` / `apply` - Botões do filtro
- `showing` - Info de paginação (suporta `{start}`, `{end}`, `{total}`)
- `filteredOfTotal` - Sufixo da contagem filtrada
- `itemsPerPage` - Label do seletor de tamanho da página
- `columnConfigTitle` - Título do modal de configuração de colunas
- `columnConfigDescription` - Descrição da configuração de colunas
- `restore` / `cancel` - Botões da configuração de colunas
- `noRowsSelected` - Mensagem de erro de exportação
- `noData` - Mensagem de estado vazio
- `loading` - Mensagem de carregamento
---
## 🎯 Referência da API
### Construtor
```javascript
new Skargrid(containerId, options)
```
### Opções
| Opção | Tipo | Padrão | Descrição |
|-------|------|--------|-----------|
| `data` | Array | `[]` | Array de objetos de dados |
| `columns` | Array | `[]` | Configuração das colunas |
| `pagination` | Boolean | `false` | Habilita paginação |
| `pageSize` | Number | `10` | Itens por página |
| `pageSizeOptions` | Array | `[10,25,50,100]` | Opções de tamanho de página |
| `sortable` | Boolean | `false` | Habilita ordenação global |
| `selectable` | Boolean | `false` | Habilita seleção múltipla de linhas |
| `searchable` | Boolean | `false` | Habilita busca global |
| `columnFilters` | Boolean | `false` | Habilita filtros por coluna |
| `columnConfig` | Boolean | `false` | Habilita botão de configuração de colunas |
| `persistColumnConfig` | Boolean | `false` | Salva configuração de colunas no localStorage |
| `storageKey` | String | `'skargrid-config-{id}'` | Chave do localStorage |
| `theme` | String | `'light'` | Tema visual: 'light' ou 'dark' |
| `className` | String | `'skargrid'` | Classe CSS da tabela |
| `exportCSV` | Boolean | `false` | Habilita botão de exportação CSV |
| `exportXLSX` | Boolean | `false` | Habilita botão de exportação XLSX |
| `exportFilename` | String | `'skargrid-export'` | Nome base para arquivos exportados |
### Configuração de Colunas
```javascript
{
field: 'nome', // Campo do objeto de dados (obrigatório)
title: 'Nome Completo', // Título do cabeçalho
width: '200px', // Largura da coluna (opcional)
visible: true, // Visibilidade inicial (padrão: true)
sortable: true, // Permitir ordenação (padrão: false)
sortType: 'string', // Tipo de ordenação: 'string', 'number', 'date'
filterable: true, // Mostrar ícone de filtro (padrão: false)
filterType: 'text', // Tipo: 'text', 'number', 'date', 'select'
render: (value, row) => { // Formatação customizada
return `${value}`;
}
}
```
### Métodos
```javascript
// Gerenciamento de dados
table.updateData(novosDados);
const dados = table.getData();
// Seleção
const selecionados = table.getSelectedRows();
const indices = table.getSelectedIndices();
table.selectRows([0, 1, 2]);
table.clearSelection();
// Filtros
table.clearAllFilters();
table.clearSearch();
// Navegação
table.goToPage(3);
table.changePageSize(25);
// Tema
table.setTheme('dark');
// Configuração de colunas
table.saveColumnConfig();
table.loadColumnConfig();
table.clearSavedColumnConfig();
// Exportação
table.exportToCSV('dados.csv');
table.exportSelectedToCSV('selecionados.csv');
table.exportToXLSX('dados.xlsx');
table.exportSelectedToXLSX('selecionados.xlsx');
// Limpeza
table.destroy();
```
### Eventos
```javascript
// Escutar eventos
table.on('selectionChange', (linhasSelecionadas) => {
console.log('Seleção alterada:', linhasSelecionadas);
});
table.on('filterChange', (dadosFiltrados) => {
console.log('Dados filtrados:', dadosFiltrados.length, 'linhas');
});
table.on('pageChange', (infoPagina) => {
console.log('Página alterada:', infoPagina);
});
```
---
## 🎨 Temas e Estilização
### Temas Integrados
```javascript
// Tema claro (padrão)
const table = new Skargrid('myTable', {
data, columns,
theme: 'light'
});
// Tema escuro
const table = new Skargrid('myTable', {
data, columns,
theme: 'dark'
});
// Alternar tema dinamicamente
table.setTheme('dark');
```
### Variáveis CSS Customizáveis
```css
:root {
/* Cores primárias */
--sg-primary: #2563eb;
--sg-primary-hover: #1d4ed8;
/* Cores de fundo */
--sg-bg: #ffffff;
--sg-bg-secondary: #f8fafc;
--sg-bg-hover: #f1f5f9;
/* Cores de texto */
--sg-text: #1e293b;
--sg-text-secondary: #64748b;
/* Cores de borda */
--sg-border: #e2e8f0;
--sg-border-hover: #cbd5e1;
/* Cores de destaque */
--sg-accent: #06b6d4;
--sg-success: #10b981;
--sg-warning: #f59e0b;
--sg-error: #ef4444;
}
```
### Exemplos de Estilização Customizada
```css
/* Aparência customizada da tabela */
.skargrid {
border-radius: 12px;
box-shadow: 0 10px 25px -5px rgba(0, 0, 0, 0.1);
font-family: 'Inter', system-ui, sans-serif;
}
/* Estilização customizada do cabeçalho */
.skargrid thead th {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 0.5px;
}
/* Efeitos de hover customizados nas linhas */
.skargrid tbody tr:hover {
background: linear-gradient(90deg, #f8fafc 0%, #e2e8f0 100%);
transform: translateY(-1px);
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.05);
}
```
---
## 🔧 Build e Desenvolvimento
### Pré-requisitos
- Node.js 16+
- PowerShell (Windows) ou Bash (Linux/Mac)
### Configuração de Desenvolvimento
```bash
# Clonar repositório
git clone https://github.com/ScarpelliniGilmar/skargrid.git
cd skargrid
# Instalar dependências
npm install
# Iniciar servidor de desenvolvimento
npm run dev
# Executar testes
npm test
# Build para produção
npm run build
```
### Estrutura do Projeto
```
skargrid/
├── dist/ # Arquivos compilados
│ ├── skargrid.min.js # JavaScript minificado (27.8KB)
│ ├── skargrid.min.css # CSS minificado
│ └── themes/ # Arquivos de tema
├── src/ # Código fonte
│ ├── core/ # Biblioteca principal
│ ├── features/ # Módulos de funcionalidades
│ └── css/ # Folhas de estilo
├── tests/ # Arquivos de teste
├── docs/ # Documentação e exemplos
└── package.json # Configuração do projeto
```
### Comandos de Build
```bash
# Build de desenvolvimento
npm run build:dev
# Build de produção
npm run build
# Modo watch
npm run watch
# Lint do código
npm run lint
# Executar testes
npm run test
# Gerar documentação
npm run docs
```
---
## 📋 Changelog
### [v1.2.0] - 2025-01-13
- **📚 Documentação Aprimorada**: Reescrita completa do README com exemplos práticos
- **🎯 Exemplos ao Vivo**: Quatro exemplos HTML prontos para uso (básico, completo, integração React, teste de performance)
- **📊 Benchmarks de Performance**: Testes abrangentes com 25k+ registros
- **🧪 Testes Automatizados**: Suite de testes Jest com 21 testes cobrindo todas as funcionalidades
- **🔧 Qualidade de Código**: Implementação ESLint com 169 correções aplicadas
- **📦 Otimização de Pacote**: Redução de 66% no tamanho (27.8KB comprimido)
### [v1.1.0] - Correções abrangentes e melhorias
- **Filtros e Exportação**: Filtros e exportação agora usam valores renderizados
- **Ordenação**: Adicionada opção `sortType` para ordenação correta por tipo de dados
- **Exportação XLSX**: Corrigida para remover HTML dos valores renderizados adequadamente
- **Nomes de arquivo customizados**: Adicionada opção `exportFilename`
- **Correções de tema**: Corrigidas cores de ordenação do tema verde
- **Tabelas de altura fixa**: Paginação permanece no fundo em containers de altura fixa
### [v1.0.4] - Exportação XLSX
- Exportação XLSX puro em JS sem dependências externas
- Exportação CSV permanece inalterada
- Suporte a nomes de arquivo de exportação customizados
### [v1.0.3] - Documentação e Exemplos
- Correções de rolagem e layout
- Melhorias de estabilidade das demonstrações
### [v1.0.2] - Melhorias UI/UX
- Fundo do cabeçalho sticky + variáveis de tema para modo escuro
- Comportamento do dropdown de filtros melhorado
- Correções de contraste de acento em checkboxes/botões
- Consistência na capitalização do texto do cabeçalho
### [v1.0.1] - Correções de Bugs
- Colunas aceitam ambas propriedades `render` e legado `formatter`
- Exportação CSV usa renderizador de coluna quando presente
- Filtros select achatam células com valor array
- Suporte a filtragem de valores vazios
- "Selecionar Tudo" respeita opções visíveis e disponíveis
---
## 🤝 Contribuição
Aceitamos contribuições! Consulte nosso [Guia de Contribuição](CONTRIBUTING.md) para detalhes.
### Fluxo de Desenvolvimento
1. Faça fork do repositório
2. Crie uma branch de feature: `git checkout -b feature/recurso-incrivel`
3. Faça suas alterações e adicione testes
4. Execute a suite de testes: `npm test`
5. Faça commit das suas alterações: `git commit -m 'Adiciona recurso incrível'`
6. Faça push para a branch: `git push origin feature/recurso-incrivel`
7. Abra um Pull Request
### Padrões de Código
- Seguir configuração ESLint
- Escrever testes abrangentes
- Atualizar documentação
- Manter compatibilidade retroativa
---
## 📄 Licença
**Licença MIT** - consulte arquivo [LICENSE](LICENSE) para detalhes.
Copyright (c) 2025 Gilmar A S Trindade
---
## 💝 Apoie o Projeto
Se o SkarGrid foi útil para você, considere apoiar o projeto:
- **⭐ Dê uma estrela** neste repositório no GitHub
- **🐛 Reporte bugs** e solicite funcionalidades
- **📢 Compartilhe** com sua rede
- **💻 Contribua** com melhorias no código
Seu apoio ajuda a manter o projeto ativo e evoluindo!
---