进度条（progressbar）

Y++ / YStudio 开发文档 · 一点滴

选择器： progressbar · 设计器组件： 进度条 · 按名称： progressbar#名称 或 #名称
用途： 水平进度指示。

硬约束与叠画

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

属性

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

属性	类型	读写	说明
`提示`	文本	读写	鼠标悬停时的提示文字
`鼠标指针`	文本	读写	空=默认；可用 arrow/hand/ibeam/cross/wait/no/sizeall 等预设，或.cur/.ani 路径（如资源/press.cur）
`左边`	小数	读写	相对窗体左边的位置（像素）
`顶边`	小数	读写	相对窗体顶边的位置（像素）
`宽度`	小数	读写	控件宽度（像素）
`高度`	小数	读写	控件高度（像素）
`停靠`	整数	读写	0无 1上 2下 3左 4右 5填充；菜单/工具/状态栏仍用专用吸附
`可见`	逻辑	读写	真=显示，假=隐藏
`启用`	逻辑	读写	真=可用，假=禁用
`句柄`	长整数	只读	组件逻辑句柄（1 起，供动画类等绑定；非 HWND）；只读
`值`	整数	读写	当前数值（在最小值与最大值之间）
`当前值`	整数	读写	同「值」；当前数值（在最小值与最大值之间）
`最小值`	整数	读写	数值范围下限
`最大值`	整数	读写	数值范围上限
`轨道背景色`	文本	读写	如 #RRGGBB
`进度色`	文本	读写	进度条填充色
`显示文本`	逻辑	读写	真=显示数值文本
`显示为百分比`	逻辑	读写	真=按百分比显示
`显示小数`	逻辑	读写	真=显示小数位
`小数位数`	整数	读写	1-6，启用小数时有效
`文本位置`	整数	读写	0左 1上 2右 3下 4组件上
`圆角`	整数	读写	像素，0=直角
`显示边框`	逻辑	读写	真=显示边框
`边框大小`	整数	读写	像素
`边框颜色`	文本	读写	如 #RRGGBB
`描边样式`	整数	读写	0=实线…4=双点划线

方法

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

方法	签名	返回	说明
`置值`	`无置值(整数数值)`	无	也可属性 `值` / `当前值`
`取值`	`整数取值()`	整数
`移动`	`无移动(小数左边, 小数顶边, [小数宽度], [小数高度])`	无	可选同时改宽高
`置焦点`	`无置焦点()`	无
`刷新`	`无刷新()`	无	立即重绘所在窗口
`显示` / `隐藏`	`无显示()` / `无隐藏()`	无	等同 `可见 = 真/假`
`置字体`	`逻辑置字体(字体类字体)`	逻辑	见 painter.md

