Bagikan melalui

Sintaks XAML PropertyPath

Objek PropertyPath mendukung sintaksis XAML sebaris yang kompleks untuk mengatur berbagai properti yang mengambil PropertyPath jenis sebagai nilainya. Topik ini mendokumentasikan PropertyPath sintaks sebagaimana diterapkan pada sintaks pengikatan dan animasi.

Di Mana PropertyPath Digunakan

PropertyPath adalah objek umum yang digunakan dalam beberapa fitur Windows Presentation Foundation (WPF). Meskipun menggunakan informasi jalur properti umum PropertyPath untuk menyampaikan informasi, penggunaan bervariasi di setiap area fitur di mana PropertyPath digunakan sebagai jenis. Oleh karena itu, lebih praktis untuk mendokumen sintaksis berdasarkan per fitur.

Terutama, WPF menggunakan PropertyPath untuk menjelaskan jalur model objek untuk melintas properti sumber data objek, dan untuk menjelaskan jalur target untuk animasi yang ditargetkan.

Beberapa properti gaya dan templat seperti Setter.Property mengambil nama properti yang memenuhi syarat yang secara dangkal menyerupai PropertyPath. Tetapi ini bukan bentuk asli PropertyPath; sebaliknya, ini adalah penggunaan format string bersyarat owner.property yang diaktifkan oleh prosesor WPF XAML dalam kombinasi dengan pengonversi jenis untuk DependencyProperty.

PropertyPath untuk Objek dalam Pengikatan Data

Pengikatan data adalah fitur WPF di mana Anda dapat mengikat nilai target properti dependensi apa pun. Namun, sumber pengikatan data tersebut tidak perlu menjadi properti dependensi; dapat berupa jenis properti apa pun yang dikenali oleh penyedia data yang berlaku. Jalur properti terutama digunakan untuk ObjectDataProvider, yang digunakan untuk mendapatkan sumber pengikatan dari objek runtime bahasa umum (CLR) dan propertinya.

Perhatikan bahwa pengikatan data ke XML tidak menggunakan PropertyPath, karena tidak digunakan Path dalam Binding. Sebagai gantinya, Anda menggunakan XPath dan menentukan sintaks XPath yang valid ke dalam Model Objek Dokumen XML (DOM) data. XPath juga ditentukan sebagai string, tetapi tidak terdokumentasi di sini; lihat Menghubungkan ke Data XML Menggunakan XMLDataProvider dan Kueri XPath.

Kunci untuk memahami jalur properti dalam pengikatan data adalah Anda dapat menargetkan pengikatan pada nilai properti individu, atau Anda dapat mengikat pada properti target yang menerima daftar atau koleksi. Jika Anda mengikat koleksi, misalnya mengikat ListBox yang akan diperluas tergantung pada berapa banyak item data dalam koleksi, maka jalur properti Anda harus mereferensikan objek koleksi, bukan item koleksi individual. Mesin pengikatan data akan secara otomatis mencocokkan koleksi yang digunakan sebagai sumber data ListBox dengan tipe target pengikatan, menghasilkan perilaku seperti mengisi ListBox dengan array item.

Properti Tunggal pada Objek Langsung sebagai Konteks Data

<Binding Path="propertyName" ... />

propertyName harus merujuk ke nama properti yang ada saat ini dalam DataContext untuk penggunaan Path. Jika pengikatan Anda memperbarui sumber, properti tersebut harus dibaca/ditulis dan objek sumber harus dapat diubah.

Pengindeks Tunggal pada Objek Langsung sebagai Konteks Data

<Binding Path="[key]" ... />

key harus berupa indeks yang ditik ke kamus atau tabel hash, atau indeks bilangan bulat array. Selain itu, nilai kunci harus merupakan jenis yang dapat diikat langsung ke properti tempat kunci tersebut diterapkan. Misalnya, tabel hash yang berisi kunci string dan nilai string dapat digunakan dengan cara ini untuk mengikat Teks untuk TextBox. Atau, jika kunci menunjuk ke koleksi atau subindex, Anda dapat menggunakan sintaks ini untuk mengikat ke properti koleksi target. Jika tidak, Anda perlu mereferensikan properti tertentu, melalui sintaks seperti <Binding Path="[key].propertyName" .../>.

