生成器面板
查阅数据来源、输出模板、筛选、排序与自动分页。
每条元素数据生成一个 output 图标；icons 放固定导航和装饰。固定图标占用的位置之外，按从左到右、从上到下的顺序放置生成项，超出一页容量时自动分页。
十条目录、每页九格的完整操作见列表分页教程，下载仍为 catalog-demo.yml。预先写好的分类页则使用 pages。
面板字段
以下字段写在 panels 中包含 generator 的那一项：
| 字段 | 类型 | 必填 | 省略行为 | 说明 |
|---|---|---|---|---|
layout | 文字列表 | 否 | 不使用字符布局 | 与固定图标一起决定固定位置；没有图标占用的字符格也属于生成区域 |
scale | 两项整数列表 | 否 | 优先使用 layout 尺寸；都未指定时宽 9，顶层高度采用窗口行数 | 面板宽度、高度 |
locate | 两项整数列表 | 否 | 在父容器中自动寻找未占用起点 | 面板相对于父容器的位置 |
icons（icon、item、items） | 图标映射 | 否 | 无固定图标，整个区域可用于生成项 | 固定导航和装饰；位置可来自布局或 slot |
generator | 生成器设置对象 | 是 | 不选择生成器面板 | 字段见下表 |
至少留一个未被固定图标占用的有效格子。一个固定图标占多个格子时，这些格子都不用于输出；仅把图标改成空气不会释放它占用的位置。
生成器字段
字段写在面板的 generator 内，不写在 output 图标内。
| 字段 | 类型 | 必填 | 省略行为 | 说明 |
|---|---|---|---|---|
source | 文字 | 否 | custom | 已注册的数据来源名称，内置来源见下文；不存在的来源不能生成列表 |
elements | 元素对象列表 | 否 | 不追加自定义条目 | custom 的内容；对其他来源则追加在来源条目之后，之后再参与筛选、排序 |
output（template） | 图标对象 | 是 | 没有输出模板，无法加载 | 每条元素的外观、子状态与点击动作；未设 id 时使用 output |
filter | 条件语句文字 | 否 | 保留所有元素 | 保留条件为真的条目；使用可立即得到结果的条件 |
sortBy | 文字 | 否 | 保留来源和追加条目的原始顺序 | 按元素原始字段名的文字值升序排序，区分大小写，不是按数字大小排序 |
extension | 文字键值映射 | 否 | 不添加扩展字段 | 不能执行动态计算：值会成为带 ext@ 前缀的文字，详见扩展限制 |
data | 文字键值映射 | 否 | 不传额外来源参数 | 只对支持这些参数的扩展来源有用；不自动变成元素字段 |
elements 的各字段使用文字、数字或布尔值，不支持嵌套对象与列表；它们最终按文字读取。字段名 title 在输出图标中对应 element_title，例如 {{&element_title}}。sortBy: title 使用原字段名，不能写 element_title。
output 支持图标字段和物品属性。生成位置由面板分配，不需要在输出模板上设置 slot；子状态或动画帧也不要再修改生成项的位置。
内置来源
表中列出原始字段名；输出时均加 element_ 前缀。来源是打开菜单时取得的一份列表，不会因玩家上线、移动或世界变化自动重取。
source | 内容 | 元素字段 |
|---|---|---|
custom | 仅使用 elements | 自行定义 |
player | 在线玩家 | name、uuid、displayName、isSneaking、isSprinting、x、y、z、yaw、pitch，有地址时包含 address |
menus | 已加载菜单 | id、type、rows、virtual、panels |
world | 已加载世界 | name、uid、environment、seed、allowAnimals、allowMonsters、difficulty、time；服务端支持时包含 minHeight、maxHeight |
sound | 声音目录 | name、ordinal |
entity_world | 玩家当前世界内的实体 | name、type |
entity_nearby | 玩家附近的实体，三个轴各延伸十格 | name、type |
player 在非 Folia 环境还提供 instance，但它不是适合直接显示的文字字段，在 Folia 环境不提供；显示玩家名称或头像使用 name。menus.type 是菜单容器类型名称，panels 是顶层配置面板数。
例如把某个生成器的 generator 替换为下面片段，可显示在线玩家头像：
generator:
source: player
sortBy: name
output:
head: '{{&element_name}}'
name: '&f{{&element_name}}'需要重新取得在线名单或实体名单时，重新打开菜单。内置来源没有通过 data 开放通用查询参数；entity_nearby 的范围也不能通过 data 改变。
筛选与重新排列
以下片段写入目录示例的 generator 内；未设置 keyword 时显示全部，设置后按标题包含关系筛选：
filter: 'any [ ctx without keyword check &element_title has &keyword ]'操作原有目录的一个按钮时，可将动作改为：
action: |-
ctx set keyword to '说明'
regenerate
icon by '<' refresh
icon by '>' refresh清除筛选使用 ctx del keyword 后再次执行相同刷新。带输入框、取消和清除动作的完整菜单见搜索列表。
regenerate 可以临时传入筛选和排序：
regenerate filter 'check &element_title has 说明' sort titlefilter省略时继续采用配置中的筛选条件；如果之前只用参数传入过一次筛选，它不会因此变成新的配置默认值。sort省略时保留当前排序；指定后按该原始字段的文字值升序排序。- 重新筛选会回到索引
0；同一玩家两次regenerate至少间隔500毫秒，过快调用不会执行。 - 它重新处理本次打开时取得的数据，不会重新请求
source。
多个生成器的限制
同一级存在多个生成器时，regenerate 会优先操作其中第一个，不能只靠 panel select 可靠地改成第二个；不传 filter 时采用的默认条件也可能来自菜单内另一生成器。不要把它写成任意多列表的独立刷新指令。
多个列表需要统一重新应用各自已有的筛选时，可使用 icons refresh，但所有受影响的生成器都会回到第一页，且固定导航仍需单独同步。需要重新取得各自的数据来源则重新打开菜单。
列表与图标刷新
| 操作 | 列表与页号 | 固定导航的状态 |
|---|---|---|
page next、page previous、page set to N | 切换页，不重新取得来源 | 不自动重新判断子状态 |
icon by '>' refresh | 不改变列表和当前页 | 重新选择并更新指定图标 |
icons update | 更新当前已有图标外观，保留当前页 | 重新计算名称、Lore 等，不重新选择 sub |
icons relocate | 重新选择当前已有图标子状态，保留当前页 | 状态条件改变时重新选择 |
regenerate | 重新筛选、排序现有数据，回到第一页 | 需要单独刷新 |
icons refresh | 重建生成器输出，回到第一页，不重取来源 | 不会顺带重新选择固定导航的子状态 |
icons 是整个菜单的批量操作，不因 panel select 限制为一个区域；固定 pages 中只处理当前有效页。要保留列表当前页并同步按钮状态，依次执行 icons relocate、icons update，或逐个使用 icon by ID refresh。目录示例采用后者。
筛选后没有条目时，生成区域为空，page get 和 page max 仍为 0；两个导航条件都不满足可翻页状态，不能把“1 / 1 页”当成存在一条数据。
固定页、生成器都使用 page 语句，完整页号、别名和目标选择见分页操作参考。
扩展限制
extension 不是可以执行表达式的字段。比如为 description 配置一段脚本，不会得到脚本结果，而是带 ext@ 前缀的文字；同名键还会覆盖原条目属性。不要用它计算价格、状态或动态说明。
固定内容直接放在 elements 每一项内：
elements:
- title: '服务器规则'
description: '查看公共规则与游戏约定'
output:
material: BOOK
name: '&f{{&element_title}}'
lore:
- '&7{{&element_description}}'动态显示写在 output.name、output.lore 等支持内联语句的外观字段中，按需用 update 更新；data 仍只是传给来源的参数，不会自动转为 element_ 字段。
Last updated on