Snail Helper

一个针对蜗牛项目的 VS Code 扩展工具集，提供快捷修复、文件头插入、基于模板创建界面文件等能力。

功能一览

• Quick Fix（Ctrl+.）：在 Lua 文件中提供“快速修复”入口，调用修复逻辑
• 命令面板与右键菜单：
  • 修复警告代码（ID: snail.fixWarningCode）
  • 插入文件头（ID: snail.insertFileHeader）
  • 基于模板创建界面（ID: snail.createUIFormTemplate）
  • 诊断与定向修复：
    • UI 界面 onGetFocus：若下一条有效代码行未调用 ClassName.super.onGetFocus(...)，给出警告并提供一键插入修复（自动补齐 self 与参数）
    • 函数式父类声明：当 class(PURE_FILE, function() return Base:create(PURE_FILE) end) 且 Base 非 cc.*，给出警告并一键替换为 class(PURE_FILE, Base)
    • UI 中的背景音乐调用：在 UI 文件内不推荐调用 AudioM.playBgMusic(...) / AudioM.changeBgMusic(...)，给出警告
    • UI 中的 registerScriptHandler：在 UI 文件内不建议使用 self:registerScriptHandler(function(ev) ... end) 重写父类注册逻辑，给出警告并提供拆分到 onEnter() / onExit() 的一键修复

激活方式

• 打开 Lua 文件（onLanguage:lua）或编辑器启动完成（onStartupFinished）时激活
• 在 Lua 文件内按 Ctrl+. 将看到“Snail Quick Fix”

命令说明

• 修复警告代码（snail.fixWarningCode）

  • 作用：对“当前行”进行一系列重构/替换
    • 宏替换：按配置将宏名替换为枚举式写法（如 BG_STYLE_NOTEBOOK → BgStyle.NOTEBOOK）
    • TextStyleM：将 TextStyleM.setTextStyle(...) 转换为 TextStyleM.setTextStyleNew(...) 并重排参数
    • 全局函数调用：按映射表将全局方法替换为命名空间方法（如 showItemDesc → FormUtil.showItemDesc）
  • 触发方式：
    • 命令面板执行
    • 快捷键：Ctrl+Shift+L（macOS: Cmd+Shift+L）
    • Lua 文件中通过 Ctrl+. 快速修复列表

• 插入文件头（snail.insertFileHeader）

  • 作用：在光标处（或当前选区）插入一段标准化的文件头注释
  • 支持：.lua / .c / .cpp / .h / .hpp / .cc
  • 注释前缀会根据语言自动选择 -- 或 //
  • 快捷键：Ctrl+Alt+H（macOS: Cmd+Alt+H）

• 基于模板创建界面（snail.createUIFormTemplate）

  • 作用：基于模板生成 Lua 界面文件，替换占位符并打开生成的主文件
  • 用法：在资源管理器中右键目标文件夹，或执行命令后选择目标目录
  • 模板文件：默认读取主工程下 client/tool/scripts_template/UITemplate.txt

诊断与自动修复规则

• UI onGetFocus 必须调用 super

  • 识别 function ClassName:onGetFocus(...)，若其下一条有效代码行未包含 ClassName.super.onGetFocus(...)，标记为警告
  • 快速修复：自动在下一行插入 ClassName.super.onGetFocus(self, ...)，缩进为当前行 +4 空格
  • 进入条件：
    • 文件为 Lua；且该文件中存在“UI 界面类”定义：
      • ClassName = class(PURE_FILE, BaseName)，并且 BaseName 不是 cc.*
      • 或 ClassName = class(PURE_FILE, function() return Base:create(PURE_FILE) end)（支持多行），并且 Base 不是 cc.*
    • 类中存在方法定义：function ClassName:onGetFocus(...)
    • 方法定义后的“下一条有效代码行”（跳过空行、-- 单行注释和 --[[ ... ]] 多行注释）没有出现 ClassName.super.onGetFocus(...)
    • UIFormBase 本身不参与此检查

• 函数式父类应改为直接父类名

  • 识别 ClassName = class(PURE_FILE, function() return Base:create(PURE_FILE) end)（支持多行），当 Base 非 cc.* 时发出警告
  • 快速修复：把函数参数整体替换为 Base

• UI 中的 AudioM 背景音乐调用

  • 进入条件：
    • 文件为 Lua，且该文件中存在有效“UI 界面类”（父类非 cc.*），例如：
      • ClassName = class(PURE_FILE, BaseName)
      • 或 ClassName = class(PURE_FILE, function() return Base:create(PURE_FILE) end)
  • 规则与级别：
    • AudioM.playBgMusic(...)：警告（Warning）。建议继承 UIFormBase 后重写 getBgMusic() 指定界面 BGM
    • AudioM.changeBgMusic(...)：警告（Warning）。建议继承 UIFormBase 后替换为 self:changeBgMusic(...)
  • 快速修复：
    • 插入忽略注释（插入在“当前行的上一行”）：
      • 仅忽略 play：-- @snail-ignore:playBgMusic
      • 仅忽略 change：-- @snail-ignore:changeBgMusic

• UI 中的 registerScriptHandler 重写

  • 识别：self:registerScriptHandler(function(ev) ... end)（允许多行，括号配对）
  • 规则与级别：警告（Warning）。建议不要在 UI 中重写父类注册逻辑
  • 快速修复：删除注册代码，并将 ev == "enter" 和 ev == "exit" 分支内的代码分别迁移到：
    • function ClassName:onEnter() ... end
    • function ClassName:onExit() ... end
  • 行为细节：
    • 新函数会插入到“包裹该注册调用的函数”的 end 下一行
    • 自动规范化缩进（函数体相对函数头 +4 空格），并保留已有代码结构
    • 删除注册调用前一行注释；合并周边空行，仅保留 1 个空行

设置项（Settings）

以下设置可在“设置”中搜索 snail 调整：

• snail.base.rootDir（字符串，默认 ./）

  • 含义：整体工程的根目录；用于定位相对路径

• snail.template.templateDir（字符串，资源作用域）

  • 含义：界面模板所在目录（可相对 rootDir 或绝对路径）
  • 说明：未设置时，命令会使用内置默认路径 ./client/tool/scripts_template

• snail.fix.functionReplacement（对象，资源作用域）

  • 含义：全局函数替换映射表
  • 示例：

      {
      	"showItemDesc": "FormUtil.showItemDesc",
      	"openPanel": "UIRouter.open"
      }
    

• snail.fix.macroReplacement（对象，资源作用域）

  • 含义：宏替换映射表
  • 示例：

      {
      	"BG_STYLE_NOTEBOOK": "BgStyle.NOTEBOOK",
      	"COLOR_RED": "Color.RED"
      }
    

注意事项

• Quick Fix 仅在 Lua 文件且当前行非空时可看到条目
• 模板路径不存在时会给出提示，请检查 snail.base.rootDir 与 snail.template.templateDir

代码补全（UI 模板）

在 UI 类 Lua 文件内，输入标识符时会提供以下模板补全（按当前单词范围替换，缩进与类名自动匹配）：

• onEnter：进入界面函数
• onExit：退出界面函数
• getBgMusic：返回界面 BGM 信息
• onGetFocus：获得焦点
• onLoseFocus：失去焦点

兼容性

• 需要 VS Code 版本 ≥ 1.53.0