Get started with runtime UI

Get started with runtime UI by a simple example.

阅读时间4 分钟

最后更新于 1 个月前

Try the following simple runtime UI example to get started. The example adds a label, a button, a toggle, and a text field in a scene. When you click the button, the Console window shows a message. When you select the toggle and click the button, the Console window shows how many times the buttons have been clicked. When you enter a text message in the text field, the Console window shows the message.

Prerequisites

This guide is for developers familiar with the Unity Editor, UI Toolkit, and C# scripting. Before you start, get familiar with the following:

You can find the completed files that this example creates in this GitHub repository.

Create a Panel Renderer and a UXML Document

Create a Panel Renderer GameObject in the SampleScene and a UXML Document to define the UI structure.

Create a project in Unity Editor with any template.
In the SampleScene, select
GameObject
?
> UI Toolkit > Panel Renderer. This creates the following:
- A UI Toolkit folder with a Panel Settings asset and a default runtime theme.
- A GameObject with a Panel Renderer component attached. The Panel Renderer component is connected to the Panel Settings asset.
Select the Panel Renderer GameObject in the hierarchy.
In the Source Asset field, select New. This creates an empty UXML Document.
Rename the UXML Document to SimpleRuntimeUI.uxml.

Enable in-scene UI authoring

You can edit the UXML Document in either UI Builder or the Hierarchy window directly. This example demonstrates how to use the Hierarchy window to edit the UXML Document. By default, in-scene UI authoring is disabled. To enable it:

Select Edit >
Project Settings
?
.
In the Project Settings window, select UI Toolkit > Enable in-scene UI Authoring. This displays the UXML Document's visual tree in the Hierarchy window.

Add a root element for your UXML Document

Add a visual element as the root of the UXML Document you created.

In the Hierarchy window, select the arrow icon (>) next to SimpleRuntimeUI.uxml to enter the UI Staging mode.
In the UI Staging mode, select + > UI Toolkit > Standard Elements >
Visual Element
?
to add a VisualElement as the root element.
Select the VisualElement in the Hierarchy window, and in the
Inspector
?
window, expand the Style section.
Set Flex > Grow to
```
1
```
to make the VisualElement fill the entire screen.

Add child elements of the VisualElement

Add a Label, a Button, a Toggle, and a TextField as child elements of the VisualElement.

Right-click the VisualElement in the Hierarchy window, and select Standard Elements > Label to add a Label as a child element of the VisualElement.
Select the Label and in the Inspector window, expand the Attributes section and set the Text attribute to
```
This is a Label
```
.
Select Window > UI Toolkit > UI Library to open the UI Library window.
In the UI Library window, search for
```
Button
```
.
Drag the Button from the UI Library window to the Hierarchy window to add the Button as a child element of the VisualElement.
Select the Button and in the Inspector window:
- Enter
```
button
```
  as the name of the Button element.
- Expand the Attributes section and set the Text attribute to
```
This is a Button
```
  .
Repeat the steps to add a Toggle and a TextField as child elements of the VisualElement:
- Set the name of the Toggle element to
```
toggle
```
  , and set the Text attribute to
```
Display the counter?
```
  .
- Set the name of the TextField element to
```
input-message
```
  , and set the Label attribute to
```
Enter a message
```
  .
In the Hierarchy window, right-click the SimpleRuntimeUI.uxml, and select Save to save the UXML document.

The finished UXML file looks like the following:


<ui:UXML xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements" noNamespaceSchemaLocation="../../../../UIElementsSchema/UIElements.xsd">    <ui:VisualElement style="flex-grow: 1;">        <ui:Label text="This is a Label" display-tooltip-when-elided="true" />        <ui:Button text="This is a Button" display-tooltip-when-elided="true" name="button" />        <ui:Toggle label="Display the counter?" name="toggle" />        <ui:TextField picking-mode="Ignore" label="Text Field" name="input-message" value="filler text" />    </ui:VisualElement></ui:UXML>

Define the behavior of your UI controls

To add logic, create a C# script that derives from

MonoBehaviour

to access the controls that the UXML Document component references.

Create a C# script named

SimpleRuntimeUIWithUXML.cs

with the following contents:


using UnityEngine;using UnityEngine.UIElements;public class SimpleRuntimeUIWithUXML : MonoBehaviour{    private Button button;    private Toggle toggle;    private int clickCount;    void Awake()    {        GetComponent<PanelRenderer>().RegisterUIReloadCallback(OnUIReload);    }    void OnDestroy()    {        GetComponent<PanelRenderer>().UnregisterUIReloadCallback(OnUIReload);    }    private void OnUIReload(PanelRenderer panelRenderer, VisualElement root, int version)    {        button = root.Q<Button>("button");        toggle = root.Q<Toggle>("toggle");        button.RegisterCallback<ClickEvent>(PrintClickMessage);        var inputFields = root.Q<TextField>("input-message");        inputFields.RegisterCallback<ChangeEvent<string>>(InputMessage);    }    private void PrintClickMessage(ClickEvent evt)    {        ++clickCount;        Debug.Log($"{"button"} was clicked!" +                (toggle.value ? " Count: " + clickCount : ""));    }    public static void InputMessage(ChangeEvent<string> evt)    {        Debug.Log($"{evt.newValue} -> {evt.target}");    }}

Add SimpleRuntimeUIWithUXML.cs as a component of the Panel Renderer GameObject.

Test your runtime UI

Enter Play mode in the Unity Editor.
Interact with the button and toggle to check the debug messages in the Console.

文档

Development

User Acquisition

Monetization

工业

Unity Engine

User Manual

Script Reference