Migrate dari Unity UI (UGUI) ke UI Toolkit

Halaman ini memandu pengembang dengan pengalaman dalam Unity UI(User Interface) Memungkinkan pengguna untuk berinteraksi dengan aplikasi Anda. Unity saat ini mendukung tiga sistem UI. More info
Lihat di Glossary (UGUI) untuk transisi ke sistem UI Toolkit baru. Ini menjelajahi kesamaan dan perbedaan antara UGUI dan UI Toolkit.

Sebagai sistem UI runtime-only, halaman ini berfokus pada UI runtime. UI Toolkit dapat membuat UI runtime dan Editor. Panduan ini berlaku untuk kedua kasus penggunaan untuk UI Toolkit.

Email: info@ids-imaging.com

Kedua UGUI dan UI Toolkit membangun dan memelihara UI di dalam struktur pohon hirarki. Dalam UGUI, semua elemen dalam hierarki ini terlihat sebagai individu GameObjectsObjek mendasar dalam adegan Unity, yang dapat mewakili karakter, props, pemandangan, kamera, waypoints, dan banyak lagi. Fungsi GameObject didefinisikan oleh Komponen yang melekat padanya. More info
Lihat di Glossary di panel tampilan hierarki. Dalam UI Toolkit, elemen visual yang diatur ke dalam Visual Tree. Pohon Visual tidak terlihat di panel.

Untuk melihat dan debug hirarki UI di UI Toolkit, Anda dapat menggunakan UI Dustgger. Anda dapat menemukan UI Debugger di bilah alat Editor, di bawah Window > UI Toolkit > Debugger.

Perbedaan utama

Kanvas versus

Komponen Canvas di UGUI mirip dengan komponen UIDocument di UI Toolkit. Kedua MonoBehaviours yang melekat pada GameObjects.

Dalam UGUI, komponen Canvas duduk di akar pohon UI. Ini bekerja dengan komponen Canvas Scaler untuk menentukan urutan jenis, rendering, dan mode scaling UI underneath.

Dalam UI Toolkit, komponen UIDocument mengandung referensi ke objek PanelSettings. PanelSettings mengandung pengaturan rendering untuk UI, termasuk mode skala dan urutan semacam. Beberapa komponen UIDocument dapat menunjuk ke objek PanelSettings yang sama, yang mengoptimalkan kinerja ketika menggunakan beberapa layar UI pada sceneAdegan berisi lingkungan dan menu permainan Anda. Pikirkan setiap file Adegan unik sebagai tingkat yang unik. Di setiap Adegan, Anda menempatkan lingkungan, hambatan, dan dekorasi, pada dasarnya merancang dan membangun permainan Anda dalam potongan-potongan. More info
Lihat di Glossary yang sama.

Dalam UGUI, hirarki pohon UI duduk di bawah komponen GameObject memegang komponen Canvas. Dalam UI Toolkit, komponen UIDocument memegang referensi ke elemen akar Pohon Visual.

Komponen UIDocument juga mengandung referensi ke file UXML yang mendefinisikan tata letak UI dari mana Pohon Visual dibangun pada runtime. Lihat bagian Membuat UI untuk informasi lebih lanjut.

Note:
Untuk UI Editor, tidak ada komponen UIDocument diperlukan. Anda dapat memperoleh kelas kustom Anda dari EditorWindow, kemudian menerapkan CreateGUI(). Untuk contoh praktis, lihat panduan pada Membuat jendela editor kustom.

Komponen GameObject versus Elemen Visual

UI Toolkit mengacu pada elemen UI sebagai kontrol atau elemen visual. Contoh elemen UI adalah:

• Controls
• Buttons
• Label teks

UGUI membangun hirarki UI dari GameObjects. Menambahkan elemen UI baru memerlukan menambahkan GameObjects baru ke hierarki. Kontrol individu diterapkan sebagai komponen MonoBehaviour.

Dalam UI Toolkit, Pohon Visual virtual dan tidak menggunakan GameObjects. Anda tidak dapat lagi membangun atau melihat hierarki UI dalam tampilan hirarki, tetapi menghilangkan overhead menggunakan GameObject untuk setiap elemen UI.

Dalam UGUI, elemen UI derive (arah atau tidak langsung) dari kelas dasar UIBehavior. Demikian pula, di UI Toolkit semua elemen UI berasal dari kelas dasar yang disebut VisualElement. Perbedaan kunci adalah kelas VisualElement tidak berasal dari MonoBehaviour. Anda tidak dapat melampirkan elemen visual ke GameObjects.

