物品展示组件

物品展示组件用于显示一个原版或已注册物品的图标与数量，适合奖励预览、商店商品、任务需求和配方说明。它只负责展示，不提供物品放入、取出或交换行为。

组件默认完全透明，不会自动绘制槽位框或底色。需要背景时，可以像图片组件一样配置一张静态图片，并用源图选区裁剪九宫格或图集中的某一块。

适用场景

奖励和掉落预览
商店商品与价格展示
任务需要物品
配方材料和结果

需要玩家交互物品时，请使用物品槽组件。

通用配置

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`id`	ID	字符串	自动生成 `item_display_N`	页面内唯一 ID	用于服务端 API 和状态更新。
`type`	类型	只读字符串	`item_display`	固定值	创建后不能修改。
`parent`	父级	字符串	空	布局组件 ID	为空表示根级元素。
`z`	层级	整数	`0`	任意整数	控制物品图标绘制顺序。
`visible`	显示	布尔值	`true`	`true`、`false`	静态显隐开关。
`enabled`	启用	布尔值	`true`	`true`、`false`	控制是否响应组件事件。
`dragMode`	拖拽	枚举	`off`	`off`、`temporary`、`remember`	关闭拖动、仅本次页面保留位置，或在本地记住位置。
`pointerEvents`	指针处理	枚举	`auto`	`auto`、`block`、`pass`	配置事件或提示后 `auto` 命中；纯展示可用 `pass`。
`scale`	缩放	数字或公式	`1`	非负值	以展示区域中心缩放画面和命中范围，不改变布局值。
`opacity`	背景透明度	数字或公式	`1`	`0` 至 `1`	只影响展示背景和边框，物品、数量与附魔效果保持不透明。
`visibleWhen`	显示条件	条件表达式	空	只读条件	可根据页面变量控制展示。
`enabledWhen`	启用条件	条件表达式	空	只读条件	可根据页面变量控制事件。
`tooltip`	多行提示	字符串列表	空	最多 32 行，每行最多 256 字符	组件自定义悬浮提示。
`containerBinding`	容器绑定	字符串	空	当前容器的语义槽位 ID	仅容器替换页面使用；显示绑定槽位中的真实物品。
`containerTooltip`	容器提示	布尔值	`true`	`true`、`false`	没有显式 `tooltip` 时是否显示绑定物品提示。
`layout.x`	X	数字或公式	创建时画布位置	合法布局公式	图标区域左上角 X。
`layout.y`	Y	数字或公式	创建时画布位置	合法布局公式	图标区域左上角 Y。
`layout.width`	宽	数字或公式	`18`	合法布局公式	推荐保持接近原版物品图标尺寸。
`layout.height`	高	数字或公式	`18`	合法布局公式	推荐保持接近原版物品图标尺寸。
`events.leftPress` `/rightPress/middlePress`	按下脚本	ChaUI Script	空	多行脚本	对应按键按下时触发。
`events.leftRelease` `/rightRelease/middleRelease`	松开脚本	ChaUI Script	空	多行脚本	对应按键捕获仍有效并松开时触发。
`events.leftClick`	左键脚本	ChaUI Script	空	多行脚本	左键点击展示区域时触发。
`events.rightClick`	右键脚本	ChaUI Script	空	多行脚本	右键点击时触发。
`events.middleClick`	中键脚本	ChaUI Script	空	多行脚本	中键点击时触发。
`events.hoverEnter`	悬浮进入脚本	ChaUI Script	空	多行脚本	鼠标进入时触发。
`events.hoverLeave`	悬浮离开脚本	ChaUI Script	空	多行脚本	鼠标离开时触发。

专属配置

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`itemDisplay.itemId`	当前编辑器未直接显示	字符串	空	命名空间物品 ID	当前实际渲染的物品，例如 `minecraft:diamond`。
`itemDisplay.itemCount`	当前编辑器未直接显示	非负整数	`0`	`0` 或正整数	数量大于 0 时显示物品及数量装饰。
`itemDisplay.itemPayload`	当前编辑器未直接显示	字符串	空	服务端生成的物品快照	由 API 自动下发，用于还原名称、附魔、组件数据和 Mod 物品外观；页面作者通常不用手写。

原版物品提示

