Bahasa

Gambaran umum properti terlampir

Properti terlampir adalah konsep XAML. Properti terlampir memungkinkan pasangan properti/nilai tambahan diatur pada objek, tetapi properti bukan bagian dari definisi objek asli. Properti yang dilampirkan biasanya didefinisikan sebagai bentuk khusus properti dependensi yang tidak memiliki pembungkus properti yang konvensional dalam model objek tipe pemilik.

Prasyarat

Kami berasumsi bahwa Anda memahami konsep dasar properti dependensi, dan telah membaca Gambaran Umum Properti Dependensi.

Properti Terlampir dalam XAML

Di XAML, Anda mengatur properti terlampir dengan menggunakan sintaks AttachedPropertyProvider.PropertyName. Berikut adalah contoh bagaimana Anda dapat mengatur Canvas.Left di XAML.

<Canvas>
  <Button Canvas.Left="50">Hello</Button>
</Canvas>

Nota

Kami hanya menggunakan Canvas.Left sebagai contoh properti terlampir tanpa sepenuhnya menjelaskan mengapa Anda akan menggunakannya. Jika Anda ingin tahu lebih banyak tentang fungsi Canvas.Left dan bagaimana Canvas menangani komponen tata letaknya, lihat topik referensi Kanvas atau Tentukan tata letak dengan XAML.

Mengapa menggunakan properti terlampir?

Properti terlampir adalah cara untuk menghindari konvensi pengodean yang mungkin mencegah objek yang berbeda dalam hubungan berkomunikasi satu sama lain pada waktu proses. Dimungkinkan untuk menempatkan properti pada kelas dasar umum sehingga setiap objek bisa mendapatkan dan mengatur properti tersebut. Tetapi akhirnya banyaknya skenario di mana Anda mungkin ingin melakukan ini akan membengkak kelas dasar Anda dengan properti yang dapat dibagikan. Mungkin juga terdapat keadaan di mana hanya dua dari ratusan keturunan yang mencoba menggunakan suatu properti. Itu bukan desain kelas yang bagus. Untuk mengatasi hal ini, konsep properti terlampir memungkinkan objek untuk menetapkan nilai untuk properti yang tidak ditentukan struktur kelasnya sendiri. Kelas yang menentukan dapat membaca nilai dari objek anak pada waktu proses setelah berbagai objek dibuat di pohon objek.

Misalnya, elemen turunan dapat menggunakan properti terlampir untuk menginformasikan elemen induk mereka tentang bagaimana elemen tersebut disajikan di UI. Ini adalah kasus dengan properti terlampir Canvas.Left. Canvas.Left dibuat sebagai properti terlampir karena diatur pada elemen yang terkandung dalam elemen Canvas , bukan pada Kanvas itu sendiri. Setiap elemen anak yang mungkin kemudian menggunakan Canvas.Left dan Canvas.Top untuk menentukan offset tata letaknya dalam induk kontainer tata letak Kanvas . Properti terlampir memungkinkan ini berfungsi tanpa mengacaukan model objek elemen dasar dengan banyak properti yang masing-masing hanya berlaku untuk salah satu dari banyak kontainer tata letak yang mungkin. Sebagai gantinya, banyak kontainer tata letak mengimplementasikan kumpulan properti terlampir mereka sendiri.

Untuk mengimplementasikan properti terlampir, kelas Canvas menentukan bidang DependencyProperty statis bernama Canvas.LeftProperty. Kemudian, Canvas menyediakan metode SetLeft dan GetLeft sebagai aksesor publik untuk properti terlampir, untuk mengaktifkan pengaturan XAML dan akses nilai run-time. Untuk XAML dan untuk sistem properti dependensi, set API ini memenuhi pola yang memungkinkan sintaks XAML tertentu untuk properti terlampir, dan menyimpan nilai di penyimpanan properti dependensi.

Cara jenis pemilik menggunakan properti terlampir

Meskipun properti terlampir dapat diatur pada elemen XAML apa pun (atau DependencyObject yang mendasar), itu tidak secara otomatis berarti bahwa pengaturan properti menghasilkan hasil yang nyata, atau bahwa nilainya pernah diakses. Jenis yang mendefinisikan properti terlampir biasanya mengikuti salah satu skenario berikut:

  • Tipe yang mendefinisikan properti terlampir adalah induk dalam hubungan dengan objek lain. Objek anak akan menetapkan nilai untuk properti terlampir. Jenis pemilik properti terlampir memiliki beberapa perilaku bawaan yang melakukan iterasi melalui elemen turunannya, mendapatkan nilai, dan bertindak pada nilai-nilai tersebut pada titik tertentu dalam masa pakai objek (tindakan tata letak, SizeChanged, dll.)
  • Jenis yang mendefinisikan properti terlampir digunakan sebagai elemen turunan untuk berbagai elemen induk dan model konten yang mungkin, tetapi informasi tersebut belum tentu merupakan informasi tata letak.
  • Properti terlampir melaporkan info ke layanan, bukan ke elemen UI lain.

Untuk informasi selengkapnya tentang skenario dan jenis pemilik ini, lihat bagian "Selengkapnya tentang Canvas.Left" dari Properti terlampir kustom.

Properti terlampir dalam kode

Properti terlampir tidak memiliki pembungkus properti umum untuk mendapatkan dan mengatur akses yang mudah seperti yang dilakukan properti dependensi lainnya. Ini karena properti terlampir belum tentu menjadi bagian dari model objek yang berfokus pada kode pada instans di mana properti tersebut diatur. (Ini diizinkan, meskipun jarang, untuk menentukan properti yang merupakan properti terlampir yang dapat diatur oleh jenis lain pada diri mereka sendiri, dan yang juga memiliki penggunaan properti konvensional pada jenis pemilik.)

