使用 Painter2D API 创建径向进度指示器
版本： 2023.2+
此示例演示如何创建自定义控件并使用 Painter2D API 将视觉内容绘制到视觉元素实例化或派生自 C# 的可视化树的节点VisualElement类。您可以设置外观样式、定义行为并将其作为 UI 的一部分显示在屏幕上。更多信息
请参阅术语表.
示例概述
此示例创建显示进度的自定义控件，作为加载栏的替代方法。进度指示器在显示百分比的标签周围的部分填充环中显示进度值。它支持一个介于 0 和 100 之间的值，该值决定了填充环的量。
您可以在此 GitHub 存储库中找到此示例创建的已完成文件。
先决条件
本指南适用于熟悉 Unity 编辑器、UI 工具包和 C# 脚本的开发人员。在开始之前，请熟悉以下内容：
创建径向进度控件及其自定义网格
创建一个 C# 脚本来定义RadialProgressvisual 元素和 C# 脚本来定义自定义网格Unity 的主要图形基元。网格构成了 3D 世界的很大一部分。Unity 支持三角或四边形多边形网格。Nurbs、Nurms、Subdiv 表面必须转换为多边形。更多信息
请参阅术语表.使用 USS 文件设置视觉元素的样式。
- 使用任何模板创建 Unity 项目。
- 创建一个名为
radial-progress以存储您的文件。 - 在
radial-progress文件夹中，创建一个名为RadialProgress.cs内容如下：
using Unity.Collections;
using UnityEngine;
using UnityEngine.UIElements;
namespace MyGameUILibrary
{
// An element that displays progress inside a partially filled circle
[UxmlElement]
public partial class RadialProgress : VisualElement
{
// These are USS class names for the control overall and the label.
public static readonly string ussClassName = "radial-progress";
public static readonly string ussLabelClassName = "radial-progress__label";
// These objects allow C# code to access custom USS properties.
static CustomStyleProperty<Color> s_TrackColor = new CustomStyleProperty<Color>("--track-color");
static CustomStyleProperty<Color> s_ProgressColor = new CustomStyleProperty<Color>("--progress-color");
Color m_TrackColor = Color.gray;
Color m_ProgressColor = Color.red;
// This is the label that displays the percentage.
Label m_Label;
// This is the number that the Label displays as a percentage.
float m_Progress;
// A value between 0 and 100
[UxmlAttribute]
public float progress
{
// The progress property is exposed in C#.
get => m_Progress;
set
{
// Whenever the progress property changes, MarkDirtyRepaint() is named. This causes a call to the
// generateVisualContents callback.
m_Progress = value;
m_Label.text = Mathf.Clamp(Mathf.Round(value), 0, 100) + "%";
MarkDirtyRepaint();
}
}
// This default constructor is RadialProgress's only constructor.
public RadialProgress()
{
// Create a Label, add a USS class name, and add it to this visual tree.
m_Label = new Label();
m_Label.AddToClassList(ussLabelClassName);
Add(m_Label);
// Add the USS class name for the overall control.
AddToClassList(ussClassName);
// Register a callback after custom style resolution.
RegisterCallback<CustomStyleResolvedEvent>(evt => CustomStylesResolved(evt));
// Register a callback to generate the visual content of the control.
generateVisualContent += GenerateVisualContent;
progress = 0.0f;
}
static void CustomStylesResolved(CustomStyleResolvedEvent evt)
{
RadialProgress element = (RadialProgress)evt.currentTarget;
element.UpdateCustomStyles();
}
// After the custom colors are resolved, this method uses them to color the meshes and (if necessary) repaint
// the control.
void UpdateCustomStyles()
{
bool repaint = false;
if (customStyle.TryGetValue(s_ProgressColor, out m_ProgressColor))
repaint = true;
if (customStyle.TryGetValue(s_TrackColor, out m_TrackColor))
repaint = true;
if (repaint)
MarkDirtyRepaint();
}
void GenerateVisualContent(MeshGenerationContext context)
{
float width = contentRect.width;
float height = contentRect.height;
var painter = context.painter2D;
painter.lineWidth = 10.0f;
painter.lineCap = LineCap.Butt;
// Draw the track
painter.strokeColor = m_TrackColor;
painter.BeginPath();
painter.Arc(new Vector2(width * 0.5f, height * 0.5f), width * 0.5f, 0.0f, 360.0f);
painter.Stroke();
// Draw the progress
painter.strokeColor = m_ProgressColor;
painter.BeginPath();
painter.Arc(new Vector2(width * 0.5f, height * 0.5f), width * 0.5f, -90.0f, 360.0f * (progress / 100.0f) - 90.0f);
painter.Stroke();
}
}
}
设置自定义控件的样式
创建一个名为 USS 文件RadialProgress.uss内容如下：
.radial-progress {
min-width: 26px;
min-height: 20px;
--track-color: rgb(130, 130, 130);
--progress-color: rgb(46, 132, 24);
--percentage-color: white;
margin-left: 5px;
margin-right: 5px;
margin-top: 5px;
margin-bottom: 5px;
flex-direction: row;
justify-content: center;
width: 100px;
height: 100px;
}
.radial-progress__label {
-unity-text-align: middle-left;
color: var(--percentage-color);
}
在 UI 文档中使用自定义控件并测试
使用 UI 生成器添加控件并应用 USS 样式表。使用不同的控件测试控件Progress值。
- 创建名为
RadialProgressExample.uxml. - 双击
RadialProgressExample.uxml在 UI Builder 中打开它。 - 在“库”窗口中，选择“项目”>“自定义控件”> UxmlSerializedData > MyUILibrary。
- 将 RadialProgress 拖到“层次结构”窗口。
- 在 UI Builder 的 StyleSheets 部分中，将
RadialProgress.uss作为现有的 USS。 - 在“层次结构”窗口中，选择“RadialProgress”。
- 在检查器一个Unity 窗口，显示有关当前选定游戏对象、资产或项目设置的信息，允许您检查和编辑值。更多信息
请参阅术语表窗口，请输入radial-progress在“名称”框中。 - 在“检查器”窗口中，在“进度”框中输入不同的值。中的百分比视口用户在屏幕上应用的可见区域。
在术语表中查看更改，绿色进度环将调整大小。
创建逻辑以使用动态值更新进度
创建一个 C# MonoBehaviour 脚本来更新Progress控件的属性，其中包含用于演示目的的动态值。 在radial-progress文件夹中，创建一个名为RadialProgressComponent.cs内容如下：
using MyUILibrary;
using UnityEngine;
using UnityEngine.UIElements;
[RequireComponent(typeof(UIDocument))]
public class RadialProgressComponent : MonoBehaviour
{
RadialProgress m_RadialProgress;
void OnEnable()
{
var root = GetComponent<UIDocument>().rootVisualElement;
m_RadialProgress = new RadialProgress() {
style = {
position = Position.Absolute,
left = 20, top = 20, width = 200, height = 200
}
};
root.Add(m_RadialProgress);
}
void Update()
{
m_RadialProgress.progress = ((Mathf.Sin(Time.time) + 1.0f) / 2.0f) * 60.0f + 10.0f;
}
}
在运行时测试进度指示器
- 在 Unity 中，选择“游戏对象”>“UI 工具包”>“UI 文档”。
- 在“层次结构”窗口中选择 UIDocument。
- 将RadialProgressComponent.cs添加为 UIDocument 的组件游戏对象Unity 场景中的基本对象，可以表示角色、道具、风景、相机、航路点等。游戏对象的功能由附加到它的组件定义。更多信息
请参阅术语表. - 进入播放模式。进度指示器出现在场景场景包含游戏的环境和菜单。将每个唯一的场景文件视为一个独特的关卡。在每个场景中，你放置你的环境、障碍物和装饰品，基本上是将你的游戏设计和构建成碎片。更多信息
请参阅术语表，进度环和值动态变化。