【前端接口】GUI:Attach_MainTop：主界面挂载与常驻控件的定位体系

实战应用：用在哪里

活动图标、在线奖励按钮、红点提示这些常驻元素要钉在主界面的固定区域：GUI:Attach_MainTop、Attach_Parent、Attach_SceneF 组成的挂载体系是前端界面架构的定位基石。挂载点决定控件的归属层，归属层决定控件的生命周期与遮挡关系。

挂载体系

---挂载到主界面顶部区域
function GUI:Attach_MainTop(widget) end

-- 活动图标挂主界面顶部
local actIcon = GUI:Image_Create(nil, "actIcon", 0, 0, "activity_icon.png")
GUI:Attach_MainTop(actIcon)
GUI:setPosition(actIcon, 900, 40)
GUI:addOnClickEvent(actIcon, function()
    GUI:Win_Open("activity_list")
end)

Attach_MainTop 把控件挂到主界面顶部区域，挂载后控件的坐标系随主界面的布局管理，分辨率适配由挂载体系统一处理。挂载点的家族覆盖界面的主要区域：主界面顶部（活动图标）、场景前景（地面的机关提示）、场景背景、界面最上层（全屏强弹窗），控件挂对层是界面架构的第一课。

挂载层与生命周期

-- 挂场景层的地面提示：进图创建离图销毁
function onEnterMap(actor, mapId)
    if mapId == "bossroom" then
        groundTip = GUI:Image_Create(nil, "groundTip", 300, 200, "boss_tip.png")
        GUI:Attach_SceneF(groundTip)
    end
end

function onLeaveMap(actor, mapId)
    if groundTip then
        groundTip:removeFromParent()
        groundTip = nil
    end
end

场景层的控件随地图切换销毁重建，界面层的控件跨场景常驻，控件的生命周期由挂载层决定。挂载的选择错误是界面 Bug 的常见根源：该挂界面的控件挂了场景层，切图就丢；该挂场景的提示挂了界面层，遮挡了战斗视野。与 QF 的 entermap/leavemap 触发的配合：地图相关的界面元素在服务端触发的地图事件里创建与销毁，前后端的地图状态同步让挂载的时机精准。

验证与监控

主界面常驻控件的数量监控，挂载控件的堆积会让主界面变成图标坟场。

踩坑记录

挂载层的遮挡关系曾经让活动图标被全屏弹窗压住，层级的优先级表是挂载体系的配套文档。多分辨率下的挂载坐标曾经错位，挂载体系的锚点配置（Attach 的方位变体：LeftBottom、RightTop 等）替代绝对坐标后适配问题清零。

上线要点

控件的挂载层选择写进界面开发的规范：常驻 UI 挂界面层、世界相关的挂场景层、强提醒挂最上层。挂载控件的红点联动：挂载的入口控件与红点树的节点绑定，红点亮起挂载控件才显示角标。主界面区域的规划图（哪个区域放哪类控件）是界面架构的图纸，新控件的挂载按图纸对号入座。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。