• Struktur UI dengan UX
Pengujian di dalam Pembuat UI
Tulis Template UXML

Struktur UI dengan UX

Unity Extensible Markup Language (UXML) file adalah file teks yang menentukan struktur antarmuka pengguna. Format UXML terinspirasi oleh HTML, XAML, dan XML. Jika Anda telah bekerja dengan format ini sebelum, Anda akan menemukan kesamaan dengan UXML. Namun, format UX mencakup perbedaan kecil untuk memberikan cara yang efisien untuk bekerja dengan Unity.

Bagian ini menjelaskan format UXML yang mendukung Unity dan memberikan rincian tentang menulis, memuat, dan mendefinisikan template UXML. Ini juga mencakup informasi tentang mendefinisikan elemen baru, dan bagaimana menggunakan UQuery.

UXML memudahkan pengguna yang kurang teknis untuk membangun antarmuka pengguna dalam Unity. Di UXML Anda dapat:

  • mendefinisikan struktur antarmuka pengguna (UI) di XML.
  • mendefinisikan tata letak UI(User Interface) Memungkinkan pengguna untuk berinteraksi dengan aplikasi Anda. Unity saat ini mendukung tiga sistem UI. More info
    Lihat di Glossary     dengan stylesheet USS.

Pengembang daun ini untuk melakukan tugas teknis, seperti aset impor, mendefinisikan logika, dan memproses data.

Menentukan elemen baru

Dengan UI Toolkit, Anda dapat menentukan komponen antarmuka pengguna dan elemen Anda sendiri.

Sebelum Anda dapat menggunakan file UXML untuk menentukan elemen baru, Anda harus mendapatkan kelas baru dari VisualElement atau salah satu subklasnya, kemudian menerapkan fungsi yang tepat dalam kelas baru ini. Kelas baru Anda harus menerapkan konstruktor default.

Misalnya, kode berikut berasal dari kelas StatusBar baru dan menerapkan konstruktor defaultnya:

class StatusBar : VisualElement
{
    public StatusBar()
    {
        m_Status = String.Empty;
    }

    string m_Status;
    public string status { get; set; }
}

Dalam rangka untuk UI Toolkit untuk meluruskan kelas baru ketika membaca file UXML, Anda harus mendefinisikan pabrik untuk kelas Anda. Kecuali pabrik Anda perlu melakukan sesuatu yang istimewa, Anda dapat memperoleh pabrik dari UxmlFactoy<T>. Disarankan bahwa Anda menempatkan kelas pabrik dalam kelas komponen Anda.

Sebagai contoh, kode berikut menunjukkan cara menentukan pabrik untuk kelas StatusBar dengan menolak pabriknya dari UxmlFactory<T>. Pabrik ini dinamakan UxmlFactory:

class StatusBar : VisualElement
{
    public new class UxmlFactory : UxmlFactory<StatusBar> {}

    // ...
}

Dengan pabrik ini didefinisikan, Anda dapat menggunakan elemen <StatusBar> dalam file UXML.

Menentukan atribut pada elemen

Anda dapat mendefinisikan sifat UX untuk kelas baru dan mengatur pabriknya untuk menggunakan sifat-sifat ini.

Sebagai contoh, kode berikut menunjukkan cara menentukan kelas UXML untuk menginisialisasi properti status sebagai properti kelas StatusBar. Status properti menginisialisasi dari data XML.

class StatusBar : VisualElement
{
    public new class UxmlFactory : UxmlFactory<StatusBar, UxmlTraits> {}

    public new class UxmlTraits : VisualElement.UxmlTraits
    {
        UxmlStringAttributeDescription m_Status = new UxmlStringAttributeDescription { name = "status" };

        public override IEnumerable<UxmlChildElementDescription> uxmlChildElementsDescription
        {
            get { yield break; }
        }

        public override void Init(VisualElement ve, IUxmlAttributes bag, CreationContext cc)
        {
            base.Init(ve, bag, cc);
            ((StatusBar)ve).status = m_Status.GetValueFromBag(bag, cc);
        }
    }

    // ...
}

