菜单栏（menubar）

选择器： menubar · 设计器组件： 菜单栏 · 按名称： menubar#名称 或 #名称
用途： 窗体顶栏主菜单与下拉子菜单。

硬约束与叠画

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=自由
栏高度	整数	读写	菜单栏高度（像素）
项高度	整数	读写	下拉项行高（像素）
助记符	逻辑	读写	真=显示 & 助记符下划线
显示勾选	逻辑	读写	真=下拉子项左侧显示勾选框
勾选框大小	整数	读写	下拉子项勾选框边长（像素，默认14）
显示边框线	逻辑	读写	真=显示菜单栏边框
边框大小	整数	读写	边框线粗细（像素）
边框线颜色	文本	读写	如 #RRGGBB
文字色	文本	读写	如 #RRGGBB
背景色	文本	读写	空=透明；如 #RRGGBB
透明背景	逻辑	读写	真=不绘制栏背景（默认真）
悬停文字色	文本	读写	如 #FF6644
悬停背景色	文本	读写	如 #3E3E42

方法

调用必须带括号。索引从 0 起（含主菜单与子项）。加入子菜单/加入分割线 的 父索引=-1 → 最后一个主菜单。勾选需属性「显示勾选」。下表为带类型签名。

方法	签名	返回	说明
取项目数	整数 取项目数()	整数	主菜单+子项总数
取项目文本	文本 取项目文本(整数 索引)	文本	索引从 0
置项目文本	无 置项目文本(整数 索引, 文本 文本)	无
清空	无 清空()	无
删除项目	无 删除项目(整数 索引)	无
加入主菜单	无 加入主菜单(文本 文本, [文本 图标=""])	无
加入子菜单	无 加入子菜单(整数 父索引, 文本 文本, [文本 图标=""])	无	父 -1=最后一个主菜单
加入分割线	无 加入分割线([整数 父索引=-1])	无
置项目禁用	无 置项目禁用(整数 索引, 逻辑 禁用)	无
置项目图标	无 置项目图标(整数 索引, 文本 图标)	无
置项目勾选	无 置项目勾选(整数 索引, 逻辑 勾选)	无	需「显示勾选」
取项目勾选	整数 取项目勾选(整数 索引)	整数	1/0
取勾选索引列表	整数数组 取勾选索引列表()	整数数组
置全部可勾选	无 置全部可勾选(逻辑 可勾选)	无	并自动开「显示勾选」
移动	无 移动(小数 左边, 小数 顶边, [小数 宽度], [小数 高度])	无	可选同时改宽高
置焦点	无 置焦点()	无
刷新	无 刷新()	无
显示 / 隐藏	无 显示() / 无 隐藏()	无	等同 可见 = 真/假
置字体	逻辑 置字体(字体类 字体)	逻辑	见 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	鼠标右键双击控件。
项被单击	整数 索引, 文本 项目文本	用户点击下拉菜单中的某一项时触发。
勾选状态改变	整数 当前索引, 文本 项目, 逻辑 勾选	显示勾选时，用户点击勾选框或程序置勾选后触发。

函数 菜单栏1.单击 (整数 X, 整数 Y) {
    // …
}

YSS 样式

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

布局与子选择器

默认透明背景、尺寸模式=自由（改 YSS 几何/配色不会把栏拉满窗宽；需随窗同宽请在设计器设「尺寸模式=自适应」或代码 尺寸模式 = 0）。

项 / 下拉子控件： menubar:item · menubar:item:hover · menubar:dropdown（或 :drop-down / :popup）

样式概览

YSS 控制顶栏外壳、顶栏项悬停、下拉面板、子项悬停与勾选框外观。

伪状态与映射

伪态映射（ 必读）：

在伪态块 / 子选择器中写的键	实际落到控件的字段
menubar:item:hover { background-color } / background	item-hover-background → hover-background-color
menubar:item:hover { color }	item-hover-color → hover-color
menubar:dropdown { background-color } / background	dropdown-background-color（下拉面板底色，映射 backColor2）
:hover { background-color } / background（基选择器伪态）	hover-background-color
:hover { color }	hover-color

也可直接在基选择器写 hover-* / dropdown-background-color / item-hover-* 等键，效果相同。

行为项警告： show-checkboxes 写入 YSS 会覆盖属性「显示勾选」。若已在属性面板开启，勿写 show-checkboxes: false 误关。
悬停文字： 顶栏与下拉项悬停时背景走 hover-background-color / item-hover-background；文字色当前仍以 color 为准，hover-color 已写入字段但运行时未单独换字色。

属性说明（逐键）

本控件支持 YSS 通用属性速查 中的栏类子集；下表按「尺寸 → 下拉勾选 → 顶栏/下拉配色 → 下拉面板 → 助记符 → 外壳 → 字体」展开。每条写清：作用、取值、绘制时机、注意点。

尺寸与行高

