复选框（checkbox）

选择器： checkbox · 设计器组件： 复选框 · 按名称： checkbox#名称 或 #名称
用途： 二元/三态勾选。

硬约束与叠画

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）；只读
标题	文本	读写	复选框/单选框旁显示的文字
字体	文本	读写	字体名称，如 微软雅黑；读写：组件.字体 / 组件.字体 = “…”
字号	整数	读写	像素；读写：组件.字号 / 组件.字号 = 16
粗体	逻辑	读写	真=粗体；读写：组件.粗体 / 组件.粗体 = 真
斜体	逻辑	读写	真=斜体；读写：组件.斜体 / 组件.斜体 = 真
文字色	文本	读写	如 #FFFFFF 或 #RRGGBB
选中	逻辑	读写	真=选中，假=未选中
三态	逻辑	读写	真=可在 未选/选中/不确定 间切换
不确定	逻辑	读写	三态下的中间状态（仅设计预览/属性）

方法

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

方法	签名	返回	说明
置边框	无 置边框([逻辑 显示边框=真], [整数 边框大小=1], [文本 边框颜色], [整数 描边样式])	无	描边：0实 1虚 2点 3点划 4双点划
置选中	无 置选中([逻辑 选中=真])	无	也可属性 选中；开关：真=ON
移动	无 移动(小数 左边, 小数 顶边, [小数 宽度], [小数 高度])	无	可选同时改宽高
置焦点	无 置焦点()	无
刷新	无 刷新()	无
显示 / 隐藏	无 显示() / 无 隐藏()	无	等同 可见 = 真/假
置字体	逻辑 置字体(字体类 字体)	逻辑	见 painter.md

复选框1.置选中(真)
如果 (复选框1.选中) { 输出("已选") }

事件

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

事件	参数	说明
选中改变	整数 X, 整数 Y, 整数 状态	选中状态发生变化；参数「状态」：1=选中，0=未选中，-1=不确定（单选框仅 0/1）。

函数 复选框1.选中改变 (整数 X, 整数 Y, 整数 状态) {
    // …
}

YSS 样式

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

样式概览

视觉分两层：外壳（整卡背景/边框/阴影）与 指示器（左侧方框 + 勾号/横条）。

伪状态与映射

伪状态： :checked（选中）· :indeterminate（三态不确定）· :hover · :disabled · :focus

子控件： checkbox:indicator（与直接写 indicator-* 等价；写在 :indicator 块内的键仍用 indicator-* 名）

伪态映射（ 必读）：

在伪态块中写的键	实际含义
:checked { background-color } / color	映射为 指示器 选中填充 / 勾号色（indicator-checked-background-color / checkmark-color），不是外壳
:hover { color } / background-color	hover-color / hover-background-color（文字 / 外壳）
:indeterminate { … }	不确定态横条色等多用 indeterminate-color

改外壳选中态请用基选择器的 background-color + 运行时 选中 属性，或单独用卡片式外壳键，不要指望 :checked 的 background-color 改整卡。

属性说明（逐键）

标签文字

属性	作用	取值 / 范围	说明与注意
color	标签文字色	颜色，如 #2A2A30
font-size	字号	像素
font-family	字体族	字符串
font-bold / font-italic	粗体 / 斜体	true/false
hover-color / hover-text-color	悬停文字色	颜色	二者等效
disabled-color	禁用文字色	颜色

外壳（整卡）

属性	作用	取值 / 范围	说明与注意
background-color / background	外壳底板色	颜色	卡片风复选常用浅底。
transparent-background	不铺外壳底	true/false	默认透明时只显示指示器+文字。
border-color	外壳边框色	颜色
border-width	外壳边框宽	像素
border-radius	外壳圆角	像素
show-border	画外壳边框	true/false
padding / padding-*	内边距	像素 / 简写	影响指示器与文字相对位置。
background-gradient	外壳多停/双色渐变	≥2 色，逗号分隔	悬停若设了 hover-background-color 且正在悬停，优先悬停单色。
shadow / box-shadow	启用外壳阴影	true/false
shadow-color / shadow-blur / shadow-offset-x / shadow-offset-y	阴影色/模糊/偏移	同按钮
shadow-style	soft / hard	硬阴影=不透明偏移块	外壳后方绘制。
inner-shadow / inner-shadow-color / inner-shadow-blur	外壳内阴影	同按钮	深色凹卡效果。
hover-background-color	悬停外壳底	颜色
disabled-background-color	禁用外壳底	颜色
focus-border-color / focus-glow-color	焦点环	颜色
transition	悬停过渡	如 all 160ms ease-out	外壳/文字插值。
outer-glow / outer-glow-color / outer-glow-size	外壳外发光	同按钮	可选强调。