UxmlTraits melayani dua tujuan:

  • Pabrik ini menggunakannya untuk menginisialisasi objek baru diciptakan.
  • Proses generasi schema menganalisisnya untuk mendapatkan informasi tentang elemen. Informasi ini diterjemahkan ke dalam arah penjadwalan XML.

Contoh kode di atas melakukan berikut:

  • Pernyataan m_Status mendefinisikan atribut XML bernama status.
  • uxmlChildElementsDescription mengembalikan IEnumerable kosong yang menunjukkan bahwa elemen StatusBar tidak memiliki anak.
  • Anggota Init() membaca nilai atribut status dalam tas properti dari pembuat XML dan menetapkan properti StatusBar.status untuk nilai ini.
  • Dengan menempatkan kelas UxmlTraits di dalam kelas StatusBar memungkinkan metode Init() untuk mengakses anggota pribadi StatusBar.
  • Inherit kelas UxmlTraits baru dari kelas dasar UxmlTraits, sehingga saham atribut kelas dasar.
  • Init() panggilan base.Init() untuk menginisialisasi properti kelas dasar.

Contoh kode di atas menyatakan atribut string dengan kelas UxmlStringAttributeDescription. UI Toolkit mendukung jenis atribut berikut dan setiap tautan tipe C# ke tipe XML:

