Yenilemek için çekme

Aşağı çekerek yenileme, kullanıcının daha fazla veri almak için dokunma kullanarak veri listesini aşağı çekmesine olanak tanır. Dokunmatik ekranlı cihazlarda yukarı çekerek yenileme yaygın olarak kullanılır. Uygulamanızda çekme-yenileme uygulamak için burada gösterilen API'leri kullanabilirsiniz.

Doğru kontrol bu mu?

Verilerin düzenli olarak yenilenmesi istenebilecek bir liste veya kılavuzunuz varsa ve uygulamanız dokunmatik ekranlı cihazlarda çalışmaya yönelikse, yenilemek için aşağı çek bırak özelliğini kullanın.

RefreshVisualizer kullanarak, yenileme düğmesi gibi başka şekillerde çağrılan tutarlı bir yenileme deneyimi oluşturabilirsiniz.

Yenileme denetimleri

Çekme-yenileme 2 denetim tarafından etkinleştirilir.

• RefreshContainer - çekme-yenileme deneyimi için sarmalayıcı sağlayan bir ContentControl. Dokunma etkileşimlerini işler ve iç yenileme görselleştiricisinin durumunu yönetir.
• RefreshVisualizer- sonraki bölümde açıklanan yenileme görselleştirmesini kapsüller.

Ana denetim, kullanıcının yenilemeyi tetiklemek için çektiği içeriğin çevresine sarmalayıcı olarak yerleştirdiğiniz RefreshContainer'dir. RefreshContainer yalnızca dokunmayla çalıştığından, dokunmatik arabirimi olmayan kullanıcılar için de bir yenileme düğmesine sahip olmanız önerilir. Yenileme düğmesini uygulamadaki uygun bir konuma, komut çubuğuna veya yenilenen yüzeye yakın bir konuma konumlandırabilirsiniz.

Görselleştirmeyi yenileme

Varsayılan yenileme görselleştirmesi, yenilemenin ne zaman gerçekleşeceğini ve başlatıldıktan sonra yenilenmenin ilerleyişini iletmek için kullanılan dairesel ilerleme göstergesidir. Yenileme görselleştiricisinin 5 durumu vardır.

Kullanıcının yenilemeyi başlatmak için listede aşağı çekmesi gereken mesafe, eşiği olarak adlandırılır. görselleştirici Durum, bu eşik ile ilişkili olarak çekme durumu tarafından belirlenir. Olası değerler RefreshVisualizerState numaralandırmasında yer alır.

Idle

Görselleştiricinin varsayılan durumu Boşta . Kullanıcı, RefreshContainer ile dokunma yoluyla etkileşim kurmuyor ve devam eden bir yenileme yok.

Görsel olarak, yenileme görselleştiricisi görünürde yok.

Etkileşim

Kullanıcı listeyi PullDirection özelliği tarafından belirtilen yönde çektiğinde ve eşiğe ulaşılmadan önce, görselleştirici Etkileşim durumundadır.

• Kullanıcı bu durumdayken denetimi serbest bırakırsa, denetim Boştakonumuna döner.

  Çekme-yenileme öncesi eşikpull-to-refresh pre-threshold

  Görsel olarak, simge devre dışı olarak görüntülenir (60% opaklık). Buna ek olarak, simge kaydırma eylemiyle tam bir tur döner.

• Kullanıcı listeyi eşik ötesine çekerse, görselleştirici Etkileşim'den Beklemede'a geçer.

  Aşağı çekerek yenilemeyi

  Görsel olarak, simge 100% opaklığa geçer ve boyutu 100%'den 150%'e kadar büyüyerek daralıp genişler ve sonra geçiş sırasında tekrar 100% boyutuna döner.

Beklemede

Kullanıcı listeyi eşiği aştığında görselleştirici Beklemede durumundadır.

• Kullanıcı, listeyi serbest bırakmadan eşiğin üzerine geri taşırsa, Etkileşime durumuna döner.
• Kullanıcı listeyi serbest bırakırsa bir yenileme isteği başlatılır ve Yenileme durumuna geçirilir.

Eşik sonrası yenileme için çek-çek işlemi

