Common2DTool

概述（Overview）

Common2DTool 是一个专注于 Unity 2D UI 常用操作 的静态工具类，位于 PFGameFramework.Library 命名空间。

主要功能涵盖：

• UI 图片点击放大/还原
• CanvasGroup / Image 的 DOTween 缩放、淡入淡出动画
• InputField / TMP_InputField 输入合法性校验
• 动态更换 Image Sprite
• 按钮交互特效（悬停放大、点击缩放回弹）
• 图片显示/隐藏动画
• 选择题答案校验（严格多选题判断）
• 背景遮罩渐变 + 文字提示
• 组件自动添加/获取
• 集合比较、文本缩进、数值渐变、数组展平、随机排序等通用辅助方法

适用于快速搭建交互式 UI、教学实验、问答系统、数值展示等 2D 界面场景。

---

方法一览（API Index）

方法名	类型	异步	返回类型	主要功能	典型用途
ScaleImage	static	否	void	点击图片放大到视口中央，再次点击还原	大图预览
CsGroupScale	static	否	void	使用 DOTween 对 CanvasGroup 进行缩放动画	弹窗/面板缩放出现
CheckInputField	static	否	bool	校验 InputField / TMP_InputField 是否合法	防止非法输入
ChangeSprite	static	否	void	根据名称更换指定 Image 的 Sprite	状态切换图标
AddButtonEffect	static	否	void	为按钮添加悬停放大 + 点击回弹特效	美化按钮交互感
ShowAndHideImage / ShowImage / HideImage	static	否	void	使用 DOTween 实现图片弹簧式显示/隐藏	提示图标/图标反馈
ValidateInputField	static	否	bool	校验数字输入，不合法时显示提示并聚焦	表单验证
CheckedToggleAnswers	static	否	bool	严格判断多选题答案（必须全对且不多选）	选择题评分
ImageGradient	static	是	UniTask	黑色遮罩渐变 + 中间显示文字提示	操作提示、加载提示
GetBtnByName	static	否	Button	从按钮列表中按名称查找按钮	快速获取特定按钮
AddComponentIfMissing	static	否	void	如果缺少组件则自动添加	确保组件存在
GetComponentIfMissing	static	否	T	获取或添加组件并返回	安全获取组件
ListEquals	static	否	bool	判断两个集合内容是否完全相等	答案对比、状态比较
AddSpace	static	否	string	为字符串添加首行缩进（透明色 hack）	文本排版美化
RefreshTextWeight	static	否	void	根据文本内容自适应背景宽度	对话气泡、标签自适应
DataIncrement1 / DataIncrement2	static	否	float	数值渐变增长（常用于分数/进度动画）	数值动画展示
MathRound	static	否	double	四舍五入保留指定小数位（AwayFromZero）	精确小数显示
Flatten2d	static	否	T[]	将二维数组展平为一维	数据处理简化
Get2DIndex	static	否	(int,int)	一维索引映射到二维行列索引	网格布局计算
RandomSort	static	否	List	随机打乱列表顺序	选项乱序、卡牌洗牌
Product	static	否	int/float/double	计算集合中所有元素的乘积	累乘计算
GetAbsoluteScale	static	否	Vector3	计算物体在层级中的绝对缩放值	UI 字体大小校正

---

方法详情

UI 交互与动画

ScaleImage

/// <summary>
/// 点击图片放大到固定大小和位置，再次点击还原（挂载在图片上使用）
/// </summary>
public static void ScaleImage(this Image image, bool isScale)

CsGroupScale

/// <summary>
/// 使用 DOTween 对 CanvasGroup 进行缩放动画（常用于弹窗）
/// </summary>
/// <param name="value">目标缩放值，通常 0~1</param>
/// <param name="fadeTime">动画时间</param>
/// <param name="ease">缓动类型</param>
public static void CsGroupScale(this CanvasGroup cg, float value, float fadeTime, Ease ease)

推荐 Ease：

• 出现：InOutQuint、InOutBack
• 消失：OutCubic、OutQuint

AddButtonEffect

/// <summary>
/// 为按钮添加悬停放大 + 点击缩放回弹特效（使用 DOTween）
/// </summary>
public static void AddButtonEffect(this Button btn)

效果参数（可自行修改类中静态字段）：

• 悬停：1.1 倍，0.2s
• 点击：0.9 倍 → 回 1.0 倍

ShowImage / HideImage / ShowAndHideImage

public static void ShowImage(this Image image)
public static void HideImage(this Image image)
public static void ShowAndHideImage(this Image image)

使用弹簧 + 淡入淡出组合，视觉反馈强烈。

---

输入校验

CheckInputField

/// <summary>
/// 简单校验 InputField 是否非空且不是特殊字符
/// </summary>
public static bool CheckInputField(this InputField inputField)
public static bool CheckInputField(this TMP_InputField inputField)

ValidateInputField

/// <summary>
/// 校验是否为合法数字，不合法则显示提示并聚焦输入框
/// </summary>
public static bool ValidateInputField(Text txtTishi, InputField iptfd, string tips)
public static bool ValidateInputField(TMP_Text txt_tishi, TMP_InputField iptfd, string tips)

---

选择题答案判断

CheckedToggleAnswers

/// <summary>
/// 严格判断多选题答案：必须全选正确选项，且不能多选
/// </summary>
public static bool CheckedToggleAnswers(IEnumerable<Toggle> options, IEnumerable<Toggle> answers)

使用 ListEquals 实现集合相等判断。

---

遮罩渐变提示

ImageGradient

/// <summary>
/// 黑色半透明遮罩渐变出现 → 显示文字 → 渐变消失
/// </summary>
public static async UniTask ImageGradient(GameObject image, string content, CancellationToken ctk)

ImageGradientAndSetTran（重载）

支持同时设置物体位置/旋转/缩放，常用于引导箭头或视角切换提示。

---

组件管理

AddComponentIfMissing / GetComponentIfMissing

public static void AddComponentIfMissing<T>(GameObject obj) where T : Component
public static T GetComponentIfMissing<T>(GameObject obj) where T : Component

用途：确保 EventTrigger、CanvasGroup 等组件存在。

---

其他实用工具

• ListEquals：集合内容完全相等判断
• AddSpace：首行缩进（使用透明色 hack）
• RefreshTextWeight：文本背景宽度自适应
• DataIncrement1/2：数值平滑增长动画
• MathRound：精确四舍五入
• Flatten2d：二维数组展平
• RandomSort：列表随机乱序
• Product：集合元素累乘
• GetAbsoluteScale：计算层级绝对缩放（用于字体校正）

---