工具栏（toolbar）

选择器： toolbar · 设计器组件： 工具栏 · 按名称： toolbar#名称 或 #名称
用途： 图标/文字工具按钮条；可水平或垂直吸附。

硬约束与叠画

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）；只读
工具项列表	文本	读写	按钮、分隔线与 @控件名 嵌入槽
位置	整数	读写	0=吸附顶部，1=自由
方向	整数	读写	0=水平，1=垂直
尺寸模式	整数	读写	0=自适应（横条随窗宽/竖条随窗高），1=自由
覆盖菜单栏	逻辑	读写	真=垂直吸附时通高并与菜单并排；假=竖条在菜单栏下方（默认）
栏高度	整数	读写	横条最小高度 / 竖条最小宽度（像素）
图标大小	整数	读写	按钮图标边长（8～128，默认16）
按钮样式	整数	读写	0=图标和文字，1=仅图标，2=仅文字，3=图标在上，4=图标在右，5=图标在下
项最小宽度	整数	读写	0=按文字自动；>0 强制每项最小宽度
项间距	整数	读写	相邻按钮间距（像素，默认2）
图文间距	整数	读写	图标与文字间距（像素，默认2）
多行	逻辑	读写	真=横条换行/竖条多列；假=溢出菜单
互斥勾选	逻辑	读写	真=可切换项同组互斥（对标 QActionGroup）
显示边框线	逻辑	读写	真=显示工具栏边框
边框大小	整数	读写	边框线粗细（像素）
边框线颜色	文本	读写	如 #RRGGBB
文字色	文本	读写	如 #RRGGBB
背景色	文本	读写	空=透明；如 #RRGGBB
透明背景	逻辑	读写	真=不绘制栏背景（默认真）
悬停文字色	文本	读写	如 #FF6644
悬停背景色	文本	读写	如 #3E3E42
勾选文字色	文本	读写	如 #FFFFFF
勾选背景色	文本	读写	如 #0E639C

方法

调用必须带括号。索引从 0 起。图标位置：0左 1右 2上 3下 -1跟栏；行跨/列跨 1～8；槽宽/槽高/宽高 0=自适应。下表为带类型签名。

方法	签名	返回	说明
取项目数	整数 取项目数()	整数
取项目文本	文本 取项目文本(整数 索引)	文本
置项目文本	无 置项目文本(整数 索引, 文本 文本)	无
清空	无 清空()	无
删除项目	无 删除项目(整数 索引)	无
加入按钮	无 加入按钮(文本 文本, [文本 图标=""])	无
加入分割线	无 加入分割线()	无
置项目禁用	无 置项目禁用(整数 索引, 逻辑 禁用)	无
置项目图标	无 置项目图标(整数 索引, 文本 图标)	无
查找项目	整数 查找项目(文本 文本, [整数 起始=0])	整数	未找到 -1
加入控件	文本 加入控件(文本 组件名, [整数 位置=-1], [整数 宽度=0], [整数 高度=0])	文本	返回新控件名；位置 -1=末尾
置项目图标位置	无 置项目图标位置(整数 索引, 整数 位置)	无	见上枚举
置项目行跨	无 置项目行跨(整数 索引, 整数 行数)	无	1～8
置项目列跨	无 置项目列跨(整数 索引, 整数 列数)	无	1～8
置项目槽宽	无 置项目槽宽(整数 索引, 整数 像素)	无	0自适应
置项目槽高	无 置项目槽高(整数 索引, 整数 像素)	无	0自适应
置项目宽度	无 置项目宽度(整数 索引, 整数 像素)	无	0自适应
置项目高度	无 置项目高度(整数 索引, 整数 像素)	无	0自适应
置项目快捷键	无 置项目快捷键(整数 索引, 文本 快捷键)	无	如 Ctrl+S
取项目快捷键	文本 取项目快捷键(整数 索引)	文本
置项目勾选	无 置项目勾选(整数 索引, 逻辑 勾选)	无	项需可切换
取项目勾选	整数 取项目勾选(整数 索引)	整数
移动	无 移动(小数 左边, 小数 顶边, [小数 宽度], [小数 高度])	无	可选同时改宽高
置焦点	无 置焦点()	无
刷新	无 刷新()	无
显示	无 显示()	无	等同 可见 = 真
隐藏	无 隐藏()	无	等同 可见 = 假

