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

# StrayFog 框架 UI组件使用指南

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

### 1.1 SFUI_Button组件

```csharp
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组件

```csharp
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组件

```csharp
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组件

```csharp
SFUI_Toggle toggle = GetComponent<SFUI_Toggle>();

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

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

### 1.5 SFUI_ScrollRect组件

```csharp
SFUI_ScrollRect scroll = GetComponent<SFUI_ScrollRect>();

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

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

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

---

## 二、UI组件命名规范

### 2.1 命名规则

| 组件类型 | 前缀 | 示例 |
|---------|------|-----|
| SFUI_Button | btn | btn_Login |
| SFUI_Text | txt | txt_Title |
| SFUI_Image | img | img_Avatar |
| SFUI_Toggle | toggle | toggle_Select |
| SFUI_ScrollRect | scroll | scroll_Content |
| SFUI_InputField | input | input_Name |

### 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项目业务开发人员