Deslizar para atualizar

A ação deslizar para atualizar permite a um usuário extrair uma lista de dados com toque para recuperar mais dados. Deslizar para atualizar é amplamente usado em dispositivos com tela touch. Você pode usar a API mostrada aqui para implementar a ação deslizar para atualizar em seu aplicativo.

Esse é o controle correto?

Use a ação deslizar para atualizar quando você tiver uma lista ou uma grade de dados que o usuário talvez queira atualizar regularmente e será provável que seu aplicativo seja executado em dispositivos móveis touch-first.

Você também pode usar o RefreshVisualizer para criar uma experiência consistente de atualização que é invocada de outras maneiras, como por um botão Atualizar.

Controles de atualização

Deslizar para atualizar é habilitado por dois controles.

• RefreshContainer – um ContentControl que fornece um wrapper para a experiência de deslizar para atualizar. Ele manipula as interações de toque e gerencia o estado do seu visualizador interno de atualização.
• RefreshVisualizer – encapsula a visualização de atualização explicada na próxima seção.

O controle principal é o RefreshContainer, que você insere como um wrapper em torno do conteúdo que o usuário desliza para disparar uma atualização. RefreshContainer só funciona com toque, portanto, recomendamos que você também tenha um botão de atualização disponível para os usuários que não têm uma interface de toque. Você pode posicionar o botão Atualizar em uma localização adequada no aplicativo, em uma barra de comandos ou em uma localização próxima à superfície sendo atualizada.

Visualização de atualização

A visualização de atualização padrão é um controle giratório de progresso circular que é usado para comunicação para quando uma atualização ocorrer e o progresso da atualização depois que ele for iniciado. O visualizador de atualização tem cinco estados.

A distância que o usuário precisa deslizar para baixo em uma lista para iniciar uma atualização é chamada de limite. O Estado do visualizador é determinado pelo estado da ação de deslizar que diz respeito a esse limite. Os valores possíveis estão contidos na enumeração RefreshVisualizerState.

Idle

O estado padrão do visualizador é Ocioso. O usuário não está interagindo com o RefreshContainer por toque e não há uma atualização em andamento.

Visualmente, não há nenhuma evidência do visualizador de atualização.

Interação

Quando o usuário deslizar a lista na direção especificada pela propriedade PullDirection, antes de o limite ser alcançado, o visualizador estará no estado Interação.

• Se o usuário liberar o controle nesse estado, o controle retornará para Ocioso.

  

  Visualmente, o ícone é exibido como desabilitado (60% de opacidade). Além disso, o ícone gira uma rotação completa com a ação de rolagem.

• Se o usuário desliza a lista para depois do limite, o visualizador faz a transição de Interação para Pendente.

  

  Visualmente, o ícone alterna para 100% de opacidade e pulsos no tamanho de até 150% e, depois, retorna para 100% do tamanho durante a transição.

Pendente

Quando o usuário desliza a lista para além do limite, o visualizador fica no estado Pendente.

• Se o usuário move a lista de volta acima do limite sem liberá-lo, ele retorna para o estado Interação.
• Se o usuário libera a lista, uma solicitação de atualização é iniciada e faz a transição para o estado Em atualização.

Visualmente, o ícone é 100% em tamanho e opacidade. Nesse estado, o ícone continua a se mover para baixo com a ação de rolagem, mas não gira.

Atualizando

Quando o usuário libera o visualizador além do limite, ele fica no estado Em atualização.

Quando esse estado é inserido, o evento RefreshRequested é acionado. Este é o sinal para começar a atualização de conteúdo do aplicativo. Argumentos de evento (RefreshRequestedEventArgs) contêm um objeto Deferral, que você deve executar um identificador para o manipulador de eventos. Em seguida, você deverá marcar o adiamento como concluído quando seu código para realizar a atualização tiver sido concluído.

Quando a atualização for concluída, o visualizador retornará para o estado Ocioso.

Visualmente, o ícone volta para a localização do limite e gira para a duração da atualização. Este giro é usado para mostrar o progresso da atualização e é substituído pela animação do conteúdo de entrada.

Espiar

Quando o usuário desliza na direção de atualização de uma posição inicial em que uma atualização não é permitida, o visualizador entra no estado Espiar. Isso normalmente acontece quando o ScrollViewer não está na posição 0 quando o usuário começa a deslizar.

• Se o usuário liberar o controle nesse estado, o controle retornará para Ocioso.

Direção de deslizamento

Por padrão, o usuário desliza uma lista de cima para baixo para iniciar uma atualização. Se você tiver uma lista ou grade com uma orientação diferente, deverá alterar a direção de deslizamento do contêiner de atualização para corresponder.

A propriedade PullDirection usa um destes valores de RefreshPullDirection : BottomToTop, TopToBottom, RightToLeft ou LeftToRight.

Quando você altera a direção de deslizamento, a posição inicial do controle giratório de progresso do visualizador gira automaticamente para que a seta seja iniciada na posição apropriada para a direção de deslizamento. Se necessário, você pode alterar a propriedade RefreshVisualizer.Orientation para substituir o comportamento automático. Na maioria dos casos, recomendamos deixar o valor padrão como Automático.

UWP e WinUI 2

Os controles de atualização para aplicativos UWP são incluídos como parte do WinUI 2. Para obter mais informações, incluindo instruções de instalação, confira WinUI 2. As APIs para esse controle existem nos namespaces Windows.UI.Xaml.Controls (UWP) e Microsoft.UI.Xaml.Controls (WinUI).

É recomendável usar a WinUI 2 mais recente para obter os estilos, modelos e recursos mais atuais para todos os controles.

Para usar o código neste artigo com a WinUI 2, use um alias em XAML (usamos muxc) para representar as APIs da Biblioteca de Interface do Usuário do Windows incluídas em seu projeto. Confira Introdução à WinUI 2 para obter mais informações.

xmlns:muxc="using:Microsoft.UI.Xaml.Controls"

<muxc:RefreshContainer />

Implementar pull-to-refresh

O aplicativo Galeria da WinUI 3 inclui exemplos interativos da maioria dos controles, recursos e funcionalidades da WinUI 3. Obtenha o aplicativo na Microsoft Store ou o código-fonte no GitHub

Adicionar a funcionalidade deslizar para atualizar a uma lista requer apenas algumas etapas.

1. Encapsule sua lista em um controle RefreshContainer.
2. Manipule o evento RefreshRequested para atualizar seu conteúdo.
3. Opcionalmente, inicie uma atualização chamando RequestRefresh (por exemplo, com o clique de um botão).

Solicitar uma atualização

O contêiner de atualização manipula interações de toque para permitir que o usuário atualize conteúdo por toque. Recomendamos que você forneça outras funcionalidades para interfaces não sensíveis ao toque, como um controle de voz ou botão de atualização.

Para iniciar uma atualização, chame o método RequestRefresh.

// See the Examples section for the full code.
private void RefreshButtonClick(object sender, RoutedEventArgs e)
{
    RefreshContainer.RequestRefresh();
}

Quando você chama RequestRefresh, o estado do visualizador vai diretamente de Ocioso para Em atualização.

Manipular uma solicitação de atualização

Para obter conteúdo atualizado quando necessário, manipule o evento RefreshRequested. No manipulador de eventos, você precisará de código específico ao seu aplicativo para obter o conteúdo atualizado.

Os argumentos de evento (RefreshRequestedEventArgs) contêm um objeto Deferral. Obtenha um identificador para o adiamento no manipulador de eventos. Em seguida, marque o adiamento como concluído quando seu código para executar a atualização for concluído.

// See the Examples section for the full code.
private async void RefreshContainer_RefreshRequested(RefreshContainer sender, RefreshRequestedEventArgs args)
{
    // Respond to a request by performing a refresh and using the deferral object.
    using (var RefreshCompletionDeferral = args.GetDeferral())
    {
        // Do some async operation to refresh the content

         await FetchAndInsertItemsAsync(3);

        // The 'using' statement ensures the deferral is marked as complete.
        // Otherwise, you'd call
        // RefreshCompletionDeferral.Complete();
        // RefreshCompletionDeferral.Dispose();
    }
}

Responder a alterações de estado

É possível responder a alterações no estado do visualizador, se necessário. Por exemplo, para evitar várias solicitações de atualização, você poderá desabilitar um botão de atualização enquanto o visualizador estiver sendo atualizado.

// See the Examples section for the full code.
private void Visualizer_RefreshStateChanged(RefreshVisualizer sender, RefreshStateChangedEventArgs args)
{
    // Respond to visualizer state changes.
    // Disable the refresh button if the visualizer is refreshing.
    if (args.NewState == RefreshVisualizerState.Refreshing)
    {
        RefreshButton.IsEnabled = false;
    }
    else
    {
        RefreshButton.IsEnabled = true;
    }
}

Como usar um ScrollViewer em um RefreshContainer

Este exemplo mostra como usar a ação deslizar para atualizar com um visualizador de rolagem.

<RefreshContainer>
    <ScrollViewer VerticalScrollMode="Enabled"
                  VerticalScrollBarVisibility="Auto"
                  HorizontalScrollBarVisibility="Auto">
 
        <!-- Scrollviewer content -->

    </ScrollViewer>
</RefreshContainer>

Como adicionar a ação deslizar para atualizar a um ListView

Este exemplo mostra como usar a ação deslizar para atualizar com uma exibição de lista.

<StackPanel Margin="0,40" Width="280">
    <CommandBar OverflowButtonVisibility="Collapsed">
        <AppBarButton x:Name="RefreshButton" Click="RefreshButtonClick"
                      Icon="Refresh" Label="Refresh"/>
        <CommandBar.Content>
            <TextBlock Text="List of items" 
                       Style="{StaticResource TitleTextBlockStyle}"
                       Margin="12,8"/>
        </CommandBar.Content>
    </CommandBar>

    <RefreshContainer x:Name="RefreshContainer">
        <ListView x:Name="ListView1" Height="400">
            <ListView.ItemTemplate>
                <DataTemplate x:DataType="local:ListItemData">
                    <Grid Height="80">
                        <Grid.RowDefinitions>
                            <RowDefinition Height="Auto" />
                            <RowDefinition Height="Auto" />
                            <RowDefinition Height="*" />
                        </Grid.RowDefinitions>
                        <TextBlock Text="{x:Bind Path=Header}"
                                   Style="{StaticResource SubtitleTextBlockStyle}"
                                   Grid.Row="0"/>
                        <TextBlock Text="{x:Bind Path=Date}"
                                   Style="{StaticResource CaptionTextBlockStyle}"
                                   Grid.Row="1"/>
                        <TextBlock Text="{x:Bind Path=Body}"
                                   Style="{StaticResource BodyTextBlockStyle}"
                                   Grid.Row="2"
                                   Margin="0,4,0,0" />
                    </Grid>
                </DataTemplate>
            </ListView.ItemTemplate>
        </ListView>
    </RefreshContainer>
</StackPanel>

public sealed partial class MainPage : Page
{
    public ObservableCollection<ListItemData> Items { get; set; } 
        = new ObservableCollection<ListItemData>();

    public MainPage()
    {
        this.InitializeComponent();

        Loaded += MainPage_Loaded;
        ListView1.ItemsSource = Items;
    }

    private async void MainPage_Loaded(object sender, RoutedEventArgs e)
    {
        Loaded -= MainPage_Loaded;
        RefreshContainer.RefreshRequested += RefreshContainer_RefreshRequested;
        RefreshContainer.Visualizer.RefreshStateChanged += Visualizer_RefreshStateChanged;

        // Add some initial content to the list.
        await FetchAndInsertItemsAsync(2);
    }

    private void RefreshButtonClick(object sender, RoutedEventArgs e)
    {
        RefreshContainer.RequestRefresh();
    }

    private async void RefreshContainer_RefreshRequested(RefreshContainer sender, RefreshRequestedEventArgs args)
    {
        // Respond to a request by performing a refresh and using the deferral object.
        using (var RefreshCompletionDeferral = args.GetDeferral())
        {
            // Do some async operation to refresh the content

            await FetchAndInsertItemsAsync(3);

            // The 'using' statement ensures the deferral is marked as complete.
            // Otherwise, you'd call
            // RefreshCompletionDeferral.Complete();
            // RefreshCompletionDeferral.Dispose();
        }
    }

    private void Visualizer_RefreshStateChanged(RefreshVisualizer sender, RefreshStateChangedEventArgs args)
    {
        // Respond to visualizer state changes.
        // Disable the refresh button if the visualizer is refreshing.
        if (args.NewState == RefreshVisualizerState.Refreshing)
        {
            RefreshButton.IsEnabled = false;
        }
        else
        {
            RefreshButton.IsEnabled = true;
        }
    }

    // App specific code to get fresh data.
    private async Task FetchAndInsertItemsAsync(int updateCount)
    {
        for (int i = 0; i < updateCount; ++i)
        {
            // Simulate delay while we go fetch new items.
            await Task.Delay(1000);
            Items.Insert(0, GetNextItem());
        }
    }

    private ListItemData GetNextItem()
    {
        return new ListItemData()
        {
            Header = "Header " + DateTime.Now.Second.ToString(),
            Date = DateTime.Now.ToLongDateString(),
            Body = DateTime.Now.ToLongTimeString()
        };
    }
}

public class ListItemData
{
    public string Header { get; set; }
    public string Date { get; set; }
    public string Body { get; set; }
}

Obter o código de exemplo

• Exemplo de Galeria da WinUI: veja todos os controles XAML em um formato interativo.

Artigos relacionados

• Interações por toque
• Exibição de lista e exibição de grade
• Contêineres e modelos de itens
• Animações de expressão