Anda dapat menentukan jenis indeks jika perlu. Untuk detail tentang aspek jalur properti terindeks ini, lihat Binding.Path.

Beberapa Properti (Penargetan Properti Secara Tidak Langsung)

<Binding Path="propertyName.propertyName2" ... />

propertyName harus ditetapkan sebagai nama properti yang saat ini adalah DataContext. Properti propertyName dan propertyName2 adalah properti apa pun yang ada dalam suatu hubungan, di mana propertyName2 adalah properti yang ada pada tipe yang menjadi nilai dari propertyName.

Properti Tunggal, Tersambung atau Berkualifikasi Tipe tertentu

<object property="(ownerType.propertyName)" ... />

Tanda kurung menunjukkan bahwa properti ini dalam PropertyPath harus dibangun menggunakan kualifikasi parsial. Ini dapat menggunakan namespace XML untuk menemukan jenis dengan pemetaan yang sesuai. ownerType mencari jenis yang dapat diakses oleh prosesor XAML, melalui deklarasi XmlnsDefinitionAttribute di setiap assembly. Sebagian besar aplikasi memiliki namespace XML default yang dipetakan ke http://schemas.microsoft.com/winfx/2006/xaml/presentation namespace, sehingga awalan biasanya hanya diperlukan untuk jenis kustom atau jenis di luar namespace tersebut. propertyName harus merujuk ke nama properti yang ada pada ownerType. Sintaks ini umumnya digunakan untuk salah satu kasus berikut:

  • Jalur ditentukan dalam XAML yang berada dalam gaya atau templat yang tidak memiliki Jenis Target tertentu. Penggunaan yang memenuhi kriteria umumnya tidak valid untuk kasus-kasus lain selain ini, karena dalam kasus yang bukan gaya dan bukan templat, properti ada pada instans, bukan pada tipe.

  • Properti adalah properti terlampir.

  • Anda mengikat ke properti statis.

Untuk digunakan sebagai target papan cerita, properti yang ditentukan sebagai propertyName harus menjadi DependencyProperty.

Source Traversal (Pengikatan ke Hierarki Koleksi)

<object Path="propertyName/propertyNameX" ... />

Dalam sintaks ini, / digunakan untuk menavigasi dalam objek sumber data hierarkis, dan beberapa langkah ke dalam hierarki dengan karakter / berturut-turut didukung. Penelusuran sumber mempertimbangkan posisi penunjuk rekaman saat ini, yang ditentukan dengan menyinkronkan data dengan UI dari tampilannya. Untuk detail tentang pengikatan dengan objek sumber data hierarkis, dan konsep penunjuk rekaman aktif dalam pengikatan data, lihat Menggunakan Pola Master-Detail dengan Data Hierarkis atau Gambaran Umum Pengikatan Data.

Nota

Secara dangkal, sintaks ini menyerupai XPath. Ekspresi XPath yang benar untuk mengikat ke sumber data XML tidak digunakan sebagai nilai Path dan sebaliknya harus digunakan untuk properti XPath yang saling eksklusif.

Tampilan Koleksi

