SintaksIs PropertyPath XAML

Artikel
08/10/2023

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

Tempat PropertyPath digunakan

PropertyPath adalah objek umum yang digunakan dalam beberapa fitur Windows Presentation Foundation (WPF). Meskipun menggunakan informasi jalur properti umum PropertyPath untuk menyampaikan, penggunaan untuk setiap area fitur di mana PropertyPath digunakan sebagai jenis bervariasi. 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 menyerupan .PropertyPath Tetapi ini bukan benar PropertyPath; sebaliknya itu adalah penggunaan format string owner.property yang memenuhi syarat 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 didokumenkan di sini; lihat Mengikat ke Data XML Menggunakan XMLDataProvider dan Kueri XPath.

Kunci untuk memahami jalur properti dalam pengikatan data adalah Anda dapat menargetkan pengikatan ke nilai properti individual, atau Anda dapat mengikat properti target yang mengambil 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 cocok dengan koleksi yang ListBox digunakan sebagai sumber data dengan jenis target pengikatan secara otomatis, menghasilkan perilaku seperti mengisi dengan array item.

Properti Tunggal pada Objek Langsung sebagai Konteks Data

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

propertyName harus diselesaikan menjadi nama properti yang ada di saat ini DataContext untuk Path penggunaan. 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 Tidak Langsung)

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

propertyName harus diselesaikan untuk menjadi nama properti yang saat ini DataContext. Properti propertyName jalur dan propertyName2 dapat berupa properti apa pun yang ada dalam hubungan, di mana propertyName2 adalah properti yang ada pada jenis yang merupakan nilai .propertyName

Properti Tunggal, Terlampir atau Berkualifikasi Tipe

<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. Pencarian ownerType jenis yang dapat diakses oleh prosesor XAML, melalui XmlnsDefinitionAttribute deklarasi di setiap rakitan. 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 diselesaikan untuk menjadi nama properti yang ada di 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 syarat umumnya tidak valid untuk kasus selain ini, karena dalam kasus non-gaya, non-templat, properti ada pada instans, bukan jenis.
Properti adalah properti terlampir.
Anda mengikat ke properti statis.

Untuk digunakan sebagai target papan cerita, properti yang ditentukan sebagai propertyName harus berupa 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. Traversal sumber menyumbang posisi penunjuk rekaman saat ini, yang ditentukan dengan menyinkronkan data dengan UI tampilannya. Untuk detail tentang pengikatan dengan objek sumber data hierarkis, dan konsep penunjuk rekaman saat ini dalam pengikatan data, lihat Menggunakan Pola Detail Master dengan Data Hierarkis atau Gambaran Umum Pengikatan Data.

Catatan

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

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 (/). Jalur apa pun yang melewati garis miring dilalui mulai dari penunjuk rekaman saat ini.

Beberapa Pengindeks

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

<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 diselingi. Misalnya, berikut ini adalah contoh yang membuat jalur properti ke warna pada x,y ColorGrid properti tertentu yang berisi array SolidColorBrush objek kisi piksel:

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

Escapes untuk String Jalur Properti

Untuk objek bisnis tertentu, Anda mungkin mengalami kasus di mana string jalur properti memerlukan urutan escape untuk mengurai 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 keluar (menggunakan entitas XML) karakter tertentu yang khusus untuk definisi bahasa XML. Gunakan & untuk menghindari karakter "&". Gunakan > untuk menghindari tag akhir ">".
Anda harus keluar (menggunakan karakter garis miring \terbalik) yang khusus untuk perilaku pengurai WPF XAML untuk memproses ekstensi markup.
- Garis miring terbelakang (\) adalah karakter escape itu sendiri.
- Tanda sama dengan (=) memisahkan nama properti dari nilai properti.
- Koma (,) memisahkan properti.
- Kurung kurawal (}) yang tepat adalah akhir dari ekstensi markup.

Catatan

Secara teknis, pelarian ini juga berfungsi untuk jalur properti papan cerita, tetapi Anda biasanya melintas model objek untuk objek WPF yang ada, dan melarikan diri harus tidak perlu.

PropertyPath untuk Target Animasi

Properti target animasi harus merupakan properti dependensi yang mengambil Freezable jenis atau primitif. Namun, properti yang ditargetkan pada jenis dan properti animasi akhirnya dapat ada pada objek yang berbeda. Untuk animasi, jalur properti digunakan untuk menentukan koneksi antara properti objek target animasi bernama dan properti animasi target yang dimaksudkan, dengan melintas hubungan properti objek dalam nilai properti.

Pertimbangan Properti Objek Umum untuk Animasi

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

Jenis nilai atau properti yang dianimasikan harus berupa Freezable jenis atau primitif. Properti yang memulai jalur harus diselesaikan menjadi nama properti dependensi yang ada pada jenis yang ditentukan TargetName .

Untuk mendukung kloning untuk menganimasikan Freezable yang sudah dibekukan, objek yang ditentukan oleh TargetName harus merupakan FrameworkElement kelas atau FrameworkContentElement turunan.

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 .

propertyName2haruslah nama properti dependensi yang ada pada objek yang merupakan nilai .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 diterapkan. Untuk menargetkan animasi, Anda memerlukan TargetName pada objek target, dan nama tersebut ditetapkan oleh x:Name atau Name. Meskipun elemen templat dan gaya juga dapat memiliki nama, nama-nama tersebut hanya valid dalam namescope gaya dan templat. (Jika templat dan gaya berbagi namescope dengan markup aplikasi, nama tidak bisa unik. Gaya dan templat secara harfiah dibagikan antara instans dan akan mengabdikan nama duplikat.) Dengan demikian, jika properti individual elemen yang mungkin ingin Anda animasikan berasal dari gaya atau templat, Anda perlu memulai dengan instans elemen bernama yang bukan dari templat gaya, lalu menargetkan ke dalam gaya atau pohon visual templat untuk tiba di properti yang ingin Anda animasikan.

Misalnya, Background properti dari adalah Panel lengkap Brush (sebenarnya a 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 mendapatkan dari SolidColorBrush ke untuk Color menerapkan di ColorAnimation 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 jenis yang dapat diakses oleh prosesor XAML, melalui XmlnsDefinitionAttribute deklarasi di setiap rakitan. 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 diselesaikan untuk menjadi nama properti yang ada di 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 penggunaan untuk pengindeks di jalur animasi adalah pada posisi menengah antara properti yang memulai rantai pada target bernama dan properti animasi 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. PropertyPath(Object) Gunakan tanda tangan untuk mengikat penggunaan, 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.

Bagikan melalui