选择器：
combobox· 设计器组件： 组合框 · 按名称：combobox#名称或#名称
用途： 下拉选取或（可编辑时）键入文本。
硬约束与叠画
- 控件名来自窗口 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）；只读 |
项目列表 |
文本 | 读写 | 每行一项 |
当前索引 |
整数 | 读写 | 0 起，对应项目列表行号 |
当前文本 |
文本 | 读写 | 当前显示文本 |
可编辑 |
逻辑 | 读写 | 真=可手动输入文本 |
最大可见项 |
整数 | 读写 | 下拉列表最多显示项数 |
圆角 |
整数 | 读写 | 像素，0=直角 |
显示边框 |
逻辑 | 读写 | 真=显示边框 |
边框大小 |
整数 | 读写 | 像素 |
边框颜色 |
文本 | 读写 | 如 #RRGGBB |
图标 |
字节集 | 读写 | 输入框左侧/右侧装饰图标（非下拉项图标） |
图标位置 |
整数 | 读写 | 0=左，1=右 |
图标大小 |
整数 | 读写 | 像素 |
项可关闭 |
逻辑 | 读写 | 真=每项右侧显示×可删除 |
方法
调用必须带括号。索引从 0 起。类库内部类型名多为「下拉框」；设计器组件仍为「组合框」。下表为带类型签名。
| 方法 | 签名 | 返回 | 说明 |
|---|---|---|---|
置当前索引 |
无 置当前索引(整数 索引) |
无 | |
取当前索引 |
整数 取当前索引() |
整数 | |
加入项目 |
无 加入项目(文本 文本, [逻辑 禁用=假], [逻辑 可关闭=假], [文本 图标=""]) |
无 | |
置项目图标 |
无 置项目图标(整数 索引, 文本 图标) |
无 | 下拉项图标路径 |
置项目禁用 |
无 置项目禁用(整数 索引, 逻辑 禁用) |
无 | |
置项目可关闭 |
无 置项目可关闭(整数 索引, 逻辑 可关闭) |
无 | |
清空 |
无 清空() |
无 | |
取项目数 |
整数 取项目数() |
整数 | |
取项目文本 |
文本 取项目文本(整数 索引) |
文本 | |
置图片样式 |
无 置图片样式([整数 图标位置=0], [整数 图片大小=16], [整数 图片模式=0], [整数 间距=4], [整数 透明度=100]) |
无 | 位置 0左/1右；模式 0固定/1等比；透明度 0～100 |
置字体 |
逻辑 置字体(字体类 字体) |
逻辑 | painter.md |
移动 |
无 移动(小数 左边, 小数 顶边, [小数 宽度], [小数 高度]) |
无 | 可选同时改宽高 |
置焦点 |
无 置焦点() |
无 | |
刷新 |
无 刷新() |
无 | |
显示 |
无 显示() |
无 | 等同 可见 = 真 |
隐藏 |
无 隐藏() |
无 | 等同 可见 = 假 |
组合框1.加入项目("选项A")
组合框1.置当前索引(0)
事件
在代码中写 函数 控件名.事件名(...) 处理。专用事件形参多为 整数 当前索引, 文本 项目：
| 事件 | 参数 |
|---|---|
当前索引改变 / 选中项 |
整数 当前索引, 文本 项目 |
即将下拉 / 下拉完成 / 即将收起 / 已收起 |
整数 当前索引, 文本 项目 |
其余鼠标/焦点事件见下表。
| 事件 | 参数 | 说明 |
|---|---|---|
单击 |
整数 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 | 鼠标右键双击控件。 |
当前索引改变 |
整数 当前索引, 文本 项目 | 当前选中项索引发生变化时触发（程序置索引或用户选择）。 |
选中项 |
整数 当前索引, 文本 项目 | 用户从下拉列表中选定一项时触发（对应 QComboBox::activated）。 |
即将下拉 |
整数 当前索引, 文本 项目 | 下拉列表即将展开时触发。 |
下拉完成 |
整数 当前索引, 文本 项目 | 下拉列表已展开显示后触发。 |
即将收起 |
整数 当前索引, 文本 项目 | 下拉列表即将收起时触发。 |
已收起 |
整数 当前索引, 文本 项目 | 下拉列表已收起后触发。 |
函数 组合框1.单击 (整数 X, 整数 Y) {
// …
}
YSS 样式
以下为样式表（.yss）键与示例；写样式前请先读窗体 XML 取控件 名称 与 typeId，见 window-xml.md。
样式概览
YSS 分三层：输入区外壳 chrome（文字/边框/渐变/阴影）、右侧箭头按钮、下拉列表面板与项（悬停/选中/指示条/滚动条）。
伪状态与映射
伪状态： :hover（悬停）· :focus（焦点）· :disabled（禁用）
子控件 / 项： combobox:drop-down · combobox:item · combobox:item:hover · combobox:item:selected
伪态映射（ 必读）：
| 在伪态块中写的键 | 实际落到控件的字段 |
|---|---|
:hover { color } / background-color |
hover-color / hover-background-color（输入区外壳） |
:focus { border-color } / background-color |
focus-border-color / focus-background-color |
:focus { outline-color } |
focus-glow-color（焦点外环光晕） |
:disabled { color } / background-color |
disabled-color / disabled-background-color |
combobox:item:hover { background-color } / color |
item-hover-background / item-hover-color |
combobox:item:selected { background-color } / color |
item-selected-background / item-selected-color |
combobox:drop-down { background-color } |
dropdown-background-color（下拉面板底色，非箭头按钮） |
combobox:drop-down { color } |
drop-down-arrow-color（箭头三角形色） |
combobox:drop-down { button-background-color } |
drop-down-button-background-color |
combobox:drop-down { button-hover-background-color } |
drop-down-button-hover-background-color |
combobox:drop-down { border-radius } |
popup-border-radius（下拉面板圆角） |
也可直接在基选择器写 hover-* / item-* / drop-down-* 等键，效果相同。
注意： 组合框上
padding简写只改左右内边距（padding-left/padding-right）；paddingT/paddingB字段已被max-visible-items/item-height占用，勿用四向padding期望改上下。
opacity无效： 组合框的imageOpacity内部存当前项索引，此键不能用于整控透明度。
属性说明（逐键）
本控件支持 YSS 通用属性速查 中的输入类外壳子集；下表按「输入区文字 → 输入区 chrome → 焦点与描边 → 下拉面板 → 下拉项 → 箭头按钮 → 滚动条 → 伪态 → 其它」展开。每条写清：作用、取值、绘制时机、注意点。
输入区 · 文字与字体
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
color |
输入区当前文字色 | #RRGGBB / #RRGGBBAA（YSS） |
显示已选项目文本；可编辑时为当前输入色。未设时运行时用深色主题默认浅灰白。8 位色格式见 YSS.md。 |
font-size |
字号 | 整数像素，如 13 |
DIP；过小难读，过大可能裁切。 |
font-family |
字体族 | 字符串，如 "Microsoft YaHei UI" |
含空格须加引号。 |
font-bold |
粗体 | true / false |
|
font-italic |
斜体 | true / false |
|
text-align |
输入区水平对齐 | left/0 · center/1 · right/2 |
有装饰图标时与 icon-position 共同排布。 |
editable |
是否可键入 | true / false |
false=只能从下拉选取；true=可手动输入或选项目。 |
placeholder / placeholder-text |
占位文字 | 字符串 | 仅可编辑且输入为空时显示；映射内部 tooltip 字段。 |
placeholder-color |
占位文字色 | 颜色，如 #888888 |
与 color 区分；运行时写入 foreColor2 旁路。 |
输入区 · 外壳（chrome）
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
background-color / background |
输入区底板色 | 颜色；background≡background-color |
仅输入区矩形，不含右侧箭头按钮区；与 dropdown-background-color 独立。 |
background-gradient / background-gradient-stops |
输入区多停/双色渐变 | ≥2 色，逗号/分号分隔，最多 8 | 不占用 dropdown-background-color（backColor2 留给下拉面板）。 |
background-gradient-color |
输入区渐变第二色 | 颜色 | 与 background-color 组成双色线性渐变。 |
background-gradient-direction |
输入区渐变方向 | vertical（默认）/ horizontal（或 1） |
仅影响输入区填充走向。 |
transparent-background |
不铺输入区底板 | true / false |
仍绘制边框/文字/箭头按钮（若未单独透明）。 |
padding-left / padding-right |
输入区左右内边距 | 像素 0–200 |
文字与边框间距。 |
padding |
简写内边距 | 如 8 12 |
只映射左右；上下字段另作他用，见文首注意。 |
margin / margin-left / margin-top / margin-right / margin-bottom |
绘制区外边距 | 像素 / 简写 | 在控件矩形内缩进背景区，不改 HWND 布局。 |
show-border |
是否画外框 | true / false |
为 false 时忽略线宽与 border-color。 |
border-color |
外框边框色 | 颜色 | 包裹输入区+箭头按钮整体外轮廓。 |
border-width |
外框边框宽 | 像素，如 1–20 |
|
border-radius |
外框圆角 | 像素，如 0–64 |
0=直角；与下拉 popup-border-radius 独立。 |
border-style |
线型 | solid/dashed/dotted 等 |
同按钮；组合框常用 solid。 |
shadow / box-shadow |
启用输入区阴影 | true / false |
true 时若未设模糊，常默认 shadow-blur: 4。 |
shadow-color |
阴影色 | 颜色 | |
shadow-blur |
软阴影模糊半径 | 0–64 |
0 且 offset≠0 → 硬阴影块。 |
shadow-offset-x / shadow-offset-y |
阴影偏移 | -64–64 |
|
shadow-style |
阴影风格 | soft（默认）/ hard |
hard=不透明偏移块，无模糊层。 |
transition |
悬停/文字过渡 | 如 all 180ms ease-out |
对 :hover 背景/文字插值；设计器静态预览。 |
输入区 · 焦点与描边
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
focus-border-color |
焦点边框色 | 颜色 | 也可用 :focus { border-color }。 |
focus-background-color |
焦点输入区底板色 | 颜色 | 也可用 :focus { background-color }。 |
focus-glow-color |
焦点外环光晕色 | 颜色 | 也可用 :focus { outline-color }；与 outline-color 同槽。 |
outline-color |
焦点环色（别名） | 颜色 | 映射 focus-glow-color。 |
outline-width |
焦点描边宽参考 | 像素 | 部分路径会映射到边框宽槽。 |
输入区 · 装饰图标
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
icon-size |
输入框装饰图标大小 | 约 8–128 像素 |
不是下拉每项左侧图标；项图标见代码 API。 |
icon-position |
装饰图标位置 | left/0 · right/1 · top/2 · bottom/3 |
相对输入文字排布。 |
下拉面板（drop-down popup）
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
dropdown-background-color |
下拉列表面板背景色 | 颜色，如 #252526 或 #252526FF |
弹出层整块底色；与输入区 background-color、箭头按钮底色三者独立。也可写 combobox:drop-down { background-color }。运行时面板按不透明绘制。YSS 8 位色为 #RRGGBBAA（勿写 #AARRGGBB，否则 alpha 错位会出现下拉「穿透」闪烁）。不透明请用 6 位 #RRGGBB。 |
max-visible-items / dropdown-max-items |
下拉最多可见行数 | 约 1–20，如 8 |
超出时出现垂直滚动条；影响面板总高度。 |
item-height / dropdown-item-height |
下拉每一行高度 | 约 16–48 像素，如 26 |
行高固定；与 max-visible-items 相乘决定面板高度。 |
popup-border-radius |
下拉面板圆角 | 像素 0–64 |
也可写 combobox:drop-down { border-radius }；映射 sliceL 槽。 |
下拉项（item）
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
item-hover-background |
项悬停背景色 | 颜色，如 #3E3E42 |
鼠标在下拉列表某行上；也可用 combobox:item:hover { background-color }。 |
item-hover-color |
项悬停文字色 | 颜色 | 也可用 combobox:item:hover { color }。 |
item-selected-background |
项选中背景色 | 颜色，如 #0E639C |
当前高亮行；也可用 combobox:item:selected { background-color }（内部映射 :pressed/:checked/:on）。 |
item-selected-color |
项选中文字色 | 颜色，如 #FFFFFF |
也可用 combobox:item:selected { color }。 |
item-indicator / item-indicator-width |
选中项左侧色条宽度 | 像素；true≈3；none/0/false 关闭 |
范围约 0–16；开启时若未设色条色会用默认蓝 #1E88E5。 |
item-indicator-color |
选中项左侧色条颜色 | 颜色，如 #00B4FF |
与 item-indicator 配合；设色会自动启用约 3px 宽条。 |
item-closable / closable-items |
每项右侧显示 × | true / false |
可关闭/删除该项；也可在代码中按索引 置项目可关闭。 |
下拉项图标、单项禁用、单项可关闭等可在代码中按索引设置。属性「图标 / 图标位置 / 图标大小」仅作用于输入框装饰；下拉每项图标请用
加入项目第 4 参数或置项目图标。
箭头按钮（drop-down chrome）
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
drop-down-button-background-color |
箭头按钮背景色 | 颜色 | 输入区右侧小按钮区；与下拉面板底色独立。别名：button-background-color · arrow-background-color；也可写 combobox:drop-down { button-background-color }。 |
drop-down-button-hover-background-color |
箭头按钮悬停背景色 | 颜色 | 鼠标在箭头区时。别名：button-hover-background-color · arrow-hover-background-color。 |
drop-down-arrow-color |
箭头三角形颜色 | 颜色 | 也可写 combobox:drop-down { color } 或 arrow-color。 |
下拉滚动条
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
scrollbar-width |
下拉列表滚动条宽度 | 约 4–24 像素，默认约 8 |
项数超过 max-visible-items 时显示；写入 YSS 旁路表，与文本框滚动条键语义不同。 |
scrollbar-track-color |
滚动条轨道色 | 颜色 | 下拉面板右侧轨道。 |
scrollbar-thumb-color |
滚动条滑块色 | 颜色 | 可拖动块。 |
scrollbar-color |
滑块+轨道简写 | 滑块色 [轨道色]，空格分隔 |
只写一个色时仅改滑块；两个色时前者滑块、后者轨道。 |
伪态配色键（可直接写，也可由伪态块映射）
| 属性 | 作用 |
|---|---|
hover-color |
悬停时输入区文字色 |
hover-background-color |
悬停时输入区底板色 |
focus-border-color |
焦点边框色 |
focus-background-color |
焦点输入区底板色 |
focus-glow-color |
焦点外环光晕色 |
disabled-color |
禁用时文字色 |
disabled-background-color |
禁用时输入区底板色 |
使用示例
深色不可编辑下拉
combobox#组合框1 {
color: #E0E0E0;
background-color: #2D2D30;
border-color: #5A5A5A;
border-width: 1;
border-radius: 4;
show-border: true;
font-size: 13;
editable: false;
max-visible-items: 8;
item-height: 26;
dropdown-background-color: #252526;
item-hover-background: #3E3E42;
item-selected-background: #0E639C;
item-selected-color: #FFFFFF;
}
下拉面板与项（子选择器写法）
combobox:drop-down {
background-color: #252526;
border-radius: 4;
}
combobox:item:hover {
background-color: #3E3E42;
}
combobox:item:selected {
background-color: #0E639C;
color: #FFFFFF;
}
箭头按钮 + 指示条 + 滚动条
combobox#组合框1 {
drop-down-button-background-color: #3A3A40;
drop-down-button-hover-background-color: #4A4A50;
drop-down-arrow-color: #CCCCCC;
item-indicator: 3;
item-indicator-color: #00B4FF;
scrollbar-width: 10;
scrollbar-track-color: #2A2A2A;
scrollbar-thumb-color: #6A6A6A;
}
输入区渐变 / 阴影（不占下拉底色槽）
combobox#组合框1 {
background-gradient: #2D2D30, #3A3A40;
background-gradient-direction: vertical;
shadow-color: #000000;
shadow-blur: 6;
dropdown-background-color: #252526;
}
可编辑 + 占位符
combobox#标签选择 {
editable: true;
placeholder: "选择或输入…";
placeholder-color: #888888;
padding-left: 8;
padding-right: 6;
transition: all 160ms ease-out;
}
焦点、悬停与禁用
combobox#组合框1:hover {
hover-background-color: #323236;
}
combobox#组合框1:focus {
focus-border-color: #007ACC;
focus-glow-color: #007ACC;
}
combobox#组合框1:disabled {
disabled-color: #888888;
disabled-background-color: #3A3A3A;
}
完整示例
combobox#组合框1 {
color: #E0E0E0;
background-color: #2D2D30;
border-color: #5A5A5A;
border-width: 1;
border-radius: 4;
show-border: true;
font-size: 13;
text-align: left;
editable: false;
max-visible-items: 8;
item-height: 26;
dropdown-background-color: #252526;
drop-down-button-background-color: #3A3A40;
drop-down-button-hover-background-color: #4A4A50;
drop-down-arrow-color: #CCCCCC;
item-hover-background: #3E3E42;
item-hover-color: #FFFFFF;
item-selected-background: #0E639C;
item-selected-color: #FFFFFF;
item-indicator: 3;
item-indicator-color: #00B4FF;
icon-size: 16;
icon-position: left;
scrollbar-width: 8;
transition: all 180ms ease-out;
}
combobox#组合框1:hover {
hover-background-color: #323236;
}
combobox#组合框1:focus {
focus-border-color: #007ACC;
focus-glow-color: #007ACC;
}
combobox:drop-down {
background-color: #252526;
border-radius: 4;
}
combobox:item:hover {
background-color: #3E3E42;
}
combobox:item:selected {
background-color: #0E639C;
color: #FFFFFF;
}