Echo/Assets/_Project/Docs/TaskSystem_UI_Setup.md

# TaskSystem - UI 搭建与布局（UI_Test）

本文档用于把任务系统 UI 的布局调到“可维护 + 自适应分辨率 + 可扩展（动态生成任务项）”的状态。

目标场景：
- `Assets/_Project/Scenes/Test/UI_Test.unity`

目标结构（最终建议形态）：
- TaskPanelRoot（Image，可选；RectTransform：Stretch/Stretch，Offsets 全 0）
  - Content（Horizontal Layout Group）
    - Left_TaskList（用于承载 Scroll View 的“左列”）
      - Scroll View
        - Viewport（Mask）
          - Content（Vertical Layout Group + Content Size Fitter）
            - TaskItem（可复用 Prefab）
        - Scrollbar Vertical
    - Right_TaskDetails（右侧详情容器）
      - DetailText（TMP）

## 1. 总原则（先看这个，后面每一步都在用）

1) “左右两列”这类分屏 UI，外层用 `Horizontal Layout Group` 管分配；左右列用 `Layout Element` 提供宽度策略。
- 左列：固定宽（Preferred Width），不参与拉伸
- 右列：Flexible Width = 1，吃掉剩余空间

2) `ScrollRect` 必须正确引用：
- `ScrollRect.Viewport` 指向 Viewport 的 RectTransform
- `ScrollRect.Content` 指向 Viewport 下的 Content（列表根）

3) 列表项不要直接挂在 Viewport 下，而是挂在 Viewport/Content 下，由 `Vertical Layout Group` 统一排版。

4) Reach Button 这类控件如果要放进 LayoutGroup 管理尺寸，优先把 `ButtonManager.autoFitContent = false`（让父级 LayoutGroup 控尺寸）。

## 2. TaskPanelRoot 与 Content（左右分屏容器）

在层级里选中 `TaskPanelRoot`：
- RectTransform：
  - Anchor Presets：Stretch / Stretch
  - Left/Right/Top/Bottom：全部 0

选中 `TaskPanelRoot/Content`（你场景里已有同名对象）：
- 组件：`Horizontal Layout Group`
  - Padding：建议先用 `Left/Right/Top/Bottom = 40`
  - Spacing：`30`
  - Child Alignment：`Upper Left`
  - Child Control Width：勾选
  - Child Control Height：勾选
  - Child Force Expand Width：勾选
  - Child Force Expand Height：勾选

说明：
- 你当前场景里 Content 的 `Child Control Width/Height` 是关闭的，这会导致左右两列“各管各的”，很难靠 LayoutGroup 统一管理边距与自适应。

## 3. Left_TaskList（左列：固定宽 + 内部是滚动列表）

选中 `Content/Left_TaskList`：
- 添加组件：`Layout Element`
  - Preferred Width：建议先用 `420`（按需求调）
  - Flexible Width：`0`
  - Min Width：可选（例如 `360`，防止过窄）
- RectTransform：
  - Anchor Presets：Stretch / Stretch（至少 Y 方向要拉伸）
  - Pos/Size：让 LayoutGroup 控制即可，不要再手调 anchoredPosition

说明：
- 你当前 Left_TaskList 是一个固定 SizeDelta（例如 350x730）并锚在左下角；如果想交给外层布局自适应，核心是加 `Layout Element` 并让外层 `Horizontal Layout Group` 能控制子物体。

## 4. Scroll View（关键：Viewport 与 Content 的正确结构）

选中 `Left_TaskList/Scroll View`：
- 确认组件：`ScrollRect`
  - Horizontal：关闭
  - Vertical：开启
  - Viewport：拖拽到 `Viewport` 的 RectTransform
  - Content：拖拽到 `Viewport/Content` 的 RectTransform
  - Vertical Scrollbar：拖拽到 `Scrollbar Vertical`

如果你的 Scroll View 里当前没有 `Viewport/Content` 这个对象（或者你把按钮直接放在 Viewport 下了），按下面步骤整理：

1) 选中 `Scroll View/Viewport`，把它的 RectTransform 改成全拉伸：
   - Anchor Presets：Stretch / Stretch
   - Left/Right/Top/Bottom：全部 0

2) 在 `Viewport` 下新建空物体命名为 `Content`（RectTransform）：
   - Anchor：
     - Min `(0, 1)`，Max `(1, 1)`（X 拉伸，Y 顶部对齐）
   - Pivot：`(0.5, 1)`
   - Anchored Position：`(0, 0)`
   - Size Delta：`(0, 0)`

3) 给 `Viewport/Content` 添加组件：
   - `Vertical Layout Group`
     - Child Alignment：`Upper Left`
     - Spacing：`12`（按视觉调）
     - Child Control Width：勾选
     - Child Control Height：勾选
     - Child Force Expand Width：勾选
     - Child Force Expand Height：取消（列表项高度通常固定，不希望被拉伸）
     - Padding：建议 `Left/Right/Top/Bottom = 10~20`
   - `Content Size Fitter`
     - Horizontal Fit：Unconstrained
     - Vertical Fit：Preferred Size

4) 把你现在放在 `Viewport` 下的 `BtnTaskPrefab / BtnTaskPrefab 2 / ...` 全部移动到 `Viewport/Content` 下。

5) 回到 `Scroll View (ScrollRect)`：
   - 把 `Content` 字段绑定到刚创建的 `Viewport/Content`

可选兜底（动态生成任务项后，偶发排版不刷新时）：
- 在 `Viewport/Content` 上挂 Reach 的 `LayoutGroupFix`（ThirdParty 内已有），并启用延迟 rebuild。

## 5. TaskItem（列表项 Prefab 的布局建议）

如果你复用 Reach Button 作为任务项：
- `ButtonManager.autoFitContent = false`
- 由父级 `Vertical Layout Group` 决定宽度
- 在任务项根节点上添加 `Layout Element`：
  - Preferred Height：例如 `56` 或 `64`
  - Flexible Width：`0`（让父级控制）

这样列表项的高度稳定，不会因为文本变化导致整个 ScrollView 抖动。

## 6. Right_TaskDetails（右列：吃剩余宽度）

选中 `Content/Right_TaskDetails`：
- 添加组件：`Layout Element`
  - Flexible Width：`1`
  - Min Width：可选（例如 `600`，防止过窄）
- RectTransform：
  - Anchor Presets：Stretch / Stretch

选中 `Right_TaskDetails/DetailText`：
- RectTransform：Stretch / Stretch
- Size Delta：用负值做内边距（例如 `(-50, -50)` 表示四边各留 25）
- TMP：
  - Word Wrapping：开启
  - Overflow：建议 `Overflow` 或 `Truncate`（按需求）

## 7. 常见问题排查（按出现频率排序）

1) Scroll View 不滚动 / 滚动条不动
- 先检查 `ScrollRect.Content` 是否为空（必须指向 `Viewport/Content`）
- 再检查 `Viewport` 是否全拉伸（Offsets 是否为 0）

2) 左右列挤在一起、重叠、边距不生效
- 检查 `TaskPanelRoot/Content (Horizontal Layout Group)`：
  - `Child Control Width/Height` 是否勾上
  - `Child Force Expand Width/Height` 是否勾上
- 检查左右列是否都有 `Layout Element`（左列 PreferredWidth，右列 FlexibleWidth=1）

3) 动态生成任务项后，布局不刷新
- 在列表根（`Viewport/Content`）挂 `LayoutGroupFix`，或在生成后手动触发一次 `LayoutRebuilder.ForceRebuildLayoutImmediate`