Virtualização do componente do Razor ASP.NET Core

RefreshDataAsync atualiza os dados de um componente Virtualize<TItem> sem gerar uma nova renderização. Se RefreshDataAsync for invocado de um manipulador de eventos Blazor ou de um método de ciclo de vida do componente, o disparo de uma renderização não será necessário porque ela será disparada automaticamente no final do manipulador de eventos ou do método de ciclo de vida. Se RefreshDataAsync for disparado separadamente de uma tarefa ou evento em segundo plano, como no delegado ForecastUpdated a seguir, chame StateHasChanged para atualizar a interface do usuário no final da tarefa ou evento em segundo plano:

<Virtualize ... @ref="virtualizeComponent">
    ...
</Virtualize>

...

private Virtualize<FetchData>? virtualizeComponent;

protected override void OnInitialized()
{
    WeatherForecastSource.ForecastUpdated += async () => 
    {
        await InvokeAsync(async () =>
        {
            await virtualizeComponent?.RefreshDataAsync();
            StateHasChanged();
        });
    });
}

No exemplo anterior:

• RefreshDataAsync é chamado primeiro para obter novos dados para o componente Virtualize<TItem>.
• StateHasChanged é chamado para renderizar novamente o componente.

Conteúdo vazio

Use o parâmetro EmptyContent para fornecer conteúdo quando o componente tiver sido carregado e Items estiver vazio ou ItemsProviderResult<TItem>.TotalItemCount for zero.

EmptyContent.razor:

@page "/empty-content"

<PageTitle>Empty Content</PageTitle>

<h1>Empty Content Example</h1>

<Virtualize Items="stringList">
    <ItemContent>
        <p>
            @context
        </p>
    </ItemContent>
    <EmptyContent>
        <p>
            There are no strings to display.
        </p>
    </EmptyContent>
</Virtualize>

@code {
    private List<string>? stringList;

    protected override void OnInitialized() => stringList ??= new();
}

@page "/empty-content"

<PageTitle>Empty Content</PageTitle>

<h1>Empty Content Example</h1>

<Virtualize Items="stringList">
    <ItemContent>
        <p>
            @context
        </p>
    </ItemContent>
    <EmptyContent>
        <p>
            There are no strings to display.
        </p>
    </EmptyContent>
</Virtualize>

@code {
    private List<string>? stringList;

    protected override void OnInitialized() => stringList ??= new();
}

Altere o método OnInitialized lambda para ver as cadeias de caracteres de exibição do componente:

protected override void OnInitialized() =>
    stringList ??= new() { "Here's a string!", "Here's another string!" };

Suporte à rolagem de teclado

Para permitir que os usuários rolem o conteúdo virtualizado usando o teclado, verifique se os elementos virtualizados ou o próprio contêiner de rolagem são focalizáveis. Se você não executar essa etapa, a rolagem de teclado não funcionará em navegadores baseados em Chromium.

Por exemplo, você pode usar um atributo tabindex no contêiner de rolagem:

<div style="height:500px; overflow-y:scroll" tabindex="-1">
    <Virtualize Items="allFlights">
        <div class="flight-info">...</div>
    </Virtualize>
</div>

Para saber mais sobre o significado do valor tabindex -1, 0ou outros valores, consulte tabindex (documentação do MDN).

Estilos avançados e detecção de rolagem

O componente Virtualize<TItem> foi projetado apenas para dar suporte a mecanismos de layout de elemento específicos. Para entender quais layouts de elemento funcionam corretamente, o seguinte explica como Virtualize detecta quais elementos devem estar visíveis para exibição no local correto.

Se o código-fonte for semelhante ao seguinte:

<div style="height:500px; overflow-y:scroll" tabindex="-1">
    <Virtualize Items="allFlights" ItemSize="100">
        <div class="flight-info">Flight @context.Id</div>
    </Virtualize>
</div>

Em runtime, o componente Virtualize<TItem> renderiza uma estrutura DOM semelhante à seguinte:

<div style="height:500px; overflow-y:scroll" tabindex="-1">
    <div style="height:1100px"></div>
    <div class="flight-info">Flight 12</div>
    <div class="flight-info">Flight 13</div>
    <div class="flight-info">Flight 14</div>
    <div class="flight-info">Flight 15</div>
    <div class="flight-info">Flight 16</div>
    <div style="height:3400px"></div>
</div>

O número real de linhas renderizadas e o tamanho dos espaçadores variam de acordo com o estilo e o tamanho da coleção Items. No entanto, observe que há elementos espaçadores div injetados antes e depois do conteúdo. Isso tem duas finalidades:

• Fornecer um deslocamento antes e depois do conteúdo, fazendo com que os itens visíveis no momento apareçam no local correto no intervalo de rolagem e no próprio intervalo de rolagem para representar o tamanho total de todo o conteúdo.
• Detectar quando o usuário está rolando além do intervalo visível atual, o que significa que diferentes conteúdos devem ser renderizados.

Os elementos do espaçador usam internamente um Observador de Interseção para receber notificação quando estão ficando visíveis. Virtualize depende do recebimento desses eventos.

Virtualize funciona sob as seguintes condições:

• Todos os itens de conteúdo renderizados, incluindo conteúdo de espaço reservado, têm altura idêntica. Isso possibilita calcular qual conteúdo corresponde a uma determinada posição de rolagem sem primeiro buscar cada item de dados e renderizar os dados em um elemento DOM.