物品展示组件在没有配置显式 tooltip 时，会像原版背包中的物品一样显示当前物品的完整提示，包括名称、Lore、附魔和可用的物品组件信息。提示优先级固定为：显式 tooltip → 当前物品的原版提示 → 无提示，不会把两种提示叠在一起。

enabled: false 或 enabledWhen 结果为假时，物品图标仍会显示，但不会出现 Tooltip，也不会响应点击、悬浮事件或拖动。visible: false 或 visibleWhen 结果为假时，组件和物品都会完全隐藏。

绑定原版容器槽位时，可用 containerTooltip: false 关闭绑定物品提示。普通 item_display 不需要额外开关；只要当前展示的是非空气物品且组件已启用，就会显示原版提示。 | itemDisplay.path | 背景路径 | 字符串 | 空 | ChaUI 安全相对路径；仅 png、jpg、jpeg | 可使用 {vars.xxx} 等响应式路径模板；留空时不绘制背景。 | | itemDisplay.sourceX | 背景源X | 非负整数或公式 | 0 | 源图像素坐标或数字公式 | 背景选区左上角 X。 | | itemDisplay.sourceY | 背景源Y | 非负整数或公式 | 0 | 源图像素坐标或数字公式 | 背景选区左上角 Y。 | | itemDisplay.sourceWidth | 背景源宽 | 非负整数或公式 | 整张图片剩余宽度 | 像素尺寸或数字公式 | 背景选区宽度；为 0 时背景不绘制。 | | itemDisplay.sourceHeight | 背景源高 | 非负整数或公式 | 整张图片剩余高度 | 像素尺寸或数字公式 | 背景选区高度；为 0 时背景不绘制。 |

背景选区公式每次渲染重新计算并向下取整。公式无效或越界时只隐藏背景图片，物品模型、数量和附魔效果继续显示。

物品展示优先使用服务端下发的完整 itemPayload 还原物品；只有 payload 为空或无法还原时，才使用 itemId 和 itemCount 作为安全回退。需要动态更换展示物品时，推荐直接调用服务端 API，不要手工拼接 payload。

服务端临时更新会修改当前页面会话中的展示状态，不会自动改写原始页面文件。

配置示例

yaml

- id: reward_display
  type: item_display
  parent: ""
  visible: true
  enabled: false
  pointerEvents: pass
  scale: 1
  opacity: 0.85
  z: 10
  layout:
    x: 20
    y: 20
    width: 18
    height: 18
  itemDisplay:
    itemId: minecraft:diamond   # 当前实际显示的物品
    itemCount: 3                # 显示数量
    path: gui/item_frame.png    # 可选静态背景；不写就是透明
    sourceX: 0
    sourceY: 0
    sourceWidth: 18
    sourceHeight: 18
  tooltip:
    - 通关奖励
  events: {}

展示组件对象可以读取当前展示配置。下面的创建事件会记录物品 ID 和数量：

yaml

events:
  create: |-
    vars.rewardItem = component("reward_display").itemDisplay.itemId
    vars.rewardCount = component("reward_display").itemDisplay.itemCount

常见问题

不配置背景时为什么没有槽位框

这是正常效果。物品展示默认只画物品本身，不自带底框；需要底框时配置 itemDisplay.path。背景图片只负责装饰，不会替代物品内容。

背景能不能使用 GIF

不能。物品展示背景只接受 png、jpg、jpeg 静态图片。动态路径模板最终解析出的文件也必须是这三种格式。

能否显示 Mod 物品

物品 ID 必须在当前客户端注册。由服务端 API 提供的物品状态可按当前兼容环境同步更完整的显示数据。

为什么不能把物品拿走

物品展示组件只用于展示。需要放入和取出行为时使用物品槽组件。

创建事件

物品展示组件支持 events.create，可在实例创建后准备说明文字、显隐变量或关联组件状态。初始实例和动态复制实例各触发一次，但事件不能把客户端展示结果当作服务端权威物品数据。

服务端配置文件 ↘

物品展示组件 ​

适用场景 ​

通用配置 ​

专属配置 ​

原版物品提示 ​

配置示例 ​

常见问题 ​

不配置背景时为什么没有槽位框 ​

背景能不能使用 GIF ​

能否显示 Mod 物品 ​

为什么不能把物品拿走 ​

创建事件 ​