FrameworkElement.Name Properti

Definisi

Ruang nama:

Microsoft.UI.Xaml

Mendapatkan atau mengatur nama pengidentifikasi objek. Ketika prosesor XAML membuat pohon objek dari markup XAML, kode run-time dapat merujuk ke objek yang dideklarasikan XAML dengan nama ini.

public:
 property Platform::String ^ Name { Platform::String ^ get(); void set(Platform::String ^ value); };

winrt::hstring Name();

void Name(winrt::hstring value);

public string Name { get; set; }

var string = frameworkElement.name;
frameworkElement.name = string;

Public Property Name As String

<frameworkElement Name="xamlNameString"/>

Nilai Properti

String

Platform::String

winrt::hstring

Nama objek , yang harus berupa string yang valid dalam tata bahasa XamlName (lihat tabel dalam referensi atribut x:Name ). Defaultnya adalah string kosong.

Contoh

Contoh ini mendapatkan nilai untuk Name dari objek yang ada, dan menggunakan nama tersebut untuk menargetkan ulang animasi. Anda menargetkan animasi dengan mengatur properti terlampir Storyboard.TargetName .

private void Start_Animation(object sender, PointerRoutedEventArgs e)
{

    // If the Storyboard is running and you try to change
    // properties of its animation objects programmatically, 
    // an error will occur.
    myStoryboard.Stop();

    // Get a reference to the rectangle that was clicked.
    Rectangle myRect = (Rectangle)sender;

    // Change the TargetName of the animation to the name of the
    // rectangle that was clicked.
    myDoubleAnimation.SetValue(Storyboard.TargetNameProperty, myRect.Name);

    // Begin the animation.
    myStoryboard.Begin();
}

Keterangan

Penggunaan properti ini yang paling umum adalah menentukan atribut x:Name untuk objek dalam markup XAML, atau untuk membaca nilai tersebut saat diatur dalam markup. Dalam kebanyakan cara, x:Name atribut dan Name properti setara. Pada elemen tunggal apa pun, x:Name atribut dan Name properti saling eksklusif sebagai atribut XAML; jika Anda mencoba mengatur dan x:NameName pada elemen objek yang sama dalam markup, kesalahan parser akan muncul.

Saat Anda menggunakan tindakan build Halaman default untuk XAML, elemen XAML apa pun yang memiliki atribut x:Name atau Name menghasilkan referensi bidang yang akhirnya diisi oleh InitializeComponent saat XAML dimuat. Referensi bidang mengaktifkan model pemrograman di mana objek dapat langsung direferensikan berdasarkan nama di kode khusus halaman Anda di belakang, setelah pohon objek XAML dimuat ke dalam halaman atau aplikasi.

Nama harus unik dalam namescope XAML. Umumnya, namescope XAML ditentukan oleh halaman XAML, tetapi fitur tertentu seperti templat atau panggilan ke API seperti XamlReader.Load dapat menentukan namescope XAML terpisah. Untuk informasi selengkapnya, lihat Namescope XAML.

Name tidak boleh dilokalkan. Name digunakan sebagai variabel nama bidang di code-behind. Kode tersebut biasanya tidak dapat diakses oleh localizer yang mungkin memiliki akses ke file XAML yang menentukan UI, meskipun ini tergantung pada model penyebaran dan prosedur pelokalan Anda. Ini adalah salah satu alasan mengapa Anda tidak boleh menampilkan string apa pun yang berasal dari Nama di UI aplikasi Anda.

Skenario untuk Nama

Pengaturan x:Name atau Name di XAML yang mendefinisikan elemen UI mendukung beberapa skenario utama:

• Penargetan animasi Untuk menerapkan animasi ke properti objek, Anda harus menargetkan instans tertentu. Anda melakukannya dengan mengatur properti terlampir Storyboard.TargetName pada Garis Waktu apa pun. Nilai yang Anda tetapkan di sini adalah string yang Anda tetapkan sebagai x:Name atau Name. Untuk informasi selengkapnya, lihat Animasi storyboarded.
• Bagian dari templat kontrol Untuk mendukung model status visual dan inisialisasi kontrol, penulis kontrol harus menentukan Name nilai untuk bagian kunci kontrol templat. Untuk informasi selengkapnya, lihat Templat Kontrol XAML.
• Interaksi durasi umum Misalnya, kode dalam penanganan aktivitas mungkin menangani peristiwa pada objek yang menyediakan UI perubahan, tetapi perubahan pada properti terjadi pada elemen UI terdekat lainnya. Cara term mudah untuk menulis kode untuk situasi ini adalah dengan menggunakan referensi bidang yang Namedihasilkan dari .

FindName