Ada dua cara untuk mengatur properti terlampir dalam kode: gunakan API sistem properti, atau gunakan pengaktif pola XAML. Teknik-teknik ini cukup banyak setara dalam hal hasil akhir mereka, sehingga yang digunakan sebagian besar adalah masalah gaya pengkodian.

Menggunakan sistem properti

Properti terlampir untuk Windows Runtime diimplementasikan sebagai properti dependensi, sehingga nilai dapat disimpan di penyimpanan properti dependensi bersama oleh sistem properti. Oleh karena itu, properti terlampirkan mengekspos pengidentifikasi properti dependensi pada kelas pemilik.

Untuk mengatur properti terlampir dalam kode, Anda memanggil metode SetValue , dan meneruskan bidang DependencyProperty yang berfungsi sebagai pengidentifikasi untuk properti terlampir tersebut. (Anda juga meneruskan nilai yang akan ditetapkan.)

Untuk mendapatkan nilai properti terlampir dalam kode, Anda memanggil metode GetValue , sekali lagi melewati bidang DependencyProperty yang berfungsi sebagai pengidentifikasi.

Menggunakan pola aksesor XAML

Prosesor XAML harus dapat mengatur nilai properti terlampir saat XAML diurai ke dalam pohon objek. Jenis pemilik properti terlampir harus menerapkan metode aksesor khusus bernama dalam formulir GetPropertyName dan SetPropertyName. Metode aksesor khusus ini juga merupakan salah satu cara untuk mendapatkan atau mengatur properti terlampir dalam kode. Dari perspektif kode, properti terlampir mirip dengan bidang penunjang yang memiliki akses metode alih-alih akses properti, dan bidang penunjang tersebut dapat ada pada objek apa pun, bukan harus didefinisikan secara khusus.

Contoh berikutnya menunjukkan bagaimana Anda dapat mengatur properti terlampir dalam kode melalui API aksesor XAML. Dalam contoh ini, myCheckBox adalah instans kelas CheckBox . Baris terakhir adalah kode yang benar-benar menetapkan nilai; baris sebelum itu hanya menetapkan instans dan hubungan induk-anak mereka. Baris terakhir yang tidak dikomentari adalah sintaksis yang digunakan jika Anda menggunakan sistem properti. Baris terakhir yang dikomentari adalah sintaksis jika Anda menggunakan pola aksesor XAML.

    Canvas myC = new Canvas();
    CheckBox myCheckBox = new CheckBox();
    myCheckBox.Content = "Hello";
    myC.Children.Add(myCheckBox);
    myCheckBox.SetValue(Canvas.TopProperty,75);
    //Canvas.SetTop(myCheckBox, 75);

Canvas myC;
CheckBox myCheckBox;
myCheckBox.Content(winrt::box_value(L"Hello"));
myC.Children().Append(myCheckBox);
myCheckBox.SetValue(Canvas::TopProperty(), winrt::box_value(75));
// Canvas::SetTop(myCheckBox, 75);

    Canvas^ myC = ref new Canvas();
    CheckBox^ myCheckBox = ref new CheckBox();
    myCheckBox->Content="Hello";
    myC->Children->Append(myCheckBox);
    myCheckBox->SetValue(Canvas::TopProperty,75);
    // Canvas::SetTop(myCheckBox, 75);

Atribut terlampir kustom

Untuk contoh kode tentang cara menentukan properti terlampir kustom, dan info selengkapnya tentang skenario untuk menggunakan properti terlampir, lihat Properti terlampir kustom.

Sintaks khusus untuk referensi properti terlampir

Titik dalam nama properti terlampir adalah bagian kunci dari pola identifikasi. Terkadang ada ambiguitas ketika sintaks atau situasi memperlakukan titik sebagai memiliki beberapa arti lain. Misalnya, titik diperlakukan sebagai penelusuran model objek untuk jalur pengikatan. Dalam kebanyakan kasus yang melibatkan ambiguitas semacam itu, ada sintaks khusus untuk properti terlampir yang memungkinkan titik internal tetap diurai sebagai pemisah antara pemilik. dan properti pada properti terlampir.

  • Untuk menentukan properti terlampir sebagai bagian dari jalur target untuk animasi, sertakan nama properti terlampir dalam tanda kurung ()—misalnya, (Canvas.Left). Untuk informasi selengkapnya, lihat Sintaks jalur properti.

Peringatan

Batasan implementasi WinUI yang ada adalah Anda tidak dapat menganimasikan properti terlampir kustom.

  • Untuk menentukan properti terlampir sebagai properti target untuk referensi sumber daya dari file sumber daya ke x:Uid, gunakan sintaks khusus yang menyuntikkan deklarasi gaya kode "menggunakan:" sepenuhnya dirinci di dalam kurung siku ("[]"), untuk membuat pemutusan cakupan yang disengaja. Misalnya, dengan asumsi ada elemen <TextBlock x:Uid="Title" />, kunci sumber daya dalam file sumber daya yang menargetkan nilai Canvas.Top pada instans tersebut adalah Title.\[using:Microsoft.UI.Xaml.Controls\]Canvas.Top. Untuk informasi selengkapnya tentang file sumber daya dan XAML, lihat Melokalkan string di UI Anda.
  • Last updated on