Echo/Assets/_Project/Docs/ReachUI_Technical_Reference.md

Reach UI 技术速查（常用脚本与用法）

目标：日后快速检索 Reach UI 常用脚本、Inspector 关键字段、以及与本项目集成时的注意事项。

本工程 Reach UI 根目录：

• Assets/ThirdParty/UI/Reach - Complete Sci-Fi UI

一、常用脚本索引（按用途）

1) 按钮（Button）

• ButtonManager.cs
  • 用途：按钮交互、动画、状态（Normal/Highlighted/Disabled）、点击事件（UnityEvent）。
  • 常用点：
    • onClick：对接项目逻辑的主要入口（例如打开设置、开始游戏）。
    • Interactable(bool)：统一启用/禁用按钮（会走 Reach 的 Disabled 状态表现）。
    • SetText(string)：运行时改按钮文案（例如“正在加载/开始游戏”）。

2) 下拉菜单（Dropdown）

• Dropdown.cs
  • 用途：带动画的下拉选项。
  • 关键概念：
    • items：选项列表（编辑器/脚本生成皆可）。
    • Initialize()：把 items 实例化成可点击的 ItemButton；若 items 变更后不调用，运行时可能出现空引用或显示不更新。
    • SetDropdownIndex(int)：设置选中项并刷新 Header Label。
    • onValueChanged(int)：选中项变化事件。
  • 常见坑：
    • 使用 Reach 的 “Settings Element (Dropdown)” 创建的样式，通常预置了占位 items（Dropdown Item 1..N）。若要运行时改成真实列表，需要先清空并重建 items，再 Initialize()。

3) 滑条（Slider）

• SliderManager.cs
  • 用途：Slider + 数值显示（含百分比/取整等）。
  • 常用点：
    • mainSlider：Unity Slider（min/max/value 在这里设置）。
    • useRoundValue：是否取整。
    • usePercent：是否显示为百分比。
    • onValueChanged(float)：变化事件。

4) 面板切换（Panel）

• PanelManager.cs
• PanelManagerEditor.cs
  • 用途：多面板切换、Panel In/Out 动画、可选的 Tab 按钮联动。
  • Inspector 特点：
    • 该组件使用自定义 Inspector（Content/Settings 页签），部分选项不在 Unity 默认字段列表里。
  • 常用 API：
    • OpenPanel(string panelName)
    • OpenPanelByIndex(int index)
    • NextPanel() / PreviousPanel()
    • ShowCurrentPanel() / HideCurrentPanel()
  • 常见坑：
    • PanelItem 的 panelObject 必须是带 Animator 的 Panel 根物体。
    • 动画模式（MainPanel/SubPanel）与 Animator 动画片段命名需匹配；优先使用 Prefab 默认模式。

5) 热键事件（Hotkey）

• HotkeyEvent.cs
  • 用途：把一个按键（InputAction）映射到 UnityEvent（例如 ESC 关闭面板）。
  • 常见坑：
    • InputAction 的 Inspector 展示会受项目 Input System 设置影响；推荐从 Reach Demo 场景复制一个可工作的 HotkeyEvent 再改绑定。

6) 设置行组件（Settings Element）

• SettingsElement.cs
• SettingsSubElement.cs
  • 用途：快速创建“设置行（标题 + 右侧控件）”风格 UI；项目里常用的是 Settings Element (Dropdown)。

7) 图形设置示例（参考实现）

• GraphicsManager.cs
  • 用途：Reach demo 的图形设置项（分辨率/VSync/帧率/纹理/各向异性等）的示例实现，可作为绑定 Dropdown/Slider 的参考。

二、本项目集成 Reach UI 的经验规则

1) 不要删 Reach 控件的核心脚本

• Button 的动画/状态主要由 ButtonManager 驱动。
• Dropdown 的选项生成/显示由 Dropdown.Initialize() 管理。
• Slider 的展示与事件由 SliderManager 管理。

2) 下拉项修改后一定要 Initialize

• 脚本重建 items 的标准步骤：
  • dropdown.items.Clear()
  • dropdown.CreateNewItem(...) 或直接填 items
  • dropdown.Initialize()
  • 再调用 SetDropdownIndex(...)

3) “占位 Items”与“运行时重建”冲突的处理

• 若你使用 Settings Element (Dropdown) 创建样式，会自带占位 items。
• 若要运行时替换为真实列表，需要明确“由脚本接管 items”，避免编辑器占位项阻止重建。

4) 布局与动画冲突（Button 尺寸问题）

• Reach Button 经常带内部 Layout/Fitter，若放入 LayoutGroup 里尺寸异常，优先使用按钮脚本提供的开关（例如 auto-fit 相关选项），不要手动删组件。

三、Notification / Feed Notification（项目用法）

1) 指向交互提示（项目集成）

项目已在玩家侧集成“指向可交互目标时弹出提示”的逻辑，入口位于：

• PlayerController.cs

配置方式（Inspector）：

• 在 PlayerController 的 Interaction Prompt UI 区域：
  • Can Interact Notification：拖入“可互动提示”的 FeedNotification
  • Blocked Notification：拖入“不可互动提示”的 FeedNotification
  • Blocked Use Fail Reason：勾选后会用条件组件返回的 failReason 覆盖不可互动提示文本
  • Aim Prompt Refresh Interval：射线检测刷新间隔，越小越灵敏（默认 0.05）
  • Can/Blocked Notification Animator Speed：运行时对通知的 Animator 设置 speed，用于加快弹出/收起

显示规则：

• 射线命中且存在 IInteractable：
  • 条件全部通过：显示 Can Interact Notification
  • 任一条件失败：显示 Blocked Notification（可选显示失败原因）
• 未命中或没有 IInteractable：两种提示都会收起

2) 如何让 Feed Notification 动画更快弹出

FeedNotification 的动画由 Animator 控制（In/Out 两段）。加速方案优先级如下：

1. 直接调 Animator Controller 的状态 Speed（推荐，资源层面最稳定）

• 资源位置：Assets/ThirdParty/UI/Reach - Complete Sci-Fi UI/Animations/HUD/FeedNotification.controller
• 把 In/Out 状态的 Speed 调大（例如 1.5 或 2）

2. 缩短动画片段本身时长

• 资源位置：
  • Assets/ThirdParty/UI/Reach - Complete Sci-Fi UI/Animations/HUD/FeedNotification_In.anim
  • Assets/ThirdParty/UI/Reach - Complete Sci-Fi UI/Animations/HUD/FeedNotification_Out.anim

3. 运行时设置 Animator.speed（项目已提供字段）

• PlayerController 里提供了 Can Interact Notification Animator Speed / Blocked Notification Animator Speed
• 注意：Reach 的 FeedNotification 内部有按“动画片段原始时长”做协程等待的逻辑，因此 Animator 变快不一定会同步缩短等待时间，但通常不影响观感