347 lines
23 KiB
C#
347 lines
23 KiB
C#
using System;
|
||
using Cysharp.Threading.Tasks;
|
||
using Framework;
|
||
using PhxhSDK;
|
||
using UnityEngine;
|
||
using UnityEngine.UI;
|
||
|
||
/*
|
||
╔═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
|
||
║ UIWindow 按钮绑定模块 (Button Binding) ║
|
||
╠═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
|
||
║ ║
|
||
║ 【模块功能】 ║
|
||
║ 本模块提供了两大核心功能： ║
|
||
║ 1. 手动按钮绑定 API - 在OnInit()中手动绑定自定义按钮 ║
|
||
║ 2. 默认按钮自动绑定 - 约定节点名自动绑定常用按钮（返回按钮） ║
|
||
║ ║
|
||
║ 注意：默认关闭按钮和回主界面按钮的处理已移至独立的 partial 文件： ║
|
||
║ • UIWindow.DefaultCloseButton.cs - 处理默认关闭按钮（BgClose、BtnClose） ║
|
||
║ • UIWindow.DefaultHomeButton.cs - 处理默认回主界面按钮（BtnHome、BtnBackHome、HomeButton） ║
|
||
║ ║
|
||
║ 【使用方式】 ║
|
||
║ ║
|
||
║ ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ ║
|
||
║ │ 方式一：使用默认按钮（推荐） │ ║
|
||
║ └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ║
|
||
║ ║
|
||
║ 只需在预制体中创建约定名称的按钮节点，框架会自动绑定： ║
|
||
║ ║
|
||
║ ⬅️ 返回按钮： ║
|
||
║ 节点名：BtnBack、BackButton 或 BtnReturn ║
|
||
║ 默认行为：调用 Back() → 触发 OnBack() → 使用 BackStrategy ║
|
||
║ 重写方法：OnBack() (async) ║
|
||
║ 特点：与返回键（Android Back/ESC）行为完全一致 ║
|
||
║ ║
|
||
║ 示例： ║
|
||
║ public class MyWindow : UIWindow ║
|
||
║ { ║
|
||
║ // 无需任何代码，自动绑定 ║
|
||
║ } ║
|
||
║ ║
|
||
║ ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ ║
|
||
║ │ 方式二：手动绑定自定义按钮 │ ║
|
||
║ └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ║
|
||
║ ║
|
||
║ 在 OnInit() 中使用 BindButton() API 手动绑定： ║
|
||
║ ║
|
||
║ 示例： ║
|
||
║ protected override void OnInit() ║
|
||
║ { ║
|
||
║ // 通过路径绑定 ║
|
||
║ BindButton("BtnStart", OnStartClick); ║
|
||
║ ║
|
||
║ // 通过Button组件绑定 ║
|
||
║ BindButton(myButton, OnMyButtonClick); ║
|
||
║ ║
|
||
║ // 带参数绑定 ║
|
||
║ BindButton(itemButton, OnItemClick, itemData); ║
|
||
║ ║
|
||
║ // 静音绑定（不播放音效） ║
|
||
║ BindButton(silentButton, OnSilentClick, playAudio: false); ║
|
||
║ } ║
|
||
║ ║
|
||
║ ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ ║
|
||
║ │ 方式三：自定义默认按钮 │ ║
|
||
║ └──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ║
|
||
║ ║
|
||
║ 重写虚属性或虚方法自定义默认按钮： ║
|
||
║ ║
|
||
║ 示例： ║
|
||
║ public class CustomWindow : UIWindow ║
|
||
║ { ║
|
||
║ // 自定义返回逻辑（与返回键行为一致） ║
|
||
║ protected override async UniTask<bool> OnBack() ║
|
||
║ { ║
|
||
║ SaveCurrentState(); ║
|
||
║ CloseWindow(false); ║
|
||
║ return true; ║
|
||
║ } ║
|
||
║ } ║
|
||
║ ║
|
||
║ 【更多信息】 ║
|
||
║ • 关闭按钮详细文档：Assets/Code/Scripts/Framework/UI/UIWindow.DefaultCloseButton.cs ║
|
||
║ • 回主界面按钮详细文档：Assets/Code/Scripts/Framework/UI/UIWindow.DefaultHomeButton.cs ║
|
||
║ • 返回按钮详细文档：本文件中的 Default Back Button 部分 ║
|
||
║ ║
|
||
╚═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
|
||
*/
|
||
|
||
/// <summary>
|
||
/// UI窗口基类 - 按钮绑定部分
|
||
/// 提供按钮绑定API和默认按钮自动绑定功能
|
||
/// </summary>
|
||
public abstract partial class UIWindow
|
||
{
|
||
#region Button Binding Core - 按钮绑定核心逻辑
|
||
|
||
/// <summary>
|
||
/// 处理按钮点击的音频逻辑
|
||
/// </summary>
|
||
private void HandleButtonAudio(Button button, bool playAudio)
|
||
{
|
||
if (!playAudio) return;
|
||
|
||
var clickAudio = button.GetComponent<ClickAudio>();
|
||
if (clickAudio)
|
||
{
|
||
if (clickAudio.IsPlayAudio && !string.IsNullOrEmpty(clickAudio.AudioKey))
|
||
{
|
||
AudioManager.Instance.PlayAudio(clickAudio.AudioKey);
|
||
}
|
||
}
|
||
else
|
||
{
|
||
CommonUtilsFramework.PlayUICommonSound();
|
||
}
|
||
}
|
||
|
||
/// <summary>
|
||
/// 绑定按钮点击事件的核心逻辑（无参数）
|
||
/// </summary>
|
||
private void BindButtonCore(Button button, Action action, bool playAudio = true)
|
||
{
|
||
if (button is null)
|
||
{
|
||
DebugUtil.LogError("传入按钮为空，无法绑定点击事件!");
|
||
return;
|
||
}
|
||
|
||
button.onClick.RemoveAllListeners();
|
||
button.onClick.AddListener(() =>
|
||
{
|
||
DebugUtil.Log("按钮被点击: {0}", button.gameObject.name);
|
||
if (UIManager.IsUIInputBlocked) return;
|
||
|
||
UIManager.Instance.BlockUIForNormalOperation();
|
||
HandleButtonAudio(button, playAudio);
|
||
action?.Invoke();
|
||
});
|
||
|
||
DebugUtil.Log("按钮绑定完成: {0}", button.gameObject.name);
|
||
}
|
||
|
||
/// <summary>
|
||
/// 绑定按钮点击事件的核心逻辑（带参数）
|
||
/// </summary>
|
||
private void BindButtonCore<T>(Button button, Action<T> action, T parameter, bool playAudio = true)
|
||
{
|
||
if (button is null) return;
|
||
|
||
button.onClick.RemoveAllListeners();
|
||
button.onClick.AddListener(() =>
|
||
{
|
||
if (UIManager.IsUIInputBlocked) return;
|
||
|
||
UIManager.Instance.BlockUIForNormalOperation();
|
||
HandleButtonAudio(button, playAudio);
|
||
|
||
if (parameter == null)
|
||
{
|
||
DebugUtil.LogError("=== 传入参数为空! ===");
|
||
}
|
||
action?.Invoke(parameter);
|
||
});
|
||
}
|
||
|
||
#endregion
|
||
|
||
#region Button Binding Public API - 手动绑定按钮的公共API
|
||
|
||
/// <summary>
|
||
/// 通过路径绑定按钮
|
||
/// </summary>
|
||
/// <param name="target">按钮节点路径（相对于窗口根节点）</param>
|
||
/// <param name="action">点击回调</param>
|
||
/// <param name="playAudio">是否播放点击音效（默认true）</param>
|
||
/// <returns>Button组件</returns>
|
||
/// <example>
|
||
/// BindButton("TopBar/BtnSettings", OnSettingsClick);
|
||
/// </example>
|
||
public Button BindButton(string target, Action action, bool playAudio = true)
|
||
{
|
||
GameObject obj = transform.Find(target)?.gameObject;
|
||
if (obj is not null)
|
||
{
|
||
Button button = obj.GetComponent<Button>();
|
||
BindButtonCore(button, action, playAudio);
|
||
return button;
|
||
}
|
||
else
|
||
{
|
||
DebugUtil.LogError("未找到按钮节点: {0}/{1}", gameObject.name, target);
|
||
}
|
||
return null;
|
||
}
|
||
|
||
/// <summary>
|
||
/// 直接绑定Button组件
|
||
/// </summary>
|
||
/// <param name="button">Button组件</param>
|
||
/// <param name="action">点击回调</param>
|
||
/// <param name="playAudio">是否播放点击音效（默认true）</param>
|
||
/// <returns>Button组件</returns>
|
||
/// <example>
|
||
/// BindButton(myButton, OnMyButtonClick);
|
||
/// </example>
|
||
public Button BindButton(Button button, Action action, bool playAudio = true)
|
||
{
|
||
if (button is not null)
|
||
{
|
||
BindButtonCore(button, action, playAudio);
|
||
return button;
|
||
}
|
||
else
|
||
{
|
||
DebugUtil.LogError("传入按钮为空，请检查按钮绑定参数!");
|
||
}
|
||
return button;
|
||
}
|
||
|
||
/// <summary>
|
||
/// 通过GameObject绑定按钮（带参数）
|
||
/// </summary>
|
||
/// <typeparam name="T">参数类型</typeparam>
|
||
/// <param name="obj">按钮GameObject</param>
|
||
/// <param name="action">点击回调</param>
|
||
/// <param name="parameter">回调参数</param>
|
||
/// <param name="playAudio">是否播放点击音效（默认true）</param>
|
||
/// <returns>Button组件</returns>
|
||
/// <example>
|
||
/// BindButton(itemObj, OnItemClick, itemData);
|
||
/// </example>
|
||
public Button BindButton<T>(GameObject obj, Action<T> action, T parameter, bool playAudio = true)
|
||
{
|
||
if (obj is not null)
|
||
{
|
||
Button button = obj.GetComponent<Button>();
|
||
BindButtonCore(button, action, parameter, playAudio);
|
||
return button;
|
||
}
|
||
else
|
||
{
|
||
DebugUtil.LogError("传入GameObject为空，请检查按钮绑定参数!");
|
||
}
|
||
return null;
|
||
}
|
||
|
||
/// <summary>
|
||
/// 直接绑定Button组件（带参数）
|
||
/// </summary>
|
||
/// <typeparam name="T">参数类型</typeparam>
|
||
/// <param name="button">Button组件</param>
|
||
/// <param name="action">点击回调</param>
|
||
/// <param name="parameter">回调参数</param>
|
||
/// <param name="playAudio">是否播放点击音效（默认true）</param>
|
||
/// <returns>Button组件</returns>
|
||
/// <example>
|
||
/// BindButton(itemButton, OnItemClick, itemData);
|
||
/// </example>
|
||
public Button BindButton<T>(Button button, Action<T> action, T parameter, bool playAudio = true)
|
||
{
|
||
if (button is not null)
|
||
{
|
||
BindButtonCore(button, action, parameter, playAudio);
|
||
return button;
|
||
}
|
||
else
|
||
{
|
||
DebugUtil.LogError("传入按钮为空，请检查按钮绑定参数!");
|
||
}
|
||
return button;
|
||
}
|
||
|
||
#endregion
|
||
|
||
#region Default Back Button - 默认返回按钮自动绑定
|
||
|
||
/// <summary>
|
||
/// 默认返回按钮的节点名配置（子类可重写）
|
||
///
|
||
/// 默认支持的节点名：
|
||
/// - BtnBack: 返回按钮（推荐，最常用）
|
||
/// - BackButton: 返回按钮
|
||
/// - BtnReturn: 返回按钮
|
||
///
|
||
/// 自定义示例：
|
||
/// protected override string[] DefaultBackButtonNames => new[] { "BtnPrevious" };
|
||
///
|
||
/// 禁用返回按钮：
|
||
/// protected override string[] DefaultBackButtonNames => new string[0];
|
||
/// </summary>
|
||
protected virtual string[] DefaultBackButtonNames => new[] { "BtnBack", "BackButton", "BtnReturn" };
|
||
|
||
/// <summary>
|
||
/// 绑定所有配置的默认返回按钮
|
||
/// 在 DoInit() 阶段自动调用，无需手动调用
|
||
///
|
||
/// 重要说明：
|
||
/// - 返回按钮会调用 Back() 方法，触发 OnBack() 虚方法
|
||
/// - 点击返回按钮 = 按下返回键（Android Back / ESC）
|
||
/// - 子类通过重写 OnBack() 来自定义返回逻辑
|
||
/// - 默认使用 BackStrategy 配置的策略
|
||
/// </summary>
|
||
private void BindDefaultBackButtons()
|
||
{
|
||
foreach (var buttonName in DefaultBackButtonNames)
|
||
{
|
||
TryBindBackButton(buttonName);
|
||
}
|
||
}
|
||
|
||
/// <summary>
|
||
/// 尝试绑定返回按钮
|
||
/// 如果节点不存在，不会报错，只是不绑定
|
||
///
|
||
/// 绑定后，点击按钮会调用 Back() 方法，触发 OnBack() 虚方法
|
||
/// </summary>
|
||
private void TryBindBackButton(string nodeName)
|
||
{
|
||
var trans = transform.Find(nodeName);
|
||
if (trans)
|
||
{
|
||
var btn = trans.GetComponent<Button>();
|
||
if (btn)
|
||
{
|
||
// 绑定到 Back() 方法，会触发 OnBack() 虚方法
|
||
BindButton(btn, () => Back().Forget());
|
||
DebugUtil.Log("✅ 已自动绑定返回按钮: {0} -> {1} -> Back()", WindowName, nodeName);
|
||
}
|
||
}
|
||
}
|
||
|
||
// 注意：返回按钮不需要 OnBackClick() 方法
|
||
// 它直接调用 Back() 方法，触发 OnBack() 虚方法
|
||
// OnBack() 方法定义在 UIWindow.Lifecycle.cs 中
|
||
//
|
||
// 自定义返回逻辑示例：
|
||
// protected override async UniTask<bool> OnBack()
|
||
// {
|
||
// SaveCurrentState();
|
||
// CloseWindow(false);
|
||
// return true; // 返回true表示已处理
|
||
// }
|
||
|
||
#endregion
|
||
}
|