Untuk mereferensikan tampilan koleksi bernama, awali nama tampilan koleksi dengan karakter hash (#).

Penunjuk Rekaman Saat Ini

Untuk mereferensikan penunjuk rekaman saat ini untuk tampilan koleksi atau skenario pengikatan data detail master, mulai string jalur dengan garis miring ke depan (/). Setiap jalur yang melewati garis miring maju dilalui mulai dari pointer posisi saat ini.

Beberapa Pengindeks

<object Path="[index1,index2...]" ... />

atau

<object Path="propertyName[index,index2...]" ... />

Jika objek tertentu mendukung beberapa pengindeks, pengindeks tersebut dapat ditentukan secara berurutan, mirip dengan sintaks referensi array. Objek yang dimaksud dapat berupa konteks saat ini atau nilai properti yang berisi beberapa objek indeks.

Secara default, nilai pengindeks di ketik dengan menggunakan karakteristik objek yang mendasar. Anda dapat menentukan jenis indeks jika perlu. Untuk detail tentang mengetik pengindeks, lihat Binding.Path.

Mencampur Sintaksis

Setiap sintaks yang ditunjukkan di atas dapat digabungkan. Misalnya, berikut ini adalah contoh yang membuat jalur properti untuk mengakses warna pada koordinat tertentu x,y dari properti ColorGrid yang berisi sebuah array objek kisi piksel dari SolidColorBrush.

<Rectangle Fill="{Binding ColorGrid[20,30].SolidColorBrushResult}" ... />

Karakter Pelolosan untuk Jalur String Properti

Untuk objek bisnis tertentu, Anda mungkin mengalami kasus di mana string jalur properti memerlukan urutan pelolosan untuk diurai dengan benar. Kebutuhan untuk melarikan diri harus jarang terjadi, karena banyak dari karakter ini memiliki masalah interaksi penamaan serupa dalam bahasa yang biasanya akan digunakan untuk menentukan objek bisnis.

  • Di dalam pengindeks ([ ]), karakter tanda sisipan (^) lolos dari karakter berikutnya.

  • Anda harus meloloskan (menggunakan entitas XML) karakter tertentu yang spesifik dalam definisi bahasa XML. Gunakan & untuk melepaskan karakter "&". Gunakan > untuk menghindari tag akhir ">".

  • Anda harus meloloskan (menggunakan karakter garis miring terbalik \) yang spesial untuk perilaku pengurai WPF XAML dalam memproses ekstensi markup.

    • Backslash (\) adalah karakter pelolosan itu sendiri.

    • Tanda sama dengan (=) memisahkan nama properti dari nilai properti.

    • Koma (,) memisahkan properti.

    • Kurung kurawal (}) yang tepat adalah akhir dari ekstensi markup.

Nota

Secara teknis, pengalihan ini juga berfungsi untuk jalur properti storyboard, tetapi Anda biasanya menelusuri model objek untuk objek WPF yang ada, dan pengalihan tidak diperlukan.

PropertyPath untuk Target Animasi

Properti target dari animasi haruslah properti dependensi yang menerima Freezable atau tipe primitif. Namun, properti yang ditargetkan pada tipe dan properti animasi yang dihasilkan dapat ada pada objek yang berbeda. Untuk animasi, jalur properti digunakan untuk menentukan koneksi antara properti dari objek target animasi yang disebutkan dan properti animasi target yang diinginkan, dengan menelusuri hubungan objek-properti dalam hirarki tersebut.

Pertimbangan Properti Objek Umum untuk Animasi

Untuk informasi selengkapnya tentang konsep animasi secara umum, lihat Gambaran Umum Papan Cerita dan Gambaran Umum Animasi.

Tipe nilai atau properti yang dianimasikan harus berupa tipe atau tipe primitif. Properti yang memulai jalur harus mengarah ke nama properti dependensi yang ada pada jenis yang ditentukan TargetName.

Untuk mendukung kloning animasi dari Freezable yang sudah dibekukan, objek yang ditentukan oleh TargetName harus berupa kelas FrameworkElement atau turunan FrameworkContentElement.

Properti Tunggal pada Objek Target

<animation Storyboard.TargetProperty="propertyName" ... />

propertyName harus diselesaikan menjadi nama properti dependensi yang ada pada jenis yang ditentukan TargetName .

Penargetan Properti Tidak Langsung

<animation Storyboard.TargetProperty="propertyName.propertyName2" ... />

propertyName harus berupa properti yang merupakan Freezable jenis nilai atau primitif, yang ada pada jenis yang ditentukan TargetName .

propertyName2 haruslah nama properti dependensi yang ada pada objek yang merupakan nilai dari propertyName. Dengan kata lain, propertyName2 harus ada sebagai properti dependensi pada jenis yang merupakan propertyNamePropertyType.