指示器尺寸与形状

属性	作用	取值 / 范围	说明与注意
indicator-size	指示器边长	约 8–48，如 22	正方形。
indicator-radius	指示器圆角	约 0–24	0=直角；≈一半边长≈圆。
indicator-spacing	指示器与文字间距	约 0–64

指示器颜色与渐变

属性	作用	取值 / 范围	说明与注意
indicator-background-color	未选中填充色	颜色，如 #FFFFFF
indicator-border-color	指示器描边色	颜色	选中时常与填充同色。
indicator-checked-background-color	选中填充色	颜色，如 #9B6FD0	单色选中底；与渐变二选一优先渐变。
indicator-background-gradient	指示器渐变填充	≥2 色，如 #FFB020, #FF5722	仅在选中（checked==1）时绘制；覆盖单色选中底。
checkmark-color	勾号「✓」颜色	颜色，如 #FFFFFF
indeterminate-color	三态不确定横条色	颜色，如 #FFB020	需控件开启三态。
hover-indicator-border-color	悬停时指示器边框	颜色
hover-indicator-background-color	悬停时指示器填充	颜色	未选中悬停高亮常用。

指示器自定义图片

属性	作用	说明与注意
indicator-checked-image / checked-image	选中态图片	有图则不再画矢量勾；路径如 :/img/check-square.png。
indicator-unchecked-image / unchecked-image	未选中态图片
indicator-indeterminate-image / indeterminate-image	不确定态图片

---

使用示例

描边卡片

checkbox#复选框1 {
    border-radius: 10;
    background-color: #F8F7FC;
    border-color: #C8B8FF;
    border-width: 2;
    show-border: true;
    transparent-background: false;
    padding-left: 8;
    padding-right: 12;
    indicator-size: 22;
    indicator-radius: 6;
    indicator-spacing: 8;
    indicator-background-color: #FFFFFF;
    indicator-border-color: #C8B8FF;
    color: #2A2A30;
}

选中单色

checkbox#复选框1:checked {
    indicator-checked-background-color: #9B6FD0;
    indicator-border-color: #9B6FD0;
    checkmark-color: #FFFFFF;
}

选中橙渐变指示器

checkbox#复选橙渐 {
    indicator-size: 20;
    indicator-radius: 5;
    indicator-border-color: #F97316;
    checkmark-color: #FFFFFF;
    indicator-background-gradient: #FFB020, #FF5722;
}
checkbox#复选橙渐:checked {
    indicator-border-color: #FF5722;
    indicator-background-gradient: #FFB020, #FF5722;
    checkmark-color: #FFFFFF;
}

子控件写法

checkbox#复选框1:indicator {
    indicator-size: 20;
    indicator-background-color: #2D2D30;
}

---

完整示例

checkbox#复选框1 {
    border-radius: 10;
    background-color: #F8F7FC;
    border-color: #C8B8FF;
    border-width: 2;
    show-border: true;
    transparent-background: false;
    padding-left: 8;
    padding-right: 12;
    indicator-size: 22;
    indicator-radius: 6;
    indicator-spacing: 8;
    indicator-background-color: #FFFFFF;
    indicator-border-color: #C8B8FF;
    color: #2A2A30;
    font-size: 13;
    transition: all 160ms ease-out;
}

checkbox#复选框1:hover {
    hover-indicator-border-color: #9B6FD0;
    hover-indicator-background-color: #F0EAFF;
    hover-color: #1A1A20;
}

checkbox#复选框1:checked {
    indicator-checked-background-color: #9B6FD0;
    indicator-border-color: #9B6FD0;
    checkmark-color: #FFFFFF;
}

checkbox#复选框1:indeterminate {
    indeterminate-color: #FFB020;
    indicator-border-color: #FFB020;
}

checkbox#图标勾:checked {
    checked-image: :/img/check-square.png;
}

---