NLDClient-yudde/ProjectNLD/Assets/Code/Scripts/Framework/UI/UIWindow.ButtonBinding.cs

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
}