Penargetan animasi tidak langsung diperlukan karena gaya dan templat yang digunakan. Untuk menargetkan animasi, Anda memerlukan TargetName pada objek target, dan nama tersebut ditetapkan oleh x:Name atau Name. Meskipun elemen template dan gaya juga dapat memiliki nama, nama-nama tersebut hanya berlaku di dalam namescope dari gaya dan template. (Jika template dan gaya berbagi namescope dengan markup aplikasi, nama tidak bisa unik. Gaya dan template secara harfiah dibagikan antara instans dan akan mengakibatkan nama yang duplikat.) Dengan demikian, jika properti individual dari elemen yang ingin Anda animasikan berasal dari gaya atau template, Anda perlu memulai dengan elemen bernama yang bukan dari template gaya, lalu menargetkannya ke dalam pohon visual dari gaya atau template untuk mencapai properti yang ingin Anda animasikan.

Misalnya, properti dari Background adalah Panel lengkap Brush (sebenarnya SolidColorBrush) yang berasal dari templat tema. Untuk menganimasikan Brush sepenuhnya, harus ada BrushAnimation (mungkin satu untuk setiap Brush jenis) dan tidak ada jenis seperti itu. Untuk menganimasikan Brush, Anda sebagai gantinya menganimasikan properti dari jenis tertentu Brush . Anda perlu dari SolidColorBrush ke Color untuk menerapkan ColorAnimation di sana. Jalur properti untuk contoh ini adalah Background.Color.

Properti yang Terlampir

<animation Storyboard.TargetProperty="(ownerType.propertyName)" ... />

Tanda kurung menunjukkan bahwa properti ini dalam PropertyPath harus dibangun menggunakan kualifikasi parsial. Ini dapat menggunakan namespace XML untuk menemukan jenisnya. Pencarian ownerType tipe yang dapat diakses oleh prosesor XAML dilakukan melalui deklarasi XmlnsDefinitionAttribute dalam setiap assembly. Sebagian besar aplikasi memiliki namespace XML default yang dipetakan ke http://schemas.microsoft.com/winfx/2006/xaml/presentation namespace, sehingga awalan biasanya hanya diperlukan untuk jenis kustom atau jenis di luar namespace tersebut. propertyName harus diidentifikasi sebagai nama properti yang ada pada ownerType. Properti yang ditentukan sebagai propertyName harus berupa DependencyProperty. (Semua properti terlampir WPF diimplementasikan sebagai properti dependensi, sehingga masalah ini hanya menjadi perhatian untuk properti terlampir kustom.)

Pengindeks

<animation Storyboard.TargetProperty="propertyName.propertyName2[index].propertyName3" ... />

Sebagian besar properti atau Freezable jenis dependensi tidak mendukung pengindeks. Oleh karena itu, satu-satunya kegunaan pengindeks di jalur animasi adalah pada posisi menengah antara properti yang memulai rantai pada target yang disebutkan dan properti animasi yang akhirnya. Dalam sintaks yang disediakan, yaitu propertyName2. Misalnya, penggunaan pengindeks mungkin diperlukan jika properti perantara adalah koleksi seperti TransformGroup, di jalur properti seperti RenderTransform.Children[1].Angle.

PropertyPath dalam Kode

Penggunaan kode untuk PropertyPath, termasuk cara membuat PropertyPath, didokumenkan dalam topik referensi untuk PropertyPath.

Secara umum, PropertyPath dirancang untuk menggunakan dua konstruktor yang berbeda, satu untuk penggunaan pengikatan dan penggunaan animasi paling sederhana, dan satu untuk penggunaan animasi yang kompleks. Gunakan signature PropertyPath(Object) untuk penggunaan binding, di mana objek adalah string. PropertyPath(Object) Gunakan tanda tangan untuk jalur animasi satu langkah, di mana objek adalah DependencyProperty. PropertyPath(String, Object[]) Gunakan tanda tangan untuk animasi kompleks. Konstruktor terakhir ini menggunakan string token untuk parameter pertama dan array objek yang mengisi posisi dalam string token untuk menentukan hubungan jalur properti.

Lihat juga

  • Last updated on