选择器： listbox · 设计器组件： 列表框 · 按名称： listbox#名称 或 #名称
用途： 单列/多列项目列表，支持单选/多选、勾选、图标与角标。
硬约束与叠画
- 控件名来自窗口 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=列表，1=图标，2=矩阵 |
当前索引 |
整数 |
读写 |
0 起，对应项目列表行号 |
多选 |
逻辑 |
读写 |
兼容旧属性：真=多选(1)，假=单选(0)。推荐用「选择模式」。 |
选择模式 |
整数 |
读写 |
0=单选，1=多选，2=不可选 |
交替行色 |
逻辑 |
读写 |
真=奇数行浅底色 |
显示勾选 |
逻辑 |
读写 |
真=列表模式左侧显示勾选框（仅显示模式为「列表」时生效） |
关闭按钮位置 |
整数 |
读写 |
0=右中，1=右下，2=左上，3=左下，4=右上，5=左中 |
排序启用 |
逻辑 |
读写 |
真=加入/插入项目后自动按文本排序 |
文字省略 |
整数 |
读写 |
0=无，1=尾部省略，2=中间省略 |
当前文本 |
文本 |
只读 |
当前选中项文本（只读） |
行高 |
整数 |
读写 |
列表行/单元格高度（像素） |
单元格宽度 |
整数 |
读写 |
图标/矩阵模式：0=自动均分宽度；>0=固定像素 |
矩阵列数 |
整数 |
读写 |
矩阵模式：0=按单元格宽度自动计算列数；>0=固定列数 |
图标大小 |
整数 |
读写 |
项图标边长（像素） |
滚动条宽度 |
整数 |
读写 |
6～32 像素 |
项间距 |
整数 |
读写 |
图标/矩阵模式项间距 |
列表图标位置 |
整数 |
读写 |
列表模式：0=左，1=右，2=上，3=下 |
可移动 |
逻辑 |
读写 |
真=允许拖动调整项目顺序（带动画） |
点空消选 |
逻辑 |
读写 |
真=点击列表空白处取消选中（默认真） |
显示滚动条 |
整数 |
读写 |
1=不显示，2=纵向，3=横向，4=两者；仅内容超出可视区时显示 |
项可关闭 |
逻辑 |
读写 |
真=每项右侧显示×可删除 |
圆角 |
整数 |
读写 |
像素，0=直角 |
显示边框 |
逻辑 |
读写 |
真=显示边框 |
边框大小 |
整数 |
读写 |
像素 |
边框颜色 |
文本 |
读写 |
如 #RRGGBB |
背景色 |
文本 |
读写 |
如 #1E1E1E |
方法
调用必须带括号。索引均从 0 起。下表为带类型签名。叠画见页首 绘制类。
枚举（属性/角标）
| 项 |
取值 |
| 显示模式 |
0列表 · 1图标 · 2矩阵 |
| 选择模式 |
0单选 · 1多选 · 2不可选 |
| 角标位置 |
0右 · 1左 |
| 列表图标位置 |
0左 · 1右 · 2上 · 3下 |
| 文字省略 |
0无 · 1尾部 · 2中间 |
| 方法 |
签名 |
返回 |
说明 |
置当前索引 |
无 置当前索引(整数 索引) |
无 |
|
取当前索引 |
整数 取当前索引() |
整数 |
|
加入项目 |
无 加入项目(文本 文本, [逻辑 禁用=假], [逻辑 可关闭=假], [文本 图标=""]) |
无 |
末尾追加 |
插入项目 |
无 插入项目(整数 索引, 文本 文本, [逻辑 禁用=假], [逻辑 可关闭=假], [文本 图标=""]) |
无 |
|
删除项目 |
无 删除项目(整数 索引) |
无 |
|
置项目文本 |
无 置项目文本(整数 索引, 文本 文本) |
无 |
|
取项目文本 |
文本 取项目文本(整数 索引) |
文本 |
|
取当前文本 |
文本 取当前文本() |
文本 |
|
取项目数 |
整数 取项目数() |
整数 |
|
清空 |
无 清空() |
无 |
清空全部项目（与组合框同名方法一致） |
置项目图标 |
无 置项目图标(整数 索引, 文本 图标) |
无 |
路径 |
置项目禁用 |
无 置项目禁用(整数 索引, 逻辑 禁用) |
无 |
|
置项目可关闭 |
无 置项目可关闭(整数 索引, 逻辑 可关闭) |
无 |
|
置项目角标 |
无 置项目角标(整数 索引, 文本 角标, [整数 位置=0], [文本 颜色=""]) |
无 |
空角标清除 |
取项目角标 |
文本 取项目角标(整数 索引) |
文本 |
|
取项目角标位置 |
整数 取项目角标位置(整数 索引) |
整数 |
0右/1左 |
滚动到项目 |
无 滚动到项目(整数 索引) |
无 |
|
取选中索引 |
整数数组 取选中索引() |
整数数组 |
多选多项 |
置项目选中 |
无 置项目选中(整数 索引, 逻辑 选中) |
无 |
|
全选 |
无 全选() |
无 |
多选 |
清除选中 |
无 清除选中() |
无 |
单选/多选 |
取消选中 |
无 取消选中() |
无 |
等同 清除选中 |
排序 |
无 排序([逻辑 升序=真]) |
无 |
|
查找项目 |
整数 查找项目(文本 文本, [整数 起始=0]) |
整数 |
未找到 -1 |
移动项目 |
整数 移动项目(整数 旧索引, 整数 新索引) |
整数 |
成功 1；触发「项顺序改变」 |
置项目勾选 |
无 置项目勾选(整数 索引, 逻辑 勾选) |
无 |
需「显示勾选」且列表模式 |
取项目勾选 |
整数 取项目勾选(整数 索引) |
整数 |
1/0 |
移动 |
无 移动(小数 左边, 小数 顶边, [小数 宽度], [小数 高度]) |
无 |
可选同时改宽高 |
置焦点 |
无 置焦点() |
无 |
|
刷新 |
无 刷新() |
无 |
|
显示 / 隐藏 |
无 显示() / 无 隐藏() |
无 |
等同 可见 = 真/假 |
置字体 |
逻辑 置字体(字体类 字体) |
逻辑 |
见 painter.md |
列表框1.加入项目("一项")
列表框1.置当前索引(0)
输出(列表框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 |
鼠标右键双击控件。 |
选中项改变 |
整数 当前索引, 文本 项目 |
当前选中项发生变化时触发（程序置索引、键盘切换或用户点击）。参数：整数 当前索引, 文本 项目。 |
项被激活 |
整数 当前索引, 文本 项目 |
双击某项或焦点在列表时按 Enter/空格确认时触发。参数：整数 当前索引, 文本 项目。 |
项被单击 |
整数 当前索引, 文本 项目 |
用户单击某一项时触发（含多选切换）。参数：整数 当前索引, 文本 项目。 |
项被双击 |
整数 当前索引, 文本 项目 |
用户双击某一项时触发。参数：整数 当前索引, 文本 项目。 |
项被删除 |
整数 当前索引, 文本 项目 |
项被关闭按钮或删除项目方法移除时触发。参数：整数 当前索引（删除前索引）, 文本 项目。 |
项勾选改变 |
整数 当前索引, 文本 项目, 逻辑 勾选 |
显示勾选时，用户点击勾选框或程序置勾选后触发。参数：整数 当前索引, 文本 项目, 逻辑 勾选（真=勾选，假=取消勾选）。 |
项顺序改变 |
整数 旧索引, 整数 新索引 |
拖动排序或移动项目后触发。参数：整数 旧索引, 整数 新索引。 |
函数 列表框1.单击 (整数 X, 整数 Y) {
// …
}
YSS 样式
以下为样式表（.yss）键与示例；写样式前请先读窗体 XML 取控件 名称 与 typeId，见 window-xml.md。
布局与子选择器
项子控件 / 伪类： listbox:item · listbox:item:hover · listbox:item:selected
样式概览
YSS 控制外框、行高亮、左侧选中指示条与滚动条配色。
伪状态与映射
伪态映射（ 必读）：
| 在伪态块 / 子选择器中写的键 |
实际落到控件的字段 |
listbox:item:selected { background-color } / background |
item-selected-background |
listbox:item:selected { color } |
item-selected-color |
listbox:item:hover { background-color } / background |
item-hover-background |
listbox:item:hover { color } |
item-hover-color |
:selected 伪类 |
与 :pressed 同义，均映射到 选中项 配色键 |
也可直接在基选择器写 item-selected-* / item-hover-* 等键，效果相同。
槽位复用注意： scrollbar-thumb-color 与 item-hover-background 共用 hoverBackColor 槽；scrollbar-track-color 与 disabled-background-color 共用 disabledBackColor 槽。若同时设置行悬停色与滑块色，后写入者覆盖前者。
属性说明（逐键）
本控件支持 YSS 通用属性速查 中的列表类子集；下表按「显示模式 → 选择/勾选 → 项配色 → 指示条 → 交替行 → 图标 → 滚动条 → 外壳 → 字体」展开。每条写清：作用、取值、绘制时机、注意点。
显示模式与布局
| 属性 |
作用 |
取值 / 范围 |
说明与注意 |
view-mode / display-mode |
列表显示模式 |
list/0 · icon/1 · matrix/grid/2 |
list=一行一项；icon=按 cell-width 流式多列；matrix=固定 matrix-columns 列网格。 |
row-height |
列表模式行高 |
像素，如 24–200 |
影响可见行数与滚动；图标/矩阵模式亦作单元格高度参考。 |
cell-width |
图标模式单元格宽 |
像素 0–400 |
仅 view-mode: icon 生效；列数由控件宽度自动推算。 |
matrix-columns |
矩阵模式列数 |
整数 1–64 |
仅 view-mode: matrix 生效。 |
item-spacing |
项间距 |
像素 0–64 |
图标/矩阵模式下单元格之间的间隙。 |
选择与勾选
| 属性 |
作用 |
取值 / 范围 |
说明与注意 |
selection-mode |
选择模式 |
single/0 · multi/1 · none/2 |
多选时 Ctrl+单击 切换项，Shift+单击 范围选中；none 仅浏览不选中。 |
show-checkboxes |
列表模式左侧勾选框 |
true / false |
对应属性「显示勾选」；仅 view-mode: list 时绘制。行为项：写入 YSS 会覆盖属性面板同名字段；若已在属性面板开启勾选，勿在 YSS 写 show-checkboxes: false 误关。 |
项配色（行高亮）
| 属性 |
作用 |
取值 / 范围 |
说明与注意 |
item-selected-background / selected-background-color |
选中行背景 |
颜色 |
选中且非禁用时铺满整行矩形（列表模式含指示条区域）。 |
item-selected-gradient / item-selected-background-gradient |
选中行渐变底 |
≥2 色，逗号分隔；可带 #RRGGBBAA |
首色同步到 item-selected-background；覆盖单色选中底。 |
item-selected-gradient-direction |
选中渐变方向 |
horizontal（默认）/ vertical |
仪表盘常用横向淡出。 |
item-hover-background |
悬停行背景 |
颜色 |
鼠标悬停且未选中时；与 scrollbar-thumb-color 共用槽位，见文首注意。 |
item-selected-color / selected-color |
选中行文字色 |
颜色 |
|
item-hover-color |
悬停行文字色 |
颜色 |
与行悬停背景独立槽位。 |
item-radius / item-border-radius |
选中/悬停行圆角 |
像素 0–64 |
旁路表；与 item-padding 配合胶囊高亮。 |
item-padding |
选中/悬停行内缩 |
像素 |
上下约半值、左右全值内缩。 |
也可用子选择器：
listbox:item:selected { background-color: #0E639C; color: #FFFFFF; }
listbox:item:hover { background-color: #3E3E42; }
选中指示条（左侧色条）
| 属性 |
作用 |
取值 / 范围 |
说明与注意 |
item-indicator / item-indicator-width |
选中项左侧色条宽度 |
像素 0–16；true≈3；false/none/0=关闭 |
仅选中行绘制；复用运行时 outerGlowSize 槽，不是外发光。 |
item-indicator-color |
指示条颜色 |
颜色，如 #00B4FF |
未设时回退 focus-border-color 或默认蓝 #1E88E5；设色时若宽度为 0 会自动启约 3px。 |
交替行
| 属性 |
作用 |
取值 / 范围 |
说明与注意 |
alternating-row-colors |
奇偶行交替底色 |
true / false |
仅对未选中、未悬停、非禁用行生效。 |
alternate-background-color |
交替行第二色 |
颜色 |
奇数行（1-based 第 2、4…项）底色；映射 backColor2。 |
图标与项资源
| 属性 |
作用 |
取值 / 范围 |
说明与注意 |
icon-size |
项图标边长 |
像素 8–128 |
列表模式受行高约束；图标/矩阵模式居中或按 icon-position 排布。 |
icon-position |
列表模式图标相对文字位置 |
left/0 · right/1 · top/2 · bottom/3 |
亦可用中文「左/右/上/下」；仅 view-mode: list 影响布局。 |
item-icons / page-icons |
按项序逗号分隔图标路径 |
如 :/img/a.png, :/img/b.png |
路径 :/ 相对 exe 根；项序与 XML/代码项顺序一致。 |
滚动条
| 属性 |
作用 |
取值 / 范围 |
说明与注意 |
scrollbar / scrollbar-policy |
滚动条显示策略 |
auto/0 · none/hidden/1 · vertical/2 · horizontal/3 · both/4 |
内容超出可视区时按策略绘制；always 等同纵向可用。 |
scrollbar-width |
滚动条宽度 |
像素约 6–32 |
|
scrollbar-track-color |
滚动条轨道色 |
颜色 |
映射 disabledBackColor 槽；与 disabled-background-color 互斥覆盖。 |
scrollbar-thumb-color |
滚动条滑块色 |
颜色 |
映射 hoverBackColor 槽；与 item-hover-background 互斥覆盖。 |
外壳 · 底板与描边
| 属性 |
作用 |
取值 / 范围 |
说明与注意 |
color |
常态项文字色 |
#RRGGBB / #RRGGBBAA（YSS） |
未选中、未悬停、非禁用行。8 位为 CSS 顺序，见 YSS.md。 |
background-color / background |
列表区背景色 |
颜色 |
整控件内容区底色；不用 focusBackColor 盖选中（选中走行级 item-selected-*）。 |
transparent-background |
不铺列表底板 |
true / false |
仍绘制边框与行项。 |
opacity |
整控不透明度 |
0–100 |
100=不透明。 |
show-border |
是否画外框 |
true / false |
|
border-color |
外框色 |
颜色 |
获焦时若设 focus-border-color 可高亮边框。 |
border-width |
外框宽 |
像素 |
|
border-radius / corner-radius |
外框圆角 |
像素 0–64 |
|
border-style |
线型 |
见 button.md 枚举 |
列表框外框支持实线/虚线等；不是选项卡 tab-indicator。 |
transition |
悬停/选中过渡 |
如 color 150ms ease-out |
设计器静态预览；运行时对行色插值有限。 |
字体
| 属性 |
作用 |
取值 / 范围 |
说明与注意 |
font-size |
项文字字号 |
整数像素，如 13 |
DIP。 |
font-family |
字体族 |
字符串 |
含空格须加引号。 |
font-bold |
粗体 |
true / false |
|
font-italic |
斜体 |
true / false |
|
设计器 / 代码属性（非 YSS 键，但常与样式联用）
| 说明 |
备注 |
| 「关闭按钮位置」 |
属性 vAlign：0 右中 · 1 右下 · 2 左上 · 3 左下 · 4 右上 · 5 左中；项需 置项目可关闭 或插入时可关闭。 |
| 勾选框 |
仅「显示模式」= 列表 且「显示勾选」= 真（或 YSS show-checkboxes: true）时出现。 |
使用示例
基础列表 + 选中色
listbox#列表框1 {
view-mode: list;
selection-mode: single;
row-height: 28;
background-color: #2D2D30;
color: #CCCCCC;
item-selected-background: #0E639C;
item-selected-color: #FFFFFF;
border-radius: 4;
show-border: true;
border-color: #3F3F46;
font-size: 13;
}
多选 + 勾选 + 左侧指示条
listbox#任务列表 {
view-mode: list;
selection-mode: multi;
show-checkboxes: true;
row-height: 32;
item-selected-background: #094771;
item-hover-background: #3E3E42;
item-indicator: 3;
item-indicator-color: #00B4FF;
}
交替行 + 滚动条
listbox#文件列表 {
alternating-row-colors: true;
alternate-background-color: #252526;
scrollbar-width: 10;
scrollbar-track-color: #2D2D30;
scrollbar-thumb-color: #686868;
/* 注意：scrollbar-thumb-color 与 item-hover-background 同槽，二选一或接受后者覆盖 */
}
子选择器写法（等价于 item-* 键）
listbox:item:selected {
background-color: #0E639C;
color: #FFFFFF;
}
listbox:item:hover {
background-color: #3E3E42;
color: #FFFFFF;
}
图标流式多列
listbox#图标墙 {
view-mode: icon;
cell-width: 72;
row-height: 80;
icon-size: 32;
item-spacing: 8;
item-icons: :/img/a.png, :/img/b.png, :/img/c.png;
}
完整示例
listbox#列表框1 {
view-mode: list;
selection-mode: multi;
show-checkboxes: true;
alternating-row-colors: true;
alternate-background-color: #252526;
row-height: 28;
icon-size: 16;
icon-position: left;
item-selected-background: #0E639C;
item-hover-background: #3E3E42;
item-selected-color: #FFFFFF;
item-hover-color: #FFFFFF;
item-indicator: 3;
item-indicator-color: #00B4FF;
scrollbar-width: 10;
scrollbar-track-color: #2D2D30;
scrollbar-thumb-color: #686868;
background-color: #2D2D30;
color: #CCCCCC;
border-radius: 4;
show-border: true;
border-color: #3F3F46;
font-size: 13;
}
listbox:item:selected {
background-color: #0E639C;
color: #FFFFFF;
}
listbox:item:hover {
background-color: #3E3E42;
}