槽位注册表

persistent 持久槽会长期保存玩家物品，因此服务器必须先明确登记允许使用的槽位 ID。登记文件是服务端 plugins/ChaUI/slot.yml；页面、脚本和其他插件只能访问这里已经注册的持久槽。

临时槽 temporary 和背包映射槽 mapped 不写进这个文件。slot.yml 也不保存玩家物品，它只说明“哪些持久槽可以访问，以及允许放入什么物品”。

一份可以直接使用的完整配置

yaml

slots:
  # 只接受名称包含“宝石”，并且 Lore 没有“已损坏”这一整行的非空气物品
  - id: 宝石槽_1
    acceptWhen: |
      item.id != "minecraft:air" &&
      item.name.contains("宝石") &&
      !item.lore.contains("已损坏")
    rejectMessage: "这里只能放入未损坏的宝石"

  # 不写 acceptWhen，表示允许任意物品
  - id: unrestricted_slot

保存后执行 /chaui reload。重载成功后，页面可以把 itemSlot.mode 设为 persistent，并把 itemSlot.bind 设为 宝石槽_1 或 unrestricted_slot。

没有图形编辑器

当前版本不提供 slot.yml 图形编辑器。请使用能以 UTF-8 保存文本的编辑器修改文件，再执行 /chaui reload。

配置字段

配置项	必填	限制	说明
`slots`	是	最多 `1024` 项	持久槽注册列表；没有槽位时写 `slots: []`。
`slots[].id`	是	最多 `64` 个 Unicode 码点；允许 Unicode 字母、数字（包括中文）以及 `_`、`-`	全局唯一的槽位识别 ID。空白、重复、点号、斜杠和控制字符会让重载失败。
`slots[].acceptWhen`	否	最多 `512` 个字符	只读物品条件；省略或留空时允许任意物品。
`slots[].rejectMessage`	否	单行文本，最多 `256` 个 Unicode 码点	`acceptWhen` 拒绝放入或交换时显示给玩家；省略或留空时不显示额外消息。控制字符会让重载失败。

同一个 ID 只能出现一次。页面中的静态 persistent 槽也必须引用已注册 ID；否则页面加载、编辑器保存或第三方页面注册会被拒绝。

acceptWhen 能读取什么

acceptWhen 只读取当前准备进入持久槽的物品，不读取页面变量或组件状态。

字段	类型	含义
`item.id`	字符串	物品命名空间 ID；空气为 `minecraft:air`。
`item.count`	数字	物品数量；空气为 `0`。
`item.name`	字符串	去除样式后的可见名称。
`item.lore`	`List<String>`	去除样式后的原 Lore 行列表，一行对应一个元素。
`item.loreText`	字符串	为兼容整段文字判断，把 `item.lore` 使用 `\n` 拼接后的结果。

字符串支持对象方法 contains、startsWith、endsWith；列表的 contains 判断是否存在类型和值都相同的完整元素。列表可以用从 0 开始的索引读取：

text

item.name.contains("宝石")
item.name.startsWith("精炼")
item.name.endsWith("核心")
item.lore.contains("不可交易")
item.lore[0] != null && item.lore[0].contains("史诗")

索引越界返回 null，因此读取指定行后继续调用字符串方法时，建议先判断不为 null。负数、小数和非数字索引属于错误，会让本次条件失败。完整的字符串、列表与条件入门见变量与条件。

双重检查与最终权威

玩家操作时，客户端会先用服务器同步的同一条条件做即时检查，不满足时不会发送无效操作。只要请求发到服务器，服务器仍会使用自己的真实物品再次判断；客户端显示不是认证依据，服务端结果始终是最终权威。

配置了 rejectMessage 时，正常的客户端前置拒绝会立即显示该消息；如果客户端状态过期、其他插件修改了最终物品，或请求绕过了前置检查，服务端权威拒绝结果也会携带同一条消息。该消息只用于 acceptWhen 的 item_not_accepted 拒绝，不会替代版本过期、权限或会话错误等其他原因。

acceptWhen 只检查即将进入持久槽的物品：

空光标纯取出不会执行条件；
放入和交换会检查准备进入槽位的物品；
其他插件通过槽位点击事件修改最终物品后，最终结果还会再检查一次；
条件为假、语法错误或名称/Lore 无法可靠读取时，都会拒绝放入。

页面自己的 itemSlot.check 与这里用途不同：check 可以按页面变量临时阻止客户端操作，acceptWhen 则是持久槽对物品的服务端规则。需要物品安全条件时，应以 acceptWhen 为准。

动态切换到持久槽

脚本可以在当前页面会话中修改物品槽的 bind 和 mode。推荐始终先写入已注册的绑定，再切换模式：

component("动态槽").itemSlot.bind = "宝石槽_1"
component("动态槽").itemSlot.mode = "persistent"

如果目标 ID 没有注册，本次赋值或后续操作会被拒绝并保留旧状态。脚本修改只影响当前页面会话，不会改写页面 yml。完整说明见组件操作。

重载、删除与恢复

/chaui reload 会先完整检查所有 ID、重复项、条件和页面引用；全部通过后才同时采用新页面与新槽位注册表。任一项非法时继续使用重载前的有效配置，不会只发布一部分。

从 slot.yml 删除注册项不会删除玩家已经保存的物品。该 ID 会暂时不可访问；以后重新注册完全相同的 ID，原有物品会恢复访问。请不要为了“清空槽位”而删除注册项。

服务端 API 的边界

所有 persistent 槽位 API 操作都要求 ID 已注册。ChaUISlotAPI.setSlotItem 是可信的服务端写入，可以绕过 acceptWhen，方便插件发放或修正物品，但不能绕过注册要求。API 完整签名见API 方法表。

常见错误

现象	原因与处理
重载提示槽位未注册	页面或脚本准备使用的 `persistent` bind 不在 `slot.yml`；先添加相同 ID。
合法物品在客户端就被阻止	检查名称大小写、Lore 是否要求完整行，以及索引是否越界。
客户端允许，但服务端拒绝	服务端权威物品不满足条件，或其他插件改变了最终入槽物品；以服务端结果为准。
删除配置后物品看不到	这是预期的暂时禁用；重新注册同一 ID 即可恢复访问，数据不会删除。
修改后没有生效	确认文件位于 `plugins/ChaUI/slot.yml`，保存后执行 `/chaui reload`，并先处理重载报告的第一条错误。

槽位注册表 ​

一份可以直接使用的完整配置 ​

配置字段 ​

acceptWhen 能读取什么 ​

双重检查与最终权威 ​

动态切换到持久槽 ​

重载、删除与恢复 ​

服务端 API 的边界 ​

常见错误 ​