Metadata properti dependensi (WPF .NET)
Sistem properti Windows Presentation Foundation (WPF) menyertakan sistem pelaporan metadata properti dependensi. Informasi yang tersedia melalui sistem pelaporan metadata melebihi apa yang tersedia melalui karakteristik refleksi atau common language runtime (CLR). Saat mendaftarkan properti dependensi, Anda memiliki opsi untuk membuat dan menetapkan metadata ke properti tersebut. Jika Anda berasal dari kelas yang menentukan properti dependensi, Anda dapat mengambil alih metadata untuk properti dependensi yang diwariskan. Dan, jika Anda menambahkan kelas sebagai pemilik properti dependensi, Anda dapat mengambil alih metadata properti dependensi yang diwariskan.
Penting
Dokumentasi Panduan Desktop untuk .NET 7 dan .NET 6 sedang dibangun.
Prasyarat
Artikel ini mengasumsikan pengetahuan dasar tentang properti dependensi, dan bahwa Anda telah membaca gambaran umum properti Dependensi. Untuk mengikuti contoh dalam artikel ini, ini membantu jika Anda terbiasa dengan Extensible Application Markup Language (XAML) dan tahu cara menulis aplikasi WPF.
Bagaimana metadata digunakan
Anda dapat mengkueri metadata properti dependensi untuk memeriksa karakteristik properti dependensi. Ketika sistem properti memproses properti dependensi, ia mengakses metadatanya. Objek metadata untuk properti dependensi berisi jenis informasi berikut:
Nilai default properti dependensi, yang diatur oleh sistem properti ketika tidak ada nilai lain yang berlaku, seperti nilai lokal, gaya, atau pewarisan. Untuk informasi selengkapnya tentang prioritas nilai selama penetapan run-time nilai properti dependensi, lihat Prioritas nilai properti dependensi.
Referensi ke panggilan balik nilai koersi dan panggilan balik perubahan properti pada jenis pemilik. Anda hanya dapat memperoleh referensi ke panggilan balik yang memiliki
public
pengubah akses atau berada dalam cakupan akses yang diizinkan. Untuk informasi selengkapnya tentang panggilan balik properti dependensi, lihat Panggilan balik dan validasi properti dependensi.Karakteristik properti dependensi tingkat kerangka kerja WPF (jika properti dependensi adalah properti kerangka kerja WPF). Proses WPF, seperti mesin tata letak kerangka kerja dan logika pewarisan properti, mengkueri metadata tingkat kerangka kerja WPF. Untuk informasi selengkapnya, lihat Metadata properti Kerangka Kerja.
API Metadata
Kelas PropertyMetadata menyimpan sebagian besar metadata yang digunakan oleh sistem properti. Instans metadata dapat dibuat dan ditetapkan oleh:
Jenis yang mendaftarkan properti dependensi dengan sistem properti.
Jenis yang mewarisi dari kelas yang menentukan properti dependensi.
Jenis yang menambahkan diri mereka sebagai pemilik properti dependensi.
Jika jenis mendaftarkan properti dependensi tanpa menentukan metadata, sistem properti menetapkan PropertyMetadata
objek dengan nilai default untuk jenis tersebut ke properti dependensi.
Untuk mengambil metadata untuk properti dependensi, panggil salah GetMetadata satu kelebihan beban pada DependencyProperty pengidentifikasi. Metadata dikembalikan sebagai PropertyMetadata
objek.
Kelas metadata yang lebih spesifik, berasal dari PropertyMetadata
, ada untuk area arsitektur yang berbeda. Misalnya, UIPropertyMetadata mendukung pelaporan animasi, dan FrameworkPropertyMetadata mendukung properti kerangka kerja WPF. Properti dependensi juga dapat didaftarkan dengan PropertyMetadata
kelas turunan. Meskipun GetMetadata
mengembalikan PropertyMetadata
objek, jika berlaku, Anda dapat mentransmisikan ke jenis turunan untuk memeriksa properti khusus jenis.
Karakteristik properti yang diekspos oleh FrameworkPropertyMetadata
terkadang disebut sebagai bendera. Saat membuat FrameworkPropertyMetadata
instans, Anda memiliki opsi untuk meneruskan instans jenis FrameworkPropertyMetadataOptions enumerasi ke FrameworkPropertyMetadata
konstruktor. FrameworkPropertyMetadataOptions
memungkinkan Anda menentukan bendera metadata dalam kombinasi bitwise. Penggunaan FrameworkPropertyMetadata
FrameworkPropertyMetadataOptions
untuk menjaga panjang tanda tangan konstruktornya wajar. Pada pendaftaran properti dependensi, bendera metadata yang Anda tetapkan FrameworkPropertyMetadataOptions
diekspos dalam FrameworkPropertyMetadata
sebagai Boolean
properti daripada kombinasi bendera bitwise, untuk membuat kueri karakteristik metadata lebih intuitif.
Mengambil alih atau membuat metadata baru?
Saat Anda mewarisi properti dependensi, Anda memiliki opsi untuk mengubah karakteristik properti dependensi dengan mengambil alih metadatanya. Namun, Anda mungkin tidak selalu dapat menyelesaikan skenario properti dependensi Anda dengan mengambil alih metadata, dan terkadang perlu menentukan properti dependensi kustom di kelas Anda dengan metadata baru. Properti dependensi kustom memiliki kemampuan yang sama dengan properti dependensi yang ditentukan oleh jenis WPF. Untuk informasi selengkapnya, lihat Properti dependensi kustom.
Salah satu karakteristik properti dependensi yang tidak dapat Anda ambil alih adalah jenis nilainya. Jika properti dependensi yang diwariskan memiliki perkiraan perilaku yang Anda butuhkan, tetapi skenario Anda memerlukan jenis nilai yang berbeda, pertimbangkan untuk menerapkan properti dependensi kustom. Anda mungkin dapat menautkan nilai properti melalui konversi jenis atau implementasi lain di kelas turunan Anda.
Skenario untuk mengambil alih metadata
Contoh skenario untuk mengambil alih metadata properti dependensi yang ada adalah:
Mengubah nilai default, yang merupakan skenario umum.
Mengubah atau menambahkan panggilan balik perubahan properti, yang mungkin diperlukan jika properti dependensi yang diwariskan berinteraksi dengan properti dependensi lain secara berbeda dari implementasi dasarnya. Salah satu karakteristik model pemrograman yang mendukung kode dan markup, adalah bahwa nilai properti mungkin diatur dalam urutan apa pun. Faktor ini dapat memengaruhi cara Anda menerapkan panggilan balik perubahan properti. Untuk informasi selengkapnya, lihat Panggilan balik dan validasi properti dependensi.
Mengubah opsi metadata properti kerangka kerja WPF. Biasanya, opsi metadata diatur selama pendaftaran properti dependensi baru, tetapi Anda dapat menspesifikasikannya kembali dalam OverrideMetadata atau AddOwner panggilan. Untuk informasi selengkapnya tentang mengganti metadata properti kerangka kerja, lihat Menentukan FrameworkPropertyMetadata. Untuk cara mengatur opsi metadata properti kerangka kerja saat mendaftarkan properti dependensi, lihat Properti dependensi kustom.
Catatan
Karena panggilan balik validasi bukan bagian dari metadata, mereka tidak dapat diubah dengan mengesampingkan metadata. Untuk informasi selengkapnya, lihat Panggilan balik nilai validasi.
Mengesampingkan metadata
Saat menerapkan properti dependensi baru, Anda dapat mengatur metadatanya dengan menggunakan kelebihan beban Register metode. Jika kelas Anda mewarisi properti dependensi, Anda dapat mengambil alih nilai metadata yang diwariskan menggunakan metode .OverrideMetadata Misalnya, Anda mungkin menggunakan OverrideMetadata
untuk mengatur nilai khusus jenis. Untuk informasi selengkapnya dan sampel kode, lihat Mengambil alih metadata untuk properti dependensi.
Contoh properti dependensi WPF, adalah Focusable. Kelas FrameworkElement mendaftarkan Focusable
. Kelas Control berasal dari FrameworkElement
, mewarisi Focusable
properti dependensi, dan mengambil alih metadata properti yang diwariskan. Penimpaan mengubah nilai properti default dari false
menjadi true
, tetapi mempertahankan nilai metadata warisan lainnya.
Karena sebagian besar properti dependensi yang ada bukan properti virtual, implementasi yang diwariskan membayangi anggota yang ada. Saat Anda mengambil alih karakteristik metadata, nilai metadata baru menggantikan nilai asli atau digabungkan:
DefaultValueUntuk , nilai baru akan menggantikan nilai default yang ada. Jika Anda tidak menentukan
DefaultValue
dalam metadata penimpaan, nilai berasal dari leluhur terdekat yang ditentukanDefaultValue
dalam metadata.PropertyChangedCallbackUntuk , logika penggabungan default menyimpan semua
PropertyChangedCallback
nilai dalam tabel, dan semuanya dipanggil pada perubahan properti. Urutan panggilan balik ditentukan oleh kedalaman kelas, di mana panggilan balik yang didaftarkan oleh kelas dasar dalam hierarki akan berjalan terlebih dahulu.CoerceValueCallbackUntuk , nilai baru akan menggantikan nilai yang
CoerceValueCallback
ada. Jika Anda tidak menentukanCoerceValueCallback
dalam metadata penimpaan, nilai berasal dari leluhur terdekat yang ditentukanCoerceValueCallback
dalam metadata.
Catatan
Logika penggabungan default diimplementasikan oleh Merge metode . Anda dapat menentukan logika penggabungan kustom di kelas turunan yang mewarisi properti dependensi, dengan mengambil alih di kelas tersebut Merge
.
Menambahkan kelas sebagai pemilik
Untuk "mewarisi" properti dependensi yang terdaftar dalam hierarki kelas yang berbeda, gunakan metode .AddOwner Metode ini biasanya digunakan ketika kelas penambahan tidak berasal dari jenis yang mendaftarkan properti dependensi. AddOwner
Dalam panggilan, kelas penambahan dapat membuat dan menetapkan metadata khusus jenis untuk properti dependensi yang diwariskan. Untuk menjadi peserta penuh dalam sistem properti, melalui kode dan markup, kelas penambahan harus mengimplementasikan anggota publik ini:
Bidang pengidentifikasi properti dependensi. Nilai pengidentifikasi properti dependensi adalah nilai
AddOwner
pengembalian panggilan. Bidang ini harus berupapublic static readonly
bidang jenis DependencyProperty.Pembungkus
get
CLR yang mengimplementasikan danset
pengakses. Dengan menggunakan pembungkus properti, konsumen properti dependensi bisa mendapatkan atau mengatur nilai properti dependensi, sama seperti properti CLR lainnya. Aksesorget
danset
berinteraksi dengan sistem properti yang mendasar melalui DependencyObject.GetValue dan DependencyObject.SetValue panggilan, meneruskan pengidentifikasi properti dependensi sebagai parameter. Terapkan pembungkus dengan cara yang sama seperti yang Anda lakukan saat mendaftarkan properti dependensi kustom. Untuk informasi selengkapnya, lihat Properti dependensi kustom
Kelas yang memanggil AddOwner
memiliki persyaratan yang sama untuk mengekspos model objek properti dependensi yang diwariskan sebagai kelas yang menentukan properti dependensi kustom baru. Untuk informasi selengkapnya, lihat Menambahkan jenis pemilik untuk properti dependensi.
Metadata properti terlampir
Di WPF, sebagian besar properti terlampir terkait UI pada jenis WPF diimplementasikan sebagai properti dependensi. Properti terlampir yang diimplementasikan sebagai properti dependensi mendukung konsep properti dependensi, seperti metadata yang dapat diambil alih kelas turunannya. Metadata untuk properti terlampir umumnya tidak berbeda dari untuk properti dependensi. Anda dapat mengambil alih nilai default, properti mengubah panggilan balik, dan properti kerangka kerja WPF untuk properti terlampir yang diwariskan, pada instans kelas penimpaan. Untuk informasi selengkapnya, lihat Metadata properti terlampir
Catatan
Selalu gunakan RegisterAttached untuk mendaftarkan properti tempat Anda menentukan Inherits dalam metadata. Meskipun pewarisan nilai properti mungkin tampak berfungsi untuk properti dependensi yang tidak terpasang, perilaku warisan nilai untuk properti yang tidak terpasang melalui pembagian objek-objek tertentu di pohon runtime tidak terdefinisi. Properti Inherits
tidak relevan untuk properti yang tidak terpasang. Untuk informasi selengkapnya, lihat RegisterAttached(String, Type, Type, PropertyMetadata), dan bagian keterangan dari Inherits.
Menambahkan kelas sebagai pemilik properti terlampir
Untuk mewarisi properti terlampir dari kelas lain, tetapi mengeksposnya sebagai properti dependensi yang tidak terpasang di kelas Anda:
Panggil AddOwner untuk menambahkan kelas Anda sebagai pemilik properti dependensi terlampir.
Tetapkan nilai
AddOwner
pengembalian panggilan kepublic static readonly
bidang, untuk digunakan sebagai pengidentifikasi properti dependensi.Tentukan pembungkus CLR, yang menambahkan properti sebagai anggota kelas dan mendukung penggunaan properti yang tidak terpasang.
Baca juga
.NET Desktop feedback
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk