iPlugin | 图标与子图标

图标定义写在面板的 icons 映射中，或生成器的 generator.output、滚动内容的 scroll.colums 中。它是展示与点击按钮，不等同于玩家可取走的真实物品。

写在普通面板的 icons 中

A:
  material: PAPER
  name: '&f说明'
  lore:
    - '&7点击查看消息'
  action: "mmsg '&a你好'"

图标字段

字段	类型	必填	省略行为	说明
`id`（`key`）	文字	否	固定图标使用 `icons` 映射键；生成器输出使用 `output`；滚动图标使用自动名称	用于布局匹配和单图标查找；子图标沿用父 ID，即使自身填写也不会独立命名
`display`	显示属性对象	否	收集直接写在图标下的显示字段	显式填写后，不再合并图标外层的显示简写；属性见物品属性
`action`（`actions`、`handler`、`click`）	动作、动作列表或点击分类对象	否	没有点击动作；子图标允许继承时可使用父动作	写法与点击类型见点击动作
`sub`（`icons`）	子图标列表或单个子图标对象	否	没有条件子状态	选择第一个条件满足的直接子图标；通常使用列表
`condition`（`if`、`rule`）	条件语句文字	否	子图标不满足选择条件	只用于选择子图标，写在根图标上不控制它的隐藏与显示
`inherit`	布尔值	否	子图标按 `true` 处理	是否补齐父图标的显示、帧列表、帧设置与动作；根图标填写没有继承对象
`update`	整数	否	`-1`，不自动更新	根图标的显示更新周期，单位 tick；正数启用，不重新判断子状态
`relocate`	整数	否	`-1`，不自动重选	根图标的子状态判断周期，单位 tick；正数启用，不是通用的槽位移动指令
`frames`	显示属性对象列表	否	无帧动画；子图标允许继承时沿用父列表	至少两帧才启动图标动画；详见动画配置
`framesProperties`（`frames-properties`、`frames-prop`、`prop`）	帧设置对象	否	默认停留 `20` tick、模式 `LOOP`；允许继承的子图标可沿用父设置	完整字段见帧设置

update、relocate 由根图标控制。只写在某个 sub 中不会为该状态启动独立的周期任务；把周期写在根图标上。首次周期检查在图标建立约 10 tick 后，之后才按所设周期运行；只有可见、有效的图标才执行自动显示更新和重选。

display 与简写

没有 display 时，可直接填写物品来源、名称、Lore、数量、损伤、模型、颜色、发光、附魔、标志、提示框、不可破坏、NBT、enhancedLore 与 slot，以及它们的已支持别名。color 虽能填写，但不执行物品染色，见物品染色限制。

一旦使用 display，把所有显示字段放入其中，不在外层另写 slot、name 等期待合并。action、sub、update、relocate、frames、帧设置仍与 display 同级。

A:
  display:
    material: PAPER
    slot: 4
    name: '&f说明'
  action: "mmsg '&a你好'"

玩家头颅或外部物品来源的便捷键（如 head、skull、ia）放在图标外层；显式 display 内用 texture 对象，不直接放这些便捷键。例如：

A:
  display:
    texture:
      head: 'Notch'
    name: '&f玩家头像'

图标第一次显示时需要能生成物品的来源；没有来源、没有可继承物品的根图标只会为空气。位置格式见布局与槽位。

条件子状态

下面是普通面板片段：在同一格切换灰色染料与黄绿色染料。enabled 尚未设置时为关闭状态。

states-demo.yml配置效果示意 · 非游戏截图

图示状态enabled 未设置

窗口槽位 4窗口坐标 4x0面板局部坐标 4x0字符 A

变量 enabled 改变后，重新选择子图标并更新显示。

普通面板的 layout 与 icons；可放入 panels 的一项

layout:
  - '    A    '
icons:
  A:
    material: GRAY_DYE
    name: '&7尚未开启'
    action: 'ctx set enabled to true icon refresh'
    sub:
      - if: 'ctx get enabled'
        material: LIME_DYE
        name: '&a已开启'
        action: 'ctx del enabled icon refresh'

图示为配置效果示意。按钮在该面板局部槽位 4；点击灰色按钮设置 enabled 并立即刷新为黄绿色，点击黄绿色按钮删除该值并恢复灰色。

选择规则：

按 sub 顺序判断直接子图标，使用第一个条件为真的状态。
没写条件的子图标不会自动成为兜底。需要固定兜底子状态时显式写 if: 'true'，放在列表最后。
没有条件满足时显示父图标，不会把它隐藏。
条件在初次生成图标和主动/周期重选时判断，不在每次点击前自动重判。需要点击时确认条件，把判断也写进动作中。
不支持通过多层嵌套 sub 建立递归状态树；需要多种状态时，将它们列为根图标的直接子项。

子图标继承

inherit 省略或为 true 时：

内容	继承方式
`display` 的各显示字段	只补齐子图标未填的字段，包括物品来源、名称、Lore、数量、损伤、两类模型、发光、附魔、标志、提示框、不可破坏、NBT、槽位和 `enhancedLore`；`color` 仍受不染色限制
`frames`	子图标整个字段未填时沿用父列表，不按帧逐项拼接
帧设置	子图标整个对象未填时沿用父对象；自己只写 `mode` 时，未填 `delay` 使用其自身默认 `20`，不继续从父对象补字段
`action`	整个动作未填时沿用父动作；一旦填写子动作，不与父图标的点击分类逐项合并
`condition`、`update`、`relocate`、嵌套 `sub`	不按显示字段继承；周期仍由根图标控制

inherit: false 取消这些补齐规则，但不会给子图标一个新 ID，也不等于“清除已有物品属性”。独立状态应自行写出需要的物品来源与外观。

状态变化并非重新创建按钮：若新状态或某个动画帧没有物品来源，可能继续修改当前物品；需要确定材质时明确填写 material 等来源。状态切换的槽位、动画进度和首次帧停留限制见动画配置。

单图标操作

语句	作用
`icon update`	重新计算当前显示帧的名称、Lore、数量等，不重选子状态，不重新应用槽位
`icon relocate`	重判子状态；只有选择变化才应用新状态的默认显示与动画
`icon refresh`	重选状态，再更新当前显示
`icon by 'A' refresh`	按有效 ID 查找一个图标并刷新
`icon at 4 update`	按目标面板的局部槽位找一个图标并更新
`icon item`	取得当前显示物品值，不会发给玩家，也不是取出存储物品

by 与 at 可同时出现，by 优先。省略二者时使用当前点击图标；显式 ID/槽位没找到时，也可能退回当前点击图标，而不是悄悄跳过。相同 ID 的多个生成项不能用一次 icon by 'output' 当作批量更新；使用 icons update。

按 ID 或槽位查找作用于当前选定/适用的面板。跨区域时先用 panel at N select，不要把窗口槽位交给 icon at。relocate 主要含义是重新选择状态；如果新状态显式配置 slot，也会应用它的位置，所以不能把它描述为“永远不影响槽位”。

icon index 与 icon sub_index 能被识别，但不能取得可用的数值子状态索引；不要把它们当作状态条件。需要记录开关时像上例一样使用 ctx 变量。

批量操作与生成器

语句	普通图标	生成器区域
`icons update`	更新显示，不改变选择	更新当前已有输出与固定图标，保留当前页
`icons relocate`	重选状态	重选当前已有输出与固定图标，保留当前页
`icons refresh`	重选后更新	重建生成输出并回到第一页；不会顺带重选固定图标的子状态，不重新取得数据来源

icons 遍历整个菜单当前有效区域，不受 panel select 限定；固定 pages 中只处理当前有效页。批量重选后再更新、同时保留列表页的写法是：

action: |-
  ctx set enabled to true
  icons relocate
  icons update

生成器的固定上一页/下一页按钮应在翻页或筛选动作后用 icon by ID refresh 同步，详见列表刷新。

周期与暂停

写在 icons 中的一个根图标

A:
  material: PAPER
  update: 20
  relocate: 20
  name: '&f状态：{{ctx get status}}'
  sub:
    - if: 'ctx get enabled'
      name: '&a已开启'

update 更新显示；relocate 重判状态，两者各自按 20 tick 检查。只更新显示不改变子状态；只重选而选择没变，也不会更新一直在变化的文字。

语句	作用
`icon pause_update`、`icon resume_update`	暂停、恢复已有的 `update` 周期
`icon pause_relocate`、`icon resume_relocate`	暂停、恢复已有的 `relocate` 周期
`icon pause_frames`、`icon resume_frames`	控制帧动画开关，但帧播放已停住后不能可靠恢复，见动画限制

这些操作也接受 icon by 'A' ...，批量可将 icon 改成 icons。恢复操作不会为原本没设置正数周期的图标新增周期；手动 icon update、icon refresh 不会因周期被暂停而禁用。

权限按钮

展示权限状态使用 sub，点击时再次判断权限使用 action 条件；完整文件及下载见权限按钮。它使用灰色染料与绿宝石，不是上面的 enabled 开关示例。

图标与子图标

图标字段Copy Anchor Link

display 与简写Copy Anchor Link

条件子状态Copy Anchor Link

子图标继承Copy Anchor Link

单图标操作Copy Anchor Link

批量操作与生成器Copy Anchor Link

周期与暂停Copy Anchor Link

权限按钮Copy Anchor Link

On this page