猹件开发组

Appearance

On this page

进度条组件 ​

进度条组件用于只读展示一个数值在指定范围中的进度，适合生命、经验、下载、冷却和任务完成度。它不接收拖动或点击改值；需要玩家调节数值时请使用拖动条组件。

配置项 ​

配置项类型默认值说明
progress.value数字或公式0当前显示值。
progress.min数字或公式0最小值。
progress.max数字或公式100最大值，必须大于最小值。
progress.direction字符串left_to_right填充方向。
progress.path图片路径空进度条底图。
progress.fillPath图片路径空填充图片，会按当前比例裁剪。

方向支持：

  • left_to_right：从左向右；
  • right_to_left：从右向左；
  • bottom_to_top：从下向上；
  • top_to_bottom：从上向下。

底图支持 sourceX/Y/Width/Height、gifLoop、gifLoopCount；填充图支持 fillSourceX/Y/Width/Height、fillGifLoop、fillGifLoopCount。循环默认 true，次数默认 0。

完整配置 ​

yaml
id: progress_demo
version: 1
title: 进度条示例
size:
  width: 340
  height: 180
coordinateMode: absolute
display:
  mode: screen
  screen:
    dimBackground: false

vars:
  taskDone: 35
  taskTotal: 50

papi:
  refreshTicks: 20
  values: {}

events:
  open: ""
  close: ""

methods: {}

elements:
  - id: task_progress
    type: progress
    parent: ""
    visible: true
    enabled: false
    pointerEvents: pass
    scale: 1
    opacity: 1
    z: 10
    layout:
      x: 70
      y: 72
      width: 200
      height: 14
    progress:
      value: vars.taskDone
      min: 0
      max: vars.taskTotal
      direction: left_to_right
      path: gui/form/progress-empty.png
      gifLoop: true
      gifLoopCount: 0
      sourceX: 0
      sourceY: 0
      sourceWidth: 200
      sourceHeight: 14
      fillPath: gui/form/progress-fill.png
      fillGifLoop: true
      fillGifLoopCount: 0
      fillSourceX: 0
      fillSourceY: 0
      fillSourceWidth: 200
      fillSourceHeight: 14
    events: {}

示例中 vars.taskDone / vars.taskTotal 会在每次渲染时重新计算。小于最小值时显示空进度，大于最大值时显示满进度，但这种显示夹取不会改写变量。

在编辑器中配置 ​

  1. 添加“进度条”。
  2. 为当前值、最小值和最大值填写数字或公式。
  3. 点击“填充方向”循环选择四种方向。
  4. 需要素材时，纵向填写底图和填充图各自的路径、GIF 与源图选区。
  5. 进入预览，修改页面变量即可观察进度实时变化。

不使用图片时 ​

两个图片路径都留空时，会显示深色底槽和醒目的填充颜色。进度裁剪和四个方向仍然有效。

图片皮肤 ​

填充图会按进度比例同步裁剪目标区域和源图区域，完整纹理不会被压缩进更短的矩形。图片路径支持 {...} 响应式表达式，源图坐标和尺寸支持数字公式。

底图或填充图缺失、路径无效、公式无效或选区越界时，只让对应素材回退，不影响其他组件。需要带固定端帽的血条时，可参考图片裁剪与动态血条拆分端帽与中间填充。

只读展示 ​

进度条不会自行改变 vars，也没有内置 input 或 change 事件。你仍可给它配置通用悬浮提示或鼠标事件，但这些事件只执行脚本，不会把它变成可拖动控件。

常见问题 ​

进度一直为空 ​

检查当前值和范围公式。max 必须大于 min，未知变量或无法得到有限数字时会安全显示空进度。

填充图片被拉伸 ​

ChaUI 会按比例裁剪。若素材本身仍变形，请确认 fillSourceWidth、fillSourceHeight 对应原图真实选区，且布局宽高比符合设计。

点击进度条不能改值 ​

这是预期行为。进度条是只读展示；交互调节请改用拖动条。