Gambaran umum properti terlampir

Properti terlampir adalah konsep Extensible Application Markup Language (XAML). Properti terlampir memungkinkan pasangan properti/nilai tambahan diatur pada elemen XAML apa pun yang berasal dari DependencyObject, meskipun elemen tidak menentukan properti tambahan tersebut dalam model objeknya. Properti tambahan dapat diakses secara global. Properti terlampir biasanya didefinisikan sebagai bentuk khusus properti dependensi yang tidak memiliki pembungkus properti konvensional.

Prasyarat

Artikel ini mengasumsikan pengetahuan dasar tentang properti dependensi, dan Anda telah membaca gambaran umum properti dependensi . Untuk mengikuti contoh dalam artikel ini, ini membantu jika Anda terbiasa dengan XAML dan tahu cara menulis aplikasi Windows Presentation Foundation (WPF).

Mengapa menggunakan properti terlampir

Properti terlampir memungkinkan elemen turunan menentukan nilai unik untuk properti yang ditentukan dalam elemen induk. Skenario umum adalah elemen turunan yang menentukan bagaimana elemen tersebut harus dirender di UI oleh elemen induknya. Misalnya, DockPanel.Dock adalah properti terlampir karena diatur pada elemen turunan dari DockPanel, bukan DockPanel itu sendiri. Kelas DockPanel mendefinisikan bidang DependencyProperty statis, bernama DockProperty, lalu menyediakan metode GetDock dan SetDock sebagai aksesor publik untuk properti terlampir.

Properti yang terlampir pada XAML

Di XAML, Anda mengatur properti terlampir dengan menggunakan sintaks <attached property provider type>.<property name>, di mana penyedia properti terlampir adalah kelas yang menentukan properti terlampir. Contoh berikut menunjukkan bagaimana elemen turunan DockPanel dapat mengatur nilai properti DockPanel.Dock.

<DockPanel>
    <TextBox DockPanel.Dock="Top">Enter text</TextBox>
</DockPanel>

Penggunaannya mirip dengan properti statis di mana Anda mereferensikan jenis yang memiliki dan mendaftarkan properti terlampir (misalnya, DockPanel), bukan nama instans.

Saat Anda menentukan properti terlampir menggunakan atribut XAML, hanya tindakan yang ditetapkan yang berlaku. Anda tidak bisa langsung mendapatkan nilai properti melalui XAML, meskipun ada beberapa mekanisme tidak langsung untuk membandingkan nilai, seperti pemicu dalam gaya.

Properti terlampir dalam WPF

Properti terlampir adalah konsep XAML, properti dependensi adalah konsep WPF. Di WPF, sebagian besar properti terlampir terkait UI pada jenis WPF diimplementasikan sebagai properti dependensi. Properti terkait WPF yang diimplementasikan sebagai properti dependensi mendukung konsep-konsep properti dependensi, seperti metadata properti yang mencakup nilai default dari metadata.

Model penggunaan properti terlampir

Meskipun objek apa pun dapat mengatur nilai properti terlampir, itu tidak berarti pengaturan nilai akan menghasilkan hasil nyata atau nilai akan digunakan oleh objek lain. Tujuan utama properti terlampir adalah untuk menyediakan cara bagi objek dari berbagai hierarki kelas dan hubungan logis untuk melaporkan informasi umum ke jenis yang menentukan properti terlampir. Penggunaan properti terlampir biasanya mengikuti salah satu model ini:

Jenis yang mendefinisikan properti terlampir adalah elemen induk yang menetapkan nilai untuk properti terlampir. Jenis induk mengiterasi objek turunannya melalui logika internal yang beroperasi pada struktur pohon objek, mendapatkan nilai, dan memproses nilai-nilai tersebut dengan cara tertentu.
Jenis yang mendefinisikan properti terlampir digunakan sebagai elemen turunan untuk berbagai elemen induk dan model konten yang mungkin.
Jenis yang menentukan properti terlampir mewakili layanan. Jenis lain mengatur nilai untuk properti terlampir. Kemudian, ketika elemen yang mengatur properti dievaluasi dalam konteks layanan, nilai properti terlampir diperoleh melalui logika internal kelas layanan.

Contoh properti terlampir yang ditentukan orang tua

Skenario umum di mana WPF mendefinisikan properti terlampir adalah ketika elemen induk mendukung pengumpulan elemen turunan, dan elemen induk mengimplementasikan perilaku berdasarkan data yang dilaporkan oleh setiap elemen turunannya.

DockPanel menentukan properti terlampir DockPanel.Dock. DockPanel memiliki kode tingkat kelas, khususnya MeasureOverride dan ArrangeOverride, itulah bagian dari logika penyajiannya. Instans DockPanel memeriksa apakah salah satu elemen turunan langsungnya telah menetapkan nilai untuk DockPanel.Dock. Jika demikian, nilai-nilai tersebut menjadi input untuk logika penyajian yang diterapkan pada setiap elemen anak. Meskipun secara teoritis mungkin bagi properti terlampir untuk memengaruhi elemen di luar induk langsung, perilaku yang ditentukan untuk instans DockPanel berlapis adalah hanya berinteraksi dengan koleksi elemen turunan langsungnya. Jadi, jika Anda menetapkan DockPanel.Dock pada elemen yang tidak memiliki induk DockPanel, tidak ada kesalahan atau pengecualian yang akan dimunculkan dan Anda akan membuat nilai properti global yang tidak akan digunakan oleh elemen DockPanelmanapun.

