进度环（progressring）

选择器： progressring · 设计器组件： 进度环 · 按名称： progressring#名称 或 #名称 · 补全别名： jdh
用途： 环形进度指示。

硬约束与叠画

1. 控件名来自窗口 XML「名称」；属性赋值无括号（如 标题 = "确定"），方法调用必须带括号（如 刷新()）。
2. 事件写 函数 控件名.事件名(参数…)，形参类型以本页事件表为准。
3. 任意控件客户区叠画用支持库 绘制类：绘制类 g → g.绑组件(本控件名)（组件名无引号）。画布场景编辑见 画布控件。
4. 字体对象见绘制文档中的字体类；置字体(字体类) 将字体应用到本控件。
5. 不要虚构未列出的方法；YSS 键见下文与 YSS.md。

属性

设计器属性面板与代码侧可读可写属性（来源：组件类库）。

属性	类型	读写	说明
提示	文本	读写	鼠标悬停时的提示文字
鼠标指针	文本	读写	空=默认；可用 arrow/hand/ibeam/cross/wait/no/sizeall 等预设，或.cur/.ani 路径（如 资源/press.cur）
左边	小数	读写	相对窗体左边的位置（像素）
顶边	小数	读写	相对窗体顶边的位置（像素）
宽度	小数	读写	控件宽度（像素）
高度	小数	读写	控件高度（像素）
停靠	整数	读写	0无 1上 2下 3左 4右 5填充；菜单/工具/状态栏仍用专用吸附
可见	逻辑	读写	真=显示，假=隐藏
启用	逻辑	读写	真=可用，假=禁用
句柄	长整数	只读	组件逻辑句柄（1 起，供动画类等绑定；非 HWND）；只读
当前值	小数	读写	环形进度当前值（受小数位数控制）
值	小数	读写	同「当前值」
最小值	小数	读写	最小值
最大值	小数	读写	最大值
小数位数	整数	读写	0-6，0=整数；内部按定点数存储
线宽	整数	读写	环形描边宽度/圆边宽度（像素，默认 4，范围 1–32）
圆边宽度	整数	读写	同「线宽」：环形描边宽度（像素）
轨道色	文本	读写	如 #2D2D30
进度色	文本	读写	如 #007ACC
进度渐变色	文本	读写	非空则沿弧渐变到该色；空=纯色
显示文本	逻辑	读写	真=环心显示数值或环心文本
环心文本	文本	读写	非空时优先显示该文案（覆盖自动数值/%）
显示为百分比	逻辑	读写	真=显示百分比（环心文本为空时）
圆角端帽	逻辑	读写	真=进度弧线两端圆头
起始角	整数	读写	画环起始点（度）：0=正上，90=正右，顺时针为正
逆时针	逻辑	读写	真=逆时针增长，假=顺时针
不确定扫弧	整数	读写	不确定模式扫弧角度（10–350，默认90）
不确定周期	整数	读写	不确定旋转一周毫秒（默认1200）
不确定	逻辑	读写	真=旋转扫弧（不确定进度）
文字色	文本	读写	环心文字色

方法

组件类库方法（调用必须带括号）。下表为带类型签名。

方法	签名	返回	说明
置值	无 置值(小数 数值)	无	与小数位数一致；也可属性 值 / 当前值
取值	小数 取值()	小数
置小数位数	无 置小数位数(整数 位数)	无	0–6
取小数位数	整数 取小数位数()	整数
置显示格式	无 置显示格式(整数 格式)	无	0–5
取显示格式	整数 取显示格式()	整数
置范围	无 置范围(小数 最小值, 小数 最大值)	无
取最小值	小数 取最小值()	小数
取最大值	小数 取最大值()	小数
置步长	无 置步长(小数 步长)	无
取步长	小数 取步长()	小数
置前缀	无 置前缀(文本 前缀)	无
取前缀	文本 取前缀()	文本
置后缀	无 置后缀(文本 后缀)	无
取后缀	文本 取后缀()	文本
置不确定	无 置不确定(逻辑 开启)	无	真=旋转扫弧
取不确定	逻辑 取不确定()	逻辑
置环心文本	无 置环心文本(文本 内容)	无	空=自动显示数值
取环心文本	文本 取环心文本()	文本
移动	无 移动(小数 左边, 小数 顶边, [小数 宽度], [小数 高度])	无	可选同时改宽高
置焦点	无 置焦点()	无
刷新	无 刷新()	无	立即重绘所在窗口
显示 / 隐藏	无 显示() / 无 隐藏()	无	等同 可见 = 真/假
置字体	逻辑 置字体(字体类 字体)	逻辑	见 painter.md