属性	作用	取值 / 范围	说明与注意
bar-height	顶栏高度	像素 20–64；默认约 28	映射 paddingT；吸附顶部时决定菜单栏占用高度。
item-height / dropdown-item-height	下拉子项行高	像素 16–48；默认约 24	映射 paddingB；仅影响下拉面板的每一行高度，不改变顶栏主菜单文字区。

下拉勾选（行为 + 外观）

属性	作用	取值 / 范围	说明与注意
show-checkboxes	下拉子项显示勾选框	true / false	对应属性「显示勾选」；勾选框仅出现在下拉子菜单项，不在顶栏主菜单文字旁。行为项：覆盖属性面板。
check-size / indicator-size	勾选框边长	像素 8–32；默认约 14	check-size 同时写入 indicator-size 旁路与 imageSize；控制下拉左侧勾选方块尺寸。
indicator-background-color	勾选框背景色	颜色，如 #2D2D30	未勾选时的方框内填充。
indicator-border-color	勾选框边框色	颜色，如 #707070
checkmark-color / mark-color	勾选标记颜色	颜色，如 #00B464	勾选态对勾颜色。

顶栏与下拉项配色

属性	作用	取值 / 范围	说明与注意
color	顶栏主菜单与下拉项文字色	#RRGGBB / #AARRGGBB	常态文字；悬停时背景变但字色仍用本键（见文首注意）。
hover-color / item-hover-color	悬停文字色（字段）	颜色	写入 hoverForeColor；与 menubar:item:hover { color } 等价。运行时顶/下拉字色仍以 color 绘制。
hover-background-color / item-hover-background	悬停背景色	颜色，如 #3E3E42	顶栏主菜单项悬停/展开时铺底；下拉子项鼠标悬停时铺整行。
dropdown-background-color	下拉面板背景色	颜色，如 #2D2D30	映射 backColor2；亦可用 menubar:dropdown { background-color }。

助记符

属性	作用	取值 / 范围	说明与注意
show-mnemonic	显示助记符下划线	true / false	对应属性「助记符」；菜单文本中 & 前缀字符会显示下划线。

外壳 · 底板与描边

属性	作用	取值 / 范围	说明与注意
background-color / background	顶栏底板色	颜色；transparent / none = 透明	设非透明色会自动关闭 transparent-background。新菜单栏默认透明。
transparent-background	不绘制顶栏底色	true / false	true（默认）时只画边框/文字/悬停块；下拉面板仍用 dropdown-background-color。
show-border	是否画顶栏边框	true / false
border-color	顶栏边框色	颜色
border-width	顶栏边框宽	像素 0–20
border-radius	顶栏圆角	像素 0–200	吸附顶栏时通常保持 0。
opacity	整控不透明度	0–100	100=不透明。

字体

属性	作用	取值 / 范围	说明与注意
font-size	菜单文字字号	整数像素，如 13	DIP。
font-family	字体族	字符串，如 "Microsoft YaHei UI"	含空格须加引号。
font-bold	粗体	true / false
font-italic	斜体	true / false

设计器 / 代码属性（非 YSS 键，常与样式联用）

说明	备注
位置	0=吸附顶部；1=自由摆放。
尺寸模式	0=自适应（随窗体宽度）；1=自由（设计时尺寸）。新菜单栏默认自由；拖动手柄也会自动切到自由。
菜单项列表	设计期树形菜单文本；运行时可用 API 动态构建。

---

使用示例

透明顶栏 + 深色下拉

menubar#菜单栏1 {
    bar-height: 28;
    item-height: 24;
    background-color: transparent;
    transparent-background: true;
    color: #F5F5F5;
    hover-background-color: #3E3E42;
    dropdown-background-color: #2D2D30;
    show-border: false;
    font-size: 13;
}

可勾选子项

menubar#菜单栏1 {
    show-checkboxes: true;
    check-size: 14;
    indicator-background-color: #2D2D30;
    indicator-border-color: #707070;
    checkmark-color: #00B464;
}

子选择器写法

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

menubar:dropdown {
    background-color: #252526;
}

---

完整示例

menubar {
    bar-height: 28;
    item-height: 24;
    color: #F5F5F5;
    font-size: 13;
    font-family: "Microsoft YaHei UI";
    transparent-background: true;
    hover-background-color: #3E3E42;
    dropdown-background-color: #2D2D30;
    show-border: false;
}

menubar#菜单栏1 {
    show-checkboxes: true;
    check-size: 14;
    indicator-background-color: #2D2D30;
    indicator-border-color: #707070;
    checkmark-color: #00B464;
    show-mnemonic: true;
    hover-color: #FFFFFF;
    item-hover-background: #3E3E42;
}

menubar#菜单栏1:item:hover {
    background-color: #45454A;
    color: #FFFFFF;
}

menubar#菜单栏1:dropdown {
    background-color: #2D2D30;
}

---