YSS · 工具栏（toolbar）

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

选择器： toolbar · 设计器组件： 工具栏 · 按名称： toolbar#名称 或 #名称

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

默认透明背景、尺寸模式=自由（改其它属性不会把栏拉满窗宽）。

专用属性

属性	说明	映射
`orientation` / `orient`	`0` 水平 / `1` 垂直（也可用 `horizontal` / `vertical`）	属性「方向」
`cover-menubar` / `cover-menu`	真=垂直吸附时通高覆盖并与菜单并排；假=竖条在菜单下（默认）	属性「覆盖菜单栏」
`exclusive`	真=可切换项互斥勾选	属性「互斥勾选」
`click-effect` / `press-effect`	`0`～`15`（见下表；也可用英文名）	属性「点击效果」
`bar-height`	横条最小高度 / 竖条最小宽度（像素）	属性「栏高度」
`icon-size`	按钮图标边长（8–128，默认 16）	属性「图标大小」
`button-style`	`0` 图标和文字 / `1` 仅图标 / `2` 仅文字 / `3` 图标在上 / `4` 图标在右 / `5` 图标在下	属性「按钮样式」
`item-min-width`	每项最小宽度，0=按文字自动	属性「项最小宽度」
`item-spacing`	相邻按钮间距	属性「项间距」
`icon-text-spacing`	图标与文字间距（默认 2）	属性「图文间距」
`wrap` / `multi-row`	真=横条换行 / 竖条多列；假=多余项进溢出菜单 `»`	属性「多行」
`show-border`	显示工具栏边框	属性「显示边框线」
`border-width`	边框粗细	属性「边框大小」
`border-color`	边框颜色	属性「边框线颜色」
`color`	文字色	属性「文字色」
`background-color`	背景；`transparent` / `none` = 透明背景	属性「背景色」+「透明背景」
`transparent-background`	真=不绘制栏底色（默认）	属性「透明背景」
`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`	勾选背景色	属性「勾选背景色」
`font-size` / `font-family`	字体	通用

点击效果数字：0下压（默认），1无，2变暗，3高亮，4缩放，5描边，6上浮，7透明，8填充，9下划线，10粗框，11内光，12外光，13反色，14圆点，15双框。

示例

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-spacing: 4;
    background-color: transparent;   /* 默认；改成 #2D2D30 则不透明 */
    color: #F5F5F5;
    hover-color: #FFFFFF;
    item-hover-background: #3E3E42;
    item-checked-color: #FFFFFF;
    item-checked-background: #0E639C;
}

toolbar:item:hover {
    background-color: #3E3E42;
    color: #FFFFFF;
}

toolbar:item:checked {
    background-color: #0E639C;
    color: #FFFFFF;
}

代码侧：全部属性

布局/通用：提示、左边、顶边、宽度、高度、可见、启用、句柄（只读）

工具栏专用：工具项列表、位置（0吸附顶部 / 1自由）、方向（0水平 / 1垂直）、尺寸模式（0自适应 / 1自由）、覆盖菜单栏（真/假）、栏高度、图标大小、按钮样式（0图标和文字 / 1仅图标 / 2仅文字 / 3图标在上 / 4图标在右 / 5图标在下）、点击效果（0～15）、项最小宽度、项间距、多行、互斥勾选、显示边框线、边框大小、边框线颜色、文字色、背景色、透明背景、悬停文字色、悬停背景色、勾选文字色、勾选背景色

代码里请写数字或真/假，不要手打「自适应」「水平」这类中文：

工具栏1.位置 = 0
工具栏1.方向 = 0
工具栏1.尺寸模式 = 1
工具栏1.覆盖菜单栏 = 真
工具栏1.按钮样式 = 0
工具栏1.点击效果 = 0

窗体上可以放多个工具栏（工具栏1、工具栏2…）。生成调用时按该窗体的控件类型表识别类型，不是靠名字猜。

交错占格： 项可设行跨/列跨。例如第一项行跨=2 占满一列两行高；第二、三项行跨=1 会在下一列上下叠放（默认上下间距 5px）。多行时，同一列只有一项且未设高度的，会自动铺满全部空行（设计时与运行时相同）。每项图标位置可单独设：0左 1右 2上 3下（-1=跟栏上的按钮样式）。无图标的纯文本项，文字默认水平垂直居中。

项宽高： 每项可设宽度/高度，0=自适应。也可调用 置项目宽度 / 置项目高度（与 置项目槽宽 / 置项目槽高 相同）。

多行： 属性「多行」=真。横条宽度不够时换行撑高；竖条则多列。

