【前端接口】GUI:ItemBox_Create：物品格子与道具展示的标准件

实战应用：用在哪里

背包、仓库、商店、邮件附件的物品格子全是同一颗标准件：GUI:ItemBox_Create。格子负责物品的图标、数量角标、品质边框、点击响应的标准化展示，道具展示的视觉一致性由这个控件统一兜底。

创建与数据绑定

---创建物品格 parent:父节点 ID:x/y:坐标 img:底图 boxindex:格位 stdmode:标准模式
function GUI:ItemBox_Create(parent, ID, x, y, img, boxindex, stdmode) end

-- 背包界面创建 40 个格子
for i = 1, 40 do
    local box = GUI:ItemBox_Create(bagWin, "bagBox" .. i, col * 42, row * 42, "cell_bg.png", i, 0)
    GUI:ItemBox_UpdateBoxData(box, bagData[i])
end

格子的底图、格位序号、标准模式三参数决定格子的身份，ItemBox_UpdateBoxData 把物品数据（图标、数量、品质）灌进格子。格子的数据驱动更新：背包的数据变化后只 Update 变化的格子，整屏重刷是性能的反模式。格子的点击响应：ItemBox 系列的点击与长按事件接口（addDoubleEvent、addPressEvent）让单击看详情、双击使用、长按拆分的交互分层得以实现。

格子的状态表达

-- 锁定格与选中态
GUI:ItemBox_setIconGrey(box, true)
GUI:ItemBox_setItemShowChooseState(box, true)

灰化表达锁定与不可用，选中态表达多选操作，格子的状态语言统一后玩家的学习成本为零。物品格子与 ItemShow（纯展示控件）的分工：可交互的格子用 ItemBox，纯展示的（公告里的道具介绍）用 ItemShow，控件的选择按交互需求定。

验证与监控

格子控件的数量与刷新频率的监控，背包满配 60 格的界面的帧率是低端机的测试基线。

踩坑记录

格位序号与数据数组的错位曾经让 A 格显示 B 格的物品，格位与数据的绑定关系单一数据源驱动后修复。物品数量角标的字体在数量过千时的显示溢出，数量的大数缩写（9999 显示 9.9K）是角标的处理细节。

上线要点

物品格子的图标加载是异步的，滚动列表里大量格子的图标加载要做可视区优先，滚到哪加载到哪。格子的品质边框颜色与物品品质的映射表全局统一，品质的颜色语言全站一致。格子的点击响应要区分触摸与滑动，列表滚动的误触在 ItemBox_setItemTouchSwallow 的吞触摸配置里解决。

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