【前端接口】GUI:ListView_Create：滚动列表与邮件界面的标准实现

实战应用：用在哪里

邮件列表、排行榜样、公告列表、任务列表——凡是竖着滚的一排排内容都是 GUI:ListView_Create 的领地。列表控件的创建、条目的推入与复用、滚动事件的监听构成前端列表的标准三件套。

创建与推入条目

---创建列表 parent:父节点 ID:x/y:坐标 width/height:尺寸 direction:方向
function GUI:ListView_Create(parent, ID, x, y, width, height, direction) end

-- 邮件列表：竖向滚动，逐条推入
local list = GUI:ListView_Create(mailWin, "mailList", 20, 60, 380, 300, 1)
for _, mail in ipairs(mailData) do
    local item = GUI:ListView_pushBackDefaultItem(list)
    local title = GUI:Text_Create(item, "title", 10, 10, 14, "#FFFFFF", mail.title)
    local date = GUI:Text_Create(item, "date", 260, 12, 11, "#AAAAAA", mail.date)
end

direction 定滚动方向：竖向列表是主流，横向列表用于道具轮播。pushBackDefaultItem 按列表的默认条目模板推入条目，条目内部的控件在推入后动态创建并绑定数据。列表的滚动事件（addOnScrollEvent）支撑滚动加载：滚到底部自动拉取下一页，分页数据的懒加载在滚动事件里触发。

列表的操作

-- 定位到列表顶部与刷新
GUI:ListView_scrollToTop(list)
GUI:ListView_removeAllItems(list)
-- 重建数据
for _, mail in ipairs(newMailData) do
    GUI:ListView_pushBackDefaultItem(list)
end

邮件已读后的列表刷新用 removeAllItems 加全量重建的简单方案，条目数量可控时全量重建比增量维护更不容易出错。滚动到顶、滚动到百分比、按索引跳转条目（jumpToItem）的操作接口让列表可以程序化导航：新邮件到达时跳到顶部，领取奖励后定位到下一封未读。列表的弹性（setBounceEnabled）与裁剪（setClippingEnabled）的开关影响滚动的手感与内容的边界。

验证与监控

列表的条目数量与滚动帧率的监控，千条列表的流畅滚动需要虚拟化方案而不是无脑全量创建。

踩坑记录

列表条目的高度不一致曾经让滚动定位计算错乱，条目高度的统一或使用变长感知的接口是两种解法。列表内嵌套列表的滚动冲突（滚内层带动外层）在邮件附件的横滑列表出现过，嵌套滚动的触摸吞 Billy 配置是解法。

上线要点

列表的条目模板在布局编辑器里做好，pushBackDefaultItem 复用模板比手工创建条目高效且一致。列表数据的增量更新（新邮件插入顶部）与全量重建的取舍按条目量级决策。滚动位置的保存与恢复：切页回来还在原来的滚动位置，交互的记忆感是细节品质。

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