PyQt-Fluent-Widgets 侧边导航栏 NavigationInterface 完全指南：结构、自定义菜单项与四种显示模式

PyQt-Fluent-Widgets 侧边导航栏 NavigationInterface 完全指南：结构、自定义菜单项与四种显示模式

发布时间：2026/9/26 18:57:54
PyQt-Fluent-Widgets 侧边导航栏 NavigationInterface 完全指南：结构、自定义菜单项与四种显示模式 桌面应用UI组件【免费下载链接】PyQt-Fluent-WidgetsA fluent design widgets library based on C Qt/PyQt/PySide. Make Qt Great Again.项目地址https://gitcode.com/gh_mirrors/py/PyQt-Fluent-Widgets点击查看免费下载PyQt-Fluent-Widgets 提供了 Fluent Design 风格的侧边导航组件NavigationInterface可与QStackedWidget组合构成标准的导航 内容区主窗口骨架。本篇以 docs/source/navigation.md 为线索结合仓库源码与示例系统讲解导航接口的整体结构、菜单项添加方式、自定义NavigationWidget的方法、routeKey 路由机制以及四种显示模式的切换规则帮助你快速搭建可折叠、可自定义的侧边导航界面。一、整体结构NavigationInterface NavigationPanel NavigationWidget从文档与源码看侧边导航由三层结构组成NavigationInterface对外暴露的导航接口容器继承自QWidget负责把导航面板与主窗口布局组织起来。在 navigation_interface.py 中它默认将自身宽度初始化为 48px对应折叠态的窄条宽度并设置WA_TranslucentBackground以支持亚克力等半透明效果。NavigationPanel真正承载菜单项的左侧面板继承自QFrame。NavigationInterface.__init__中创建了self.panel NavigationPanel(self)并把displayModeChanged信号转发给上层见 navigation_interface.py。NavigationWidget所有导航菜单项的基类。NavigationPanel内部按三个区域组织这些菜单项见 navigation_panel.pytopLayout顶部布局含返回按钮、菜单按钮与普通项scrollAreascrollLayout中部可滚动区域菜单项过多时可滚动bottomLayout底部布局通常放设置等项与 QStackedWidget 的搭配方式文档给出的标准用法是把NavigationInterface与QStackedWidget一起放入QHBoxLayout。参考示例 examples/navigation/navigation2/demo.pyself.hBoxLayout QHBoxLayout(self) self.navigationInterface NavigationInterface( self, showMenuButtonTrue, showReturnButtonTrue) self.stackWidget QStackedWidget(self) self.hBoxLayout.addWidget(self.navigationInterface) self.hBoxLayout.addWidget(self.stackWidget) self.hBoxLayout.setStretchFactor(self.stackWidget, 1)NavigationInterface构造函数签名为见 navigation_interface.pyNavigationInterface(parentNone, showMenuButtonTrue, showReturnButtonFalse, collapsibleTrue)参数默认值作用parentNone父窗口showMenuButtonTrue是否显示展开/折叠用的菜单按钮showReturnButtonFalse是否显示返回按钮配合路由历史使用collapsibleTrue导航面板是否可折叠二、向导航面板添加菜单项文档指出所有导航菜单项都应继承自NavigationWidget并通过NavigationInterface.addWidget()或NavigationPanel.addWidget()加入面板。对于最常见的图标 文字按钮PyQt-Fluent-Widgets 已实现子类NavigationPushButton并提供便捷方法NavigationInterface.addItem()一步创建。addItem()快速添加标准菜单项addItem() 的完整签名为addItem(routeKey: str, icon: Union[str, QIcon, FluentIconBase], text: str, onClickNone, selectableTrue, positionNavigationItemPosition.TOP, tooltip: str None, parentRouteKey: str None) - NavigationTreeWidgeticon支持字符串路径、QIcon或FluentIconBase如FluentIcon枚举selectable控制该项是否可被选中是否显示选中高亮返回值是NavigationTreeWidget即图标 文字 可选箭头的树形按钮。示例 examples/navigation/navigation2/demo.py 中的封装很好地展示了典型用法def addSubInterface(self, interface, icon, text: str, positionNavigationItemPosition.TOP): self.stackWidget.addWidget(interface) self.navigationInterface.addItem( routeKeyinterface.objectName(), iconicon, texttext, onClicklambda: self.switchTo(interface), positionposition, tooltiptext )这里用interface.objectName()作为routeKey点击时通过lambda切换QStackedWidget的当前子界面并把text同时作为悬停提示。addWidget()添加自定义菜单项addWidget() 的参数如下文档原样列出def addWidget( self, routeKey: str, widget: NavigationWidget, onClickNone, positionNavigationItemPosition.TOP, tooltip: str None, parentRouteKey: str None )各参数含义routeKey被添加项的唯一标识。文档用网页 URL来类比QStackedWidget中的子界面相当于网页routeKey相当于网页地址。切换子界面时NavigationPanel会把routeKey压入导航历史点击返回按钮时弹出栈顶的routeKey——若历史中还有其他routeKey则切换到对应的子界面否则回退到defaultRouteKey对应的界面。因此必须在程序运行前调用NavigationInterface.setDefaultRouteKey()见 navigation2/demo.py 中的注释与调用。widget要加入面板的NavigationWidget实例。onClick连接到该控件clicked信号的槽函数。如需在点击时切换子界面文档推荐写成lambda: self.stackWidget.setCurrentWidget(self.xxxInterface)。position插入面板的位置可取三种值对应 navigation_panel.py 中的NavigationItemPosition枚举NavigationItemPosition.TOP顶部布局NavigationItemPosition.SCROLL可滚动区域菜单项过多时可滚动查看NavigationItemPosition.BOTTOM底部布局。tooltip菜单项的悬停提示文本。需要说明的是源码在注册时会为该控件安装NavigationToolTipFilter只有面板处于折叠态isCompacted时才显示提示见 navigation_panel.py这与 Windows 导航栏的行为一致。parentRouteKey父级菜单项的 routeKey。父项必须是NavigationTreeWidgetBase的实例传入后该控件会成为树形菜单的子节点。其他常用 API从 navigation_interface.py 与 navigation_panel.py 可以看到面板还支持addSeparator(positionTOP)添加分隔线addItemHeader(text, positionTOP)/insertItemHeader()添加分组标题折叠时标题会以动画方式收起addUserCard(routeKey, avatar, title, subtitle, onClick, position, aboveMenuButton)添加用户卡片可设置头像、标题、副标题aboveMenuButtonTrue时可放在菜单按钮上方insertItem() / insertWidget(index, ...)在指定索引插入removeWidget(routeKey)按 routeKey 移除菜单项并同步清理路由历史setCurrentItem(name)以编程方式选中某个菜单项。三、自定义导航菜单项继承 NavigationWidget文档明确指出若要自定义菜单项应继承NavigationWidget并重写paintEvent()必要时重写setCompacted()。下面以文档中的头像项为例同时可在 examples/navigation/navigation2/demo.py 中查看完整版本from qfluentwidgets import NavigationWidget class AvatarWidget(NavigationWidget): Avatar widget def __init__(self, parentNone): super().__init__(isSelectableFalse, parentparent) self.avatar QImage(resource/shoko.png).scaled( 24, 24, Qt.KeepAspectRatio, Qt.SmoothTransformation) def paintEvent(self, e): painter QPainter(self) painter.setRenderHints( QPainter.SmoothPixmapTransform | QPainter.Antialiasing) painter.setPen(Qt.NoPen) if self.isPressed: painter.setOpacity(0.7) # draw background if self.isEnter: c 255 if isDarkTheme() else 0 painter.setBrush(QColor(c, c, c, 10)) painter.drawRoundedRect(self.rect(), 5, 5) # draw avatar painter.setBrush(QBrush(self.avatar)) painter.translate(8, 6) painter.drawEllipse(0, 0, 24, 24) painter.translate(-8, -6) if not self.isCompacted: painter.setPen(Qt.white if isDarkTheme() else Qt.black) font QFont(Segoe UI) font.setPixelSize(14) painter.setFont(font) painter.drawText(QRect(44, 0, 255, 36), Qt.AlignVCenter, zhiyiYo)基类提供哪些绘制状态从 navigation_widget.py 可以看到NavigationWidget为自定义绘制准备了丰富状态isPressed/isEnter按下与悬停状态由鼠标事件自动维护isCompacted面板是否处于紧凑折叠态。紧凑时控件固定为40 x 36展开时固定为EXPAND_WIDTH x 36其中EXPAND_WIDTH类属性默认312navigation_widget.py。自定义项应在paintEvent中根据该值决定是否绘制文字——头像示例正是通过if not self.isCompacted省略文字绘制isSelected/isAboutSelected选中态与即将选中态供指示条动画使用isSelectable是否可选中。头像示例传入False点击后不会出现选中高亮lightTextColor/darkTextColor/setTextColor()浅色与深色主题下的文字颜色indicatorRect()与setIndicatorColor()左侧选中指示条的位置与颜色。clicked信号在mouseReleaseEvent中发出见 navigation_widget.py所以自定义项的onClick参数会自然生效非可选中的项如头像点击后会走_onWidgetClicked中不可选中则弹出 flyout 菜单的分支逻辑见 navigation_panel.py。关于 setCompacted()基类的默认实现会直接切换控件尺寸并触发重绘。若你的自定义项在紧凑态需要不同布局如隐藏副标题、缩小头像可重写setCompacted()。仓库内置的NavigationUserCard就是一个典型紧凑态显示 24px 小头像并隐藏文字展开态以动画放大到 64px 头像并淡入标题与副标题见 navigation_widget.py。四、routeKey 路由机制与返回按钮文档把routeKey比作网页 URL其背后的实现是全局路由对象qrouterqfluentwidgets/common/router.py。NavigationPanel在初始化时把self.history qrouter作为自己的导航历史navigation_panel.py并做了两件事返回按钮的可用状态与qrouter.emptyChanged信号绑定历史为空时禁用返回按钮的clicked信号连接到qrouter.pop。历史如何记录Router内部按QStackedWidget维护各自的StackedHistoryrouter.pysetDefaultRouteKey(stacked, routeKey)设置默认路由历史列表的底部元素即默认 routeKeypush(stacked, routeKey)压入新路由若栈顶已是相同 routeKey 则忽略避免重复记录pop()弹出栈顶并调用goToTop()把QStackedWidget切换到当前栈顶 routeKey 对应的子界面栈空只剩默认项时回退到默认界面remove(routeKey)删除指定路由如removeWidget()时同步清理。标准接线方式参考 examples/navigation/navigation2/demo.py# 运行前必须设置默认路由 qrouter.setDefaultRouteKey(self.stackWidget, self.musicInterface.objectName()) self.stackWidget.currentChanged.connect(self.onCurrentInterfaceChanged) self.stackWidget.setCurrentIndex(1)其中onCurrentInterfaceChanged在界面切换时同步选中导航项并压入历史def onCurrentInterfaceChanged(self, index): widget self.stackWidget.widget(index) self.navigationInterface.setCurrentItem(widget.objectName()) qrouter.push(self.stackWidget, widget.objectName())五、四种显示模式Display Mode文档列出导航面板的四种显示模式对应 navigation_panel.py 中的NavigationDisplayMode枚举模式枚举值触发条件默认阈值EXPAND2大窗口宽度默认 1008px 及以上展开为带文字的左侧面板COMPACT1中等窗口宽度默认 1007px 及以下仅图标窄条MENU3窗口较窄1007px 及以下时手动展开为覆盖式菜单MINIMAL0小窗口下仅显示一个菜单按钮面板隐藏需自行管理按钮见 navigation3 示例默认阈值与源码实现默认阈值来自NavigationPanel的两个属性navigation_panel.pyself.expandWidth 322 # 面板展开宽度 self.minimumExpandWidth 1008 # 允许展开的最小窗口宽度展开时面板通过QPropertyAnimation在 48px 与expandWidth之间做 150ms、OutQuad缓动的宽度动画navigation_panel.py。判断进入EXPAND还是MENU的逻辑为navigation_panel.pyexpandWidth self.minimumExpandWidth self.expandWidth - 322 if (self.window().width() expandWidth and not self.isMinimalEnabled) or not self._isCollapsible: self.displayMode NavigationDisplayMode.EXPAND else: self.displayMode NavigationDisplayMode.MENU即默认情况下窗口宽度 ≥1008 322 - 322 1008时为EXPAND否则为MENU。窗口尺寸变化时面板通过事件过滤器自动切换模式navigation_panel.py窗口变窄且当前为EXPAND宽度 minimumExpandWidth时自动折叠窗口变宽且当前为COMPACT、且菜单按钮不可见时自动展开处于MENU模式时点击面板外区域自动收起。调整展开宽度调用NavigationInterface.setExpandWidth()可改变大窗口展开阈值文档原意。其底层实现为navigation_panel.pydef setExpandWidth(self, width: int): if width 42: return self.expandWidth width NavigationWidget.EXPAND_WIDTH width - 10注意两点宽度必须大于 42px 才会生效它同时会更新类属性NavigationWidget.EXPAND_WIDTH因此影响后续创建的菜单项展开宽度。相应地setMinimumExpandWidth()用于调整允许展开的最小窗口宽度这一阈值。MINIMAL 模式手动管理菜单按钮MINIMAL模式下NavigationPanel会隐藏自身仅留下一个菜单按钮且该按钮需要你自行布局管理。仓库示例 examples/navigation/navigation3/demo.py 展示了完整做法class NavigationBar(QWidget): Navigation widget def __init__(self, parentNone): super().__init__(parentparent) self.hBoxLayout QHBoxLayout(self) self.menuButton NavigationToolButton(FIF.MENU, self) self.navigationPanel NavigationPanel(parent, True) # isMinimalEnabledTrue self.titleLabel QLabel(self) self.navigationPanel.move(0, 31) self.hBoxLayout.setContentsMargins(5, 5, 5, 5) self.hBoxLayout.addWidget(self.menuButton) self.hBoxLayout.addWidget(self.titleLabel) self.menuButton.clicked.connect(self.showNavigationPanel) self.navigationPanel.setExpandWidth(260) self.navigationPanel.setMenuButtonVisible(True) self.navigationPanel.hide() # enable acrylic effect self.navigationPanel.setAcrylicEnabled(True)要点以NavigationPanel(parent, True)直接实例化面板第二个参数isMinimalEnabledTrue使其初始即处于MINIMAL模式自行创建NavigationToolButton作为菜单按钮点击时调用navigationPanel.expand()展开面板示例中showNavigationPanel做了show() raise_() expand()面板折叠后会自动隐藏见 navigation_panel.py 中_onExpandAniFinished对MINIMAL模式的处理该示例还开启了面板亚克力效果setAcrylicEnabled(True)在MENU模式下面板会以圆角覆盖式菜单呈现navigation_panel.py。六、其他实用配置与扩展除上述核心能力外NavigationInterface还暴露了若干开关navigation_interface.pyexpand(useAniTrue)/toggle()以编程方式展开或切换面板setMenuButtonVisible()/setReturnButtonVisible()控制菜单按钮与返回按钮显隐setCollapsible(collapsible)关闭折叠能力后面板将始终保持在展开状态setAcrylicEnabled(isEnabled)开启/关闭面板亚克力背景开启后需主题与平台支持setIndicatorAnimationEnabled()控制选中指示条是否使用滑动动画setUpdateIndicatorPosOnCollapseFinished()控制折叠动画结束后是否立即更新指示条位置widget(routeKey)按 routeKey 获取对应菜单项控件未注册的 key 会抛出RouteKeyError见 navigation_panel.py。关于另一种风格的导航界面仓库 examples/navigation/navigation1/demo.py 提供了对应的完整示例程序navigation2标准结构与navigation3MINIMAL 模式两个示例分别对应本文第二节与第五节的讲解可直接运行对照学习。小结本文围绕NavigationInterface梳理了从结构搭建、菜单项添加、自定义绘制到路由与显示模式的完整链路结构NavigationInterface内含NavigationPanel与QStackedWidget一起放入QHBoxLayout即可组成主窗口添加菜单项标准按钮用addItem()自定义控件用addWidget()并通过position控制 TOP / SCROLL / BOTTOM 三个区域自定义继承NavigationWidget重写paintEvent()必要时重写setCompacted()可直接利用isPressed / isEnter / isCompacted / isSelected等状态绘制路由routeKey配合全局qrouter实现历史记录与返回按钮运行前必须调用setDefaultRouteKey()显示模式EXPAND / COMPACT / MENU / MINIMAL四种模式随窗口宽度自动切换也可通过setExpandWidth()、setMinimumExpandWidth()调整阈值MINIMAL模式需自行管理菜单按钮参考 navigation3 示例。掌握这些 API 与源码实现细节后你就能按需定制出符合 Fluent Design 规范、且具备折叠/展开/最小化自适应能力的侧边导航界面。赞分享桌面应用UI组件【免费下载链接】PyQt-Fluent-WidgetsA fluent design widgets library based on C Qt/PyQt/PySide. Make Qt Great Again.项目地址https://gitcode.com/gh_mirrors/py/PyQt-Fluent-Widgets点击查看免费下载相关推荐Simple-Salesforce Bulk 2.0新特性解析为什么它比V1快10倍Simple Salesforce Bulk 2.0新特性解析为什么它比V1快10倍 Simple Salesforce是一款专为Python开发者设计的Sa后端开发工具PyQt-Fluent-Widgets 导航组件深度解析打造专业级侧边栏与选项卡界面PyQt Fluent Widgets 导航组件深度解析打造专业级侧边栏与选项卡界面 引言 在现代桌面应用开发中导航界面是用户体验的关键部分。PyQt Fl桌面应用UI组件CoreUI React侧边栏导航实战自定义菜单与权限控制CoreUI React侧边栏导航实战自定义菜单与权限控制 CoreUI React管理模板提供了强大的侧边栏导航系统通过简单的配置就能实现复杂的菜单结构和前端上一篇OpenCode 快速上手指南如何 5 步装好并跑通这个开源 AI 编程代理下一篇Salt 的 PostgreSQL Schema 管理状态模块salt.states.postgres_schema实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考