7日杀TxGUI工具库【10分钟快速构建起UI界面】

TxGUI框架技术文档V1.0
作者：东方清华EX
适用场景：七日杀UI开发 | Unity通用扩展

一、框架概述

TxGUI是专为七日杀设计的轻量级UI构建框架，基于Unity引擎开发，采用声明式编程模型简化UI开发流程。框架
提供完整的UI组件系统和布局管理功能。

核心特性

• 模块化控件系统：包含20+常用UI组件（按钮、面板、输入框、视频播放器等）
• 响应式布局：内置网格布局系统，支持锚点定位与自适应缩放
• 链式调用API：通过流畅接口设计提升代码可读性
• 标准化组件：所有控件基于统一的UIBaseControl基类

二、快速入门

详细教程视频：https://www.bilibili.com/video/BV1LUnvzFEW1/?share_source=copy_web&vd_source=cf88c968ee6de3a494a37d8249c1b8bd

1. 基础环境配置

// 须引入的核心命名空间
using static SdtdGameUI.TxGUI; //推荐使用静态导入哦(可选)
using SdtdGameUI.Controls;
using UnityEngine.UI;

2. 创建基础UI界面

public class ExampleUI : MonoBehaviour
 {
 void Start()
 {
 // 创建UI画布
GameObject canvas = Build(() =>
 {
 // 添加主面板
            Panel()
                .Anchor(EnumUIAnchor.CenterMiddle) // 居中定位
                .Size(400, 300)
                .Childs(() =>
                {
                    // 添加标题文本
                    Text("七日杀UI演示")
                        .TextSize(24)
                        .TextColor(Color.yellow)
                        .Position(0, 25);
                    
                    // 添加交互按钮
                    Button("点击测试")
                        .Position(-100, -50)
                        .OnClick(() => Debug.Log("按钮被点击！"));
                });
        });
        DontDestroyOnLoad(canvas); // 保持UI持久化
    }
 }

三、核心API详解

1. 画布构建系统

主要方法

方法	功能描述
Build(Action uiDeclare)	UI画布构建入口，接收UI声明lambda表达式
ParentStack	管理UI元素层级关系的线程安全栈

2. 控件创建方法

控件类型	创建方法	主要参数
面板容器	Panel()	支持嵌套布局和子控件管理
文本显示	Text(string text)	支持文本内容和基础样式设置
按钮控件	Button(string text)	支持点击事件回调
图像组件	RawImage(Texture tex)	支持纹理贴图显示
输入框	InputField(string placeholder)	支持占位符文本
视频播放	VideoPlayer(VideoClip clip)	实验性功能，支持本地视频剪辑

四、控件属性配置

1. 锚点系统（EnumUIAnchor）

枚举值	描述	适用场景
LeftTop	左上角对齐	菜单栏、工具提示
LeftMiddle	左侧居中对齐	侧边栏元素
LeftBottom	左下角对齐	状态栏信息
CenterTop	水平居中顶部对齐	标题栏
CenterMiddle	屏幕绝对中心	主要内容区域
CenterBottom	水平居中底部对齐	底部操作区
RightTop	右上角对齐	右上角功能区
RightMiddle	右侧居中对齐	辅助信息显示
RightBottom	右下角对齐	版权信息、状态显示
Stretch	填充父容器	全屏背景、覆盖层

2. 布局配置方法

// 典型面板布局配置
Panel()
    .Anchor(EnumUIAnchor.CenterMiddle) // 设置锚点为屏幕中心
    .Size(400, 300) // 设置面板尺寸
    .Position(0, 0) // 设置相对位置
    .Childs(() => {
        // 子控件配置
    });

五、基础控件详解

1. 面板控件（PanelControl）

面板是UI布局的基础容器，支持嵌套和网格布局。

主要功能

• 嵌套布局：通过Childs方法添加子控件
• 网格系统：支持水平和垂直网格布局
• 基础样式：支持颜色、材质、透明度设置

使用示例

Panel()
    .Anchor(EnumUIAnchor.CenterMiddle)
    .Size(300, 200)
    .Childs(() => {
        // 添加子控件
        Text("面板标题")
            .TextSize(18)
            .Position(0, 30);
    });

网格布局

Panel()
    .UseHorizontalGrid((100, 50), (10, 10)) // 水平网格：100x50单元格，10px间距
    .Childs(() => {
        // 网格内子控件
    });

2. 文本控件（TextControl）

基于TextMeshPro的文本显示组件。

配置选项

• 文本大小：TextSize(int size)
• 文本颜色：TextColor(Color color)
• 字符间距：TextSpace(float spacing)
• 对齐方式：TextAlign(TextAlignmentOptions align)

使用示例

Text("欢迎使用TxGUI")
    .TextSize(24)
    .TextColor(Color.white)
    .TextAlign(TextAlignmentOptions.Center);

3. 按钮控件（ButtonControl）

支持点击交互的基础按钮组件。

功能特性

