Bagikan melalui

Metadata properti dependensi (WPF .NET)

  • Artikel

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 FrameworkPropertyMetadataFrameworkPropertyMetadataOptions 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 ditentukan DefaultValue 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 menentukan CoerceValueCallback dalam metadata penimpaan, nilai berasal dari leluhur terdekat yang ditentukan CoerceValueCallback 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 berupa public static readonly bidang jenis DependencyProperty.

  • Pembungkus get CLR yang mengimplementasikan dan set pengakses. Dengan menggunakan pembungkus properti, konsumen properti dependensi bisa mendapatkan atau mengatur nilai properti dependensi, sama seperti properti CLR lainnya. Aksesor get dan set 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 ke public 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