Attribute Attribute value
UxmlStringAttributeDescription A string
UxmlFloatAttributeDescription Nilai titik mengambang presisi tunggal dalam kisaran tipe C # float.
UxmlDoubleAttributeDescription Nilai titik mengambang presisi ganda dalam kisaran tipe C # double.
UxmlIntAttributeDescription Nilai integer dalam kisaran tipe C # int.
UxmlLongAttributeDescription Nilai bilangan bulat panjang dalam kisaran tipe C # long.
UxmlBoolAttributeDescription true atau false
UxmlColorAttributeDescription string mewakili warna (#FFFFFF)
UxmlEnumAttributeDescription<T> Sebuah string mewakili salah satu nilai untuk jenis Enum.T.

Pada contoh kode di atas, uxmlChildElementsDescription mengembalikan IEnumerable kosong yang menunjukkan bahwa elemen StatusBar tidak menerima anak-anak.

Untuk memiliki elemen menerima anak-anak dari jenis apa pun, Anda harus menimpa properti uxmlChildElementsDescription. Misalnya, untuk elemen StatusBar untuk menerima anak-anak dari jenis apa pun, properti uxmlChildElementsDescription harus ditentukan sebagai berikut:

public override IEnumerable<UxmlChildElementDescription> uxmlChildElementsDescription
{
    get
    {
        yield return new UxmlChildElementDescription(typeof(VisualElement));
    }
}

Menentukan prefiksi namespace

Setelah Anda mendefinisikan elemen baru di C#, Anda dapat mulai menggunakan elemen dalam file UXML Anda. Jika elemen baru Anda didefinisikan dalam namespace baru, Anda harus mendefinisikan prefix untuk namespace. Prefix Namespace dideklarasikan sebagai atribut pada elemen <UXML> root dan mengganti nama namespace penuh ketika mencetak elemen.

Untuk menentukan prefiks namespace, tambahkan atribut UxmlNamespacePrefix ke perakitan Anda untuk setiap prefiks namespace yang ingin Anda tentukan.


[assembly: UxmlNamespacePrefix("My.First.Namespace", "first")]
[assembly: UxmlNamespacePrefix("My.Second.Namespace", "second")]

Anda dapat melakukan ini di tingkat akar (di luar ruang nama) dari setiap file C # dari perakitan.

Sistem generasi skema melakukan berikut:

  • Cek atribut ini dan menggunakannya untuk menghasilkan skema.
  • Menambahkan definisi prefix namespace sebagai atribut dari elemen <UXML> dalam file UXML baru dibuat
  • Sertakan lokasi file schema untuk namespace dalam atribut xsi:schemaLocation.

Anda harus memperbarui skema UXML proyek Anda. Pilih Assets > Update UXML Schema untuk memastikan bahwa editor teks Anda mengenali elemen baru.

Prefix yang ditentukan tersedia di UXML yang baru dibuat dengan memilih Create > UI Toolkit > Editor Window di folder Project/Assets/Editor.

Penggunaan lanjutan

Sesuaikan nama UX

Anda dapat menyesuaikan nama UXML dengan menahan sifat IUxmlFactory.uxmlName dan IUXmlFactory.uxmlQualifiedName. Pastikan uxmlName unik di dalam ruang nama Anda dan bahwa uxmlQualifiedName unik dalam proyek Anda.

Jika kedua nama tidak unik, pengecualian dibuang ketika Anda mencoba memuat perakitan Anda.

Contoh kode berikut menunjukkan cara override dan kustom nama UXML:

public class FactoryWithCustomName : UxmlFactory<..., ...>
{
    public override string uxmlName
    {
        get { return "UniqueName"; }
    }

    public override string uxmlQualifiedName
    {
        get { return uxmlNamespace + "." + uxmlName; }
    }
}

Memilih pabrik untuk elemen

Secara default, elemen IUxmlFactory meluruskan dan memilih elemen menggunakan nama elemen.

Anda dapat membuat proses seleksi mempertimbangkan nilai atribut pada elemen dengan overriding IUXmlFactory.AcceptsAttributeBag. Pabrik kemudian akan memeriksa atribut elemen untuk memutuskan jika dapat mengulangi objek untuk elemen UXML.

Ini berguna jika kelas VisualElement Anda adalah generik. Dalam hal ini, pabrik kelas untuk spesialisasi kelas Anda dapat memeriksa nilai atribut XML type. Tergantung pada nilai, sekiasi dapat diterima atau ditolak.

Dalam kasus di mana lebih dari satu pabrik dapat meluruskan elemen, pabrik terdaftar pertama dipilih.

Mempertahankan nilai default atribut kelas dasar

Anda dapat mengubah nilai default dari atribut yang dinyatakan dalam kelas dasar dengan mengatur kelas defaultValue yang berasal dari kelas UxmlTraits.

Misalnya, kode berikut menunjukkan cara mengubah nilai default m_TabIndex:

class MyElementTraits : VisualElement.UxmlTraits
    {
        public MyElementTraits()
        {
            m_TabIndex.defaultValue = 0;
        }
    }

Menerima atribut apa pun

Secara default, schema XML yang dihasilkan menyatakan bahwa elemen dapat memiliki atribut.

Nilai atribut, selain yang dinyatakan dalam kelas UxmlTraits, tidak dibatasi. Ini berbeda dengan validator XML yang memeriksa nilai atribut yang dinyatakan sesuai dengan deklarasinya.

Atribut tambahan disertakan dalam kantong IUxmlAttributes yang dilewatkan ke fungsi IUxmlFactory.AcceptsAttributBag() dan IUxmlFactory.Init(). Ini hingga implementasi pabrik untuk menggunakan atribut tambahan ini. Perilaku default adalah untuk membuang atribut tambahan.

Ini berarti bahwa atribut tambahan ini tidak melekat pada VisualElement instan dan Anda tidak dapat meminta atribut ini dengan UQuery.

Ketika mendefinisikan elemen baru, Anda dapat membatasi atribut yang diterima bagi mereka secara eksplisit menyatakan dengan menetapkan properti UxmlTraits.canHaveAnyAttribute pada konstrukor false Anda.UxmlTraits constructor.

Menggunakan definisi Skema

File definisi Skema menentukan atribut dan elemen anak mana setiap elemen UXML dapat mengandung. Gunakan file definisi skema sebagai panduan untuk menulis dokumen yang benar dan untuk memvalidasi dokumen Anda.

Dalam file template UXML, atribut xsi:noNamespaceSchemaLocation dan xsi:schemaLocation dari elemen akar <UXML> menentukan lokasi file definisi skema.

Pilih Assets > Create > UI Toolkit > Editor Window untuk secara otomatis memperbarui definisi skema Anda dengan informasi terbaru dari sub-kelas VisualElement yang digunakan oleh proyek Anda. Untuk memaksa pembaruan file skema UXML, pilih Assets > Update UXML Schema.

Note: Beberapa editor teks tidak mengenali atribut xsi:noNamespaceSchemaLocation. Jika editor teks Anda tidak dapat menemukan file definisi skema, Anda juga harus menentukan atribut xsi:schemaLocation.

Pengujian di dalam Pembuat UI
Tulis Template UXML