• 点击事件：OnClick(UnityAction handler)
• 文本配置：继承自文本相关接口
• 视觉效果：支持图片和基础样式设置

使用示例

Button("确认操作")
    .Position(0, -50)
    .OnClick(() => {
        Debug.Log("执行确认操作");
    });

4. 图像控件（RawImgControl）

用于显示纹理贴图的原始图像组件。

配置方法

• 纹理设置：通过构造函数传入Texture
• 颜色调整：Color(Color color)
• 材质设置：Material(Material mat)
• 射线检测：IsRaycast(bool value)
• 遮罩支持：Maskable(bool value)

使用示例

RawImg(Texture2D texture)
    .Color(new Color(1, 1, 1, 0.8f)) // 半透明白色
    .IsRaycast(true); // 启用射线检测

5. 输入框控件（InputFieldControl）

基于TMP_InputField的文本输入组件。

事件监听

• 值变化：OnValChange(UnityAction<string> handler)
• 编辑完成：OnEndEdit(UnityAction<string> handler)
• 选择事件：OnSelect(UnityAction<string> handler)

使用示例

InputField("请输入内容")
    .OnValChange((text) => {
        Debug.Log($"输入内容：{text}");
    });

6. 视频播放控件（VideoPlayerControl）

实验性视频播放组件（基于VideoPlayer和RawImage）。

配置选项

• 循环播放：Looping(bool value)
• 静音设置：Mute(bool value)

使用示例

VideoPlayer(VideoClip clip)
    .Looping(true)
    .Mute(false);

7. 滑动条控件（SliderControl）

数值调节滑动条组件。

功能配置

• 方向设置：Direction(Slider.Direction dire)
• 数值范围：Min(float min)、Max(float max)
• 当前值：Value(float value)
• 值变化事件：OnValChange(UnityAction<float> handler)

使用示例

Slider()
    .Min(0).Max(100)
    .Value(50)
    .OnValChange((val) => {
        Debug.Log($"当前值：{val}");
    });

8. 切换开关控件（ToggleControl）

布尔值切换开关组件。

功能特性

• 标签文本：通过构造函数设置
• 值变化事件：OnValChange(UnityAction<bool> handler)
• 文本样式：继承自文本相关接口

使用示例

Toggle("启用功能")
    .OnValChange((isEnabled) => {
        Debug.Log($"功能状态：{isEnabled}");
    });

9. 滚动视图控件（ScrollViewControl）

实验性滚动视图组件（基于ScrollRect）。

10. 下拉菜单控件（DropdownControl）

实验性下拉选择组件（基于Dropdown）。

11. 滚动条控件（ScrollbarControl）

实验性滚动条组件（基于Scrollbar）。

六、布局系统详解

1. 锚点定位系统

通过EnumUIAnchor枚举实现精确的UI元素定位：

• 绝对定位：使用Position方法设置具体坐标
• 相对定位：通过Anchor方法设置相对于父容器的对齐方式

2. 响应式设计原则

• 百分比尺寸：使用0-1.0范围的浮点数设置相对尺寸
• 弹性布局：通过网格系统实现自适应排列
• 屏幕适配：基于参考分辨率(1440×900)的自动缩放

七、框架使用评价

1. 技术优势

✅ 开发效率：声明式API大幅简化UI代码编写，提升开发速度✅ 代码可读性：链式调用和流畅接口使UI逻辑更加清晰✅ 布局灵活性：强大的网格系统和锚点系统支持复杂界面设计✅ 性能优化：内置的布局计算优化减少运行时性能开销✅ 组件化设计：标准化的控件基类便于功能扩展和维护

2. 实际应用价值

• 快速原型开发：可在短时间内构建完整的UI界面原型
• 模块化维护：每个UI组件独立封装，便于后期维护和升级
• 团队协作友好：标准化的API设计降低团队成员间的学习成本
• 跨项目复用：核心框架可轻松适配其他Unity项目

3. 局限性说明

⚠️ 实验性功能：视频播放、滚动视图等高级组件仍在完善中⚠️ 学习曲线：需要适应声明式编程思维模式⚠️ 特定依赖：依赖于特定的预制体格式和TextMeshPro组件

4. 适用场景推荐

🔹 推荐使用：

• 七日杀Mod界面开发
• 数据展示和配置界面
• 复杂表单和输入界面
• 菜单系统和导航界面

🔸 谨慎使用：

• 对性能要求极高的战斗界面
• 需要深度定制渲染效果的特殊UI
• 非UGUI基础组件的复杂集成

八、最佳实践

• 将下载解压缩的文件（包含一个DLL和一个Resources文件夹）放置在你的Mod文件夹中，注意任何内容尤其是资源包和文件夹路径不允许改动。
• 在你创建的DLL工程里面选择引用Thingex.7dtd.GameUI即可开始研发。
• 详细教程视频：https://www.bilibili.com/video/BV1LUnvzFEW1/?share_source=copy_web&vd_source=cf88c968ee6de3a494a37d8249c1b8bd

九、Mod下载链接（实验性版本）