

UITK Typed UXML充当了UXML 中定义的 UI 结构和 C# 代码中间的桥梁,它能将你通过Unity UI Toolkit创建的UXML文件自动生成安全的强类型的C#包装类,从而取代 UQuery 那种基于字符串的查询方式,彻底告别手写 UQuery 代码。从而避免了因手写UQuery代码时因拼写错误、UI 改名等引入错误,在编译检查正常,而在运行时才会暴漏问题的情况。让你的代码变得干净、安全。
1.为什么选择 UITK Typed UXML?
现有 UI Toolkit 的C#代码往往采用字符串查询元素的方式(Uquery),当出现拼写错误时很难在编译阶段及时发现,而这些错误在 UI 实际运行时又会对运行效果造成不可预测的影响。
UITK Typed UXML工具,将创建的UXML文件自动生成为安全的强类型的C#包装类,为每个 UXML 元素生成清晰可靠的代码,可以完美的替代字符串查找方式,从而规避上述问题的发生。同时UITK Typed UXML工具还能为你提供完整的智能提示、类型检查、可空类型注解等功能。
2.简介
UITK Typed UXML工具为每个 UXML文件都会生成一个对应的分部 C# 类。该类为文件中的每个具名元素提供一个只读的类型化属性。如果存在重名元素,还会额外生成一个 IReadOnlyList<T> 类型的集合属性。对于模板实例,生成类的同时会公开底层的TemplateContainer 和针对其内部视图的类型化包装器。
此外,您还可以通过配置,让生成的类包含空属性、TryGet* 辅助方法、名称常量、USS 常量、静态工厂方法以及分部钩子,以满足不同的开发需求。
3.主要功能及特点
- 为每个 UXML 文件自动生成对应的C#分部类,保存 UXML 时即同步更新代码,无需手动操作。
- 实时预览面板:在将生成的代码写入文件之前,即可在预览面板中查看代码内容,提前确认生成结果是否符合预期。
- 全面的类型化属性支持:为具名元素、重名元素集合、插槽、嵌套模板,以及使用 [UxmlElement] 标记的自定义控件,统统生成强类型属性,不再需要字符串查询。
- 可选的 TryGet* 辅助方法:提供带有 [NotNullWhen(true)] 注解的 TryGet* 方法,安全地获取元素,并让编译器知道获取成功时结果不为空。
- 可选的静态工厂方法:支持通过 FromVisualTree、LoadFromAssetDatabase、LoadFromResources 以及 Addressables 等多种方式创建视图实例。
- 可选分部钩子(OnBeforeAssign / OnAfterAssign):允许在属性赋值前后插入自定义逻辑,灵活扩展生成行为。
- 可选的名称常量:可选择为 UXML 中的元素名称和 USS 类名自动生成常量,避免硬编码字符串。
- 智能增量缓存:仅重新生成发生变更的 UXML、USS 或配置文件,避免不必要的重复生成,提升响应速度。
- 灵活的配置方式:支持通过项目设置(Project Settings)进行全局配置,也支持为每个 UXML 文件单独添加 JSON 覆盖配置,满足不同模块的个性化需求,灵活方便。
4.快速上手
- 导入资源包
- 打开窗口(Window)→ UI Toolkit → TypedUxml Preview
- 在项目窗口(Project window)中选中任意 .uxml 文件——预览会即时更新
- 保存文件即可自动生成,或点击面板中的生成(Generate)按钮
包含:安装指南、快速上手、预览面板、配置说明、API 参考、示例、疑难解答和更新日志等完整文档。
5.了解更多
