FrameworkElement.Name Properti

  • Referensi

Definisi

Ruang nama:
Windows.UI.Xaml
Edit

Mendapatkan atau mengatur nama identifikasi 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 Nama dari objek yang sudah 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();
}

Private Sub Start_Animation(ByVal sender As Object, ByVal e As PointerRoutedEventArgs)
    ' 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.
    Dim myRect As Rectangle = CType(sender, Rectangle)
    ' 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()
End Sub

Keterangan

Penggunaan paling umum dari properti ini adalah menentukan atribut x:Name untuk objek dalam markup XAML, atau untuk membaca nilai tersebut saat diatur dalam markup. Dalam kebanyakan cara, atribut x:Name dan properti Name setara. Pada elemen tunggal apa pun, atribut x:Name dan properti Name saling eksklusif sebagai atribut XAML; jika Anda mencoba mengatur x:Name dan Name 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, 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.

Nama tidak boleh dilokalkan. Nama 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:Nama atau Nama di XAML yang menentukan 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:Nama atau Nama. Untuk informasi selengkapnya, lihat Animasi storyboarding.

  • Bagian templat kontrol Untuk mendukung model status visual dan inisialisasi kontrol, penulis kontrol harus menentukan nilai Nama untuk bagian kunci kontrol templat. Untuk informasi selengkapnya lihat Mulai Cepat: Mengontrol templat.
  • 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 dihasilkan dari Nama.

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, yang sebenarnya dicari FindName 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 pada objek akar tersebut, dan Anda akan mencari namescope XAML templat daripada halaman yang lebih besar.

Pengikatan nama dan data

Anda tidak dapat menggunakan nilai string Nama sebagai nilai sumber langsung untuk sumber pengikatan data. Jika Anda harus menampilkan nilai string yang sama dengan Nama di UI dengan pengikatan, Anda harus mereplikasi nilai yang sama ke properti Tag , yang dapat digunakan sebagai sumber pengikatan properti. Juga jangan gunakan Nama 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 Nama untuk objek pada durasi, tetapi ada beberapa pertimbangan dan batasan penting yang harus Anda waspadai.

Mengubah nilai Nama dalam kode pada durasi jika objek memiliki nilai Nama sebelumnya 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 Nama, bidang dan nama yang perlu Anda gunakan untuk menemukan objek melalui FindName sekarang berbeda karena bidang tetap sebagai nama yang ditentukan markup.

Mengatur nilai Nama untuk objek yang dibuat dalam kode dan karena itu 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 Nama. 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 metode Tambahkan 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 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 run time Anda, atau Anda mungkin perlu membungkus panggilan yang menambahkan objek yang baru diberi nama dalam blok try-catch untuk menangkap pengecualian yang dapat dihasilkan dari nama duplikat. Atau Anda dapat menambahkan kode Anda sendiri ke implementasi InitializeComponent yang membaca nilai nama yang dihasilkan XAML.

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

Berlaku untuk

Lihat juga