进度条1.置值(75)
输出(进度条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	鼠标右键双击控件。
`值改变`	整数当前值	当前数值发生变化时触发（程序置值等）。

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

YSS 样式

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

样式概览

YSS 控制轨道色、填充色/渐变、数值/百分比文字与不确定动画（已填充段 chunk + 轨道 groove）。

伪状态与映射

子控件： progressbar:chunk（已填充段） · progressbar:groove（轨道）

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

子控件映射（必读）：

在子控件块中写的键	实际落到控件的字段
`progressbar:groove { background-color }`	轨道色 → `track-color` / `background-color`（`backColor`）
`progressbar:chunk { background-gradient-color }`	填充起始色 → `progress-color` / `background-gradient-color`（`backColor2`）
`progressbar:chunk { background-color }`	填充结束色 → `pressed-background-color`（渐变终点）

方向说明： 进度条控件本体为水平填充（从左向右增长）。没有独立的 orientation: vertical 控件朝向键；background-gradient-direction 仅控制填充段内部双色渐变为水平或垂直，不改变进度增长方向。

属性说明（逐键）

下表按「数值与范围 → 轨道 groove → 填充 chunk → 文字 → 外壳 → 不确定态 → 兼容别名」展开。每条写清：作用、取值、绘制时机、注意点。

数值与范围

属性	作用	取值 / 范围	说明与注意
`value` / `current-value`	当前值	数值；受 `decimals` 控制	设计器/YSS 可预设预览值；运行时 `(value-min)/(max-min)` 决定填充比例。
`min` / `minimum`	最小值	数值，默认约 `0`
`max` / `maximum`	最大值	数值，默认约 `100`	须 `max > min` 才有有效比例。
`decimals` / `decimal-places`	小数位数	`0`–`6`；`0`=整数	影响显示文字与内部定点存储。

轨道（groove）

属性	作用	取值 / 范围	说明与注意
`track-color`	轨道底色	颜色，如 `#E6E6EC`	推荐新名；映射 `backColor`；绘制全长圆角矩形。
`background-color` / `background`	轨道色兼容写法	颜色	与 `track-color` 等价；亦可作控件底板色。
`border-radius`	轨道与填充圆角	像素，如 `0`–`64`	同时作用于 groove 与 chunk 圆角；`0`=直角条。
`round-cap`	填充端头圆角	`true` / `false`，默认 `true`	`false` 时端头更平直；映射 `showHotkeyUnderline` 槽。
`transparent-background`	不绘制控件底板	`true` / `false`	`true` 时仍可由 `track-color` 绘制轨道全长。
`margin` / `margin-left` / `margin-top` / `margin-right` / `margin-bottom`	绘制区域外边距	像素 / 简写	在控件矩形内缩进绘制区，不改 HWND 布局。

子控件写法：progressbar:groove { background-color: #E6E6EC; } 与 track-color 等价。

绘制时机： 轨道在 chunk 之下先画；chunk 宽度 = 比例 × 轨道宽，最小宽度约 2×border-radius 以保证小比例时仍可见。

已填充段（chunk）

属性	作用	取值 / 范围	说明与注意
`progress-color`	已填充段起始色	颜色，如 `#5B6FE8`	推荐新名；映射 `backColor2`。
`progress-gradient`	填充渐变第二色	颜色；`none`/`transparent`/`0`/空=关闭渐变	映射 `pressedForeColor` 槽作渐变终点；非空且与起始色不同时沿 `background-gradient-direction` 渐变。
`background-gradient-color`	填充起始色兼容别名	颜色	同 `progress-color` → `backColor2`。
`pressed-background-color`	填充结束色兼容别名	颜色	与起始色不同时绘制双色渐变；`progressbar:chunk { background-color }` 亦映射到此槽。
`background-gradient-direction`	填充渐变方向	`horizontal`/`1` · `vertical`/`0`（默认）	仅影响 chunk 内部渐变走向，非控件朝向。
`stroke` / `line-width` / `border-width`	线宽 / 描边参考	约 `1`–`32` 像素	进度条上主要影响外边框语义；chunk 高度由轨道区域决定。

子控件写法示例：

progressbar:chunk {
    background-gradient-color: #5B6FE8;  /* 起始 */
    background-color: #FF6B9D;           /* 结束 → pressed-background-color */
}

颜色槽对照（易混）：

视觉部位	推荐键	内部字段
轨道 groove	`track-color`	`backColor`
填充起始	`progress-color`	`backColor2`
填充渐变终点	`progress-gradient` 或 `pressed-background-color`	`pressedForeColor` / `pressedBackColor`

progress-gradient 与 pressed-background-color 均可作填充终点；子选择器 :chunk { background-color } 写结束色时走 pressed-background-color 槽。

进度文字

属性	作用	取值 / 范围	说明与注意
`show-text`	是否绘制进度文字	`true` / `false`	文字可绘于条带左/上/右/下（由内部 `textPos` 决定，YSS 暂无独立 `text-position` 键）。
`center-text` / `label`	自定义覆盖文案	非空字符串	非空则覆盖自动数值/百分比；空字符串=用自动文案。
`percent` / `show-percent`	按百分比显示	`true` / `false`	可配合 `decimals` 显示小数百分比，如 `66.5%`。
`color`	数值文字颜色	颜色
`font-size`	数值字号	像素
`font-family`	数值字体族	字符串
`font-bold` / `font-italic`	粗体 / 斜体	`true` / `false`

外壳边框

属性	作用	取值 / 范围	说明与注意
`show-border`	是否画外边框	`true` / `false`	包裹整个进度条控件区。
`border-color`	外边框色	颜色	与 chunk/groove 填充独立。
`border-width`	外边框宽	像素	与 `stroke`/`line-width` 共用字段上限约 32。

不确定态（indeterminate）

属性	作用	取值 / 范围	说明与注意
`indeterminate`	不确定/忙碌动画	`true` / `false`	真=扫动或滚动示意，忽略固定 `value` 比例；映射 `checked` 槽。

使用示例

基础双色填充

progressbar#进度条1 {
    track-color: #E6E6EC;
    progress-color: #5B6FE8;
    progress-gradient: #FF6B9D;
    background-gradient-direction: horizontal;
    border-radius: 12;
}

子控件分别设轨与块

progressbar:groove {
    background-color: #E6E6EC;
}

progressbar:chunk {
    background-gradient-color: #5B6FE8;
    background-color: #FF6B9D;
}

整数百分比 + 自定义范围

progressbar#进度条1 {
    value: 66;
    min: 0;
    max: 100;
    decimals: 0;
    show-text: true;
    percent: true;
    track-color: #2D2D30;
    progress-color: #007ACC;
    color: #CCCCCC;
    border-radius: 8;
}

兼容旧写法（双色槽别名）

progressbar#进度条2 {
    background-color: #1A2438;
    background-gradient-color: #00F0FF;
    pressed-background-color: #FF2EC4;
    background-gradient-direction: horizontal;
    border-radius: 2;
}

不确定忙碌

progressbar#忙碌条 {
    indeterminate: true;
    track-color: #3A3A40;
    progress-color: #00B4FF;
    show-text: false;
    border-radius: 4;
}

自定义环心文案（覆盖百分比）

progressbar#上传条 {
    value: 100;
    show-text: true;
    center-text: "完成";
    track-color: #2D2D30;
    progress-color: #00C853;
}

完整示例

progressbar#进度条1 {
    border-radius: 12;
    track-color: #E6E6EC;
    progress-color: #5B6FE8;
    progress-gradient: #FF6B9D;
    background-gradient-direction: horizontal;
    value: 66;
    min: 0;
    max: 100;
    show-text: true;
    percent: true;
    round-cap: true;
    color: #2A2A30;
    show-border: false;
}

/* 兼容旧写法（与上等价的双色填充） */
progressbar#进度条2 {
    background-color: #1A2438;
    background-gradient-color: #00F0FF;
    pressed-background-color: #FF2EC4;
    background-gradient-direction: horizontal;
    border-radius: 2;
}

progressbar:groove {
    background-color: #E6E6EC;
}

progressbar:chunk {
    background-gradient-color: #5B6FE8;
    background-color: #FF6B9D;
}