图片组件 ​

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

适用场景 ​

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

图片路径可以填写相对于 resourcepacks/ChaUI/ 的路径，例如 gui/logo.png，也可以填写公开可访问的 http:// 或 https:// URL。支持按实际内容识别 PNG、JPG、JPEG 和 GIF；本地路径不能使用绝对路径、反斜杠或 ..。

公网 URL 可以包含查询参数，也可以在路径和查询中使用响应式 {...}，但协议、域名和显式端口必须固定，不能把变量放进主机部分。ChaUI 不发送 Cookie、Authorization 或自定义请求头，不允许访问 localhost、局域网、链路本地和保留地址；每次重定向也会重新检查目标。加载会异步进行，加载中或失败时使用缺失素材表现，不阻塞渲染。相同完整 URL 会复用内存缓存；需要主动刷新时可改变查询参数。http:// 与 https:// 都能使用，但 HTTP 不提供传输机密性与完整性，正式素材推荐使用 HTTPS。

单次公网图片最多下载 16 MiB，静态图与 GIF 单帧最大 4096×4096。GIF 最多 256 帧，总解码像素最多 16,777,216，单素材估算解码内存最多 64 MiB。全局最多同时下载 2 个素材并等待 64 个请求；解码缓存最多 128 条、合计最多 256 MiB，失败后同一 URL 冷却 30 秒。公网素材不写入磁盘缓存，页面关闭后会释放当前页面的引用，纹理缓存同时按 128 条与 256 MiB 限制，并且只逐出没有页面继续使用的纹理。

通用配置 ​

专属配置 ​

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: {}

若素材放在公开图床，可只把 image.path 改成网络地址；主机保持固定，变量放在路径或查询参数中：

image:
  path: https://cdn.example.com/chaui/{vars.theme}/logo.png?v={vars.assetRevision}
  gifLoop: true
  gifLoopCount: 0

脚本可以读取图片对象当前使用的路径。把下面的完整事件块替换到 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/，并逐字核对路径、扩展名和大小写；普通页面不会从服务端插件同步本地素材。display.mode: vanilla 原版菜单页面会先查找活动菜单包中的同路径素材，再回退到 ChaAssets 和客户端本地目录，具体见页面包与素材。公网地址应确认它是直接返回图片数据的公开 HTTP/HTTPS URL，且没有跳转到私网、登录页或不受支持的格式。

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

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

只想显示素材的一部分 ​

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

创建事件 ​

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