Qt导航栏组件E01：可折叠侧边栏

系列编号：E-01
导航风格：深色侧栏，丝滑切换图文/图标模式
适用场景：需适配不同分辨率的桌面业务系统、数据看板、工具类应用

一、引言

在桌面应用开发中，如何丝滑地切换图文/图标模式，实现这个需求时会遇到几个具体问题：

• 动画属性选择：直接用 setFixedWidth 跳变宽度会产生闪烁，QPropertyAnimation 需要一个可读写的 Q_PROPERTY 目标——fixedWidth 没有对应的 WRITE 方法，需要自定义中间属性才能驱动动画。
• 子控件的显隐时机：文本标签的 setVisible(false) 应在动画开始时立即执行（缩小方向），还是在动画结束后执行（展开方向）？时机不对会导致文字在过渡中被压缩变形。
• 折叠模式下的 Tooltip：用户看不到文字，必须在 setCollapsedMode 时同步更新 Tooltip，否则菜单项缺少文字提示。

本文以 CollapsibleSidebar（折叠控制+动画）和 NavItemWidget（自绘导航项+状态管理）为核心，自定义宽度变化的动画、双模式 UI 状态同步、自绘选中/悬停态三个技术点，完整代码可在文末下载。

二、最终效果预览