docs：为核心管理器添加详细中文注释

- GameManager.gd：游戏状态管理注释 - NetworkManager.gd：网络请求管理注释 - SceneManager.gd：场景切换管理注释 - StringUtils.gd：字符串工具函数注释按照docs注释规范，添加文件头、函数说明、参数描述和使用示例方便协同开发者快速理解和调用
2026-01-02 21:19:53 +08:00
parent aaaf2b31a8
commit 2f1ccbc2cd
4 changed files with 708 additions and 59 deletions
--- a/_Core/utils/StringUtils.gd
+++ b/_Core/utils/StringUtils.gd
@@ -1,26 +1,102 @@
 class_name StringUtils

-# 字符串工具类 - 提供常用的字符串处理功能
+# ============================================================================
+# StringUtils.gd - 字符串工具类
+# ============================================================================
+# 静态工具类，提供常用的字符串处理功能
+# 
+# 核心功能:
+# - 输入验证（邮箱、用户名、密码）
+# - 字符串格式化和转换
+# - 时间格式化和相对时间计算
+# - 文件大小格式化
+#
+# 使用方式:
+#   var is_valid = StringUtils.is_valid_email("user@example.com")
+#   var formatted_time = StringUtils.format_utc_to_local_time(utc_string)
+#
+# 注意事项:
+# - 所有方法都是静态的，无需实例化
+# - 验证方法返回布尔值或包含详细信息的字典
+# - 时间处理方法支持UTC到本地时间的转换
+# ============================================================================
+
+# ============ 输入验证方法 ============

 # 验证邮箱格式
+# 
+# 参数:
+#   email: String - 待验证的邮箱地址
+# 
+# 返回值:
+#   bool - true表示格式正确，false表示格式错误
+# 
+# 验证规则:
+# - 必须包含@符号
+# - @前后都必须有内容
+# - 域名部分必须包含至少一个点
+# - 顶级域名至少2个字符
+# 
+# 使用示例:
+#   if StringUtils.is_valid_email("user@example.com"):
+#       print("邮箱格式正确")
 static func is_valid_email(email: String) -> bool:
 	var regex = RegEx.new()
 	regex.compile("^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$")
 	return regex.search(email) != null

-# 验证用户名格式（字母、数字、下划线）
+# 验证用户名格式
+# 
+# 参数:
+#   username: String - 待验证的用户名
+# 
+# 返回值:
+#   bool - true表示格式正确，false表示格式错误
+# 
+# 验证规则:
+# - 只能包含字母、数字、下划线
+# - 长度不能为空且不超过50个字符
+# - 不能包含空格或特殊字符
+# 
+# 使用示例:
+#   if StringUtils.is_valid_username("user_123"):
+#       print("用户名格式正确")
 static func is_valid_username(username: String) -> bool:
+	# 检查长度
 	if username.is_empty() or username.length() > 50:
 		return false
 	
+	# 检查字符组成
 	var regex = RegEx.new()
 	regex.compile("^[a-zA-Z0-9_]+$")
 	return regex.search(username) != null

 # 验证密码强度
+# 
+# 参数:
+#   password: String - 待验证的密码
+# 
+# 返回值:
+#   Dictionary - 包含验证结果的详细信息
+#   {
+#     "valid": bool,      # 是否符合最低要求
+#     "message": String,  # 验证结果消息
+#     "strength": int     # 强度等级 (1-4)
+#   }
+# 
+# 验证规则:
+# - 最少8位，最多128位
+# - 必须包含字母和数字
+# - 强度评级：包含字母(+1)、数字(+1)、特殊字符(+1)、长度>=12(+1)
+# 
+# 使用示例:
+#   var result = StringUtils.validate_password_strength("MyPass123!")
+#   if result.valid:
+#       print("密码强度: ", result.message)
 static func validate_password_strength(password: String) -> Dictionary:
 	var result = {"valid": false, "message": "", "strength": 0}
 	
+	# 检查长度限制
 	if password.length() < 8:
 		result.message = "密码长度至少8位"
 		return result
@@ -29,9 +105,10 @@ static func validate_password_strength(password: String) -> Dictionary:
 		result.message = "密码长度不能超过128位"
 		return result
 	
-	var has_letter = false
-	var has_digit = false
-	var has_special = false
+	# 检查字符类型
+	var has_letter = false    # 是否包含字母
+	var has_digit = false     # 是否包含数字
+	var has_special = false   # 是否包含特殊字符
 	
 	for i in range(password.length()):
 		var character = password[i]
@@ -42,6 +119,7 @@ static func validate_password_strength(password: String) -> Dictionary:
 		elif character in "!@#$%^&*()_+-=[]{}|;:,.<>?":
 			has_special = true
 	
+	# 计算强度等级
 	var strength = 0
 	if has_letter:
 		strength += 1
@@ -54,27 +132,72 @@ static func validate_password_strength(password: String) -> Dictionary:
 	
 	result.strength = strength
 	
+	# 检查最低要求
 	if not (has_letter and has_digit):
 		result.message = "密码必须包含字母和数字"
 		return result
 	
+	# 密码符合要求
 	result.valid = true
 	result.message = "密码强度: " + ["弱", "中", "强", "很强"][min(strength - 1, 3)]
 	return result

+# ============ 字符串格式化方法 ============
+
 # 截断字符串
