rucky/Nanami-UI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e915bbd74a7878ee947d8722eef79c60dc2538f3
Nanami-UI/docs/插件功能概览.md
rucky 6e18269bfd 完成焦点等开发
2026-03-31 18:03:23 +08:00

16 KiB
Raw Blame History

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. 针对地图、角色面板、聊天三个大模块分别拆详细设计文档。