选择器：
treeview· 设计器组件： 树形视图 · 按名称：treeview#名称或#名称
用途： 层级节点列表，支持展开/收起、勾选、图标与角标。
硬约束与叠画
- 控件名来自窗口 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=自动，1=不显示，2=纵向，3=横向(忽略)，4=两者(按纵向)；内容超出可视区时显示 |
滚动条宽度 |
整数 | 读写 | 6～32 像素 |
图标大小 |
整数 | 读写 | 节点图标边长（像素） |
圆角 |
整数 | 读写 | 像素，0=直角 |
显示边框 |
逻辑 | 读写 | 真=显示边框 |
边框大小 |
整数 | 读写 | 像素 |
边框颜色 |
文本 | 读写 | 如 #RRGGBB |
当前文本 |
文本 | 只读 | 当前选中节点文本（只读） |
允许编辑 |
逻辑 | 读写 | 真=可按 F2 或双击编辑节点文本 |
开启勾选 |
逻辑 | 读写 | 真=节点前显示复选框 |
联动勾选 |
逻辑 | 读写 | 真=勾选父节点时同步子节点 |
勾选三态 |
逻辑 | 读写 | 真=支持未选/选中/不确定 |
显示连线 |
逻辑 | 读写 | 真=显示分支连线与展开框；假=导航风格（只保留缩进层级） |
是否缩进 |
逻辑 | 读写 | 真=子级按层级水平缩进；假=全部左对齐 |
缩进方式 |
整数 | 读写 | 0=像素，1=Tab（按字号估算） |
缩进宽度 |
整数 | 读写 | 像素模式为每级像素（默认20）；Tab 模式为每级 Tab 个数（默认1） |
拖拽排序 |
逻辑 | 读写 | 真=同级节点可拖动排序 |
拖动动画 |
整数 | 读写 | 拖动时幽灵/吸附预设 0–9 |
交换动画 |
整数 | 读写 | 放下后交换位移动画预设 0–9 |
编辑快捷键 |
整数 | 读写 | 虚拟键码（如 #F2键=113、#Home键=36）；0=F2，-1=禁用键盘编辑 |
默认展开层级 |
整数 | 读写 | 0=全部展开（默认）；N=展开深度小于 N 的节点（根深度为 0） |
方法
调用必须带括号。节点索引从 0 起；根级父索引为 -1。下表为带类型签名。
| 常量 | 取值 |
|---|---|
| 角标位置 | 0右 · 1左 |
| 勾选 | 0未选 · 1选中 · 2不确定 |
| 查找失败 | 未找到返回 -1 |
| 方法 | 签名 | 返回 | 说明 |
|---|---|---|---|
置当前索引 |
无 置当前索引(整数 索引) |
无 | |
取当前索引 |
整数 取当前索引() |
整数 | |
加入节点 |
无 加入节点(文本 文本, [文本 图标=""]) |
无 | 根级 |
加入项目 |
无 加入项目(文本 文本) |
无 | 无图标的根项 |
加入子节点 |
无 加入子节点(整数 父索引, 文本 文本, [文本 图标=""]) |
无 | 父 -1=根 |
置项目图标 |
无 置项目图标(整数 索引, 文本 图标) |
无 | |
置项目角标 |
无 置项目角标(整数 索引, 文本 角标, [整数 位置=0], [文本 颜色=""]) |
无 | 位置 0右/1左 |
取项目角标 |
文本 取项目角标(整数 索引) |
文本 | |
取项目角标位置 |
整数 取项目角标位置(整数 索引) |
整数 | |
清空 |
无 清空() |
无 | |
删除项目 |
无 删除项目(整数 索引) |
无 | |
删除子树 |
无 删除子树(整数 索引) |
无 | |
取项目数 |
整数 取项目数() |
整数 | |
取项目文本 |
文本 取项目文本(整数 索引) |
文本 | |
置项目文本 |
无 置项目文本(整数 索引, 文本 文本) |
无 | |
取当前文本 |
文本 取当前文本() |
文本 | |
展开节点 |
无 展开节点(整数 索引) |
无 | |
折叠节点 |
无 折叠节点(整数 索引) |
无 | |
展开全部 |
无 展开全部() |
无 | |
折叠全部 |
无 折叠全部() |
无 | |
取节点已展开 |
整数 取节点已展开(整数 索引) |
整数 | 1/0 |
取勾选索引列表 |
整数数组 取勾选索引列表() |
整数数组 | |
取选中索引 |
整数 取选中索引() |
整数 | 同当前 |
取选中文本 |
文本 取选中文本() |
文本 | |
置项目勾选 |
无 置项目勾选(整数 索引, 整数 勾选) |
无 | 0未选 1选中 2不确定 |
取项目勾选 |
整数 取项目勾选(整数 索引) |
整数 | |
滚动到节点 |
无 滚动到节点(整数 索引) |
无 | |
取父索引 |
整数 取父索引(整数 索引) |
整数 | 根父=-1 |
取节点深度 |
整数 取节点深度(整数 索引) |
整数 | 根=0 |
取子节点数 |
整数 取子节点数(整数 索引) |
整数 | |
查找节点 |
整数 查找节点(文本 文本, [整数 起始=0]) |
整数 | 未找到 -1 |
移动 |
无 移动(小数 左边, 小数 顶边, [小数 宽度], [小数 高度]) |
无 | 可选同时改宽高 |
置焦点 |
无 置焦点() |
无 | |
刷新 |
无 刷新() |
无 | |
显示 / 隐藏 |
无 显示() / 无 隐藏() |
无 | 等同 可见 = 真/假 |
置字体 |
逻辑 置字体(字体类 字体) |
逻辑 | 见 painter.md |
树形视图1.加入节点("根")
树形视图1.加入子节点(0, "子项")
树形视图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 | 鼠标右键双击控件。 |
节点选中改变 |
整数 索引, 文本 项目文本 | 当前选中节点发生变化时触发（程序置索引、键盘切换或用户点击）。参数：整数 索引, 文本 项目文本。 |
节点被激活 |
整数 索引, 文本 项目文本 | 双击某节点或焦点在树上按 Enter/空格确认时触发。参数：整数 索引, 文本 项目文本。 |
节点被单击 |
整数 索引, 文本 项目文本 | 用户单击某一节点时触发。参数：整数 索引, 文本 项目文本。 |
节点被双击 |
整数 索引, 文本 项目文本 | 用户双击某一节点时触发。参数：整数 索引, 文本 项目文本。 |
即将展开 |
整数 索引, 文本 项目文本 | 节点即将展开前触发（用户点击展开符或程序展开）。参数：整数 索引, 文本 项目文本。 |
已展开 |
整数 索引, 文本 项目文本 | 节点已展开后触发。参数：整数 索引, 文本 项目文本。 |
即将收起 |
整数 索引, 文本 项目文本 | 节点即将折叠前触发。参数：整数 索引, 文本 项目文本。 |
已收起 |
整数 索引, 文本 项目文本 | 节点已折叠后触发。参数：整数 索引, 文本 项目文本。 |
节点勾选改变 |
整数 当前索引, 文本 项目, 逻辑 勾选 | 开启勾选时，用户点击勾选框或程序置勾选后触发。参数：整数 当前索引, 文本 项目, 逻辑 勾选。 |
节点顺序改变 |
整数 旧索引, 整数 新索引 | 拖拽排序移动节点后触发。参数：整数 旧索引, 整数 新索引。 |
节点被删除 |
整数 索引, 文本 项目文本 | 删除节点或子树后触发。参数：整数 索引, 文本 项目文本。 |
函数 树形视图1.单击 (整数 X, 整数 Y) {
// …
}
YSS 样式
以下为样式表（.yss）键与示例；写样式前请先读窗体 XML 取控件 名称 与 typeId，见 window-xml.md。
布局与子选择器
项子控件 / 伪类： treeview:item · treeview:item:hover · treeview:item:selected
样式概览
YSS 控制外框、行高亮（圆角/阴影）、复选框外观、缩进与树枝线。
伪状态与映射
伪态映射（ 必读）：
| 在子选择器 / 伪态块中写的键 | 实际落到控件的字段 |
|---|---|
treeview:item:selected { background-color } / background |
item-selected-background |
treeview:item:selected { color } |
item-selected-color |
treeview:item:hover { background-color } / background |
item-hover-background |
treeview: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槽。后写入者覆盖前者。行为项警告：
show-checkboxes、link-check、three-state-checkboxes写入 YSS 会覆盖属性面板同名字段。若已在属性面板开启勾选，勿在 YSS 写show-checkboxes: false误关；纯样式表若不需要改行为，建议不写这些键。
属性说明（逐键）
本控件支持 YSS 通用属性速查 中的列表类子集；下表按「行布局 → 勾选 → 缩进/树枝 → 行高亮 → 滚动条 → 外壳 → 字体」展开。每条写清：作用、取值、绘制时机、注意点。
行布局
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
row-height |
节点行高 | 像素，如 24–200 |
影响可见行数、展开符与图标垂直居中。 |
icon-size |
节点图标边长 | 像素 8–128 |
实际绘制受行高约束（不超过行高−边距）。 |
勾选（行为 + 外观）
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
show-checkboxes |
节点前复选框 | true / false |
对应属性「开启勾选」。行为项：覆盖属性面板；勿误写 false 关闭已开启的勾选。 |
link-check / linked-checkboxes |
父子联动勾选 | true / false |
对应属性「联动勾选」。行为项：覆盖属性面板；纯样式建议不写。 |
three-state-checkboxes / three-state-check |
勾选三态（半选） | true / false |
对应属性「勾选三态」。行为项：同上。 |
check-size / indicator-size |
复选框边长 | 像素 8–32 |
默认约 14。 |
indicator-background-color |
复选框背景色 | 颜色 | 未勾选框内填充。 |
indicator-border-color |
复选框边框色 | 颜色 | |
checkmark-color / mark-color |
勾选标记颜色 | 颜色 | 选中行上若与底色接近，运行时会自动改用高对比色。 |
缩进与树枝线
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
show-branch-lines / branch-lines / show-lines |
绘制层级连接线 | true / false |
连接父子节点的竖/横线。 |
indent / enable-indent |
启用层级缩进 | true / false |
false 时各级左对齐（仍可有展开符）。 |
indent-mode / indent-style |
缩进计量方式 | 像素/0 · Tab/1/制表符 |
影响每级递增量解释。 |
indent-width / indent-size |
每级缩进宽度 | 像素 0–256 |
默认约 18。 |
行高亮（选中 / 悬停）
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
item-selected-background |
选中行背景 | 颜色 | 铺满行宽（含缩进区左侧到右缘）。 |
item-hover-background |
悬停行背景 | 颜色 | 未选中行悬停；与 scrollbar-thumb-color 共用槽位。 |
item-selected-color |
选中行文字色 | 颜色 | |
item-hover-color |
悬停行文字色 | 颜色 | |
item-radius / item-border-radius / item-corner-radius |
选中/悬停行圆角 | 像素 0–64 |
胶囊形行高亮；0=直角铺满。 |
item-padding |
行高亮区内缩 | 像素 0–32 |
仅上下内缩（左右仍铺满行宽）；配合 item-radius 形成「行内胶囊」效果。 |
shadow / box-shadow |
选中行软阴影 | true / false |
与 item-radius 配合可模拟浮起；见 shadow-*。 |
shadow-color |
阴影色 | 颜色 | 常与 item-selected-background 同色。 |
shadow-blur |
模糊半径 | 0–64 |
|
shadow-offset-x / shadow-offset-y |
阴影偏移 | -64–64 |
只偏移阴影，不缩进行矩形。 |
shadow-style |
阴影风格 | soft / hard |
同按钮语义。 |
滚动条
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
scrollbar / scrollbar-policy |
滚动条策略 | auto/0 · vertical/1 · none/hidden/2 · always/3 |
树形视图无横向策略枚举；超出时纵向滚动。 |
scrollbar-width |
滚动条宽度 | 像素约 6–32 |
|
scrollbar-track-color |
轨道色 | 颜色 | 映射 disabledBackColor 槽。 |
scrollbar-thumb-color |
滑块色 | 颜色 | 映射 hoverBackColor 槽；与 item-hover-background 互斥覆盖。 |
外壳 · 底板与描边
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
color |
常态节点文字色 | #RRGGBB / #AARRGGBB |
未选中、非悬停行。 |
background-color / background |
控件背景色 | 颜色 | 行间隙/空白区底色；选中走 item-selected-*。 |
transparent-background |
不铺底板 | true / false |
|
opacity |
整控不透明度 | 0–100 |
|
show-border |
外框 | true / false |
|
border-color |
边框色 | 颜色 | |
border-width |
边框宽 | 像素 | |
border-radius / corner-radius |
外框圆角 | 像素 0–64 |
与行级 item-radius 独立。 |
transition |
行色过渡 | 如 background-color 150ms ease-out |
设计器静态预览为主。 |
字体
| 属性 | 作用 | 取值 / 范围 | 说明与注意 |
|---|---|---|---|
font-size |
节点字号 | 整数像素，如 13 |
DIP。 |
font-family |
字体族 | 字符串 | 含空格须加引号。 |
font-bold |
粗体 | true / false |
|
font-italic |
斜体 | true / false |
使用示例
胶囊选中行 + 阴影
treeview#树形视图1 {
row-height: 36;
border-radius: 16;
item-radius: 12;
item-padding: 6;
item-selected-background: #00B8A0;
item-selected-color: #FFFFFF;
box-shadow: true;
shadow-color: #00B8A0;
shadow-blur: 12;
shadow-offset-y: 3;
}
勾选 + 树枝线
treeview#资源树 {
row-height: 28;
show-checkboxes: true;
link-check: true;
show-branch-lines: true;
indent: true;
indent-width: 20;
check-size: 14;
indicator-background-color: #2D2D30;
indicator-border-color: #606060;
checkmark-color: #00B464;
}
子选择器写法
treeview:item:selected {
background-color: #094771;
color: #FFFFFF;
}
treeview:item:hover {
background-color: #2A2D2E;
color: #FFFFFF;
}
完整示例
treeview#树形视图1 {
row-height: 26;
scrollbar-width: 10;
icon-size: 18;
show-checkboxes: true;
link-check: true;
three-state-checkboxes: true;
check-size: 14;
indicator-background-color: #2D2D30;
indicator-border-color: #606060;
checkmark-color: #00B464;
show-branch-lines: true;
indent: true;
indent-width: 18;
background-color: #252526;
color: #CCCCCC;
border-radius: 4;
show-border: true;
border-color: #3F3F46;
item-hover-background: #2A2D2E;
item-selected-background: #094771;
item-hover-color: #FFFFFF;
item-selected-color: #FFFFFF;
item-radius: 6;
item-padding: 4;
scrollbar-track-color: #2D2D30;
scrollbar-thumb-color: #686868;
font-size: 13;
}
treeview:item:hover {
background-color: #2A2D2E;
}