Metode utilitas FindName, yang tersedia dari FrameworkElement apa pun, dapat menemukan objek berdasarkan nama di pohon objek selama berada di namescope XAML saat ini. FindName mencari pohon objek yang dibuat XAML secara keseluruhan. Secara teknis, apa yang FindName sebenarnya mencari adalah namescope XAML, yang tidak mempertahankan metafora pohon dan sebaliknya direpresentasikan sebagai tabel hash nama. FindName tidak dapat menemukan nama yang ditentukan dalam templat yang diterapkan. Untuk menemukan item dalam templat yang diterapkan, gunakan VisualTreeHelper.GetChild untuk mendapatkan objek akar templat yang diterapkan. Kemudian Anda dapat memanggil FindName objek akar itu, dan Anda akan mencari namescope XAML templat daripada halaman yang lebih besar.

Pengikatan nama dan data

Anda tidak dapat menggunakan nilai Name string sebagai nilai sumber langsung untuk sumber pengikatan data. Jika Anda harus menampilkan nilai string yang sama seperti Name di UI dengan pengikatan, Anda harus mereplikasi nilai yang sama ke properti Tag , yang dapat digunakan sebagai sumber pengikatan properti. Juga jangan gunakan Name sebagai target pengikatan.

Nilai x:Name atau Name adalah pengidentifikasi yang Anda gunakan untuk mengidentifikasi elemen sumber untuk pengikatan ElementName . Untuk informasi selengkapnya, lihat Pengikatan data secara mendalam.

Nama Pengaturan dalam kode

Anda dapat mengatur nilai Name untuk objek pada durasi, tetapi ada beberapa pertimbangan dan batasan penting yang harus Anda waspadai.

Mengubah nilai Name dalam kode pada durasi jika objek memiliki nilai sebelumnya Name yang ditetapkan di XAML umumnya tidak disarankan. Ini karena mengatur nama setelah pohon objek dimuat tidak akan membuat atau mengubah nama identifikasi referensi bidang yang setara. Jika referensi bidang sudah ada karena x:Name disediakan dalam markup awal, dan Anda mengubah nilai Name, bidang dan nama yang perlu Anda gunakan untuk menemukan objek melalui FindName sekarang berbeda karena bidang tetap sebagai nama yang ditentukan markup.

Name Mengatur nilai untuk objek yang dibuat dalam kode dan karenanya tidak pernah memiliki nilai Nama yang ditentukan XAML sesuai untuk skenario tertentu. Salah satu skenario tersebut adalah jika Anda ingin dapat menemukan objek yang dibuat XAML atau dibuat kode di pohon dengan menggunakan FindName sebagai fungsi utilitas umum. Untuk membuat skenario tersebut berfungsi, Windows Runtime terus menggunakan dan menambahkan ke representasi hashtable namescope XAML pada durasi. Jika Anda mencoba menambahkan objek bernama baru ke pohon objek yang sebagian besar dibuat XAML yang ada, nama harus unik, jika tidak, pengecualian nama duplikat terjadi. Pengecualian nama duplikat mungkin tidak terjadi pada upaya untuk mengatur Name. Sampai Anda mencoba menambahkan objek bernama duplikat ke pohon objek utama, objek baru memiliki namescope XAML mandiri. Hanya pada saat Anda menghubungkan objek ke pohon objek yang lebih besar sehingga kondisi nama duplikat dapat dideteksi. Atau, pengecualian mungkin terjadi pada operasi yang menghubungkan objek di pohon, misalnya pada panggilan ke Add metode koleksi yang terhubung ke pohon objek utama.

Mungkin sulit untuk mengetahui nilai Nama mana yang sudah ada di namescope XAML yang nantinya akan Anda tambahkan objek baru. Tidak ada API tertentu yang melaporkan hashtable lengkap dari nama yang ada dalam namescope XAML. Jika Anda mengatur nilai Nama dalam kode secara ekstensif, Anda mungkin memerlukan teknik untuk menghasilkan string nama yang unik untuk penggunaan duplikat Anda, atau Anda mungkin perlu membungkus panggilan yang menambahkan objek bernama baru dalam blok try-catch untuk menangkap pengecualian yang dapat dihasilkan dari nama duplikat. Atau Anda dapat menambahkan kode Anda sendiri ke InitializeComponent implementasi yang membaca nilai nama yang dihasilkan XAML.

Perhatikan bahwa Anda hanya dapat mengatur Name pada durasi untuk objek yang merupakan FrameworkElement atau Sebaris. Jika objek tidak memiliki Name properti, dan mengatur nama di XAML akan diperlukan menggunakan x:Name atribut daripada Name, tidak ada API run-time yang tersedia untuk mengatur nama run-time objek tersebut.

Lihat juga

• FindName(String)
• TargetName
• atribut x:Name
• Cakupan nama XAML
• Gambaran umum XAML