进度环1.置值(66.5)
进度环1.置不确定(假)
进度环1.置环心文本("完成")

事件

在代码中写 函数 控件名.事件名(...) 处理。

事件	参数	说明
单击	整数 X, 整数 Y	鼠标左键单击控件。
双击	整数 X, 整数 Y	鼠标左键双击控件。
右键单击	整数 X, 整数 Y	鼠标右键单击控件。
鼠标按下	整数 X, 整数 Y, 逻辑 按下	鼠标键在控件上按下。按下=真表示当前仍按住。
鼠标抬起	整数 X, 整数 Y, 逻辑 按下	鼠标键在控件上放开。
鼠标移动	整数 X, 整数 Y, 逻辑 按下	鼠标在控件上移动。按下表示左键是否按住。
鼠标进入	整数 X, 整数 Y	鼠标指针进入控件区域。
鼠标离开	整数 X, 整数 Y	鼠标指针离开控件区域。
鼠标左键单击	整数 X, 整数 Y	鼠标左键单击（与「单击」同时触发）。
鼠标左键双击	整数 X, 整数 Y	鼠标左键双击（与「双击」同时触发）。
鼠标中间单击	整数 X, 整数 Y	鼠标中键单击控件。
鼠标齿轮滚动	整数 X, 整数 Y, 逻辑 向上	在控件上滚动鼠标滚轮。向上=真表示向上滚。
鼠标右键单击	整数 X, 整数 Y	鼠标右键单击（与「右键单击」同时触发）。
鼠标右键双击	整数 X, 整数 Y	鼠标右键双击控件。
值改变	小数 当前值, 整数 来源	当前数值发生变化时触发（程序置值等）；参数为小数与来源（0=程序）。

函数 进度环1.单击 (整数 X, 整数 Y) {
    // …
}

YSS 样式

以下为样式表（.yss）键与示例；写样式前请先读窗体 XML 取控件 名称 与 typeId，见 window-xml.md。

布局与子选择器

数值按「小数位数」定点存储（同数值微调框 / 进度条）。

伪态 / 子控件： 无专用子选择器；轨道与进度弧均通过基选择器颜色键区分（track-color / progress-color / progress-gradient）。

样式概览

YSS 控制轨道环、进度弧、环心文字与不确定旋转动画。

伪状态与映射

颜色槽对照（ 必读）：

视觉部位	推荐键	内部字段
轨道环（整圈底色）	track-color	backColor
进度弧（起始/纯色）	progress-color	backColor2
进度弧渐变终点	progress-gradient	pressedForeColor

属性说明（逐键）

下表按「数值与范围 → 环形 track/progress → 环心文字 → 几何与方向 → 不确定态 → 外壳」展开。每条写清：作用、取值、绘制时机、注意点。

数值与范围

属性	作用	取值 / 范围	说明与注意
value / current-value	当前值	小数；受 decimals 控制	如 66.5；设计器/YSS 可预设预览；弧长 = 比例 × 360°。
min / minimum	最小值	数值，默认 0
max / maximum	最大值	数值，默认 100	须 max > min 弧长才有效。
decimals / decimal-places	小数位数	0–6；0=整数	影响环心自动数值格式。

环形 · 轨道与进度弧

属性	作用	取值 / 范围	说明与注意
track-color	轨道环颜色（未走过弧）	颜色，如 #2D2D30	映射 backColor；先画整圈底色环。
progress-color	进度弧颜色（起始/纯色）	颜色，如 #5B6FE8	映射 backColor2；无渐变时整段弧用此色。
progress-gradient	进度弧渐变第二色	颜色；none/transparent/0/空=纯进度色	映射 pressedForeColor；非空且与起始色不同时弧沿圆周渐变到该色。
stroke / line-width / ring-width / border-width	环形描边宽度	约 1–32 像素，默认约 4	四键同义；环本体粗细主要看此值，非外框 border-width 语义。
round-cap	弧线两端圆头	true / false，默认 true	false 时端点更平直；在弧线端点画圆帽。
start-angle	画环起始角	度数；0=正上，90=正右	顺时针为正；进度从该角起增长。
ccw / counterclockwise	逆时针增长	true / false	默认 false=顺时针。