Properti yang terlampir dalam kode

Properti terlampir (attached properties) di WPF tidak memiliki metode pembungkus CLR get dan set yang khas karena properti tersebut mungkin diatur dari luar namespace CLR. Untuk mengizinkan prosesor XAML mengatur nilai-nilai tersebut saat mengurai XAML, kelas yang menentukan properti terlampir harus menerapkan metode aksesor khusus dalam bentuk Get<property name> dan Set<property name>.

Anda juga dapat menggunakan metode aksesor khusus untuk mendapatkan dan mengatur properti terlampir dalam kode, seperti yang ditunjukkan dalam contoh berikut. Dalam contoh, myTextBox adalah instans kelas TextBox.

DockPanel myDockPanel = new();
TextBox myTextBox = new();
myTextBox.Text = "Enter text";

// Add child element to the DockPanel.
myDockPanel.Children.Add(myTextBox);

// Set the attached property value.
DockPanel.SetDock(myTextBox, Dock.Top);

Dim myDockPanel As DockPanel = New DockPanel()
Dim myTextBox As TextBox = New TextBox()
myTextBox.Text = "Enter text"

' Add child element to the DockPanel.
myDockPanel.Children.Add(myTextBox)

' Set the attached property value.
DockPanel.SetDock(myTextBox, Dock.Top)

Jika Anda tidak menambahkan myTextBox sebagai elemen turunan dari myDockPanel, panggilan SetDock tidak akan menimbulkan pengecualian atau memiliki efek apa pun. Hanya nilai DockPanel.Dock yang ditetapkan pada elemen anak dari DockPanel yang dapat memengaruhi rendering, dan rendering akan sama apakah Anda mengatur nilai sebelum atau sesudah menambahkan elemen anak yang ditambahkan ke DockPanel.

Dari perspektif kode, properti terpasang seperti bidang dukungan yang memiliki metode pengakses alih-alih pengakses properti, dan dapat diatur pada objek mana pun tanpa perlu terlebih dahulu didefinisikan pada objek tersebut.

Metadata properti terlampir

Metadata untuk properti terlampir umumnya tidak berbeda dari untuk properti dependensi. Saat mendaftarkan properti terlampir, gunakan FrameworkPropertyMetadata untuk menentukan karakteristik properti, seperti apakah properti memengaruhi penyajian atau pengukuran. Saat Anda menentukan nilai default dengan menimpa metadata properti terlampir, nilai tersebut menjadi default untuk properti terlampir yang implisit pada instans dari kelas yang menimpa. Jika nilai properti terlampir tidak diatur, nilai default dilaporkan saat properti dikueri dengan menggunakan aksesor Get<property name> dengan instans kelas tempat Anda menentukan metadata.

Untuk mengaktifkan pewarisan nilai properti pada properti, gunakan properti terlampir alih-alih properti dependensi yang tidak terlampir. Untuk informasi selengkapnya, lihat Pewarisan nilai properti.

Atribut terlampir kustom

Kapan membuat properti terlampir

Membuat properti terlampir berguna saat:

Anda memerlukan mekanisme pengaturan properti yang tersedia untuk kelas selain kelas yang menentukan. Skenario umum adalah untuk tata letak UI, misalnya DockPanel.Dock, Panel.ZIndex, dan Canvas.Top adalah semua contoh properti tata letak yang ada. Dalam skenario tata letak, elemen turunan dari elemen pengontrol tata letak dapat mengekspresikan persyaratan tata letak ke induk tata letaknya dan untuk menetapkan nilai untuk properti terlampir yang ditentukan oleh induk.
Salah satu kelas Anda mewakili layanan, dan Anda ingin kelas lain mengintegrasikan layanan secara lebih transparan.
Anda menginginkan dukungan Visual Studio WPF Designer, seperti kemampuan untuk mengedit properti melalui jendela Properti . Untuk informasi selengkapnya, lihat Gambaran umum penulisan kontrol
Anda ingin menggunakan pewarisan nilai properti.

Cara membuat properti terlampir

Jika kelas Anda mendefinisikan properti terlampir hanya untuk digunakan oleh jenis lain, kelas Anda tidak perlu berasal dari DependencyObject. Jika tidak, ikuti model WPF untuk memiliki properti terlampir juga menjadi properti dependensi, dengan cara membuat kelas Anda turunan dari DependencyObject.

Tentukan properti terlampir Anda sebagai dependensi di kelas yang mendefinisikan dengan mendeklarasikan bidang public static readonly tipe DependencyProperty. Kemudian, tetapkan nilai pengembalian metode RegisterAttached ke bidang , yang juga dikenal sebagai pengidentifikasi properti dependensi . Ikuti konvensi penamaan properti WPF yang membedakan bidang dari properti yang diwakilinya, dengan memberi nama bidang pengidentifikasi <property name>Property. Selain itu, sediakan metode aksesor statis Get<property name> dan Set<property name>, yang memungkinkan sistem properti mengakses properti terlampir Anda.

