SuperExtensions

Unity 项目扩展类 API 文档

目录

1. Collection 扩展
2. GameObject 扩展
3. Input System 扩展
4. IO 扩展
5. System 工具
6. Math 扩展
7. Texture 扩展
8. Number 格式化扩展
9. UI 扩展
10. Vector 扩展

---

Collection 扩展

ShuffleCopy<T>(this IEnumerable<T> source)

• 说明：返回一个打乱顺序的副本，不修改原集合。

• 类型参数：

  • T：集合元素类型。

• 参数：

  • source：原集合。

• 返回值：打乱顺序后的 IEnumerable<T>。

• 示例：

var shuffled = myList.ShuffleCopy();

---

ShuffleInPlace<T>(this IList<T> list)

• 说明：原地打乱顺序，会直接修改原列表。

• 类型参数：

  • T：列表元素类型。

• 参数：

  • list：需要打乱顺序的列表。

• 返回值：无。

• 示例：

myList.ShuffleInPlace();

---

PickRandom<T>(this IEnumerable<T> source)

• 说明：随机选择集合中的一个元素。

• 类型参数：

  • T：集合元素类型。

• 参数：

  • source：目标集合。

• 返回值：随机元素 T。

• 示例：

var randomItem = myList.PickRandom();

---

GameObject 扩展

提供一些常用的组件获取与查找优化方法

GetOrAddComponent<T>(this GameObject obj)

• 说明：获取对象上的组件，如果不存在则自动添加，确保对象一定拥有该组件。

• 类型参数：

  • T：组件类型。

• 参数：

  • obj：目标 GameObject。

• 返回值：已有组件或新添加的组件 T。

• 示例：

var rb = gameObject.GetOrAddComponent<Rigidbody>();

---

GetComponentsInChildrenGood<T>(this GameObject obj, bool includeInactive)

• 说明：获取子对象上的组件（不包含自身对象上的组件）。

• 类型参数：

  • T：组件类型。

• 参数：

  • obj：目标 GameObject。
  • includeInactive：是否包含未激活的对象。

• 返回值：子对象上所有组件的列表 List<T>。

• 示例：

var colliders = gameObject.GetComponentsInChildrenGood<Collider>(true);

---

GetComponentInChildrenGood<T>(this GameObject obj, bool includeInactive)

• 说明：获取子对象上的第一个组件（不包含自身对象上的组件）。

• 类型参数：

  • T：组件类型。

• 参数：

  • obj：目标 GameObject。
  • includeInactive：是否包含未激活对象。

• 返回值：找到的第一个子对象组件 T，如果没有则返回 null。

• 示例：

var childCollider = gameObject.GetComponentInChildrenGood<Collider>(true);

---

Input System 扩展

ToKey(this string keyName)

• 说明：将字符串转换为 Input System 的 Key。

• 参数：

  • keyName：按键名称（大小写不敏感）。

• 返回值：对应的 Key。

• 示例：

Key k = "Left Ctrl".ToKey();

---

ToReadableString(this Key key)

• 说明：将 Key 转换为易读字符串。

• 参数：

  • key：目标 Key。

• 返回值：易读字符串。

• 示例：

string str = Key.LeftCtrl.ToReadableString(); // "Left Ctrl"

---

其他 Key 扩展方法

• IsLetterKey(), IsNumberKey(), IsFunctionKey(), IsModifierKey(), IsNavigationKey(), IsWhitespaceKey(), IsPunctuationKey(), IsSpecialKey(), IsKeypadKey(), IsValidKey()
• 说明：判断按键类型，返回 bool。
• 示例：

bool isLetter = Key.A.IsLetterKey(); // true

• IsPressed(), WasPressedThisFrame(), WasReleasedThisFrame(), IsToggled()
• 说明：检测按键状态，返回 bool。
• 示例：

if(Key.Space.IsPressed()) { /* do something */ }

---

IO 扩展

ReadLastLinesOfFile(this string path, int maxLines = 500)

• 说明：读取文件最后几行。

• 参数：

  • path：文件路径。
  • maxLines：最大行数。

• 返回值：最后几行的字符串。

• 示例：

string lastLines = "log.txt".ReadLastLinesOfFile(100);

---

ReadTruncatedFile(this string path, int maxBytes = 100_000)

• 说明：读取文件的最后 maxBytes 字节。
• 返回值：byte[]。
• 示例：

byte[] data = "log.txt".ReadTruncatedFile(5000);

---

Truncate(this string str, int maxLength)

• 说明：截断字符串并添加省略号。
• 返回值：截断后的字符串。
• 示例：

string s = "Hello World".Truncate(5); // "Hello..."

---

ToReadableFileSize(this long byteCount) / int

• 说明：将字节数格式化为可读单位。
• 返回值：字符串，例如 "1.23 MB"。
• 示例：

long size = 12345678;
string readable = size.ToReadableFileSize();

---

System 工具

GetSystemSpecs()

• 说明：获取系统硬件信息。
• 返回值：格式化字符串。
• 示例：

string info = SystemUtils.GetSystemSpecs();

---

GetPlayerLogPath()

• 说明：获取 Unity Player 日志文件路径。
• 返回值：字符串路径。
• 示例：

string logPath = SystemUtils.GetPlayerLogPath();

---

Math 扩展

Average(List<double> values)

• 说明：计算平均值。
• 返回值：平均值 double。
• 示例：

double avg = MathStatsHelper.Average(new List<double> {1,2,3});

Sigma(List<double> values)

• 说明：计算标准差。
• 返回值：标准差 double。
• 示例：

double sigma = MathStatsHelper.Sigma(values);

Median, Min, Max

• 说明：计算中位数、最小值、最大值。
• 示例：

double median = MathStatsHelper.Median(values);

---

Texture 扩展

CompressImage(this Texture2D texture, int maxSize = 512, int jpegQuality = 75)

• 说明：压缩图片并返回 JPEG 字节。
• 返回值：byte[]
• 示例：

byte[] data = myTexture.CompressImage(256, 80);

---

CreateReadableCopy(this Texture2D original)

• 说明：创建可读的纹理副本。
• 返回值：Texture2D
• 示例：

Texture2D copy = myTexture.CreateReadableCopy();

---

Number 格式化扩展

• 方法包括：

  • Format, FormatKeepDigitsInt, GetDigitCountInt, FormatPercent, FormatScientific, FormatWithSuffix, FormatTimeHMS, FormatTimeVerbose, FormatTimeDHMS, FormatCurrency, FormatOrdinal, FormatSI, FormatHex, FormatBytes, FormatSigned, FormatRoman

• 说明：提供多种数字、时间、货币、进制、SI 单位格式化。

• 示例：

double val = 1234567;
string s1 = val.FormatWithSuffix(); // "1.2M"
string s2 = val.FormatPercent(); // "123456700.0 %"

---

UI 扩展

ContainsScreenPoint(this RectTransform rt, Vector2 screenPoint, Camera cam = null)

• 说明：检测屏幕点是否在 UI 元素中。
• 返回值：bool
• 示例：

bool hit = myRectTransform.ContainsScreenPoint(Input.mousePosition);

---

Vector 扩展

Vec 结构体

• 说明：轻量 Vector3 封装，支持 Vector2/Vector3 隐式转换。
• 操作符：+, -, *, /（逐元素运算或与 float）
• 示例：

Vec a = new Vec(1,2);
Vec b = new Vec(3,4);
Vec c = a + b; // (4,6,0)
Vector3 v3 = c; // 隐式转换

---