Menu 侧边栏菜单¶

为网站或应用提供导航的侧边栏。支持多级折叠子菜单、两种收起//展开模式（悬浮按钮模式和汉堡包按钮模式）以及漂亮的 Hover 和激活高亮。¶

基础用法¶

侧边栏菜单预览

from monkeyqt import MkMenu

# 创建一个带标题和图标的侧边栏菜单menu = MkMenu(title="控制台",  icon="House")
menu.add_item("dashboard", "仪表盘",  icon="Gauge")
menu.add_item("settings", "系统设置", icon="Gear")

多级子菜单¶

支持通过 MkSubMenu 实现多级树形折叠菜单

# 创建子菜单submenu = menu.add_submenu("用户管理", icon="Users")
# 往子菜单中添加菜单项menu.add_submenu_item(submenu, "user-list", "用户列表", icon="List")
menu.add_submenu_item(submenu, "user-role", "角色管理", icon="UserGear")

折叠模式¶

通过 collapse_mode 参数配置侧边栏的折叠交互： " - "floating" (默认)：在侧边栏右边框悬浮显示一个圆形的缩进按钮。 "- "hamburger"：在侧边栏顶部标题左侧显示三道杠汉堡包按钮进行折叠。

# 汉堡包折叠模式
menu = MkMenu(title="后台管理", collapse_mode="hamburger")

API 属性与方法¶

MkMenu 构造函数 &¶

MkMenu(title="", icon=None, collapse_mode="floating", item_height=50, parent=None)

参数	类型	默认值	说明
`title`	`str`	`""`	菜单栏顶部标题
`icon`	`str`	`None`	标题左侧的图标名称（（如 Phosphor 库图标名）
`collapse_mode`	`str`	`"floating"`	折叠交互模式，可选值为 `"floating"` " 或 " "`"hamburger"`
`item_height`	`int`	`50`	每个菜单项的高度（像素）

核心方法¶

方法名	参数	返回值	说明
`add_item(item_id, text, icon=None)`	`(str, str, str)`	`MkMenuItem`	添加一级菜单项
`add_submenu(title, icon=None)`	`(str, str)`	`MkSubMenu`	添加一个带折叠功能的二级子菜单容器
`add_submenu_item(submenu, item_id, text, icon=None)`	`(MkSubMenu, str, str, str)`	`MkMenuItem`	在指定的子菜单下添加子项
`set_active(item_id)`	`(str)`	`None`	代码控制高亮某项（自动取消其他项高亮）
`toggle_collapse()`	`()`	`None`	切换菜单的折叠//展开状态
`set_border_right(border_style)`	`(str)`	`None`	自定义右侧边框样式（（如 " "`"none"` " 或 " "`"1px solid #dcdfe6"`" ）

信号¶

信号名称	参数	说明
`itemClicked`	`(str)`	当任意菜单项被点击时触发，参数为 `item_id`

示例代码¶

import sys
from PySide6.QtWidgets import QApplication, QMainWindow, QHBoxLayout, QWidget, QLabel, QStackedWidget
from monkeyqt import MkMenu

class MenuDemo(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("MkMenu Demo")
        self.resize(800, 600)

        # 主窗口布局
        main_widget = QWidget()
        self.setCentralWidget(main_widget)
        layout = QHBoxLayout(main_widget)
        layout.setContentsMargins(0, 0, 0, 0)
        layout.setSpacing(0)

        # 1. 创建左侧菜单
        self.menu = MkMenu(title="monkeyqt", icon="AppWindow", collapse_mode="floating")
        layout.addWidget(self.menu)

        # 2. 右侧内容区域
        self.stacked_widget = QStackedWidget()
        layout.addWidget(self.stacked_widget, stretch=1)

        # 添加一些测试页面        self.page_dashboard = QLabel("仪表盘主页" ))
        self.page_users = QLabel("用户列表页面")
        self.page_settings = QLabel("系统设置页面")

        for page in [self.page_dashboard, self.page_users, self.page_settings]:
            page.setStyleSheet("font-size: 24px; font-weight: bold; qproperty-alignment: AlignCenter;")
            self.stacked_widget.addWidget(page)

        # 3. 添加菜单项并建立关联
        self.menu.add_item("dashboard", "仪表盘",  icon="Gauge")

        submenu = self.menu.add_submenu("用户管理", icon="Users")
        self.menu.add_submenu_item(submenu, "users", "用户列表", icon="UserList")

        self.menu.add_item("settings", "系统设置", icon="Gear")

        # 绑定点击信号进行页面切换
        self.menu.itemClicked.connect(self._on_menu_clicked)

        # 默认选中仪表盘        self.menu.set_active("dashboard")

    def _on_menu_clicked(self, item_id):
        if item_id == "dashboard":
            self.stacked_widget.setCurrentWidget(self.page_dashboard)
        elif item_id == "users":
            self.stacked_widget.setCurrentWidget(self.page_users)
        elif item_id == "settings":
            self.stacked_widget.setCurrentWidget(self.page_settings)

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = MenuDemo()
    window.show()
    sys.exit(app.exec())