• Os espaçadores e as linhas de conteúdo são renderizados em uma única pilha vertical com cada item preenchendo toda a largura horizontal. Em casos típicos, Virtualize trabalha com elementos div. Se você estiver usando o CSS para criar um layout mais avançado, tenha em mente os seguintes requisitos:

  • O estilo de contêiner de rolagem requer um display com qualquer um dos seguintes valores:
    • block (o padrão para um div).
    • table-row-group (o padrão para um tbody).
    • flex com flex-direction definido como column. Certifique-se de que os filhos imediatos do componente Virtualize<TItem> não sejam reduzidos sob regras flexíveis. Por exemplo, adicione .mycontainer > div { flex-shrink: 0 }.
  • O estilo de linha de conteúdo requer um display com um dos seguintes valores:
    • block (o padrão para um div).
    • table-row (o padrão para um tr).
  • Não use CSS para interferir no layout dos elementos do espaçador. Os elementos do espaçador têm um valor display de block, exceto se o pai for um grupo de linhas de tabela, nesse caso, eles assumem table-row como valor padrão. Não tente influenciar a largura ou a altura do elemento do espaçador, inclusive fazendo com que eles tenham uma borda ou pseudo-elementos content.

Qualquer abordagem que impeça que os espaçadores e elementos de conteúdo sejam renderizados como uma única pilha vertical ou faça com que os itens de conteúdo variem de altura, impede o funcionamento correto do componente Virtualize<TItem>.

O componente Virtualize<TItem> dá suporte ao uso do documento em si como a raiz de rolagem, como uma alternativa para ter algum outro elemento com overflow-y: scroll. No exemplo a seguir, os elementos <html> ou <body> são estilizados em um componente com overflow-y: scroll:

<HeadContent>
    <style>
        html, body { overflow-y: scroll }
    </style>
</HeadContent>

O componente Virtualize<TItem> dá suporte ao uso do documento em si como a raiz de rolagem, como uma alternativa para ter algum outro elemento com overflow-y: scroll. Ao usar o documento como a raiz de rolagem, evite estilizar os elementos <html> ou <body> com overflow-y: scroll porque faz com que o observador de interseção trate a altura rolável completa da página como a região visível, em vez de apenas o visor de janela.

Você pode reproduzir esse problema criando uma grande lista virtualizada (por exemplo, 100.000 itens) e tentando usar o documento como a raiz de rolagem com html { overflow-y: scroll } nos estilos CSS da página. Embora possa funcionar corretamente às vezes, o navegador tenta renderizar todos os 100.000 itens pelo menos uma vez no início da renderização, o que pode causar um bloqueio na guia do navegador.

Para contornar esse problema antes do lançamento do .NET 7, evite estilizar elementos <html>/<body> com overflow-y: scroll ou adote uma abordagem alternativa. No exemplo a seguir, a altura do elemento <html> é definida como pouco mais de 100% da altura do visor:

<HeadContent>
    <style>
        html { min-height: calc(100vh + 0.3px) }
    </style>
</HeadContent>

O componente Virtualize<TItem> dá suporte ao uso do documento em si como a raiz de rolagem, como uma alternativa para ter algum outro elemento com overflow-y: scroll. Ao usar o documento como a raiz de rolagem, evite estilizar os elementos <html> ou <body> com overflow-y: scroll pois faz com que a altura rolável completa da página seja tratada como a região visível, em vez de apenas o visor de janela.

Você pode reproduzir esse problema criando uma grande lista virtualizada (por exemplo, 100.000 itens) e tentando usar o documento como a raiz de rolagem com html { overflow-y: scroll } nos estilos CSS da página. Embora possa funcionar corretamente às vezes, o navegador tenta renderizar todos os 100.000 itens pelo menos uma vez no início da renderização, o que pode causar um bloqueio na guia do navegador.

Para contornar esse problema antes do lançamento do .NET 7, evite estilizar elementos <html>/<body> com overflow-y: scroll ou adote uma abordagem alternativa. No exemplo a seguir, a altura do elemento <html> é definida como pouco mais de 100% da altura do visor:

<style>
    html { min-height: calc(100vh + 0.3px) }
</style>

Controlar o nome da tag de elemento do espaçador

Se o componente Virtualize<TItem> for colocado dentro de um elemento que requer um nome de tag filho específico, SpacerElement permite que você obtenha ou defina o nome da tag do espaçador de virtualização. O valor padrão é div. Para o exemplo a seguir, o componente Virtualize<TItem> é renderizado dentro de um elemento do corpo da tabela (tbody), portanto, o elemento filho apropriado para uma linha de tabela (tr) é definido como o espaçador.

VirtualizedTable.razor:

@page "/virtualized-table"

<PageTitle>Virtualized Table</PageTitle>

<HeadContent>
    <style>
        html, body {
            overflow-y: scroll
        }
    </style>
</HeadContent>

<h1>Virtualized Table Example</h1>

<table id="virtualized-table">
    <thead style="position: sticky; top: 0; background-color: silver">
        <tr>
            <th>Item</th>
            <th>Another column</th>
        </tr>
    </thead>
    <tbody>
        <Virtualize Items="fixedItems" ItemSize="30" SpacerElement="tr">
            <tr @key="context" style="height: 30px;" id="row-@context">
                <td>Item @context</td>
                <td>Another value</td>
            </tr>
        </Virtualize>
    </tbody>
</table>

@code {
    private List<int> fixedItems = Enumerable.Range(0, 1000).ToList();
}

No exemplo anterior, a raiz do documento é usada como o contêiner de rolagem, portanto, os elementos html e body são estilizados com overflow-y: scroll. Para obter mais informações, consulte os seguintes recursos:

• Seção Virtualização no nível da raiz
• Controlar o conteúdo principal em aplicativos ASP.NET Core Blazor