猹件开发组

Appearance

On this page

环形进度条组件 ​

环形进度条把一个数值显示成圆弧，适合成功率、冷却时间、任务进度和半圆仪表。它只显示进度，不会因点击或拖动修改数值。编辑器组件库中选择“环形进度条”，无需准备图片即可预览。

配置项 ​

组件类型为 ring_progress，专属配置写在 ringProgress 下。

配置项说明
value当前值，必填，支持数字或公式，例如 vars.chance。
min / max数值范围，必填，最大值必须大于最小值。支持公式。
startAngle起始角度，默认 0，表示顶部；90 表示右侧，180 表示底部。支持公式。
sweepAngle满进度对应的总角度，默认 360；必须大于 0 且不超过 360。支持公式。
directionclockwise 为顺时针（默认），counterclockwise 为逆时针。
thickness圆环粗细，默认 12 GUI 像素，必须为正数，支持公式；超过半径时按半径显示。
trackColor无底图时的底环颜色，默认 #29323A。
fillColor无填充图片时的进度颜色，默认 #FFD45A。
path / fillPath可选底环图片、进度填充图片。

颜色必须写成带引号的六位格式，例如 "#FFD45A"。透明度使用组件根级 opacity。

圆环在组件区域内居中，以宽高较小的一边作为直径；设置非正方形宽高不会把圆环拉成椭圆。当前值超出范围时只限制显示，不改写页面变量。当前值无法求值时显示空进度；范围、角度或厚度公式无效时暂不绘制该组件。

第一个成功率圆环 ​

将下面页面保存为 pages/ring_progress_demo.yml。打开后显示从顶部顺时针填充的黄色半圆环，中间显示 50%；修改 chance 后，圆环与文字会一起变化。

yaml
id: ring_progress_demo
version: 1
title: 成功率圆环
size:
  width: 320
  height: 220
coordinateMode: absolute
display:
  mode: screen
  screen:
    dimBackground: false
vars:
  chance: 50
papi:
  refreshTicks: 20
  values: {}
events: {}
methods: {}
elements:
  - id: chance_ring
    type: ring_progress
    visible: true
    enabled: false
    pointerEvents: pass
    scale: 1
    rotation: 0
    opacity: 1
    z: 1
    layout:
      x: 100
      y: 45
      width: 120
      height: 120
    ringProgress:
      value: vars.chance
      min: 0
      max: 100
      startAngle: 0
      sweepAngle: 360
      direction: clockwise
      thickness: 14
      trackColor: "#29323A"
      fillColor: "#FFD45A"
    events: {}
  - id: chance_label
    type: text
    visible: true
    enabled: false
    pointerEvents: pass
    z: 2
    layout:
      x: 110
      y: 100
      width: 100
      height: 16
    text:
      value: "{vars.chance}%"
      textSize: 1
      align: center
      color: "#FFD45A"
    events: {}

在现有事件脚本中使用 vars.chance = 75;，即可显示四分之三进度。也可以用 component("chance_ring").ringProgress.value = 75; 直接修改组件当前会话中的值；这样会替换该字段原先的变量公式。中文入口为 组件("chance_ring").环形进度条.value。

半圆、图片与绕圈指针 ​

半圆仪表可将 startAngle 设为 270、sweepAngle 设为 180，保持顺时针，此时满进度覆盖上半圆。value 表示数值范围中的比例，不是角度。

图片支持与图片组件相同的路径规则。底环支持 sourceX、sourceY、sourceWidth、sourceHeight、gifLoop、gifLoopCount；填充图片支持 fillSourceX、fillSourceY、fillSourceWidth、fillSourceHeight、fillGifLoop、fillGifLoopCount。源图选区支持响应式公式，路径支持响应式内容。GIF 默认循环，次数 0 表示无限循环。

图片选区居中等比覆盖正圆，并按圆环及当前角度裁剪；中心保持透明。优先使用正方形素材，长方形选区的长边会被居中裁切。未配置图片或图片不可用时显示对应颜色。

圆环不内置文字或指针。中心文字使用上例的独立文本组件；绕圈指针使用与圆盘同尺寸的透明图片，只在边缘绘制箭头，再动态修改该图片的 rotation。透明图片中心要与圆环中心重合，才能形成绕圈效果。