UnityAI/03_核心功能/UI组件使用指南.md

StrayFog 框架 UI组件使用指南

一、常用UI组件（框架封装）

1.1 SFUI_Button组件

SFUI_Button btn = GetComponent<SFUI_Button>();

// 添加点击事件
btn.OnAddClickListener += OnBtnClick;

// 添加鼠标进入/退出事件
btn.OnAddEnterListener += OnBtnEnter;
btn.OnAddExitListener += OnBtnExit;

// 设置按钮状态
btn.SetSelfGray(true);      // 设置灰色不可用
btn.interactable = false;   // 设置不可交互

void OnBtnClick(GameObject go)
{
    // 处理点击
}

void OnBtnEnter(GameObject go)
{
    // 鼠标进入
}

void OnBtnExit(GameObject go)
{
    // 鼠标退出
}

1.2 SFUI_Text组件

SFUI_Text txt = GetComponent<SFUI_Text>();

// 设置文本
txt.text = "Hello World";

// 设置颜色
txt.color = Color.red;

// 设置字体大小
txt.fontSize = 24;

// 设置描边
txt.outlineColor = Color.black;
txt.outlineWidth = 2;

1.3 SFUI_Image组件

SFUI_Image img = GetComponent<SFUI_Image>();

// 加载Sprite
HFFunCatalogue.Sprite.LoadSprite("Icon_Player", sprite => {
    img.sprite = sprite;
});

// 设置透明度
img.SetAlpha(0.5f);

// 设置灰度
img.SetSelfGray(true);

1.4 SFUI_Toggle组件

SFUI_Toggle toggle = GetComponent<SFUI_Toggle>();

// 添加状态改变事件
toggle.onValueChanged.AddListener(OnToggleValueChanged);

void OnToggleValueChanged(bool isOn)
{
    Debug.Log($"Toggle is {isOn}");
}

1.5 SFUI_ScrollRect组件

SFUI_ScrollRect scroll = GetComponent<SFUI_ScrollRect>();

// 设置滚动位置
scroll.verticalNormalizedPosition = 1f;

// 添加滚动事件
scroll.onValueChanged.AddListener(OnScrollValueChanged);

void OnScrollValueChanged(Vector2 value)
{
    // 处理滚动
}

---

二、UI组件命名规范

2.1 命名规则

变量名直接使用组件名，保持与 Unity 编辑器中组件名称一致。

组件类型	示例
SFUI_Button	BtnLogin
SFUI_Text	TxtTitle
SFUI_Image	ImgAvatar
SFUI_Toggle	ToggleSelect
SFUI_ScrollRect	ScrollContent
SFUI_InputField	InputName

命名约定：

• 变量名 = 组件名（保持完全一致）
• 首字母大写，采用 PascalCase 命名风格

使用示例：

BtnLogin = FindUICtrlByName<SFUI_Button>("BtnLogin");
TxtTitle = FindUICtrlByName<SFUI_Text>("TxtTitle");
ImgAvatar = FindUICtrlByName<SFUI_Image>("ImgAvatar");

2.2 层级结构

WindowRoot/
├── bg/                    # 背景层
├── content/               # 内容层
│   ├── header/            # 头部
│   ├── body/              # 主体
│   └── footer/            # 底部
└── top/                   # 顶层（弹窗、提示等）

---

三、框架封装组件列表

组件名	基类	扩展功能
SFUI_Button	Button	灰色状态、多事件委托
SFUI_Text	Text	描边、阴影扩展
SFUI_Image	Image	灰度、透明度快捷设置
SFUI_Toggle	Toggle	状态改变事件
SFUI_ScrollRect	ScrollRect	滚动优化
SFUI_InputField	InputField	输入限制
SFUI_Slider	Slider	数值范围限制
SFUI_Dropdown	Dropdown	选项管理

---

四、UI性能优化

4.1 优化建议

• 对象池复用：频繁创建的UI元素使用对象池
• 图集打包：将小图标打包到SpriteAtlas
• 层级优化：合理设置Canvas层级
• 避免过度绘制：减少重叠UI元素
• 批量操作：使用RectTransform批量修改

---

版本: v1.0
适用范围: GiftGameX项目业务开发人员