Görsel olarak simgenin boyutu ve opaklığı 100%. Bu durumda, simge kaydırma eylemiyle aşağı doğru ilerlemeye devam eder ancak artık dönmez.

Canlandırıcı

Kullanıcı, görselleştiriciyi eşiğin ötesine geçirip serbest bıraktığında, Yenileme durumunda olur.

Bu duruma girildiğinde RefreshRequested olayı tetiklenir. Bu, uygulamanın içerik yenilemesini başlatma sinyalidir. Olay argümanları (RefreshRequestedEventArgs), olay işleyicisinde tutum almanız gereken bir Erteleme nesnesi içerir. Ardından, yenilemeyi gerçekleştirme kodunuz tamamlandığında ertelemeyi tamamlandı olarak işaretlemeniz gerekir.

Yenileme tamamlandığında görselleştirici Boşta durumuna döner.

Görsel olarak simge eşik konumuna geri döner ve yenileme süresi boyunca döner. Bu döndürme, yenilemenin ilerleme durumunu göstermek için kullanılır ve gelen içeriğin animasyonuyla değiştirilir.

Bakmak

Kullanıcı yenilemeye izin verilmeyen bir başlangıç konumundan yenileme yönünü çektiğinde, görselleştirici Göz atma durumuna girer. Bu durum genellikle kullanıcı çekmeye başladığında ScrollViewer 0 konumunda olmadığında gerçekleşir.

• Kullanıcı bu durumdayken denetimi serbest bırakırsa, denetim Boştakonumuna döner.

Çekme yönü

Varsayılan olarak, kullanıcı yenilemeyi başlatmak için bir listeyi yukarıdan aşağıya çeker. Farklı yönlendirmeye sahip bir listenize veya kılavuza sahipseniz, yenileme kapsayıcısının çekme yönünü eşleşecek şekilde değiştirmeniz gerekir.

PullDirection özelliği şu RefreshPullDirection değerlerinden birini alır: BottomToTop, TopToBottom, RightToLeftveya LeftToRight.

Çekme yönünü değiştirdiğinizde, görselleştiricinin ilerleme döndürücüsünün başlangıç konumu otomatik olarak döndürülür, böylece ok çekme yönü için uygun konumda başlar. Gerekirse, otomatik davranışı geçersiz kılmak için RefreshVisualizer.Orientation özelliğini değiştirebilirsiniz. Çoğu durumda, Otomatikvarsayılan değerini bırakmanızı öneririz.

Yenilemek için çekmenin uygulanması

• Önemli API'ler: RefreshContainer, RefreshVisualizer

WinUI 3 Galeri uygulamasını açın ve 'PullToRefresh'i eylemde görün

WinUI 3 Galeri uygulaması çoğu WinUI 3 denetimi, özelliği ve işlevselliğine ilişkin etkileşimli örnekler içerir. Uygulamayı Microsoft Store'dan alın veya GitHub'dan kaynak kodunu alın

Listeye çekme-yenileme işlevselliği eklemek için yalnızca birkaç adım gerekir.

1. Listenizi RefreshContainer denetimine sarmalayın.
2. İçeriğinizi yenilemek amacıyla RefreshRequested olayını ele alın.
3. İsteğe bağlı olarak, RequestRefresh çağırarak yenileme başlatın (örneğin, bir düğme tıklamasıyla).

Uyarı

RefreshVisualizer örneğini kendi başına oluşturabilirsiniz. Ancak, içeriğinizi bir RefreshContainer'a sarmalamanızı ve dokunmamış senaryolar için bile RefreshContainer.Visualizer özelliği tarafından sağlanan RefreshVisualizer'ı kullanmanızı öneririz. Bu makalede, görselleştiricinin her zaman güncelleme kapsayıcısından alındığını varsayıyoruz.

Ayrıca, kolaylık sağlamak için yenileme kapsayıcısının RequestRefresh ve RefreshRequested üyelerini kullanın. refreshContainer.RequestRefresh() refreshContainer.Visualizer.RequestRefresh()eşdeğerdir ve hem RefreshContainer.RefreshRequested olayını hem de RefreshVisualizer.RefreshRequested olaylarını tetikler.

Yenileme isteğinde bulun

