Virtual scroll do Quasar explicado

Entender o virtual scroll do Quasar somente com a documentação foi um desafio para mim. Apenas observando o componente em funcionamento que a lógica por trás do gerenciamento de scroll realmente começou a fazer sentido.

Para que você não precise perder esse tempo, reuni neste artigo os principais pontos que a documentação oficial não explica com tanto detalhe.

O que é virtual scroll?

Virtual scroll é uma técnica de programação front-end utilizada para melhorar o desempenho de listas com grandes volumes de itens.
Nesses cenários, o principal problema é lidar com um número muito grande de nós no DOM, o que pode causar lentidão e alto consumo de memória.

A solução é manter no DOM apenas um conjunto limitado de nós, correspondente aos itens visíveis para o usuário naquele momento.

Conforme o usuário rola a lista, o algoritmo calcula quais itens devem estar visíveis e então reutiliza, atualiza ou reposiciona os nós existentes para representar os novos itens esperados.

Outro detalhe importante é que implementações de virtual scroll mantêm, além dos nós visíveis, ¨nós extras antes e depois da área visível. Isso reduz a sensação de travamento durante a rolagem e esconde o recálculo que acontece nos bastidores.

O componente QVirtualScroll do Quasar

No ecossistema do Quasar, essa técnica aparece por meio do componente QVirtualScroll, responsável por implementar o virtual scroll do Quasar tanto em modo de lista quanto de tabela, controlados pelo prop type.

De forma geral, o uso envolve alguns pontos essenciais:

1. O q-virtual-scroll precisa ter altura definida (com height ou max-height, por exemplo);
2. A lista de dados deve ser passada pelo prop items;
3. O conteúdo de cada item é renderizado no slot default, normalmente usando:

• q-item no modo lista;
• tr no modo tabela.

4. Pelo scoped slot, é possível acessar:

• os dados do item;
• o index, que deve ser usado como key do elemento renderizado.

Como o virtual scroll do Quasar funciona e como ajustá-lo?

Embora funcione bem com a configuração padrão, alguns cenários exigem ajustes finos.
Isso é feito por meio de seis props principais, que representam conceitos centrais da virtualização usada pelo Quasar.

Tamanho do item

O tamanho do item corresponde à altura (listas verticais) ou largura (horizontais) de cada elemento.

Esse valor permite calcular quantos itens cabem na área visível:

itens visíveis = tamanho da área de scroll ÷ tamanho do item

Exemplo

• área de scroll: 500 px
• altura do item: 50 px

Resultado: 10 itens visíveis.

O virtual scroll do Quasar mede esse valor automaticamente após a renderização inicial, mas também é possível informar um tamanho aproximado usando: virtual-scroll-item-size

Definir um valor próximo do real melhora o comportamento inicial da rolagem.

Percentual de nós extras antes e depois

Para evitar que o usuário perceba recálculos durante o scroll, o virtual scroll do Quasar mantém itens adicionais fora da área visível.

Por padrão, essa quantidade equivale a 100% dos itens visíveis.

No exemplo com 10 itens visíveis:

• 10 antes
• 10 visíveis
• 10 depois

Total no DOM: 30 itens.

Esses valores são configurados por:

• virtual-scroll-slice-ratio-before
• virtual-scroll-slice-ratio-after

Onde:

• 1 = 100%
• 0.5 = 50%

Slice (fatia renderizada)

O termo slice representa a porção total da lista mantida no DOM:

itens antes + itens visíveis + itens depois

O prop: virtual-scroll-slice-size define a quantidade mínima de itens nessa fatia.

O valor final respeita a proporção before : visible : after.

Exemplo

• proporção esperada → 10 : 10 : 10 = 30
• slice-size = 31

Como 31 quebra a proporção, o próximo valor válido é: 33 (11 : 11 : 11).

Regiões sticky

Em algumas situações, é necessário manter cabeçalhos ou rodapés fixos, como:

• títulos de colunas
• totais de uma lista

Se essas regiões fizerem parte da área de scroll, elas prejudicam o cálculo de itens visíveis.

Para resolver isso, o virtual scroll do Quasar permite informar seus tamanhos em pixels:

• virtual-scroll-sticky-size-start
• virtual-scroll-sticky-size-end

Assim, o cálculo considera apenas a área realmente rolável.

Resumindo…

(Tabela retirada da documentação do Quasar e imagem alterada para demonstrar cada parte de uma lista com virtual scroll)

Conclusão

O virtual scroll do Quasar mostra, na prática, como é possível trabalhar com grandes volumes de dados sem comprometer o desempenho da interface. Ao manter no DOM apenas uma fatia controlada de itens — incluindo a área visível e regiões extras ao redor dela — o componente reduz o custo de renderização e garante uma rolagem fluida.

Compreender conceitos como tamanho do item, proporção de nós extras, slice renderizada e regiões sticky permite ajustar o comportamento do componente para diferentes cenários.