类型 函数 库 widget.* 返回值 TableViewWidget 修订 版本 2024.3703 关键词 widget, tableview, 列表, listview 另请参阅 TableViewWidget
创建一个 TableViewWidget 对象。
TableViewWidget 对象包含一个遮罩，该遮罩将其视图限制在定义的宽度和高度内。嵌套遮罩限制为 3，因此在将遮罩对象插入到作为容器的其他遮罩对象（包括 display.newContainer、widget.newScrollView、widget.newTableView 或遮罩的 display group）时必须小心。其他使用遮罩的显示对象包括 display.newText、display.newEmbossedText 和任何其他 遮罩的 显示对象。例如，一个文本对象（一个遮罩）在一个容器（一个遮罩）内，而该容器又在另一个容器（一个遮罩）内，将达到但不超过 3 个嵌套遮罩的限制。
TableViewWidget 对象不支持 缩放。
widget.newTableView( options )
此函数接受一个参数 options，它是一个包含以下参数的表
字符串。要分配给表格视图的可选标识字符串。默认为 widget_tableView。
数字。控件的 **x** 和 **y** 中心点的坐标。如果定义了 left 和 top 值，则这些值将被覆盖。
数字。将在其中创建控件的左侧和顶部位置。如果指定，则这些值将覆盖 x 和 y 参数。
数字。表格视图的宽度和高度。
数字。确定向上或向下轻弹内容时的移动速度。默认值为 0.972。
数字。限制表格视图的最大滚动速度。默认值为 2。
布尔值。如果设置为 true，则表格视图将被锁定，这意味着它无法垂直滚动。
布尔值。如果设置为 false，则表格视图在到达上限或下限时将停止滚动。默认为 true。
数字。指定传播行触摸事件之前的延迟（以毫秒为单位）。默认为 110 毫秒。
侦听器。用于侦听 TableViewWidget 行渲染事件的函数。此函数在通过 object:insertRow() 添加行时、所有可见行event.row 是对已渲染行的引用。
侦听器。用于侦听 TableViewWidget 触摸/点击事件的函数。在此侦听器函数中，event.phase 值包括 "tap"、"press"、"release"、"swipeLeft" 和 "swipeRight"。此外，event.target 是对与之交互的行的引用，event.target.index 是该行的索引号。
侦听器。用于侦听 TableViewWidget 触摸/滚动事件的函数。在此侦听器函数中，event.phase 返回预期的触摸交互阶段 "began"、"moved" 或 "ended"。此外，当表格视图轻弹/滑动动量自然停止时，可以检测到 "stopped" 阶段。最后，可以通过 event.limitReached 检测到任一方向的滚动限制。如果发生这种情况，event.direction 将根据表格视图到达限制时的移动方向返回 "up" 或 "down"。
可以使用 options 表中的以下参数自定义表格视图控件的视觉效果
布尔值。如果设置为 true，则线条不会分隔各个行。默认值为 false。
表格。包含 RGB+A 背景颜色设置的表格。默认为白色。
backgroundColor = { 0.8, 0.8, 0.8 }
布尔值。如果为 true，则表格视图的背景将被隐藏，但它仍然可以接收触摸。
布尔值。如果设置为 true，则表格视图将不会显示滚动条。
表。包含自定义滚动条的 图像 表单 规格的表。自定义滚动条需要图像表单中的 3 帧。每帧都需要是大小相等的正方形。在 scrollBarOptions 表中，必须指定 4 个必需参数：sheet、topFrame、middleFrame 和 bottomFrame。
scrollBarOptions = {
sheet = scrollBarSheet, -- Reference to the image sheet
topFrame = 1, -- Number of the "top" frame
middleFrame = 2, -- Number of the "middle" frame
bottomFrame = 3 -- Number of the "bottom" frame
}
数字。这些数字表示内容到达相应限制时将停止的表格视图顶部和底部到像素的距离。两者的默认值均为 0。
创建表格视图时，它只是创建一个指定宽度和高度的空白区域。实际行是通过 object:insertRow() 函数“渲染”的。
要完成此操作，需要进行一些基本设置。首先，编写一个目标侦听器函数来渲染新行，例如
local function onRowRender( event )
-- Get reference to the row group
local row = event.row
-- Cache the row "contentWidth" and "contentHeight" because the row bounds can change as children objects are added
local rowHeight = row.contentHeight
local rowWidth = row.contentWidth
local rowTitle = display.newText( row, "Row " .. row.index, 0, 0, nil, 14 )
rowTitle:setFillColor( 0 )
-- Align the label left and vertically centered
rowTitle.anchorX = 0
rowTitle.x = 0
rowTitle.y = rowHeight * 0.5
end
接下来，在表格视图声明的 onRowRender 参数中指定该函数。此时，可以调用 object:insertRow() 插入新行，或者在循环中执行该调用以一次渲染多行。请参考下面的用法示例。
local widget = require( "widget" )
-- The "onRowRender" function may go here (see example under "Inserting Rows", above)
-- Create the widget
local tableView = widget.newTableView(
{
left = 200,
top = 200,
height = 330,
width = 300,
onRowRender = onRowRender,
onRowTouch = onRowTouch,
listener = scrollListener
}
)
-- Insert 40 rows
for i = 1, 40 do
-- Insert a row into the tableView
tableView:insertRow{}
end
local widget = require( "widget" )
-- The "onRowRender" function may go here (see example under "Inserting Rows", above)
-- Create the widget
local tableView = widget.newTableView(
{
left = 200,
top = 200,
height = 330,
width = 300,
onRowRender = onRowRender,
onRowTouch = onRowTouch,
listener = scrollListener
}
)
-- Insert 40 rows
for i = 1, 40 do
local isCategory = false
local rowHeight = 36
local rowColor = { default={1,1,1}, over={1,0.5,0,0.2} }
local lineColor = { 0.5, 0.5, 0.5 }
-- Make some rows categories
if ( i == 1 or i == 21 ) then
isCategory = true
rowHeight = 40
rowColor = { default={0.8,0.8,0.8,0.8} }
lineColor = { 1, 0, 0 }
end
-- Insert a row into the tableView
tableView:insertRow(
{
isCategory = isCategory,
rowHeight = rowHeight,
rowColor = rowColor,
lineColor = lineColor
}
)
end
local widget = require( "widget" )
-- The "onRowRender" function may go here (see example under "Inserting Rows", above)
-- Create image sheet for custom scroll bar
local scrollBarOpt = {
width = 20,
height = 20,
numFrames = 3,
sheetContentWidth = 20,
sheetContentHeight = 60
}
local scrollBarSheet = graphics.newImageSheet( "scrollBar.png", scrollBarOpt )
-- Create the widget
local tableView = widget.newTableView(
{
left = 200,
top = 200,
height = 330,
width = 300,
onRowRender = onRowRender,
onRowTouch = onRowTouch,
listener = scrollListener,
scrollBarOptions = {
sheet = scrollBarSheet,
topFrame = 1,
middleFrame = 2,
bottomFrame = 3
}
}
)
-- Insert 40 rows
for i = 1, 40 do
-- Insert a row into the tableView
tableView:insertRow(
{
isCategory = false,
rowHeight = 36,
rowColor = { default={1,1,1}, over={1,0.5,0,0.2} },
lineColor = { 0.5, 0.5, 0.5 }
}
)
end