尺寸模式： 0自适应时宽/高由布局接管（改任意属性都会按窗体拉满）。1自由才能拖动手柄或在属性面板改几何「宽度」「高度」。新工具栏默认自由；拖动手柄也会自动切到自由。旧工程若仍是自适应，请在属性里改成「自由」。

嵌入控件： 调用 加入控件("下拉框") / 加入控件("按钮") 等，按组件类型名新建控件并放入工具栏（不必先在窗体上放「下拉框1」）。也可带宽高：加入控件("文本框", -1, 120, 24)。内部会生成唯一名称（如 __tb_下拉框_1）。工具项列表也可写 @下拉框，运行时首次布局会创建并改写为内部名。

图文间距： 栏属性「图文间距」控制图标与文字间距（默认 2）。单项可在工具项列表「图文间距」列覆盖（-1=跟栏）。多行撑开时，「图标在上/下」会把图标+文字作为整体垂直居中；仅有图标无文字时图标水平垂直居中。

代码侧：全部方法

通用对象方法：移动(左边, 顶边, [宽度], [高度])、置焦点()、刷新()、显示()、隐藏()

工具栏专用：

方法	说明
`取项目数()`	全部工具项数量
`取项目文本(索引)`	按索引取文本
`置项目文本(索引, 文本)`	按索引改文本
`清空()`	清空全部项
`删除项目(索引)`	删除指定项
`加入按钮(文本, [图标=""])`	末尾追加按钮
`加入分割线()`	末尾追加分割线
`加入控件(组件名, [位置=-1], [宽度=0], [高度=0])`	按类型名新建控件放入栏（如 `按钮`/`下拉框`），非嵌入窗体已有控件
`置项目图标位置(索引, 位置)`	`0`左 `1`右 `2`上 `3`下；`-1`跟栏
`置项目行跨(索引, 行数)`	`1`～`8`；`2`=占两行高
`置项目列跨(索引, 列数)`	`1`～`8`；沿栏方向宽度倍数
`置项目槽宽(索引, 宽度)` / `置项目宽度`	该项宽度像素，`0`=自适应
`置项目槽高(索引, 高度)` / `置项目高度`	该项高度像素，`0`=自适应；多行时单列一项铺满
`置项目禁用(索引, 禁用)`	设置禁用（分割线/嵌入项无效）
`置项目图标(索引, 图标)`	设置图标（`:/xxx.png`）
`查找项目(文本, [起始=0])`	按文本查找索引，未找到 -1
`置项目快捷键(索引, 快捷键)`	设置快捷键（如 `Ctrl+S`）；空文本清除
`取项目快捷键(索引)`	返回快捷键文本
`置项目勾选(索引, 勾选)`	设置勾选（自动标记为可切换；分割线无效）
`取项目勾选(索引)`	返回是否勾选

代码侧：全部事件

通用指针/焦点/键盘（与其它控件相同）：单击、双击、右键单击、鼠标按下、鼠标抬起、鼠标移动、鼠标进入、鼠标离开、获得焦点、失去焦点 等

工具栏专用：

事件	参数
`项被单击`	整数索引, 文本项目
`勾选状态改变`	整数索引, 文本项目, 逻辑勾选

完整示例

函数 主窗口.创建完毕 () {
    工具栏1.加入按钮("导出", ":/export.png")
    工具栏1.置项目快捷键(0, "Ctrl+E")
    // 默认项为 新建 / --- / 保存，索引 1 是分割线，请对 0 或 2 操作
    工具栏1.置项目勾选(0, 真)
    工具栏1.置项目禁用(2, 真)
    工具栏1.置项目行跨(0, 2)          // 第一项占两行
    工具栏1.置项目图标位置(2, 2)      // 保存：图标在上
    工具栏1.加入控件("下拉框")
    工具栏1.加入控件("文本框", -1, 120, 24)
}

函数 工具栏1.项被单击 (整数 索引, 文本 项目) {
    输出 (索引, 项目)
}

说明： 图标路径请用资源选择器得到的 :/... 形式。设计时与运行时均按原比例居中绘制。把「图标大小」设为 64 时，工具栏会按图标自动撑高。「多行」为否时，装不下的按钮进入溢出菜单 »（嵌入控件仍留在栏上）。垂直吸附默认不覆盖菜单栏；覆盖菜单栏 = 真 后竖条通高并与菜单并排。快捷键可在工具项列表「快捷键」列填写；焦点在文本框时，Ctrl+C/V/X/A/Z/Y 仍优先给编辑。行跨/列跨、每项图标位置、宽度/高度也可在「设置工具项列表」里改。无图标仅文本的项，文字水平垂直居中。