# 列表 List

## 介绍

列表，顾名思义，即是一个包含了多个元素的值的集合与容器。除此以外，如果您有其他编程语言的开发经验，您可以将列表理解成类似于数组的类型结构。

{% hint style="info" %}
注意：列表中的元素可以是任何类型的值！
{% endhint %}

列表具有如下特性：

* 列表中的元素是**有顺序**的，按照插入的顺序进行排列
* 列表中的元素通过**下标**进行访问

{% hint style="info" %}
下标：即元素在列表中的次序，但由于编程开发的历史原因，下标通常从 0 开始，即第一个元素的下标是 0，最后一个元素的下标是列表的长度减去1，即`list.length - 1`&#x20;
{% endhint %}

## 何时使用列表？

当你的物品中，存在以下需求时，可以考虑使用列表：

* 需要结构化存储大量数据
* 需要一个容器用来存储许多数据
* 需要使用到列表自展开功能，即自动展示多行lore时

## 示例

### 定义一个列表

您可以通过`[]`字面量语法来声明一个列表，并且列表中可以直接设置好其他元素，例如 `[1, 2, 3]`，即包含了三个数字元素的列表。

具体示例如下：

```yaml
data:
  # 定义了一个含有三个数字的列表
  number_list: '[1, 2, 3]'
  # 定义了一个含有三个字符串的列表
  string_list: '["1", "2", "3"]'
  # 定义了一个含有混合类型的元素的列表
  mixed_list: '[1, 2, "这是字符串值的3", 4, "这是字符串值的5"]'
  # 定义了一个含有多个列表元素的的嵌套列表, 支持无限嵌套
  nested_list: '[
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
  ]'
```

### 访问列表中的元素

您可以通过 `list[idx]` 来访问列表中的元素，其中，`list` 是已经定义好的列表，`idx` 是待访问的元素的下标。

具体示例如下：

```yaml
define:
  # 预先定义一个普通的数字列表, 方便后面演示使用
  my_list: '[1, 2, 3, 4, 5]'
  # 预先定义一个嵌套, 方便后面演示使用
  my_nested_list: '[
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
  ]'

data:
  # 访问列表中的第一个元素
  my_first_elem: 'my_list[0]'
  # 访问列表中的最后一个元素
  my_last_elem: 'my_list[my_list.length - 1]'
  # 访问嵌套列表中的第一个列表的第一个元素
  my_nested_first_elem: 'my_nested_list[0][0]'
  # 访问嵌套列表中的最后一个列表的最后一个元素
  my_nested_last_elem: 'my_nested_list[my_list.length - 1][my_nested_list[my_list.length - 1].length - 1]'
  # 👆上面的访问方式太长了, 下面是优化后的写法
  # 1. 首先获取嵌套列表的最后一个元素, 也是一个列表
  my_nested_last_list: 'my_nested_list[my_list.length - 1]'
  # 2. 访问这个元素的最后一个元素
  my_nested_last_elem: 'my_nested_last_list[my_nested_last_list.length - 1]'
```

### 追加一个元素

您可以通过 `list.push(elem)` 来追加一个元素，其中，`list` 是已经定义好的列表，`elem` 是待追加的元素。

具体示例如下：

```yaml
data:
  # 预先定义一个普通的数字列表, 方便后面演示使用
  my_list: '[]'

action:
  onKill:
    # 在每次击杀一个生物时, 往列表中插入一个数字1
    - 'run: my_list.push(1)'
    # 更新物品
    - 'update'
```
