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

StrayFog 框架 UI组件使用指南

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

1.1 SFUI_Button组件

SFUI_Button btn = GetComponent<SFUI_Button>();

// 添加点击事件（带防重复注册保护）
btn.OnAddClickListener -= OnBtnClick;
btn.OnAddClickListener += OnBtnClick;

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

btn.OnAddExitListener -= OnBtnExit;
btn.OnAddExitListener += OnBtnExit;

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

void OnBtnClick(GameObject go) { /* 处理点击 */ }
void OnBtnEnter(GameObject go) { /* 鼠标进入 */ }
void OnBtnExit(GameObject go) { /* 鼠标退出 */ }

1.2 SFUI_TextMeshProUGUI组件

SFUI_TextMeshProUGUI txt = GetComponent<SFUI_TextMeshProUGUI>();

// 设置文本
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（使用框架封装方法）
img.HFSetItemIcon("Icon_Player");

// 加载远程图片
img.HFSetUrlSprite("https://example.com/icon.png");

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

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

// 清空Sprite
img.HFClearSprite();

1.4 SFUI_Toggle组件

SFUI_Toggle toggle = GetComponent<SFUI_Toggle>();

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

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

1.5 SFUI_ScrollRect组件（列表绑定模式）

SFUI_ScrollRect scroll = GetComponent<SFUI_ScrollRect>();
List<ItemInfo> m_items = new List<ItemInfo>();

// ✅ 列表绑定（推荐方式）
scroll.BindEvent(
    () => { return m_items.Count; },                    // 数据源数量
    (idx) => { return itemPrefab.gameObject; },         // 实例化模板
    OnUpdateItem,                                       // 更新回调
    (item) => {                                         // 组件获取
        return item.gameObject.HFGetOrAddSimulateBehaviour<BagItemSlot>();
    }
);

// 刷新列表
scroll.ShowView();                   // 显示视图
scroll.RefreshView(null);           // 刷新当前视图
scroll.ScrollToIndex(0);            // 滚动到指定索引

// 添加拖拽事件
scroll.OnAddBeginDragListener -= OnBeginDrag;
scroll.OnAddBeginDragListener += OnBeginDrag;

void OnUpdateItem(SFUI_ScrollRectItem item)
{
    var slot = item.simulateBehaviour as BagItemSlot;
    slot.SetData(m_items[item.dataIdx]);
}

void OnBeginDrag(GameObject go) { /* 处理拖拽开始 */ }

---

二、UI组件命名规范

2.1 命名规则

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

组件类型	示例
SFUI_Button	BtnLogin, BtnClose
SFUI_TextMeshProUGUI	TxtTitle, TxtNum
SFUI_Image	ImgIcon, ImgKuang
SFUI_Toggle	ToggleSelect
SFUI_ScrollRect	BagListView, ScrollContent
SFUI_InputField	InputName, InputPassword
SFUI_GridLayoutGroup	GridItemContainer

命名约定：

• 变量名 = 组件名（保持完全一致）
• 首字母大写，采用 PascalCase 命名风格
• 前缀说明：Btn（按钮）、Txt（文本）、Img（图片）、Toggle（开关）、Scroll（滚动）、Input（输入框）、Grid（网格）

2.2 层级结构

WindowRoot/
├── bg/                    # 背景层
├── content/               # 内容层
│   ├── header/            # 头部（标签页、标题）
│   ├── body/              # 主体（列表、内容区）
│   └── footer/            # 底部（操作按钮）
└── top/                   # 顶层（弹窗、提示、遮罩）

---

三、框架封装组件列表

组件名	基类	扩展功能
SFUI_Button	Button	灰色状态、多事件委托、选中状态
SFUI_Text	Text	描边、阴影扩展
SFUI_TextMeshProUGUI	TextMeshProUGUI	继承原生功能
SFUI_Image	Image	灰度、透明度快捷设置、Sprite加载
SFUI_Toggle	Toggle	状态改变事件
SFUI_ScrollRect	ScrollRect	列表绑定模式、滚动优化
SFUI_InputField	InputField	输入限制
SFUI_Slider	Slider	数值范围限制
SFUI_Dropdown	Dropdown	选项管理
SFUI_GridLayoutGroup	GridLayoutGroup	网格布局

---

四、UI性能优化

4.1 优化建议

优化项	说明	实现方式
对象池复用	频繁创建的UI元素使用对象池	使用 HFClassEntityManager
图集打包	将小图标打包到SpriteAtlas	在Unity中配置SpriteAtlas
层级优化	合理设置Canvas层级	使用 HFUIWindowLayer 属性
避免过度绘制	减少重叠UI元素	合理设计UI布局
批量操作	使用RectTransform批量修改	禁用后批量修改再启用
列表优化	使用SFUI_ScrollRect绑定模式	自动复用列表项

4.2 列表性能优化示例

// ✅ 使用SFUI_ScrollRect绑定模式（自动复用）
BagListView.BindEvent(
    () => { return m_items.Count; },
    (idx) => { return itemPrefab.gameObject; },
    OnUpdateItem,
    (item) => { return item.gameObject.HFGetOrAddSimulateBehaviour<BagItemSlot>(); }
);

// ✅ 数据变化时只刷新必要项
private void OnBagItemUpdate(IHFEventArg<enHFCTCEvent> arg)
{
    // 只在数据实际变化时刷新
    if (HasDataChanged())
    {
        BagListView.ShowView();
    }
}

---

五、子组件开发规范

5.1 子组件模板

public class CustomSlot : AbsHFUIWindow
{
    // UI组件
    private SFUI_Button Btn_Item;
    private SFUI_Image Img_Icon;

    // 数据和回调
    private Action<ItemInfo> onSelect;
    private ItemInfo item;

    protected override void OnRunAwake()
    {
        base.OnRunAwake();
        Btn_Item = FindUICtrlByName<SFUI_Button>("Btn_Item");
        Img_Icon = FindUICtrlByName<SFUI_Image>("Img_Icon");

        // 事件绑定（带防重复保护）
        Btn_Item.OnAddClickListener -= OnClick;
        Btn_Item.OnAddClickListener += OnClick;
    }

    public void SetData(ItemInfo item, Action<ItemInfo> onSelect)
    {
        this.item = item;
        this.onSelect = onSelect;
        
        // 更新UI
        Img_Icon.HFSetItemIcon(item.ItemConfig.Resource);
    }

    private void OnClick(GameObject go)
    {
        onSelect?.Invoke(item);
    }
}

---

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