+# 
+# 参数:
+#   text: String - 原始字符串
+#   max_length: int - 最大长度
+#   suffix: String - 截断后缀（默认为"..."）
+# 
+# 返回值:
+#   String - 截断后的字符串
+# 
+# 功能:
+# - 如果字符串长度超过限制，截断并添加后缀
+# - 如果字符串长度未超过限制，返回原字符串
+# 
+# 使用示例:
+#   var short_text = StringUtils.truncate("这是一个很长的文本", 10, "...")
+#   # 结果: "这是一个很长..."
 static func truncate(text: String, max_length: int, suffix: String = "...") -> String:
 	if text.length() <= max_length:
 		return text
 	return text.substr(0, max_length - suffix.length()) + suffix

 # 首字母大写
+# 
+# 参数:
+#   text: String - 原始字符串
+# 
+# 返回值:
+#   String - 首字母大写的字符串
+# 
+# 使用示例:
+#   var capitalized = StringUtils.capitalize_first("hello world")
+#   # 结果: "Hello world"
 static func capitalize_first(text: String) -> String:
 	if text.is_empty():
 		return text
 	return text[0].to_upper() + text.substr(1)

-# 转换为标题格式（每个单词首字母大写）
+# 转换为标题格式
+# 
+# 参数:
+#   text: String - 原始字符串
+# 
+# 返回值:
+#   String - 每个单词首字母大写的字符串
+# 
+# 功能:
+# - 将每个单词的首字母转换为大写
+# - 其余字母转换为小写
+# - 以空格分隔单词
+# 
+# 使用示例:
+#   var title = StringUtils.to_title_case("hello world game")
+#   # 结果: "Hello World Game"
 static func to_title_case(text: String) -> String:
 	var words = text.split(" ")
 	var result = []
@@ -84,27 +207,75 @@ static func to_title_case(text: String) -> String:
 	return " ".join(result)

 # 移除HTML标签
+# 
+# 参数:
+#   html: String - 包含HTML标签的字符串
+# 
+# 返回值:
+#   String - 移除HTML标签后的纯文本
+# 
+# 功能:
+# - 使用正则表达式移除所有HTML标签
+# - 保留标签之间的文本内容
+# 
+# 使用示例:
+#   var plain_text = StringUtils.strip_html_tags("<p>Hello <b>World</b></p>")
+#   # 结果: "Hello World"
 static func strip_html_tags(html: String) -> String:
 	var regex = RegEx.new()
 	regex.compile("<[^>]*>")
 	return regex.sub(html, "", true)

 # 格式化文件大小
+# 
+# 参数:
+#   bytes: int - 文件大小（字节）
+# 
+# 返回值:
+#   String - 格式化后的文件大小字符串
+# 
+# 功能:
+# - 自动选择合适的单位（B, KB, MB, GB, TB）
+# - 保留一位小数（除了字节）
+# - 使用1024作为换算基数
+# 
+# 使用示例:
+#   var size_text = StringUtils.format_file_size(1536)
+#   # 结果: "1.5 KB"
 static func format_file_size(bytes: int) -> String:
 	var units = ["B", "KB", "MB", "GB", "TB"]
 	var size = float(bytes)
 	var unit_index = 0
 	
+	# 自动选择合适的单位
 	while size >= 1024.0 and unit_index < units.size() - 1:
 		size /= 1024.0
 		unit_index += 1
 	
+	# 格式化输出
 	if unit_index == 0:
 		return str(int(size)) + " " + units[unit_index]
 	else:
 		return "%.1f %s" % [size, units[unit_index]]

+# ============ 时间处理方法 ============
+
 # 将UTC时间字符串转换为本地时间显示
+# 
+# 参数:
+#   utc_time_str: String - UTC时间字符串（格式: 2025-12-25T11:23:52.175Z）
+# 
+# 返回值:
+#   String - 格式化的本地时间字符串
+# 
+# 功能:
+# - 解析ISO 8601格式的UTC时间
+# - 转换为本地时区时间
+# - 格式化为易读的中文时间格式
+# 
+# 使用示例:
+#   var local_time = StringUtils.format_utc_to_local_time("2025-12-25T11:23:52.175Z")
+#   # 结果: "2025年12月25日 19:23:52" (假设本地时区为UTC+8)
 static func format_utc_to_local_time(utc_time_str: String) -> String:
 	# 解析UTC时间字符串 (格式: 2025-12-25T11:23:52.175Z)
 	var regex = RegEx.new()
@@ -148,7 +319,22 @@ static func format_utc_to_local_time(utc_time_str: String) -> String:
 		local_dict.second
 	]

-# 获取相对时间描述（多少分钟后）
+# 获取相对时间描述
+# 
+# 参数:
+#   utc_time_str: String - UTC时间字符串
+# 
+# 返回值:
+#   String - 相对时间描述（如"5分钟后"、"2小时30分钟后"）
+# 
+# 功能:
+# - 计算指定时间与当前时间的差值
+# - 返回人性化的相对时间描述
+# - 支持秒、分钟、小时的组合显示
+# 
+# 使用示例:
+#   var relative_time = StringUtils.get_relative_time_until("2025-12-25T12:00:00Z")
+#   # 结果: "30分钟后" 或 "现在可以重试"
 static func get_relative_time_until(utc_time_str: String) -> String:
 	# 解析UTC时间字符串
 	var regex = RegEx.new()
@@ -183,6 +369,7 @@ static func get_relative_time_until(utc_time_str: String) -> String:
 	# 计算时间差（秒）
 	var diff_seconds = target_timestamp - current_timestamp
 	
+	# 格式化相对时间
 	if diff_seconds <= 0:
 		return "现在可以重试"
 	elif diff_seconds < 60: