# Nanami-UI 插件功能概览 本文基于当前仓库代码结构整理，目标是快速回答两个问题： 1. 这个乌龟服插件当前做了什么。 2. 每块功能主要落在哪些代码文件里。 ## 1. 插件定位 `Nanami-UI` 是一个面向 Turtle WoW 1.12 环境的大型整合型 UI 插件。整体风格以 `SFrames` 为统一命名空间，核心能力主要包括： - 自定义单位框体：玩家、宠物、目标、目标的目标、队伍、团队、焦点、天赋树。 - 动作条与按键：动作条重排、绑定管理、绑定导入导出。 - 地图与导航：小地图/世界地图换肤、地图迷雾揭示、区域等级、队友图标、暗月马戏团辅助。 - 聊天与社交：聊天框接管、私聊容器、社交面板重做。 - 背包与交易：背包/银行整合、离线库存、商人、交易、邮件、拾取窗口。 - 任务与书籍：任务对话、任务日志皮肤、书籍阅读界面。 - 职业与养成：角色面板、装备统计、观察面板、法术书、训练师、专业/制造、野兽训练。 - 辅助与增强：Tooltip、Tweaks、AFK 屏保、Setup Wizard、配置面板等。 ## 2. 加载主线 ### 2.1 入口文件 - [Nanami-UI.toc](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Nanami-UI.toc) 负责定义加载顺序、依赖和 SavedVariables。 - [Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Core.lua) 定义全局表 `SFrames`、事件分发、初始化总流程、角色配置快照、斜杠命令。 - [Config.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Config.lua) 提供默认配置、主题预设、颜色与样式生成逻辑。 ### 2.2 初始化方式 当前插件的模块大致分成两种启动方式： - `Core.lua` 集中初始化 通过 `SFrames:DoFullInitialize()` 分批启动关键模块与延迟模块，避免登录瞬间内存尖峰。 - 模块自举初始化 一部分界面文件自己监听 `PLAYER_LOGIN` / `ADDON_LOADED` / 专用事件，在对应窗口可用时初始化。 ### 2.3 Core 直接管理的模块 `Core.lua` 当前显式初始化的模块包括： - 立即加载：`Player`、`Pet`、`Target`、`ToT`、`Party`、`FloatingTooltip`、`ActionBars` - 延迟批量加载：`Raid`、`Bags`、`Focus`、`TalentTree`、`Minimap`、`MinimapBuffs`、`MinimapButton`、`Chat`、`MapReveal`、`WorldMap`、`ZoneLevelRange`、`MapIcons`、`Tweaks`、`AFKScreen`、`LootDisplay` ### 2.4 自举型模块 这类文件通常在自身内部注册事件并完成初始化： - [QuestUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\QuestUI.lua) - [TrainerUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TrainerUI.lua) - [TradeSkillUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TradeSkillUI.lua) - [BeastTrainingUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BeastTrainingUI.lua) - [BookUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BookUI.lua) - [Merchant.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Merchant.lua) - [Mail.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Mail.lua) - [SocialUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SocialUI.lua) - [SpellBookUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SpellBookUI.lua) - [FlightMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\FlightMap.lua) - [QuestLogSkin.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\QuestLogSkin.lua) ## 3. 核心框架与基础设施 ### 3.1 核心与公共能力 - [Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Core.lua) 事件总线、统一初始化、角色配置快照、斜杠命令、若干兼容性保护。 - [Config.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Config.lua) 默认配置、主题生成、颜色方案、类职业主题映射。 - [Media.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Media.lua) 字体与状态条材质列表，兼容 LibSharedMedia。 - [Factory.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Factory.lua) 通用边框、背景、按钮、下拉、输入框等 UI 工厂方法。 - [Movers.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Movers.lua) 布局模式、拖拽锚点、网格吸附、统一解锁/锁定框体。 - [IconMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\IconMap.lua) `img/icon.tga` 的图标坐标表，供多个界面复用。 - [Bindings.xml](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bindings.xml) 插件按键绑定入口。 - [ConfigUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ConfigUI.lua) 综合配置面板，覆盖 UI、背包、动作条、小地图、角色等多页设置。 - [SetupWizard.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SetupWizard.lua) 首次安装向导，也可作为二次配置入口。 - [GameMenu.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\GameMenu.lua) 游戏菜单增强，提供 Nanami-UI 相关入口。 - [MinimapButton.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\MinimapButton.lua) 小地图按钮，用于打开主要面板或功能入口。 ### 3.2 斜杠命令 [Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Core.lua) 中已确认的主命令入口为： - `/nanami` - `/nui` 从当前代码可见，至少包含以下子命令： - `unlock` / `move` - `lock` - `chatreset` - `test` - `partyh` - `partyv` - `partylayout` - `focus` - `clearfocus` - `targetfocus` - `fcast` - `focushelp` 此外还有若干模块自己的调试或快捷命令： - [DarkmoonGuide.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\DarkmoonGuide.lua)：`/dmf`、`/darkmoon` - [FlightMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\FlightMap.lua)：`/ftcdebug`、`/ftcexport` - [GearScore.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\GearScore.lua)：`/gsdebug` - [BeastTrainingUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BeastTrainingUI.lua)：`/btdebug` ## 4. 功能与代码文件对应 ### 4.1 单位框体与战斗信息 - [Units\Player.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Player.lua) 玩家框体，包含血量/能量、头像、施法条、buff/debuff、移动锚点等。 - [Units\Pet.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Pet.lua) 宠物框体。 - [Units\Target.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Target.lua) 目标框体，含施法识别与法术图标映射。 - [Units\ToT.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\ToT.lua) 目标的目标框体。 - [Units\Party.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Party.lua) 队伍框体，支持布局切换、拖拽物品到队友等逻辑。 - [Units\Raid.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\Raid.lua) 团队框体。 - [Focus.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Focus.lua) 焦点系统，支持设置焦点、目标焦点、对焦点施法。 - [Tooltip.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Tooltip.lua) 浮动 Tooltip、单位信息扩展。 - [MinimapBuffs.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\MinimapBuffs.lua) 小地图附近的 buff/debuff 重新排布。 - [ActionBars.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ActionBars.lua) 主动作条、姿态条、宠物条、键位显示、范围检测、布局修正。 - [KeyBindManager.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\KeyBindManager.lua) 按键绑定查看、导入导出、编辑。 ### 4.2 地图与导航 - [Minimap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Minimap.lua) 小地图换肤，支持不同边框样式与职业主题皮肤。 - [WorldMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\WorldMap.lua) 世界地图整体重绘与窗口化，是地图类功能的主要承载文件。 - [MapReveal.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\MapReveal.lua) 迷雾揭示与 overlay 数据补丁。 - [ZoneLevelRange.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ZoneLevelRange.lua) 世界地图区域等级、阵营归属、副本/团队本信息提示。 - [MapIcons.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\MapIcons.lua) 世界地图、小地图、战场地图上的队伍/团队职业图标显示。 - [DarkmoonGuide.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\DarkmoonGuide.lua) 暗月马戏团 Sayge Buff 指引面板。 - [DarkmoonMapMarker.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\DarkmoonMapMarker.lua) 现在只保留兼容占位，实际标记逻辑已并入 `WorldMap.lua`。 - [FlightMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\FlightMap.lua) 飞行点目的地列表、飞行进度条与路径可视化。 - [FlightData.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\FlightData.lua) 飞行路线耗时数据库。 ### 4.3 聊天与社交 - [Chat.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Chat.lua) 聊天框全面换肤与接管，保留原生聊天后端。 - [Whisper.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Whisper.lua) 私聊联系人和聊天记录容器。 - [SocialUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SocialUI.lua) 好友、忽略、Who、公会、团队管理界面重做。 ### 4.4 背包、银行、商人、交易、邮件、拾取 - [Bags\Offline.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Offline.lua) 跨角色离线背包/银行数据采集。 - [Bags\Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Core.lua) 背包模块总入口。 - [Bags\Container.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Container.lua) 背包容器 UI 与交互。 - [Bags\Bank.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Bank.lua) 银行界面与银行容器管理。 - [Bags\Sort.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Sort.lua) 背包整理逻辑。 - [Bags\Features.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Features.lua) 自动卖灰、自动开包等附加功能。 - [Merchant.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Merchant.lua) 商人面板重做，含回购、批量购买、修理。 - [Trade.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Trade.lua) 交易窗口重做。 - [Mail.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Mail.lua) 邮件面板重做，支持收件管理与多物品发送队列。 - [LootDisplay.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\LootDisplay.lua) 接管原生拾取窗口视觉层，同时尽量保留原生按钮交互。 - [SellPriceDB.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SellPriceDB.lua) 物品售卖价格数据库，服务于商人/背包场景。 ### 4.5 任务、书籍、日志 - [QuestUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\QuestUI.lua) NPC 任务对话、详情、进度、奖励等流程界面。 - [QuestLogSkin.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\QuestLogSkin.lua) 任务日志窗口换肤。 - [BookUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BookUI.lua) 书籍/卷轴阅读窗口重做。 ### 4.6 角色、法术、训练、专业 - [CharacterPanel.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\CharacterPanel.lua) 角色面板核心文件，体量很大，集成装备、属性、模型、称号、套装等内容。 - [StatSummary.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\StatSummary.lua) 装备统计摘要与独立统计面板。 - [InspectPanel.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\InspectPanel.lua) 观察面板与目标装备信息展示。 - [SpellBookUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\SpellBookUI.lua) 法术书重做。 - [TrainerUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TrainerUI.lua) 职业训练师界面重做。 - [TradeSkillUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TradeSkillUI.lua) 专业制造/制作界面重做。 - [BeastTrainingUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\BeastTrainingUI.lua) 猎人宠物训练界面重做。 - [PetStableSkin.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\PetStableSkin.lua) 宠物管理员/兽栏界面皮肤化。 - [Units\TalentTree.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Units\TalentTree.lua) 天赋树显示模块。 - [TalentDefaultDB.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TalentDefaultDB.lua) 默认天赋数据库。 - [TradeSkillDB.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\TradeSkillDB.lua) 专业/配方静态数据库。 - [ClassSkillData.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ClassSkillData.lua) 职业训练技能数据。 - [GearScore.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\GearScore.lua) 装等/装备评分能力。 ### 4.7 其他增强 - [Tweaks.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Tweaks.lua) 各种杂项增强，当前能看到包括自动下马/取消变形、冷却文本、世界地图 Tooltip 处理、战斗提示等。 - [AFKScreen.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\AFKScreen.lua) AFK 全屏界面，显示模型、时间、世界 Buff 等信息。 - [Roll.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Roll.lua) 与掷骰/需求贪婪相关的界面或逻辑扩展。 ## 5. 数据、资源与文档文件 ### 5.1 图片与材质资源 - `img/` 存放小地图底图、职业风格贴图、动作条材质、图标图集等资源。 - [IconMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\IconMap.lua) 对 `img/icon.tga` 提供图标索引。 ### 5.2 现有文档 - [docs\LootDisplay-技术要点.md](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\docs\LootDisplay-技术要点.md) 记录接管拾取窗口时的关键实现思路。 - [docs\AutoDismount-技术总结.md](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\docs\AutoDismount-技术总结.md) 记录自动下马/取消变形的实现方案。 ### 5.3 辅助脚本与研究资料 - `agent-tools/` 看起来用于生成或整理职业训练相关数据。 - `*.pdf` 当前仓库中包含乌龟服属性收益研究资料，更偏设计/数值参考，不属于插件运行时代码。 ## 6. SavedVariables 与依赖 ### 6.1 SavedVariables 根据 [Nanami-UI.toc](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Nanami-UI.toc)： - `SFramesDB` 角色级配置。 - `SFramesGlobalDB` 全局配置和跨角色数据。 ### 6.2 可选依赖 `toc` 中声明的可选依赖包括： - `ShaguTweaks` - `Blizzard_CombatLog` - `HealComm-1.0` - `DruidManaLib-1.0` - `!Libs` - `pfQuest` - `RDbItems` 从代码上看，这些依赖主要用于： - 治疗预测、Debuff/Overlay 数据读取。 - 地图尺寸与覆盖层补全。 - 额外物品/任务数据支持。 ## 7. 维护视角下的重点文件 如果后续要继续分析或改功能，优先关注下面这些“枢纽文件”： - [Core.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Core.lua) 初始化顺序、模块开关、斜杠命令、配置快照。 - [Config.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Config.lua) 默认值和主题系统。 - [ConfigUI.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\ConfigUI.lua) 用户可见设置入口。 - [CharacterPanel.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\CharacterPanel.lua) 当前仓库里体量最大、耦合也较高的角色面板核心。 - [Chat.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Chat.lua) 体量大、接管深，聊天相关问题通常会从这里开始查。 - [WorldMap.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\WorldMap.lua) 地图增强的主要承载点。 - [Bags\Container.lua](e:\Game\trutle wow\Interface\AddOns\Nanami-UI\Bags\Container.lua) 背包显示与交互核心。 ## 8. 当前文档的边界 这份文档是“基础概览版”，目前更偏结构和职责映射，尚未逐项展开： - 每个模块的详细事件流。 - 每个配置项对应的具体字段。 - 模块之间的调用关系图。 - Turtle WoW 私有 API 或兼容处理的逐点说明。 如果继续往下做，比较自然的下一步是： 1. 补一份“初始化时序图”。 2. 补一份“配置字段与模块对应表”。 3. 针对地图、角色面板、聊天三个大模块分别拆详细设计文档。