Yenileme kapsayıcısı, kullanıcının dokunma yoluyla içerik yenilemesine izin vermek için dokunma etkileşimlerini işler. Dokunmatik olmayan arabirimler için yenileme düğmesi veya ses denetimi gibi başka avantajlar sağlamanızı öneririz.

Yenileme başlatmak için RequestRefresh yöntemini çağırın.

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

RequestRefresh'i çağırdığınızda, görselleştirici durumu Boşta konumundan doğrudan Yenilemekonumuna gider.

Yenileme isteğini işleme

Gerektiğinde yeni içerik almak için RefreshRequested olayını işleyin. Olay işleyicisinde, yeni içeriği almak için uygulamanıza özgü bir koda ihtiyacınız olacaktır.

Olay args (RefreshRequestedEventArgs) bir Erteleme nesnesi içerir. Olay işleyicisinde erteleme için bir tanıtıcı alın. Ardından yenilemeyi gerçekleştirme kodunuz tamamlandığında ertelemeyi tamamlandı olarak işaretleyin.

// 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();
    }
}

Durum değişikliklerine yanıt verme

Gerekirse görselleştiricinin durumundaki değişiklikleri yanıtlayabilirsiniz. Örneğin, birden çok yenileme isteğini önlemek için, görselleştirici yenilenirken yenileme düğmesini devre dışı bırakabilirsiniz.

// 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;
    }
}

RefreshContainer'da ScrollViewer Kullanma

Uyarı

RefreshContainer'ın İçeriği ScrollViewer, GridView, ListView gibi kaydırılabilir bir denetim olmalıdır. İçerik'i Kılavuz gibi bir denetime ayarlamak tanımsız davranışa neden olur.

Bu örnekte, kaydırma görüntüleyicisi ile yenileme için çekme özelliğinin nasıl kullanılacağı gösterilmektedir.

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

    </ScrollViewer>
</RefreshContainer>

ListView'a çekme-yenileme ekleme

Bu örnekte, bir liste görünümüyle yenileme için çekme özelliğinin nasıl kullanılacağı gösterilmektedir.

<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; }
}

UWP ve WinUI 2

Önemli

Bu makaledeki bilgiler ve örnekler, Windows Uygulama SDK'sı ve WinUI 3kullanan uygulamalar için iyileştirilmiştir, ancak genellikle WinUI 2kullanan UWP uygulamaları için geçerlidir. Platforma özgü bilgiler ve örnekler için UWP API başvurusuna bakın.

Bu bölüm, denetimi bir UWP veya WinUI 2 uygulamasında kullanmak için ihtiyacınız olan bilgileri içerir.

UWP uygulamaları için yenileme denetimleri WinUI 2'nin bir parçası olarak eklenir. Yükleme yönergeleri de dahil olmak üzere daha fazla bilgi için bkz. WinUI 2. Bu denetimin API'leri hem Windows.UI.Xaml.Controls (UWP) hem de Microsoft.UI.Xaml.Controls (WinUI) ad alanlarında mevcuttur.

• UWP API'leri:RefreshContainer, RefreshVisualizer
• WinUI 2 API'ler:RefreshContainer, RefreshVisualizer
• WinUI 2 galeri uygulamasını açın ve PullToRefresh'i iş başında görün. WinUI 2 Galeri uygulaması çoğu WinUI 2 denetimi, özelliği ve işlevselliğine ilişkin etkileşimli örnekler içerir. Uygulamayı Microsoft Store'dan alın veya GitHub'dan kaynak kodunu alın.

Tüm denetimler için en güncel stilleri, şablonları ve özellikleri almak için en son WinUI 2'yi kullanmanızı öneririz.

Bu makaledeki kodu WinUI 2 ile kullanmak için, projenize dahil edilen Windows UI Kitaplığı API'lerini temsil etmek için XAML'de bir diğer ad kullanın (muxckullanıyoruz). Daha fazla bilgi için WinUI 2'yi kullanmaya başlama hakkında bölümüne bakın.

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

<muxc:RefreshContainer />

İlgili makaleler

• Dokunma etkileşimleri
• Liste görünümü ve kılavuz görünümü
• Öğe kapsayıcıları ve şablonları
• İfade animasyonları