图片组件 ​

图片组件用于在页面中显示本地图片或 GIF 动图，适合背景、图标、装饰、头像框和状态提示。素材由客户端从当前游戏版本目录的 resourcepacks/ChaUI/ 中读取。

适用场景 ​

• 页面背景与装饰图层
• Logo、图标和状态标识
• GIF 动画提示
• 从整张素材中截取一块区域显示

图片路径始终填写相对于 resourcepacks/ChaUI/ 的路径，例如 gui/logo.png。支持 PNG、JPG、JPEG 和 GIF；路径不能使用绝对路径、反斜杠或 ..。

通用配置 ​

专属配置 ​

image.key 与 image.texture 不属于当前图片组件字段，保存时会被拒绝。请只使用 image.path。

图片路径可以跟随变量变化。例如 gui/{vars.theme}/logo.png 会在 vars.theme 为 blue 时读取 gui/blue/logo.png。ChaUI 会在表达式求值后再次检查最终路径；如果结果为空、越过素材目录、使用反斜杠或扩展名不受支持，只让当前图片安全回退，不会让页面崩溃。

四个源图字段也可以填写 vars、vals、window、parent、self 和数学函数组成的公式。结果有小数时向下取整为源图像素；结果为负数、非有限值、未知变量或选区越界时只跳过当前图片。制作动态图集和无拉伸血条请先阅读图片裁剪与动态血条。

配置示例 ​

先在页面根级 vars 中加入 theme: default，再把下面组件放入 elements。这样更换 vars.theme 时会自动读取另一套素材目录。

- id: logo
  type: image
  parent: ""
  visible: true
  enabled: true
  pointerEvents: auto
  scale: 1
  opacity: 0.9
  z: 10
  layout:
    x: window.width * 0.5 - 64
    y: 20
    width: 128
    height: 64
  image:
    path: gui/{vars.theme}/logo.gif # theme 变化时自动换图
    gifLoop: true               # 允许循环
    gifLoopCount: 0             # 0 表示无限循环
    sourceX: 0                  # 从源图左上角开始
    sourceY: 0
    sourceWidth: 256            # 截取 256×128 区域
    sourceHeight: 128
  tooltip:
    - 服务器 Logo
  events: {}

脚本可以读取图片对象当前使用的路径。把下面的完整事件块替换到 logo 组件中，悬浮时会把路径保存到页面变量并显示在本地日志中：

events:
  hoverEnter: |-
    vars.logoPath = component("logo").image.path
    log("当前 Logo：{vars.logoPath}")

源图字段可以在当前页面会话中读取、固定赋值或绑定公式：

events:
  leftClick: |-
    component("logo").image.sourceWidth = formula(vars.visiblePixels)
    vars.currentWidth = component("logo").image.sourceWidth
    vars.widthFormula = component("logo").image.expression("sourceWidth").source

直接赋数字会清除旧公式；formula(...) 会继续跟随变量。脚本修改不会写回服务端页面文件。

常见问题 ​

图片显示为缺失素材 ​

检查文件是否存在于当前客户端的 resourcepacks/ChaUI/，并逐字核对路径、扩展名和大小写。ChaUI 不会从服务端自动下载素材。

GIF 修改路径后为什么重新播放 ​

每次打开页面和每次动态修改图片路径都会建立新的播放作用域，这是预期行为。

只想显示素材的一部分 ​

同时填写源 X、源 Y、源宽和源高。选区越界或尺寸非法时，组件会安全跳过图片绘制。

创建事件 ​

图片组件支持 events.create，适合在组件出现时根据变量选择初始路径、显隐或尺寸。页面初始图片与脚本动态创建的图片都会对各自实例触发一次；隔离预览中的变化不会保存。