GameObjectExtensions

概述（Overview）

GameObjectExtensions 是一个专注于 Unity GameObject 常用操作 的静态扩展方法集合，位于 PFGameFramework.Library 命名空间。

主要功能包括：

• 激活状态判断与递归设置
• 安全获取组件/脚本（带日志提示）
• 显示/隐藏快捷方法
• 子物体查找（按名称、安全查找、获取全部）
• 层级（Layer）批量设置（递归）
• 父物体获取
• 查找并激活物体
• 物体克隆（指定位置与旋转）
• Tag 设置（避免重复设置）

适用于快速管理物体状态、层级控制、子物体查找、调试提示等常见 3D/2D 场景操作。

---

方法一览（API Index）

方法名	返回类型	主要功能	典型用途
IsActive	bool	判断物体自身和层级是否激活	替代 activeSelf && activeInHierarchy
SetActiveRecursively	void	递归激活/禁用物体及其所有子物体	整组显隐控制
GetScriptSafe	void	安全检查指定脚本是否存在并打印日志	调试脚本挂载情况
GetComponentSafe	void	安全获取组件，存在/不存在时分别执行回调并打印日志	带提示的组件检查
Show / Hide	void	快速激活/禁用物体	简洁显隐操作
FindChild / FindChildSafe	GameObject or null	按名称查找子物体（安全版返回 null 不报错）	快速定位子物体
GetAllChildren	List	获取所有直接子物体列表	批量处理子物体
SetLayer (int / string)	void	递归设置物体及子物体的层级（支持层名）	统一层级管理（如射线检测、渲染分组）
GetParent	GameObject or null	获取父物体（若无父物体返回 null）	层级导航
FindAndActivate	GameObject or null	全局查找物体并激活	快速激活场景中特定物体
Clone	GameObject	在指定位置和旋转克隆物体	动态生成副本
SetTag	void	设置 Tag（避免重复设置）	安全批量打标签

---

方法详情

激活状态相关

IsActive

/// <summary>
/// 判断物体是否真正处于激活状态（自身 + 层级）
/// </summary>
public static bool IsActive(this GameObject gameObject)

等价于 gameObject.activeSelf && gameObject.activeInHierarchy

SetActiveRecursively

/// <summary>
/// 递归设置物体及其所有子物体的激活状态
/// </summary>
public static void SetActiveRecursively(this GameObject gameObject, bool active)

典型用法：

panel.SetActiveRecursively(false); // 关闭整个 UI 面板及其所有子元素

---

组件/脚本安全检查

GetScriptSafe

/// <summary>
/// 检查指定脚本是否存在，并打印相应日志（仅针对 MonoBehaviour）
/// </summary>
public static void GetScriptSafe<T>(this GameObject gameObject) where T : MonoBehaviour

输出示例：

Player 上存在脚本 PlayerController.
Cube 上没有找到脚本 MoveController.

GetComponentSafe

/// <summary>
/// 安全获取任意组件，存在/不存在时分别执行回调并打印日志
/// </summary>
/// <param name="onComponentFound">组件存在时回调</param>
/// <param name="onComponentNotFound">组件不存在时回调</param>
public static void GetComponentSafe<T>(
    this GameObject gameObject,
    Action<T> onComponentFound = null,
    Action onComponentNotFound = null)
    where T : Component

示例：

go.GetComponentSafe<Rigidbody>(
    rb => rb.mass = 10f,
    () => Debug.Log("需要添加刚体组件！")
);

---

显示/隐藏快捷方法

public static void Show(this GameObject gameObject)
public static void Hide(this GameObject gameObject)

简洁替代：

button.Show();      // 等价于 button.SetActive(true);
effect.Hide();      // 等价于 effect.SetActive(false);

---

子物体查找

FindChild / FindChildSafe

/// <summary>
/// 查找指定名称的直接子物体
/// </summary>
public static GameObject FindChild(this GameObject gameObject, string childName)

/// <summary>
/// 安全查找子物体，不存在返回 null
/// </summary>
public static GameObject FindChildSafe(this GameObject gameObject, string childName)

区别：FindChild 使用 transform.Find()，若路径错误会抛异常；FindChildSafe 更安全。

GetAllChildren

/// <summary>
/// 获取所有直接子物体（不包含子孙）
/// </summary>
public static List<GameObject> GetAllChildren(this GameObject gameObject)

---

层级（Layer）管理

SetLayer（两种重载）

/// <summary>
/// 递归设置物体及所有子物体的 Layer（int）
/// </summary>
public static void SetLayer(this GameObject gameObject, int layer)

/// <summary>
/// 递归设置 Layer（传入层名称字符串）
/// </summary>
public static void SetLayer(this GameObject gameObject, string layerName)

示例：

player.SetLayer("Player");          // 使用层名
uiRoot.SetLayer(LayerMask.NameToLayer("UI"));

---

其他常用操作

GetParent

/// <summary>
/// 获取父物体，若无父物体返回 null
/// </summary>
public static GameObject GetParent(this GameObject gameObject)

FindAndActivate

/// <summary>
/// 全局查找物体并激活（GameObject.Find + SetActive）
/// </summary>
public static GameObject FindAndActivate(this GameObject gameObject, string name)

注意：GameObject.Find 性能较低，仅建议在初始化或少量使用时调用。

Clone

/// <summary>
/// 在指定位置和旋转克隆物体
/// </summary>
public static GameObject Clone(this GameObject gameObject, Vector3 position, Quaternion rotation)

示例：

var bullet = bulletPrefab.Clone(spawnPoint.position, spawnPoint.rotation);

SetTag

/// <summary>
/// 设置 Tag，仅在不同时才修改
/// </summary>
public static void SetTag(this GameObject gameObject, string tag)

---