绘制顺序： 先画整圈轨道环 → 再画进度弧（覆盖在轨道上）→ 最后画环心文字（若启用）。

环几何（运行时，非 YSS 键）： 环半径 ≈ min(宽,高)/2 − stroke/2；环心位于控件矩形中心。

环心文字（center text）

属性	作用	取值 / 范围	说明与注意
show-text	环心是否绘制文字	true / false	false 时仅显示环，无中心数字。
center-text / label	自定义环心文案	字符串；空="" 表示用自动值	非空则完全覆盖自动数值/百分比；常用于 "完成" 等固定词。
percent / show-percent	自动文案按百分比	true / false	与 decimals 配合可显示如 66.5%。
color	环心文字颜色	颜色，如 #CCCCCC
font-size	环心字号	像素，如 14
font-family	环心字体族	字符串
font-bold / font-italic	粗体 / 斜体	true / false

环心文字居中绘制，区域约为控件宽的 72%、高的 40%（上限约 18px 字号 band）。

不确定态（indeterminate）

属性	作用	取值 / 范围	说明与注意
indeterminate	旋转扫弧忙碌态	true / false	真=忽略固定 value，播放旋转动画。
indet-sweep	不确定扫弧角度	约 10–350 度，默认 90	弧段长度；越大扫过范围越宽。
indet-period	旋转一周毫秒数	约 100–60000，默认 1200	越小转得越快。

不确定态下仍绘制轨道环；进度弧变为一段扫过弧，绕环心旋转。

外壳与边距

属性	作用	取值 / 范围	说明与注意
transparent-background	不绘制控件底板	true / false	常用 true 让环「浮」在窗体底上。
border-radius	控件矩形圆角	像素	主要影响可选外框；环形状由 stroke 决定。
show-border / border-color	外矩形边框	true/false + 颜色	环本体不依赖此外框；调试布局时可用。
margin / margin-left / margin-top / margin-right / margin-bottom	绘制区域外边距	像素 / 简写	在控件矩形内缩进环与文字。

---

使用示例

基础进度环 + 百分比

progressring#进度环1 {
    track-color: #3A3A40;
    progress-color: #5B6FE8;
    progress-gradient: #00D4AA;
    stroke: 8;
    show-text: true;
    percent: true;
    round-cap: true;
}

小数 + 自定义起始角

progressring#进度环1 {
    value: 66.5;
    min: 0;
    max: 100;
    decimals: 1;
    stroke: 8;
    track-color: #2D2D30;
    progress-color: #5B6FE8;
    start-angle: 90;
    ccw: false;
    show-text: true;
    color: #CCCCCC;
    font-size: 14;
}

固定环心文案

progressring#完成环 {
    value: 100;
    show-text: true;
    center-text: "完成";
    track-color: #2D2D30;
    progress-color: #00C853;
    stroke: 6;
}

不确定忙碌环

progressring#忙碌环 {
    indeterminate: true;
    indet-sweep: 120;
    indet-period: 800;
    track-color: #3A3A40;
    progress-color: #00B4FF;
    stroke: 6;
    show-text: false;
    transparent-background: true;
}

纯色弧（关闭渐变）

progressring#纯色环 {
    track-color: #404040;
    progress-color: #FF6B9D;
    progress-gradient: none;
    stroke: 10;
    round-cap: true;
}

细轨粗弧对比

progressring#仪表盘 {
    track-color: #1E1E22;
    progress-color: #FFD54F;
    stroke: 12;
    round-cap: true;
    show-text: true;
    percent: true;
    color: #FFFFFF;
    font-size: 16;
    font-bold: true;
}

---

完整示例

progressring#进度环1 {
    value: 66.5;
    min: 0;
    max: 100;
    decimals: 1;
    stroke: 8;
    track-color: #2D2D30;
    progress-color: #5B6FE8;
    progress-gradient: #00D4AA;
    show-text: true;
    center-text: "";
    round-cap: true;
    start-angle: 0;
    ccw: false;
    percent: true;
    indeterminate: false;
    color: #CCCCCC;
    font-size: 14;
    transparent-background: true;
}

progressring#忙碌环 {
    indeterminate: true;
    indet-sweep: 120;
    indet-period: 800;
    track-color: #3A3A40;
    progress-color: #00B4FF;
    stroke: 6;
    show-text: false;
}

---