工具栏1.加入按钮("保存", "save.png")
工具栏1.置项目快捷键(0, "Ctrl+S")

事件

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

事件	参数	说明
单击	整数 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.项被单击 (整数 当前索引, 文本 项目) {
    // …
}

YSS 样式

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

布局与子选择器

默认透明背景、尺寸模式=自由（改其它属性不会把栏拉满窗宽；需随窗同宽请在设计器设「尺寸模式=自适应」）。

样式概览

YSS 控制栏外壳、项悬停/勾选色与布局几何。

伪状态与映射

项伪类： toolbar:item · toolbar:item:hover · toolbar:item:checked（勾选）

伪态映射：

写法	实际字段
toolbar:item:hover { background-color } / color	item-hover-background / item-hover-color
toolbar:item:checked { background-color } / color	item-checked-background / item-checked-color
基选择器 :hover { … }	hover-*（整栏少用；优先项级）

属性说明（逐键）

方向与吸附

属性	作用	取值 / 范围	说明与注意
orientation / orient	栏方向	0/horizontal 水平；1/vertical 垂直
cover-menubar / cover-menu	竖条是否通高盖菜单	true/false	真=垂直吸附时通高并与菜单并排；假=竖条在菜单下（默认）
exclusive	可切换项互斥勾选	true/false	类似单选组

点击反馈与几何

属性	作用	取值 / 范围	说明与注意
click-effect / press-effect	按下视觉效果	0–15 或英文名	见下表
bar-height	横条最小高度 / 竖条最小宽度	像素
icon-size	按钮图标边长	8–128，默认 16
button-style	图文排布	0图标和文字 · 1仅图标 · 2仅文字 · 3图标在上 · 4图标在右 · 5图标在下	亦可用 icon-above 等名
item-min-width	每项最小宽度	0=按文字自动
item-spacing	相邻按钮间距	像素
icon-text-spacing	图标与文字间距	默认约 2
wrap / multi-row	换行/多列	true/false	真=横条换行/竖条多列；假=多余按钮进溢出菜单 »（嵌入控件不进溢出菜单）

click-effect 枚举（常见）： 0下压 · 1无 · 2变暗 · 3高亮 · 4缩放 · 5描边 · 6上浮 · 7透明 · 8填充 · 9下划线 · 10粗框 · 11内光 · 12外光 · 13反色 · 14圆点 · 15双框；亦可写 press 等实现别名。

项配色

属性	作用	说明与注意
color	常态文字色
hover-color / item-hover-color	项悬停文字色
hover-background-color / item-hover-background	项悬停背景
item-checked-color / checked-color / item-selected-color	勾选文字色
item-checked-background / checked-background-color / item-selected-background	勾选背景

外壳

属性	作用	说明与注意
background-color / background	栏底色	transparent/none=透明
transparent-background	不绘栏底	默认 true
show-border / border-width / border-color / border-radius	边框
font-size / font-family / font-bold / font-italic	字体

---

使用示例

壳 token：

@import "shell_tokens.yss";
toolbar {
    background-color: var(--bar);
    color: var(--fg);
    item-hover-background: var(--bar-hover);
    item-checked-background: var(--accent-deep);
}

竖条互斥图标在上：

toolbar#工具栏1 {
    orientation: vertical;
    exclusive: true;
    icon-size: 24;
    button-style: icon-above;
    wrap: true;
    item-hover-background: #3E3E42;
    item-checked-background: #0E639C;
    item-checked-color: #FFFFFF;
    transparent-background: true;
}

完整示例

toolbar#工具栏1 {
    orientation: vertical;
    cover-menubar: false;
    click-effect: press;
    exclusive: true;
    bar-height: 36;
    icon-size: 64;
    button-style: icon-above;
    wrap: true;
    item-min-width: 0;
    item-spacing: 4;
    icon-text-spacing: 2;
    background-color: transparent;
    transparent-background: true;
    color: #F5F5F5;
    hover-color: #FFFFFF;
    item-hover-background: #3E3E42;
    item-checked-color: #FFFFFF;
    item-checked-background: #0E639C;
    show-border: false;
}