开关（switch）

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

选择器： switch · 设计器组件： 开关 · 按名称： switch#名称 或 #名称
用途： 二元切换控件（开/关）。

硬约束与叠画

控件名来自窗口 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）；只读
`标题`	文本	读写	开关旁显示的文字（可留空）
`开启`	逻辑	读写	真=开，假=关

方法

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

方法	签名	返回	说明
`置选中`	`无置选中([逻辑选中=真])`	无	也可属性 `选中`；开关：真=ON
`移动`	`无移动(小数左边, 小数顶边, [小数宽度], [小数高度])`	无	可选同时改宽高
`置焦点`	`无置焦点()`	无
`刷新`	`无刷新()`	无
`显示` / `隐藏`	`无显示()` / `无隐藏()`	无	等同 `可见 = 真/假`
`置字体`	`逻辑置字体(字体类字体)`	逻辑	见 painter.md

开关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	鼠标右键双击控件。
`选中改变`	整数 X, 整数 Y, 整数状态	选中状态发生变化；参数「状态」：1=选中，0=未选中，-1=不确定（单选框仅 0/1）。

函数 开关1.单击 (整数 X, 整数 Y) {
    // …
}

YSS 样式

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

样式概览

YSS 控制轨道 track（pill 胶囊底）、滑块圆点 thumb 与旁侧标签文字。

伪状态与映射

伪状态： :checked（开启）· :off（关闭）

伪态映射（必读）：

在伪态块中写的键	实际落到控件的字段
基选择器 / `:off { background-color }`	`background-color` → 运行时关闭轨道色（`backColor`）
`:checked { background-color }`	`background-gradient-color` → 运行时开启轨道色（`backColor2`）
`thumb-color`（任意块）	`pressedForeColor` → 滑块圆点色
`color`	旁侧标签文字色（`:checked` 块内 `color` 不自动映射为开启文字色）

也可直接在基选择器写 background-color（关轨）并在 :checked 块写 background-color（开轨），效果与上表相同。

注意： 开关没有 :hover / :focus / :disabled 专用 YSS 伪态键；禁用态由运行时整体降不透明度处理。轨道几何（宽/高比）由控件尺寸与运行时布局决定，YSS 不提供独立 track-width / track-height 键。

属性说明（逐键）

下表按「标签文字 → 轨道 track → 滑块 thumb → 伪态 → 几何说明」展开。每条写清：作用、取值、绘制时机、注意点。

标签文字

属性	作用	取值 / 范围	说明与注意
`color`	开关旁标签文字颜色	`#RRGGBB` / `#AARRGGBB`	标签在轨道右侧；文案来自控件 `文本` 属性或 XML。未设时用浅灰白。
`font-size`	标签字号	整数像素，如 `12`	DIP。
`font-family`	标签字体族	字符串，如 `"Microsoft YaHei UI"`	含空格须加引号。
`font-bold`	标签粗体	`true` / `false`
`font-italic`	标签斜体	`true` / `false`

标签与轨道水平排列：轨道在左，文字在右，间距约 8px（运行时/设计器一致）。

轨道（track）

属性	作用	取值 / 范围	说明与注意
`background-color` / `background`	关闭时轨道颜色	颜色，如 `#4A4A50`	映射 `backColor`；`:off` 块中写同一键等价。绘制为圆角胶囊矩形。
`border-radius`	轨道圆角	像素，如 `14`	大值≈胶囊形；实际轨道圆角由轨道高度推算（约为轨道高的一半）。

开启轨道色（二选一写法）：

写法	说明
`switch:checked { background-color: #9B6FD0; }`	推荐；`:checked` 的 `background-color` 映射为 `background-gradient-color` → 开启轨 `backColor2`
基选择器 `background-gradient-color`	直接写开启色槽；无法在同一规则块区分关/开，通常配合 `:checked` 使用

轨道几何（运行时/设计器，非 YSS 键）：

量	说明
轨道高度	≈控件高的 55%，clamp 约 14–22px
轨道宽度	≈控件宽的 38%，clamp 约 32–52px
轨道位置	靠控件左侧，垂直居中

未设关闭色时默认约 #555555；未设开启色且选中时默认约 #007ACC。

滑块（thumb）

属性	作用	取值 / 范围	说明与注意
`thumb-color`	滑块圆点颜色	颜色，如 `#FFFFFF`	映射 `pressedForeColor`；关/开两态默认共用同一 thumb 色，可在 `:checked` 块单独覆盖。

滑块几何（运行时/设计器，非 YSS 键）：

量	说明
形状	圆形
直径	≈轨道高 − 内边距（内边距≈轨道高的 12%）
位置	关闭时靠左；开启时靠右；切换时有动画

未设 thumb-color 时默认白色 #FFFFFF。

伪态配色速查

属性 / 伪态	作用
`background-color`（基 / `:off`）	关闭轨道色
`:checked { background-color }`	开启轨道色
`thumb-color`	滑块圆点色
`color`	标签文字色

禁用态

开关无 disabled-* YSS 键。禁用时运行时对整控（轨道+thumb+标签）乘以约 0.55 不透明度；设计器预览同逻辑。

使用示例

灰轨关、紫轨开

switch#开关1 {
    background-color: #4A4A50;
    thumb-color: #FFFFFF;
    border-radius: 14;
}
switch#开关1:checked {
    background-color: #9B6FD0;
}

带标签文字色

switch#夜间模式 {
    color: #CCCCCC;
    font-size: 12;
    background-color: #3A3A40;
    thumb-color: #F0F0F0;
}
switch#夜间模式:checked {
    background-color: #5B6FE8;
    color: #FFFFFF;
}

`:off` 显式关闭态（便于对照）

switch#开关1:off {
    background-color: #4A4A50;
}
switch#开关1:checked {
    background-color: #9B6FD0;
}

开启态单独改 thumb

switch#开关1 {
    thumb-color: #EEEEEE;
}
switch#开关1:checked {
    background-color: #00B4FF;
    thumb-color: #FFFFFF;
}

品牌色 ON + 深色 OFF

switch#通知 {
    background-color: #3A3A40;
    thumb-color: #CCCCCC;
    border-radius: 12;
    color: #D0D0D0;
}
switch#通知:checked {
    background-color: #00C853;
    thumb-color: #FFFFFF;
    color: #FFFFFF;
}

完整示例

switch#开关1 {
    background-color: #4A4A50;
    thumb-color: #FFFFFF;
    border-radius: 14;
    color: #D0D0D0;
    font-size: 12;
}

switch#开关1:off {
    background-color: #4A4A50;
}

switch#开关1:checked {
    background-color: #9B6FD0;
    color: #FFFFFF;
}