列表属性（PropertyList）

PropertyList 是一个可变的 ViewModel 项列表。

用它来管理脚本中的重复数据集合（例如菜单项、库存条目或动态 UI 行）。PropertyList 支持：

通过 length 读取项数
基于 1 的索引访问（list[1]、list[2]……）
变更操作（push、insert、swap、pop、shift、clear）
通过 addListener 和 removeListener 发送变更通知

有关完整的工作示例，请参阅 Scripting Lists 演示。

字段（Fields）

`length`

列表中当前项的数量。

function handleSwap(self: MenuListController)
  if self.menu and self.menu.length >= 2 then
    self.menu:swap(1, 2)
  end
end

`addListener`

添加一个在列表发生变化时调用的监听器。

function init(self: MenuListController, context: Context): boolean
  local vmi = context:rootViewModel() :: Data.Main
  if vmi then
    self.menu = vmi.menu
    self.listChanged = listChanged

    self.menu:addListener(self.listChanged)
  else
    print('[MenuListController] Warning: Could not find Main ViewModel.')
  end

  return true
end

`removeListener`

移除之前添加的列表变更监听器。

function handleRemoveListener(self: MenuListController)
  if self.menu and self.listChanged then
    self.menu:removeListener(self.listChanged)
  end
end

方法（Methods）

`push`

push(vm: ViewModel) -> ()

在列表末尾添加一个视图模型。

function addButton(menu: PropertyList, label: string)
  local buttonVm = Data.Button.new()

    local buttonLabel = buttonVm:getString('label')
    if buttonLabel then
      buttonLabel.value = label
    end

    menu:push(buttonVm)
end

获取列表项索引：

function setItemLabel(menu: PropertyList, index: number, label: string)
  if index >= 1 and index <= menu.length then
    local item = menu[index] :: Data.Button
    local itemLabel = item:getString('label')
    if itemLabel then
      itemLabel.value = label
    end
  end
end

`insert`

insert(vm: ViewModel, index: number) -> ()

在指定索引处插入一个视图模型。

function insertAt(menu: PropertyList, label: string, index: number)
  local buttonVm = Data.Button.new()

  local buttonLabel = buttonVm:getString('label')
  if buttonLabel then
    buttonLabel.value = label
  end

  local insertIndex = math.max(1, math.min(index, menu.length + 1))
  menu:insert(buttonVm, insertIndex)
end

`swap`

swap(index1: number, index2: number) -> ()

交换 index1 和 index2 上视图模型的位置。

function swapItems(menu: PropertyList, index1: number, index2: number)
  local highestIndex = math.max(index1, index2)

  if menu and menu.length >= highestIndex then
    menu:swap(index1, index2)
  end
end

`pop`

pop() -> ViewModel?

移除并返回列表中的最后一个视图模型。

function handlePop(self: MenuListController)
  if self.menu then
    self.menu:pop()
  end
end

`shift`

shift() -> ViewModel?

移除并返回列表中的第一个视图模型。

function handleShift(self: MenuListController)
  if self.menu then
    self.menu:shift()
  end
end

`clear`

clear() -> ()

移除列表中的所有视图模型。

function handleClearItems(self: MenuListController)
  if self.menu then
    self.menu:clear()
  end
end

`remove`

remove(viewModel: ViewModel) -> ()

从列表中移除一个视图模型。

`removeAllOf`

removeAllOf(viewModel: ViewModel) -> ()

移除所有引用该视图模型实例的列表项。

`removeAt`

removeAt(index: number) -> ()

从列表中移除指定 1 起始索引处的视图模型。

字段（Fields）​

length​

addListener​

removeListener​

方法（Methods）​

push​

insert​

swap​

pop​

shift​

clear​

remove​

removeAllOf​

removeAt​