Bekerja dengan kontrol UI Toolkit di skrip mirip dengan bekerja dengan kontrol UGUI. Tabel berikut menunjukkan interaksi skrip umum dengan kontrol UI di UGUI, dan rekan-rekan UI Toolkit mereka.

Action	UGUI	UI Toolkit
Tulis teks ke label	m_Label.text = "My Text";	m_Label.text = "My Text";
Baca keadaan toggle	bool isToggleChecked = m_Toggle.isOn;	bool isToggleChecked = m_Toggle.value;
Masukkan panggilan ke tombol	m_Button.onClick.AddListener(MyCallbackFunc);	m_Button.clicked += MyCallbackFunc_1; or m_Button.RegisterCallback<ClickEvent>(MyCallbackFunc_2);%

Untuk mempelajari lebih lanjut tentang kontrol dan sifat dan peristiwa mereka, silakan lihat halaman Controls Overview.

Mengakses elemen UI

Dalam UGUI, ada dua cara scriptsSepotong kode yang memungkinkan Anda untuk membuat Komponen Anda sendiri, memicu peristiwa permainan, memodifikasi sifat komponen dari waktu ke waktu dan menanggapi input pengguna dengan cara apa pun yang Anda sukai. More info
Lihat di Glossary dapat mengakses elemen UI:

• Menetapkan referensi ke komponen UI di Editor.
• Mencari komponen dalam hirarki menggunakan fungsi pembantu seperti GetComponentInChildren<T>().

Karena tidak ada GameObject atau komponen di UI Toolkit, Anda tidak dapat langsung menetapkan referensi ke kontrol di Editor. Mereka harus diselesaikan pada runtime menggunakan fungsi query. Sebagai gantinya, akses Pohon Visual melalui komponen UIDocument.

UIDocument adalah MonoBehaviour, sehingga Anda dapat menetapkannya sebagai referensi dan membuat bagian dari PrefabJenis aset yang memungkinkan Anda untuk menyimpan GameObject lengkap dengan komponen dan properti. Prefab bertindak sebagai template dari mana Anda dapat membuat instance objek baru di tempat kejadian. More info
Lihat di Glossary. Komponen UIDocument memegang referensi ke elemen visual akar. Dari akar, skrip dapat menemukan elemen anak dengan tipe atau nama, mirip dengan UGUI.

Tabel di bawah ini menunjukkan perbandingan langsung dari mengakses kontrol UI di Unity UI dan UI Toolkit

Action	UGUI	UI Toolkit
Temukan elemen UI dengan nama	transform.FindChild("childName");	rootVisualElement.Query("childName");
Temukan elemen UI dengan tipe	transform.GetComponentInChildren<Button>();	rootVisualElement.Query<Button>();
Penugasan langsung referensi di Editor	Possible	Not possible

Membuat UI

Salah satu perbedaan terbesar antara UGUI dan UI Toolkit adalah penciptaan antarmuka pengguna.

Baik UGUI dan UI Toolkit memungkinkan Anda untuk secara visual membangun UI dan pratinjau di Editor. Dalam UGUI, UI kemudian disimpan di dalam Prefab, bersama dengan skrip logika yang melekat pada kontrol UI individu.

UI Toolkit Tata letak UI dibuat di UI Builder, kemudian disimpan sebagai satu atau beberapa file UXML. Pada runtime, komponen UIDocument memuat file UXML yang merakit Pohon Visual dalam memori.

Untuk metode yang mirip dengan UGUI, Anda dapat membuat kontrol UI langsung dari skrip, kemudian tambahkan ke Pohon Visual pada runtime.

Prefabs

UGUI menggunakan GameObjects untuk kontrol UI individu dan Prefab yang keduanya mengandung visual dan logika. UI Toolkit mengambil pendekatan yang berbeda untuk digunakan kembali, karena memisahkan logika dan tata letak. Anda dapat membuat komponen UI yang dapat digunakan kembali melalui UXML dan kontrol kustom.

Untuk membuat template yang mirip dengan Prefab di UI Toolkit:

1. Buat file UXML untuk elemen UI parsial.
2. Buat GameObject dengan komponen UIDocument.
3. Referensi file UXML di GameObject.
4. Tambahkan skrip untuk menangani logika komponen UI ke GameObject yang sama.
5. Simpan GameObject sebagai Prefab.

UI Layout

Mengatur elemen UI individu di layar di UGUI adalah proses manual. Secara default, kontrol UI bebas mengambang dan hanya dipengaruhi oleh orang tua langsung mereka. Kontrol UI lain di bawah orang tua yang sama tidak mempengaruhi posisi atau ukuran saudara mereka. Pivots dan jangkar mengontrol posisi dan ukuran elemen.

Sistem tata letak UI Toolkit dipengaruhi oleh desain web, dan berdasarkan generasi tata letak otomatis. Sistem tata letak otomatis mempengaruhi semua elemen secara default, dan ukuran elemen dan posisi akan mempengaruhi elemen lain di bawah induk yang sama.

Perilaku default dalam UI Toolkit sebanding untuk menempatkan semua elemen di dalam VerticalLayoutGroup di UGUI, dan menambahkan komponen LayoutElement untuk masing-masing.

Anda dapat menonaktifkan generasi tata letak otomatis dengan mengubah properti IStyle position elemen visual. Semua elemen visual memiliki properti ini. Lihat Visual Tree untuk sampel kode.

UI Toolkit tidak memiliki setara langsung untuk penahan dan pivot elemen UI, karena perbedaan tata letak fundamental dibandingkan dengan UGUI.

Ukuran dan posisi elemen dikendalikan oleh mesin tata letak. Untuk mempelajari lebih lanjut tentang ini, silakan lihat dokumentasi Layout Engine, dan bagian Positioning halaman Pohon Visual.

Pesanan pengiriman

Dalam UGUI, urutan GameObjects di hirarki menentukan urutan rendering. Objek lebih jauh di hirarki render terakhir dan muncul di atas. Dalam adegan dengan beberapa Kanvas, komponen Sort Order pada akar Canvas menentukan urutan render dari pohon UI individu.

Perintah render di Pohon Visual di UI Toolkit beroperasi dengan cara yang sama. Orang tua elemen render sebelum anak-anak mereka, dan anak-anak render dari yang pertama sampai akhir, sehingga yang terakhir muncul di atas. IUn a adegan dengan beberapa Dokumen UI, urutan render ditentukan oleh pengaturan Sort Order pada komponen root UIDocument.

Untuk mengubah urutan rendering elemen di UGUI, seperti membuat elemen muncul di atas, Anda dapat memanggil fungsi sibling pada komponen Transform dari GameObject. Kelas VisualElement menawarkan fungsi yang sebanding untuk mengontrol urutan rendering. Seperti semua kontrol UI Toolkit berasal dari kelas ini, semua kontrol memiliki akses ke fungsi ini.

Tabel di bawah ini menunjukkan fungsi UGUI untuk mengontrol pesanan render dan fungsi setara dalam UI Toolkit:

Action	UGUI	UI Toolkit
Membuat elemen render di bawah semua saudara lainnya	transform.SetAsFirstSibling();	myVisualElement.SendToBack();
Membuat elemen render di atas semua saudara lainnya	transform.SetAsLastSibling();	myVisualElement.BringToFront();
Kontrol manual urutan render elemen relatif terhadap saudaranya	transform.SetSiblingIndex(newIndex);	myVisualElement.PlaceBehind(sibling); myVisualElement.PlaceInFront(sibling);

Events

Sama seperti UGUI, interaksi pengguna dalam acara pemicu UI Toolkit. Kode dapat berlangganan menerima callback pada acara, seperti menekan tombol atau memindahkan slider.

Dalam UGUI, semua elemen UI didasarkan pada MonoBehaviour, dan dapat mengekspos acara mereka di Editor. Hal ini memungkinkan untuk mengatur logika dengan GameObjects lain, misalnya untuk menyembunyikan atau menyembunyikan elemen UI lainnya, atau untuk menetapkan fungsi callback.

Dalam UI Toolkit, logika dan tata letak UI disimpan secara terpisah. Callbacks tidak dapat lagi diatur secara langsung pada GameObjects atau disimpan di Prefab. Anda harus mengatur semua callback pada runtime, dan menanganinya melalui scripting.

Button playButton = new Button("Play");
playButton.RegisterCallback<ClickEvent>(OnPlayButtonPressed);
...
private void OnPlayButtonPressed(ClickEvent evt)
{
  // Handle button press
}

Sistem pengiriman acara di UI Toolkit berbeda dari acara di UGUI. Tergantung pada jenis acara, peristiwa tidak hanya dikirim ke kontrol UI target, tetapi juga untuk semua kontrol orang tua.

Untuk mempelajari lebih lanjut tentang ini, lihat Events Dispatching.