详细讲解列表容器的创建跟使用
🤖 回答引擎: 前端Lua |
🕒 时间: 2026-05-23 14:11:35 |
👁️ 阅读: 1
根据浮生梦老师前端课程内容，列表容器是游戏UI开发中非常重要的组件，用于展示大量数据项。以下是详细讲解：
## 一、列表容器创建
### 1. ListView创建（垂直/水平列表）
```lua
-- 创建父窗口
local parent = GUI:Win_Create("ListParent", 0, 0, 0, 0, false, false, true, false, false, false, 1)
-- 创建垂直列表容器
local listView = GUI:ListView_Create(
parent, -- 父节点对象
"list_view", -- 唯一ID
100, -- 位置X
100, -- 位置Y
300, -- 容器宽度
400, -- 容器高度
1, -- 方向：1垂直，2水平
100, -- 单个cell宽度
50, -- 单个cell高度
10 -- 需创建cell个数（初始数量）
)
-- 创建水平列表容器示例
local horizontalList = GUI:ListView_Create(
parent,
"horizontal_list",
100,
200,
400,
100,
2, -- 方向：2水平
80,
80,
5
)
```
### 2. TableView创建（更灵活的列表）
```lua
-- 创建TableView
local tableView = GUI:TableView_Create(
parent, -- 父节点对象
"table_view", -- 唯一ID
100, -- 位置X
300, -- 位置Y
300, -- 容器宽度
200, -- 容器高度
1 -- 方向：1垂直，2水平
)
```
## 二、列表容器基本设置
### 1. 背景设置
```lua
-- 设置背景图片
GUI:ListView_setBackGroundImage(listView, "res/public/1900000610.png")
-- 设置背景九宫格（防止拉伸变形）
GUI:ListView_setBackGroundImageScale9Slice(listView, 10, 10, 10, 10)
-- 设置背景颜色
GUI:ListView_setBackGroundColorType(listView, 1) -- 1：单色
GUI:ListView_setBackGroundColor(listView, "#ff0000") -- 红色背景
GUI:ListView_setBackGroundColorOpacity(listView, 150) -- 透明度150
-- 移除背景图片
GUI:ListView_removeBackGroundImage(listView)
```
### 2. 滚动设置
```lua
-- 设置滚动事件
GUI:ListView_addOnScrollEvent(listView, function()
SL:Print("列表正在滚动")
end)
-- 滚动到指定百分比位置
GUI:ListView_scrollToPercentVertical(listView, 50, 1.0, true) -- 垂直方向50%位置
GUI:ListView_scrollToPercentHorizontal(listView, 30, 0.5, false) -- 水平方向30%位置
-- 滚动到顶部/底部
GUI:ListView_scrollToTop(listView, 1.0, true) -- 1秒内滚动到顶部
GUI:ListView_scrollToBottom(listView, 1.0, true) -- 1秒内滚动到底部
-- 添加鼠标滚轮支持
GUI:ListView_addMouseScrollPercent(listView)
```
## 三、列表项管理
### 1. 添加列表项
```lua
-- 创建列表项
local function createListItem(index)
local item = GUI:Layout_Create(nil, "item_"..index, 0, 0, 100, 50)
-- 添加背景
local bg = GUI:Image_Create(item, "bg", 0, 0, "res/public/1900000612.png")
GUI:Widget_setSize(bg, 100, 50)
-- 添加文字
local text = GUI:Text_Create(item, "text", 10, 10, 16, "#ffffff", "项目"..index)
return item
end
-- 添加列表项到末尾
for i = 1, 5 do
local item = createListItem(i)
GUI:ListView_pushBackCustomItem(listView, item)
end
-- 插入到指定位置
local newItem = createListItem(99)
GUI:ListView_insertCustomItem(listView, newItem, 2) -- 插入到第2个位置
```
### 2. 删除列表项
```lua
-- 删除指定索引的项
GUI:ListView_removeItemByIndex(listView, 3) -- 删除第3项
-- 删除指定对象
local itemToRemove = GUI:getChildByName(listView, "item_2")
if itemToRemove and not GUI:Win_IsNull(itemToRemove) then
GUI:ListView_removeChild(listView, itemToRemove)
end
-- 删除所有项
GUI:ListView_removeAllItems(listView)
```
### 3. TableView动态项管理
```lua
-- 设置cell总数（动态数据）
GUI:TableView_setTableViewCellsNumHandler(tableView, function()
return 20 -- 总共20个cell
end)
-- 设置cell创建函数
GUI:TableView_setCellCreateEvent(tableView, function(parentCell, cellIndex)
-- 清除旧内容
local children = GUI:getChildren(parentCell)
for _, child in ipairs(children) do
GUI:removeFromParent(child)
end
-- 创建新内容
local bg = GUI:Image_Create(parentCell, "cell_bg", 0, 0, "res/public/1900000612.png")
GUI:Widget_setSize(bg, 100, 50)
local text = GUI:Text_Create(parentCell, "cell_text", 10, 10, 16, "#ffffff", "Cell "..cellIndex)
-- 添加点击事件
GUI:addOnClickEvent(parentCell, function()
SL:Print("点击了Cell "..cellIndex)
end)
end)
-- 添加cell点击事件
GUI:TableView_addOnTouchedCellEvent(tableView, function(cellIndex)
SL:Print("TableView点击了第"..cellIndex.."个cell")
end)
```
## 四、列表容器操作
### 1. 滚动控制
```lua
-- 跳转到指定项
GUI:ListView_jumpToItem(listView, 5) -- 跳转到第5项
-- TableView滚动到指定cell
GUI:TableView_scrollToCell(tableView, 8)
-- 设置内容偏移
GUI:TableView_setContentOffset(tableView, 0, 50) -- Y轴偏移50像素
```
### 2. 刷新与布局
```lua
-- 刷新布局
GUI:ListView_doLayout(listView)
-- 强制绘制可见区域
GUI:ListView_paintItems(listView)
-- 自动绘制可见区域
GUI:ListView_autoPaintItems(listView)
```
### 3. 滚动容器大小设置
```lua
-- 设置滚动范围大小
GUI:ScrollView_setInnerContainerSize(listView, 500, 800) -- 设置内部容器大小
```
## 五、使用技巧
### 1. 性能优化
```lua
-- 大量数据时使用TableView（虚拟列表）
local tableView = GUI:TableView_Create(parent, "big_list", 0, 0, 300, 400, 1)
-- 设置cell数量（只创建可见区域的cell）
GUI:TableView_setTableViewCellsNumHandler(tableView, function()
return 1000 -- 1000条数据，但只渲染可见的几条
end)
```
### 2. 事件处理
```lua
-- 列表项点击事件
local function onItemClick(item)
local itemName = GUI:getWidgetName(item)
SL:Print("点击了：" .. itemName)
-- 获取点击位置
local pos = GUI:getPosition(item)
SL:Print("位置：x=" .. pos.x .. ", y=" .. pos.y)
end
-- 为每个列表项添加点击事件
for i = 1, GUI:ListView_getItemsCount(listView) do
local item = GUI:ListView_getItem(listView, i)
if item and not GUI:Win_IsNull(item) then
GUI:addOnClickEvent(item, function()
onItemClick(item)
end)
end
end
```
### 3. 动态更新
```lua
-- 定时刷新列表
SL:Schedule(function()
-- 清除旧数据
GUI:ListView_removeAllItems(listView)
-- 添加新数据
for i = 1, 10 do
local item = createListItem(i)
GUI:ListView_pushBackCustomItem(listView, item)
end
-- 刷新布局
GUI:ListView_doLayout(listView)
end, 5) -- 每5秒刷新一次
```
## 六、常见应用场景
1. **背包列表**：使用TableView展示物品，支持大量物品的滚动查看
2. **聊天记录**：使用ListView展示聊天消息，支持向上滚动查看历史
3. **排行榜**：使用垂直列表展示排名信息
4. **技能栏**：使用水平列表展示技能图标
5. **任务列表**：使用列表展示任务信息，支持点击查看详情
记住：ListView适合固定数量的简单列表，TableView适合大量数据的虚拟列表。根据实际需求选择合适的组件，能有效提升游戏性能和用户体验。
← 返回问答库