工坊手册

主题

EUIListView ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）
    • EUINodeBase（35 属性 / 12 函数 / 4 事件）
      • [EUIListView]（8 属性 / 3 函数）

继承成员 ​

2 个来源 / 39 属性 / 36 函数 / 10 事件

EUIListView 是一种可滚动列表容器，用于把界面子节点按指定方向组织成可滑动的列表区域。它提供背景图片、背景透明度、列表边距、裁切、回弹与滑动开关等属性，并通过 ScrollToPercent、ScrollToItem 与 GetScrollPercent 控制或读取滚动位置。

适用场景 ​

适用于需要在玩家界面上展示条数较多、超出可视范围的条目集合时，例如背包或商店面板：创建一个列表容器挂到界面根节点下，再把子项依次加入并滚动到目标条目。

使用要点 ​

先通过 game:GetService("World"):CreateUnit("EUIListView", { Parent = parent, Position = ..., Size = ... }) 创建实例，并把 Parent 设为当前玩家 PlayerGui.EuiManager:GetRootNode()；随后按需设置 ScrollDirection、ListviewGravity、ItemsMargin、ClippingEnabled、BounceEnabled 与 ScrollEnabled 等属性；挂入子项后可调用 ScrollToItem(itemIndex, time) 或 ScrollToPercent(percent, time, attenuated) 滚动到目标位置，并用 GetScrollPercent() 读取当前滚动百分比。

注意事项 ​

EUIListView 是可滚动列表容器，通过 World:CreateUnit 创建，并把 Parent 设置为当前玩家 PlayerGui.EuiManager:GetRootNode()。BackgroundImage 使用有效图片资源 URI，例如 official://image/10000；设置滚动、回弹和裁切后，将子节点加入列表容器。ScrollToPercent 的 percent 取 0~100；ScrollToItem 的 itemIndex 从 0 开始，且目标索引必须对应已有子项。

代码示例 ​

创建列表视图并设置背景资源 ​

lua
-- @runtime client
local Players = game:GetService("Players")
local World = game:GetService("World")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local rootNode = localPlayer.PlayerGui.EuiManager:GetRootNode()
local listView = World:CreateUnit("EUIListView", {
    Parent = rootNode,
    Position = Vector2.New(0, 0),
    Size = Vector2.New(100, 40),
})
listView.BackgroundImage = "official://image/10000"
listView.ScrollDirection = Enums.EUIScrollDirection.Vertical
listView.BounceEnabled = true
listView.ClippingEnabled = true
local item = World:CreateUnit("EUIImage", {
    Parent = listView,
    Position = Vector2.New(0, 0),
    Size = Vector2.New(100, 40),
})
item.Image = 'official://image/10066'

属性 (8) ​

Name类型默认值说明
BackgroundOpacityFloat1.0EUIListView 的背景透明度属性，类型为 Float，默认值为 1.0。它用于控制列表控件背景的不透明程度。
BackgroundImageString""EUIListView 的背景图片属性，类型为 String，默认值为空字符串。它用于指定列表控件整体显示的背景图资源。
ClippingEnabledBooltrueEUIListView 的开启裁切属性，类型为 Bool，默认值为 true。它控制列表内容是否按列表自身区域进行裁剪。
BounceEnabledBooltrueEUIListView 的开启反弹属性，类型为 Bool，默认值为 true。它控制列表在滑动到边界时是否产生反弹效果。
ItemsMarginInt0EUIListView 的列表边距属性，类型为 Int，默认值为 0。它用于设置列表项之间的间距。
ScrollDirectionEUIScrollDirectionEnums.EUIScrollDirection.Vertical列表滚动方向，类型为 EUIScrollDirection；默认值为 Enums.EUIScrollDirection.Vertical（纵向）。
ListviewGravityEUIListviewGravityEnums.EUIListviewGravity.LeftEUIListView 的对齐方式属性，类型为 EUIListviewGravity 枚举，默认值为 0。它决定列表项在列表内的对齐位置。
ScrollEnabledBooltrueEUIListView 的开启滑动属性，类型为 Bool，默认值为 true。它控制列表是否响应滑动操作。

关联类型 ​

函数 (3) ​

ScrollToPercent ​

签名：ScrollToPercent(percent: Float, time: Float, attenuated: Bool) -> void

EUIListView 的函数，用于按比例滚动列表内容。参数为 percent（Float，滚动比例）、time（Float，滚动过程的时间）与 attenuated（Bool，控制滚动过程是否带衰减）。

参数类型说明
percentFloat目标百分比(0~100)
timeFloat滚动时长(秒)
attenuatedBool是否衰减

返回值 void

示例代码

滚动到指定百分比位置

lua
-- @runtime client
local Players = game:GetService("Players")
local World = game:GetService("World")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local rootNode = localPlayer.PlayerGui.EuiManager:GetRootNode()
local listView = World:CreateUnit("EUIListView", {
    Parent = rootNode,
    Position = Vector2.New(0, 0),
    Size = Vector2.New(200, 300),
})

listView:ScrollToPercent(50, 0.3, true)

ScrollToItem ​

签名：ScrollToItem(itemIndex: Int, time: Float) -> void

EUIListView 的函数，用于将列表滚动到指定索引的列表项位置。参数为 itemIndex（Int，目标列表项的索引）与 time（Float，滚动过程的时间）。

参数类型说明
itemIndexInt子项索引(从0开始)
timeFloat滚动时长(秒)

返回值 void

示例代码

滚动到指定子项

lua
-- @runtime client
local Players = game:GetService("Players")
local World = game:GetService("World")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local rootNode = localPlayer.PlayerGui.EuiManager:GetRootNode()
local listView = World:CreateUnit("EUIListView", {
    Parent = rootNode,
    Position = Vector2.New(0, 0),
    Size = Vector2.New(200, 300),
})
World:CreateUnit("EUIImage", {
    Parent = listView,
    Size = Vector2.New(180, 48),
    Image = "official://image/10066",
})

-- itemIndex 从 0 开始；0 表示第一个子项
listView:ScrollToItem(0, 0.5)

GetScrollPercent ​

签名：GetScrollPercent() -> Float (当前滚动百分比(0~100))

GetScrollPercent 是 EUIListView（滚动列表节点）提供的读取接口，用于获取该列表当前所处的滚动百分比位置。函数无入参，返回一个 Float 浮点数，取值含义为当前滚动进度（0~100）。

返回值 Float (当前滚动百分比(0~100))

示例代码

调用 EUIListView:GetScrollPercent 的示例。

lua
-- @runtime client
local Players = game:GetService("Players")
local World = game:GetService("World")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local rootNode = localPlayer.PlayerGui.EuiManager:GetRootNode()
local euiListView = World:CreateUnit("EUIListView", { Parent = rootNode })
local result = euiListView:GetScrollPercent()  -- 返回 Float
if result ~= nil then
    print(result)
    if result ~= 0 then
        print("结果非零")
    end
end