VisualTreeHelper Kelas

Referensi

Definisi

Ruang nama:: Windows.UI.Xaml.Media

Penting

Beberapa informasi terkait produk prarilis yang dapat diubah secara signifikan sebelum dirilis. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Edit

Menyediakan metode utilitas yang dapat digunakan untuk melintasi hubungan objek (bersama sumbu objek turunan atau objek induk) di pohon visual aplikasi Anda.

public ref class VisualTreeHelper sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class VisualTreeHelper final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class VisualTreeHelper

Public NotInheritable Class VisualTreeHelper

Warisan: Object Platform::Object IInspectable VisualTreeHelper

Atribut: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Persyaratan Windows

Rangkaian perangkat	Windows 10 (diperkenalkan dalam 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (diperkenalkan dalam v1.0)

Contoh

Berikut adalah contoh fungsi utilitas yang dapat menyalin daftar elemen anak dari jenis tertentu dari dalam pohon visual. Ini menggunakan metode traversal dasar GetChildrenCount dan GetChild. Ini menggunakan rekursi sehingga elemen dapat ditemukan tidak peduli tingkat bersarang dalam kontainer perantara. Ini juga menggunakan metode ekstensi IsSubclassOf dari System.Reflection yang memperluas perbandingan jenis untuk mempertimbangkan subjenis sebagai kecocokan untuk Jenis.

internal static void FindChildren<T>(List<T> results, DependencyObject startNode)
  where T : DependencyObject
{
    int count = VisualTreeHelper.GetChildrenCount(startNode);
    for (int i = 0; i < count; i++)
    {
        DependencyObject current = VisualTreeHelper.GetChild(startNode, i);
        if ((current.GetType()).Equals(typeof(T)) || (current.GetType().GetTypeInfo().IsSubclassOf(typeof(T))))
        {
            T asType = (T)current;
            results.Add(asType);
        }
        FindChildren<T>(results, current);
    }
}

Keterangan

Pohon visual

Tujuan dari kelas VisualTreeHelper adalah untuk membantu penemuan objek yang Anda cari di pohon runtime objek, tetapi tidak ada API hubungan objek yang lebih langsung yang tersedia untuk skenario Anda. Terkadang, Anda tidak akan tahu jenis atau nama objek yang tepat. Atau mungkin Anda tahu bahwa objek tertentu muncul di suatu tempat di pohon tetapi Anda tidak tahu posisi yang tepat. Untuk jenis skenario ini, VisualTreeHelper sangat membantu karena Anda dapat secara rekursif menemukan semua objek di pohon visual lalu melihat melalui set ini dan mencari kecocokan berdasarkan kriteria Anda.

Pohon visual untuk aplikasi dapat dikonseptualisasikan sebagai representasi terfilter dari pohon objek yang lebih besar dari objek dan properti aplikasi. Hanya objek yang memiliki implikasi penyajian yang ada di pohon visual. Misalnya, kelas koleksi tidak akan menjadi bagian dari pohon visual. Sebaliknya, pohon visual mengabstraksi koleksi apa pun menjadi konsep "anak-anak".

Namun, pohon visual juga dapat menyertakan objek yang tidak direpresentasikan sebagai elemen XAML dalam markup XAML halaman. Ini karena pohon visual menambahkan objek yang merupakan bagian kontrol yang dikomposit. Bagian kontrol ini dapat berasal dari templat kontrol yang diterapkan, yang biasanya XAML dari item kamus sumber daya, atau dari penyaji.

Markup XAML dan pohon visual tidak sama persis dengan node-for-node karena XAML dirancang untuk markup, dan kemudahan penggunaan selama definisi markup, sehingga terkadang memiliki elemen tambahan. Misalnya, XAML memiliki elemen properti, yang menetapkan nilai properti jika satu elemen ditemukan berlapis di dalam elemen lain. Di pohon visual, ini hanya akan terlihat seperti properti pada objek yang diatur oleh objek lain. XAML juga memiliki konsep properti konten, di mana properti yang ditetapkan tidak secara eksplisit ditunjuk dalam markup. Untuk informasi selengkapnya tentang terminologi tertentu dan aturan untuk XAML, lihat Gambaran umum XAML.

Pohon visual digunakan secara internal untuk proses penyajian UI, tetapi mengetahui struktur pohon visual penting untuk skenario tertentu, seperti menulis atau mengganti templat kontrol, atau analisis struktur dan bagian kontrol pada run-time. Untuk skenario ini, Windows Runtime menyediakan Api VisualTreeHelper yang dapat memeriksa pohon visual dengan cara yang lebih umum. (Anda juga dapat membuat pohon tersebut secara teoritis menggunakan properti induk dan anak-anak khusus objek, tetapi Anda harus mengetahui dengan tepat properti mana yang didukung setiap elemen, dan itu sulit ditemukan atau dikelola.)

Anda biasanya menggabungkan beberapa panggilan API VisualTreeHelper untuk menulis fungsi pembantu Anda sendiri yang menyelidiki pohon visual dengan cara yang khusus untuk skenario aplikasi Anda sendiri.

Melintas pohon visual

Melintas pohon objek (kadang-kadang dikenal secara sehari-hari saat berjalan di pohon) adalah teknik umum dalam model objek. Anda menggunakan properti yang mereferensikan objek turunan (biasanya ini adalah koleksi) atau hubungan induk ke objek yang berisi (biasanya ini dilakukan dari dalam koleksi, dan mengembalikan koleksi itu sendiri). Sebagai deskripsi kasar tentang proses, Anda memanggil berturut-turut properti anak dan properti induk, atau mungkin metode pembantu, untuk menavigasi sumbu pohon objek sampai Anda mengambil nilai yang berisi objek yang Anda cari. Sebagai aturan umum, Anda harus dapat membuat konten Anda di XAML sehingga Anda tidak perlu mengkueri struktur pohon secara luas. Untuk menghindari kebutuhan untuk melintasi pohon, Anda harus memberi elemen XAML nilai untuk atribut x:Name / Name di markup XAML yang membuatnya. Ini menciptakan referensi langsung yang tersedia untuk akses kode run-time, dan itu adalah teknik rawan kesalahan yang jauh lebih sedikit untuk mendapatkan referensi objek daripada berjalan di pohon. Atau, jika Anda membuat objek melalui kode daripada XAML, Anda harus mendeklarasikan bidang atau variabel privat yang mempertahankan referensi objek pada run-time. Biasanya tidak perlu melintasi pohon untuk menemukan objek yang dibuat dalam kode Anda sendiri.

Namun, ada kasus di mana tidak mungkin atau praktis untuk memberi nama objek dan menyimpan referensi objek dalam cakupan. Salah satu skenario tersebut adalah jika Anda menambahkan konten dinamis yang disediakan oleh pengguna atau disediakan oleh pengikatan data, atau menggunakan model tampilan dan objek bisnis. Dalam kasus ini, Anda tidak selalu dapat memprediksi jumlah item yang ditambahkan atau struktur kontrol dan turunannya. Skenario lain adalah memeriksa templat yang diterapkan untuk kontrol, atau bagian yang dikomposisikan dari kontrol atau konten penyaji.

Melintasi pohon ke bawah (jauh dari akar) beberapa tingkat dapat dilakukan menggunakan GetChildrenCount untuk nilai bukan nol lalu GetChild untuk meminta indeks tertentu. Anda mungkin harus menggunakan teknik coba/tangkap atau yang setara jika Anda mencoba mentransmisikan elemen sebagai subjenis UIElement tertentu. Umumnya elemen pengembalian VisualTreeHelper API sebagai DependencyObject dan Anda harus mentransmisikannya untuk melakukan apa pun yang berguna (bahkan untuk operasi sesederhana memeriksa nilai Namanya ).

Catatan untuk versi sebelumnya

Windows 8

Utas UI

Windows 8 mengizinkan panggilan fungsi VisualTreeHelper yang mereferensikan objek pada utas UI yang salah (bukan saat ini). Dimulai dengan Windows 8.1, fungsi melemparkan pengecualian jika tidak dipanggil dari utas UI saat ini. Akuntansi untuk perilaku baru ini harus menjadi skenario migrasi aplikasi yang sangat jarang; sulit untuk mendapatkan elemen UI di seluruh utas di tempat pertama.

Aplikasi yang dikompilasi untuk Windows 8 tetapi berjalan pada Windows 8.1 menggunakan perilaku Windows 8.1, dan akan melemparkan secara khusus pada panggilan fungsi VisualTreeHelper daripada pada kode aplikasi hilir yang menggunakan objek lintas alur.

UI Aplikasi untuk Keyboard Di Layar

Windows 8 memiliki logika yang diterapkan secara internal yang akan mengaitkan ScrollViewer dengan antarmuka pengguna aplikasi keseluruhan setiap kali pengguna memanggil Keyboard Di Layar. Keyboard Di Layar ini adalah fitur aksesibilitas tertentu yang diminta pengguna melalui Pusat Kemudahan Akses. Ini tidak sama dengan keyboard lunak yang dapat muncul di UI aplikasi untuk kontrol input teks, jika sistem tidak mendeteksi perangkat keyboard. Apa yang dilakukan ScrollViewer internal di sini adalah memungkinkan untuk menggulir area tempat aplikasi berada, jika menggulirnya dipaksa karena keyboard mengambil ruang UI.

Dimulai dengan Windows 8.1, sistem masih memiliki perilaku UI/tata letak ketika Keyboard Layar muncul, tetapi tidak lagi menggunakan ScrollViewer yang dibuat secara internal ini. Sebaliknya menggunakan kontrol internal khusus yang tidak dapat diubah atau diperiksa kode aplikasi.

Sebagian besar aspek perubahan perilaku ini tidak memengaruhi aplikasi sekalipun. Namun, aplikasi Anda mungkin telah mengantisipasi perilaku ini, dengan menyediakan Gaya implisit untuk ScrollViewer yang dimaksudkan untuk mengubah tata letak, atau dengan berjalan di pohon dengan VisualTreeHelper untuk menemukan ScrollViewer yang dibuat secara internal ini dan mengubahnya pada run-time. Untuk aplikasi yang dikompilasi untuk Windows 8.1 kode tersebut tidak akan berguna.

Aplikasi yang dikompilasi untuk Windows 8 tetapi berjalan di Windows 8.1 terus menggunakan perilaku Windows 8.

Riwayat versi

Versi Windows	Versi SDK	Nilai ditambahkan
1903	18362	GetOpenPopupsForXamlRoot

Metode

DisconnectChildrenRecursive(UIElement)	Secara eksplisit menghapus semua referensi dari UIElement target, dengan tujuan membersihkan siklus referensi.
FindElementsInHostCoordinates(Point, UIElement)	Mengambil sekumpulan objek yang terletak dalam titik koordinat x-y tertentu dari antarmuka pengguna aplikasi. Kumpulan objek mewakili komponen pohon visual yang berbagi titik tersebut.
FindElementsInHostCoordinates(Point, UIElement, Boolean)	Mengambil sekumpulan objek yang terletak dalam titik koordinat x-y tertentu dari antarmuka pengguna aplikasi. Kumpulan objek mewakili komponen pohon visual yang berbagi titik tersebut.
FindElementsInHostCoordinates(Rect, UIElement)	Mengambil sekumpulan objek yang terletak dalam bingkai Rect tertentu dari UI aplikasi. Kumpulan objek mewakili komponen pohon visual yang berbagi area persegi panjang, dan mungkin menyertakan elemen yang terlalu menguras.
FindElementsInHostCoordinates(Rect, UIElement, Boolean)	Mengambil sekumpulan objek yang terletak dalam bingkai Rect tertentu dari UI aplikasi. Kumpulan objek mewakili komponen pohon visual yang berbagi area persegi panjang, dan mungkin menyertakan elemen yang terlalu menguras.
GetChild(DependencyObject, Int32)	Dengan menggunakan indeks yang disediakan, mendapatkan objek anak tertentu dari objek yang disediakan dengan memeriksa pohon visual.
GetChildrenCount(DependencyObject)	Mengembalikan jumlah anak yang ada dalam kumpulan anak objek di pohon visual.
GetOpenPopups(Window)	Mengambil kumpulan semua kontrol popup terbuka dari Jendela target.
GetOpenPopupsForXamlRoot(XamlRoot)	Mengambil kumpulan semua kontrol popup terbuka dari target XamlRoot.
GetParent(DependencyObject)	Mengembalikan objek induk objek di pohon visual.

Berlaku untuk