Contoh berikut menunjukkan cara mendaftarkan properti dependensi menggunakan metode RegisterAttached, dan cara menentukan metode aksesor. Dalam contoh, nama properti terlampir HasFish, sehingga bidang pengidentifikasi diberi nama HasFishProperty, dan metode aksesor diberi nama GetHasFish dan SetHasFish.

public class Aquarium : UIElement
{
    // Register an attached dependency property with the specified
    // property name, property type, owner type, and property metadata.
    public static readonly DependencyProperty HasFishProperty = 
        DependencyProperty.RegisterAttached(
      "HasFish",
      typeof(bool),
      typeof(Aquarium),
      new FrameworkPropertyMetadata(defaultValue: false,
          flags: FrameworkPropertyMetadataOptions.AffectsRender)
    );

    // Declare a get accessor method.
    public static bool GetHasFish(UIElement target) =>
        (bool)target.GetValue(HasFishProperty);

    // Declare a set accessor method.
    public static void SetHasFish(UIElement target, bool value) =>
        target.SetValue(HasFishProperty, value);
}

Public Class Aquarium
    Inherits UIElement

    ' Register an attached dependency property with the specified
    ' property name, property type, owner type, and property metadata.
    Public Shared ReadOnly HasFishProperty As DependencyProperty =
        DependencyProperty.RegisterAttached("HasFish", GetType(Boolean), GetType(Aquarium),
            New FrameworkPropertyMetadata(defaultValue:=False,
                flags:=FrameworkPropertyMetadataOptions.AffectsRender))

    ' Declare a get accessor method.
    Public Shared Function GetHasFish(target As UIElement) As Boolean
        Return target.GetValue(HasFishProperty)
    End Function

    ' Declare a set accessor method.
    Public Shared Sub SetHasFish(target As UIElement, value As Boolean)
        target.SetValue(HasFishProperty, value)
    End Sub

End Class

Dapatkan aksesor

Tanda tangan fungsi metode akses get adalah public static object Get<property name>(DependencyObject target), di mana:

target adalah DependencyObject dari mana properti terlampir dibaca. Jenis target bisa lebih spesifik daripada DependencyObject. Misalnya, metode aksesor DockPanel.GetDock mengategorikan target sebagai UIElement karena properti yang terlampir dimaksudkan untuk diatur pada instansi UIElement. UiElement secara tidak langsung berasal dari DependencyObject.
Jenis pengembalian bisa lebih spesifik daripada object. Misalnya, metode GetDock mengetikkan nilai yang dikembalikan sebagai Dock karena nilai yang dikembalikan harus menjadi enumerasi Dock.

Nota

Aksesor get untuk properti terlampir diperlukan untuk dukungan pengikatan data dalam alat desain, seperti Visual Studio atau Blend untuk Visual Studio.

Aksesor Set

Tanda tangan fungsi metode akses set adalah public static void Set<property name>(DependencyObject target, object value), di mana:

target adalah DependencyObject di mana properti terlampir ditulis. Jenis target bisa lebih spesifik daripada DependencyObject. Misalnya, metode SetDock mengetik target sebagai UIElement karena properti terlampir dimaksudkan untuk diatur pada instans UIElement. UiElement secara tidak langsung berasal dari DependencyObject.
Jenis value bisa lebih spesifik daripada object. Misalnya, metode SetDock memerlukan nilai Dock. Pemuat XAML harus dapat menghasilkan jenis value dari string markup yang mewakili nilai properti terlampir. Jadi, harus ada konversi tipe, serializer nilai, atau dukungan ekstensi markup untuk tipe yang Anda gunakan.

Atribut properti yang terlampir

WPF mendefinisikan beberapa atribut .NET yang menyediakan informasi tentang properti terasosiasi dalam proses refleksi dan juga kepada pihak pengguna informasi refleksi dan properti, seperti desainer. Desainer menggunakan atribut .NET yang ditentukan WPF untuk membatasi properti yang ditunjukkan di jendela properti, untuk menghindari pengguna yang kewalahan dengan daftar global semua properti terlampir. Anda mungkin mempertimbangkan untuk menerapkan atribut ini ke properti terlampir kustom Anda sendiri. Tujuan dan sintaks atribut .NET dijelaskan dalam halaman referensi ini:

Pelajari lebih lanjut

Untuk informasi selengkapnya tentang membuat properti terlampir, lihat Mendaftarkan properti terlampir.
Untuk skenario penggunaan tingkat lanjut lainnya untuk properti dependensi dan properti terlampir, lihat Properti dependensi kustom.
Anda dapat mendaftarkan properti sebagai properti terlampir dan properti dependensi, dan menyertakan pembungkus properti konvensional. Dengan cara ini, properti dapat diatur pada elemen dengan menggunakan pembungkus properti, dan juga pada elemen lain dengan menggunakan sintaks properti terlampir XAML. Misalnya, lihat FrameworkElement.FlowDirection.

Lihat juga

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-05-07