7天上手PyQt6 Python 桌面应用开发之PyQt6 高级控件

QMenuBar 常用方法

注：QMenuBar 是菜单栏控件（窗口顶部的菜单容器），核心作用是承载 QMenu 菜单对象，构建 “文件 / 编辑 / 帮助” 等经典菜单结构，以下是其高频实用方法：

1. addMenu ()：添加菜单到菜单栏，是核心创建方法，支持两种用法：

   传入字符串：addMenu("文件")（自动创建 QMenu 对象，名称为 “文件”）；

   传入 QMenu 对象：addMenu(QMenu("编辑", self))（自定义菜单属性后添加）。

2. insertMenu ()：在指定参考菜单前插入新菜单，参数为(参考菜单, 新菜单)，如insertMenu(file_menu, edit_menu)，精准控制菜单排列顺序。

3. addSeparator ()：在菜单栏中添加分隔线（极少用，分隔线多在子菜单内添加），用于菜单分组（如 “文件” 和 “编辑” 间加分隔线）。

4. insertSeparator ()：在指定参考菜单前插入分隔线，参数为参考菜单对象，如insertSeparator(help_menu)，优化菜单视觉分组。

5. removeMenu ()：从菜单栏移除指定 QMenu 对象，仅解除布局关联（不会删除菜单，需手动调用deleteLater()销毁）。

6. clear ()：清空菜单栏中所有菜单，快速重置菜单栏结构（如切换界面时清空菜单）。

7. menu ()：根据索引获取菜单栏中的 QMenu 对象，参数为整数，如menu(0)获取第一个菜单，用于读取 / 操作指定菜单。

8. actions ()：获取菜单栏中所有菜单项（QAction）列表，返回List[QAction]类型，用于遍历、批量修改菜单状态（如禁用所有菜单）。

9. setNativeMenuBar ()：设置是否使用系统原生菜单栏（仅 Mac 系统生效），True 为融入 Mac 顶部系统菜单栏、False 为显示在窗口内，适配跨平台显示。

10. isNativeMenuBar ()：判断是否启用系统原生菜单栏，返回布尔值，校验跨平台显示配置。

11. setCornerWidget ()：设置菜单栏角落控件（如搜索框、按钮），参数为 QWidget 对象，如setCornerWidget(QLineEdit("搜索"))，拓展菜单栏功能。

12. cornerWidget ()：获取菜单栏角落的控件对象，返回 QWidget 实例，读取角落控件配置。

13. setStyleSheet ()：通过 CSS 样式表美化菜单栏，支持设置背景色、菜单文字字体 / 颜色、选中菜单样式等，如setStyleSheet("QMenuBar{background-color:#f0f0f0;}")。

14. setEnabled ()：设置菜单栏整体是否可用，True 为正常交互（可展开菜单）、False 为禁用（灰显，无法点击），控制核心交互状态。

15. setVisible ()：设置菜单栏是否可见，True 为显示、False 为隐藏，控制菜单栏在窗口中的展示状态（如极简界面隐藏菜单栏）。

16. setFont ()：设置菜单栏所有菜单名称的统一字体，传入 QFont 对象，如setFont(QFont("Microsoft YaHei", 10))，统一文字样式。

17. font ()：获取菜单栏当前使用的字体对象，返回 QFont 类型，读取字体配置是否符合预期。

18. setDefaultUp ()：设置菜单默认展开方向，True 为向上展开、False 为向下展开（默认），适配菜单栏在窗口底部的场景（如工具栏式菜单栏）。

19. isDefaultUp ()：判断菜单默认展开方向，返回布尔值，校验展开方向是否适配界面布局。

20. actionAt ()：根据坐标位置获取对应的 QAction 对象，参数为 QPoint 坐标，如actionAt(QPoint(50, 10))，用于鼠标交互相关的精准操作。

21. setTabFocusBehavior ()：设置 Tab 键聚焦菜单栏的行为，可选QMenuBar.TabFocusBehavior.CycleThroughMenus（循环聚焦所有菜单）等，适配键盘操作场景。

22. tabFocusBehavior ()：获取 Tab 键聚焦行为配置，返回对应的枚举值，校验键盘交互规则。

23. sizeHint ()：获取菜单栏的推荐尺寸，返回 QSize 对象，用于自定义窗口大小时适配菜单栏布局。

24. minimumSizeHint ()：获取菜单栏的最小推荐尺寸，返回 QSize 对象，防止菜单栏被过度压缩。

1. addAction ()：添加工具动作到工具栏，是核心创建方法，支持两种用法：

   图标 + 文本：addAction(QIcon("add.png"), "新建")（自动创建带图标 / 文字的工具按钮）；

   传入 QAction 对象：addAction(edit_action)（自定义动作属性后添加）。

2. addWidget ()：添加自定义控件到工具栏，如按钮、输入框、下拉框等，如addWidget(QLineEdit("搜索"))，拓展工具栏功能边界。

3. insertAction ()：在指定参考动作前插入新动作，参数为(参考QAction, 新QAction)，如insertAction(save_action, undo_action)，精准控制工具按钮排列顺序。

4. insertWidget ()：在指定参考动作前插入自定义控件，参数为(参考QAction, 控件)，如insertWidget(redo_action, QPushButton("筛选"))，精准布局自定义控件。

5. addSeparator ()：添加分隔线，用于工具按钮分组（如 “新建 / 保存” 与 “撤销 / 重做” 间加分隔线），优化视觉层级。

6. insertSeparator ()：在指定参考动作前插入分隔线，参数为参考 QAction 对象，如insertSeparator(help_action)，精准实现按钮分组。

7. removeAction ()：从工具栏移除指定 QAction 对象，仅解除布局关联（需手动调用deleteLater()销毁动作）。

8. clear ()：清空工具栏所有动作 / 控件，快速重置工具栏结构（如切换功能模块时清空）。

9. actionAt ()：根据坐标位置获取对应的 QAction 对象，参数为 QPoint（如actionAt(QPoint(30, 10))），用于鼠标交互的精准操作。

10. widgetForAction ()：根据 QAction 对象获取对应的工具按钮控件，返回 QWidget 实例，如widgetForAction(new_action)，用于修改单个按钮样式。

11. setMovable ()：设置工具栏是否可拖动，True 为可拖动（默认）、False 为固定位置，适配界面布局灵活性。

12. isMovable ()：判断工具栏是否可拖动，返回布尔值，校验拖动状态配置。

13. setFloatable ()：设置工具栏是否可浮动（拖出窗口成为独立面板），True 为可浮动、False 为固定在窗口，适配多窗口布局场景。

14. isFloatable ()：判断工具栏是否可浮动，返回布尔值，校验浮动状态配置。

15. setAllowedAreas ()：设置工具栏可停靠的区域，传入 Qt.ToolBarArea 枚举值（如Qt.ToolBarArea.Top | Qt.ToolBarArea.Bottom），限制工具栏仅能停靠在窗口顶部 / 底部。

16. allowedAreas ()：获取工具栏允许停靠的区域，返回对应的枚举值，校验停靠范围配置。

17. setToolButtonStyle ()：设置工具按钮的展示样式，核心可选值：

    Qt.ToolButtonIconOnly（仅显示图标，默认）；

    Qt.ToolButtonTextBesideIcon（文字在图标旁）；

    Qt.ToolButtonTextOnly（仅显示文字），适配不同界面风格。

18. toolButtonStyle ()：获取工具按钮的展示样式，返回枚举值，校验按钮显示规则。

19. setIconSize ()：设置工具栏所有图标的统一尺寸，传入 QSize 对象（如setIconSize(QSize(24, 24))），统一视觉风格。

20. iconSize ()：获取工具栏图标的尺寸，返回 QSize 对象，读取图标尺寸配置。

21. setStyleSheet ()：通过 CSS 样式表美化工具栏，支持设置背景色、按钮 hover 样式、分隔线颜色等，如setStyleSheet("QToolBar{background:#f5f5f5;} QToolButton:hover{background:#e0e0e0;}")。

22. setEnabled ()：设置工具栏整体是否可用，True 为正常交互（可点击按钮）、False 为禁用（灰显，无交互），控制核心交互状态。

23. setVisible ()：设置工具栏是否可见，True 为显示、False 为隐藏，适配极简界面 / 功能切换场景（如隐藏次要工具栏）。

24. setOrientation ()：设置工具栏方向，传入 Qt.Orientation 枚举值（Qt.Horizontal水平 /Qt.Vertical垂直），如垂直停靠时设为 Vertical，适配布局方向。

25. orientation ()：获取工具栏的方向，返回枚举值，校验布局方向配置。

26. toggleViewAction ()：获取工具栏的 “显示 / 隐藏” 切换动作，返回 QAction 对象，可添加到菜单栏（如 “视图” 菜单下控制工具栏显隐）。

27. setContextMenuPolicy ()：设置工具栏右键菜单策略，如setContextMenuPolicy(Qt.ContextMenuPolicy.CustomContextMenu)，自定义右键菜单拓展交互。

1. showMessage ()：显示临时状态消息，是核心方法。参数为(文本, 显示时长ms)，如showMessage("文件保存成功", 3000)（3 秒后自动消失）；不传时长则消息一直显示，直到被清空 / 覆盖。

2. clearMessage ()：手动清除当前显示的临时消息，立即清空状态栏的临时文本提示。

3. currentMessage ()：获取当前显示的临时消息文本，返回字符串类型，用于读取状态栏的提示内容（如校验是否显示 “操作中”）。

4. addWidget ()：添加左侧永久控件到状态栏，控件不会被临时消息覆盖，如addWidget(QLabel("当前用户：admin"))，适配固定信息展示。

5. insertWidget ()：在指定索引位置插入左侧永久控件，参数为(索引, 控件)，如insertWidget(0, QProgressBar())，精准控制控件排列顺序。

6. addPermanentWidget ()：添加右侧永久控件到状态栏，优先级高于左侧，如addPermanentWidget(QLabel("已同步"))，适合展示核心固定信息。

7. insertPermanentWidget ()：在指定索引位置插入右侧永久控件，参数为(索引, 控件)，如insertPermanentWidget(0, QPushButton("帮助"))，精准布局右侧控件。

8. removeWidget ()：从状态栏移除指定永久控件（左侧 / 右侧），传入 QWidget 对象（仅解除布局关联，需手动调用deleteLater()销毁控件）。

9. takeWidget ()：移除并返回指定索引的左侧永久控件，返回 QWidget 对象，用于回收或重新布局控件（如takeWidget(0)获取第一个左侧控件）。

10. takePermanentWidget ()：移除并返回指定索引的右侧永久控件，返回 QWidget 对象，精准回收右侧控件。

11. setSizeGripEnabled ()：设置状态栏右下角的尺寸调整手柄（Size Grip）是否显示，True 为显示（默认）、False 为隐藏，适配无需调整窗口尺寸的场景（如固定尺寸窗口）。

12. isSizeGripEnabled ()：判断尺寸调整手柄是否显示，返回布尔值，校验界面布局配置是否符合预期。

13. setStyleSheet ()：通过 CSS 样式表美化状态栏，支持设置背景色、文本字体 / 颜色、内边距等，如setStyleSheet("QStatusBar{background:#f5f5f5; color:#333; font-size:9px;}")。

14. setEnabled ()：设置状态栏整体是否可用，True 为正常显示 / 交互（控件可点击、文本可更新）、False 为禁用（灰显，无交互），控制核心交互状态。

15. setVisible ()：设置状态栏是否可见，True 为显示、False 为隐藏，适配全屏模式、极简界面等场景（如视频播放窗口隐藏状态栏）。

16. setFont ()：设置状态栏所有文本的统一字体，传入 QFont 对象，如setFont(QFont("Microsoft YaHei", 9))，统一文字样式，提升界面一致性。

17. font ()：获取状态栏当前使用的字体对象，返回 QFont 类型，读取字体配置是否符合设计要求。

18. messageChanged.connect ()：绑定 “临时消息变化” 信号，如messageChanged.connect(self.on_msg_changed)，监听消息的显示 / 清空事件（如消息消失时触发日志记录）。

19. setMinimumHeight ()：设置状态栏的最小高度，传入整数（如setMinimumHeight(30)），防止状态栏被过度压缩导致文本 / 控件显示不全。

20. setMaximumHeight ()：设置状态栏的最大高度，传入整数（如setMaximumHeight(40)），限制状态栏占用过多窗口底部空间。

21. setContentsMargins ()：设置状态栏的内边距（左、上、右、下），传入四个整数（如setContentsMargins(5, 2, 5, 2)），调整文本 / 控件与状态栏边缘的间距，优化显示效果。

22. contentsMargins ()：获取状态栏的内边距，返回 QMargins 对象，可通过.left()/.top()等提取单个方向的边距值，校验间距配置。

23. count ()：获取状态栏中永久控件（左侧 + 右侧）的总数，返回 int 类型，用于遍历控件、校验是否添加成功。

1. setValue ()：设置进度条当前值，传入整数（需在最小 - 最大值区间内），如setValue(50)（进度 50%），是控制进度的核心方法。

2. value ()：获取进度条当前值，返回整数，用于读取实时进度（如判断是否达到 100% 完成任务）。

3. setMaximum ()：设置进度条最大值，传入整数（默认 100），如setMaximum(200)（进度满值为 200，适配非百分比进度场景）。

4. maximum ()：获取进度条最大值，返回整数，校验最大值配置（如确认是否设为 100）。

5. setMinimum ()：设置进度条最小值，传入整数（默认 0），如setMinimum(10)（进度从 10 开始，适配分段进度场景）。

6. minimum ()：获取进度条最小值，返回整数，校验最小值配置。

7. setRange ()：一次性设置最小 / 最大值，参数为(min, max)，如setRange(0, 1000)，比单独设置 min/max 更便捷高效。

8. reset ()：重置进度条到初始状态（值回到最小值），如任务中断、重新开始时重置进度。

9. setOrientation ()：设置进度条方向，传入 Qt.Orientation 枚举值：

   Qt.Horizontal：水平方向（默认）；

   Qt.Vertical：垂直方向，适配侧边布局场景。

10. orientation ()：获取进度条方向，返回对应的枚举值，校验布局方向是否符合预期。

11. setFormat ()：设置进度文本显示格式，支持专属占位符：

    %p：百分比（如 50%）；

    %v：当前值（如 50）；

    %m：最大值（如 100）；

    示例：setFormat("下载进度：%p%")（显示 “下载进度：50%”），setFormat("")则隐藏文本。

12. format ()：获取当前进度文本格式，返回字符串，读取格式配置（如确认是否显示百分比）。

13. setTextVisible ()：设置进度文本是否可见，True 为显示（默认）、False 为隐藏，仅展示进度条无文字，适配极简界面。

14. isTextVisible ()：判断进度文本是否可见，返回布尔值，校验文本显示状态。

15. setInvertedAppearance ()：设置进度条是否反向显示，True 为从右→左（水平）/ 上→下（垂直）填充，False 为正向（默认），适配特殊视觉需求（如反向加载进度）。

16. isInvertedAppearance ()：判断是否反向显示，返回布尔值，校验进度填充方向。

17. setStyleSheet ()：通过 CSS 样式表美化进度条，支持自定义背景、进度块颜色、圆角等

18. setEnabled ()：设置进度条是否可用，True 为正常显示进度、False 为禁用（灰显，无法更新值），控制核心交互状态。

19. setVisible ()：设置进度条是否可见，True 为显示、False 为隐藏，如任务未开始时隐藏，开始后显示。

20. setMinimumHeight ()：设置进度条最小高度，传入整数（如setMinimumHeight(20)），防止水平进度条被过度压缩导致显示不全。

21. setMinimumWidth ()：设置进度条最小宽度，传入整数（如setMinimumWidth(200)），防止垂直进度条被过度压缩。

22. setAlignment ()：设置进度文本的对齐方式，传入 Qt.Alignment 枚举值（如Qt.AlignCenter居中、Qt.AlignRight右对齐），优化文本显示位置。

23. alignment ()：获取文本对齐方式，返回枚举值，校验文本布局配置。

24. setTextDirection ()：设置进度文本的显示方向（仅垂直进度条生效），传入QProgressBar.TextDirection枚举值（如BottomToTop从下到上），适配垂直进度条文本展示。

25. valueChanged.connect ()：绑定 “进度值变化” 信号，如valueChanged.connect(self.on_progress_update)，监听进度更新（如进度 100% 时触发 “任务完成” 弹窗）。

1. setValue ()：设置滑块当前值，传入整数（需在最小 - 最大值区间内），是控制滑块数值的核心方法。

2. value ()：获取滑块当前值，返回整数，用于读取实时数值（如音量滑块读取当前音量值）。

3. setMaximum ()：设置滑块最大值，默认 100，可适配非 0-100 的数值范围（如亮度 0-200）。

4. maximum ()：获取滑块最大值，返回整数，校验最大值配置是否符合预期。

5. setMinimum ()：设置滑块最小值，默认 0，可适配分段调整场景（如进度从 10 开始）。

6. minimum ()：获取滑块最小值，返回整数，校验最小值配置。

7. setRange ()：一次性设置最小 / 最大值，参数为 (min, max)，比单独设置 min/max 更便捷高效。

8. setOrientation ()：设置滑块方向，可选水平（默认）/ 垂直，分别适配窗口顶部 / 底部、侧边布局。

9. orientation ()：获取滑块方向，返回对应的枚举值，校验布局方向是否符合设计。

10. setSingleStep ()：设置单次步长（点击滑块箭头的调整值），默认 1，控制精细调整幅度。

11. singleStep ()：获取单次步长，返回整数，校验微调步长配置。

12. setPageStep ()：设置翻页步长（点击滑块轨道空白处的调整值），默认 10，控制快速调整幅度。

13. pageStep ()：获取翻页步长，返回整数，校验快速调整步长配置。

14. setTickPosition ()：设置刻度显示位置（需配合 tickInterval 生效），可选无刻度（默认）、滑块单侧 / 双侧显示刻度，用于可视化数值参考。

15. tickPosition ()：获取刻度显示位置，返回枚举值，校验刻度布局。

16. setTickInterval ()：设置刻度间隔，传入整数（如每 10 个单位显示 1 个刻度），需先设置 tickPosition 才会显示刻度。

17. tickInterval ()：获取刻度间隔，返回整数，校验刻度密度。

18. setTracking ()：设置是否实时跟踪数值变化，默认开启（拖动时实时触发数值变化信号），关闭则仅松开滑块后触发，适配 “拖动确认后生效” 场景。

19. hasTracking ()：判断是否开启实时跟踪，返回布尔值，校验交互逻辑。

20. setInvertedAppearance ()：设置滑块反向显示，默认正向（最大值在右 / 下），反向则最大值在左 / 上，适配特殊视觉需求。

21. isInvertedAppearance ()：判断是否反向显示，返回布尔值，校验显示方向。

22. setInvertedControls ()：设置操作反向，默认点击右 / 下箭头数值增加，反向则减少，适配反向调整需求。

23. isInvertedControls ()：判断操作是否反向，返回布尔值，校验操作逻辑。

24. setStyleSheet ()：通过样式表美化滑块，可自定义轨道、手柄的样式（如颜色、圆角、尺寸），提升界面视觉效果。

25. setEnabled ()：设置滑块是否可用，开启则可正常拖动 / 点击调整，禁用则灰显且无法操作，控制核心交互状态。

26. setVisible ()：设置滑块是否可见，开启则显示，关闭则隐藏，适配功能未激活时隐藏滑块的场景。

27. valueChanged.connect ()：绑定数值变化信号，监听滑块调整（如音量滑块联动音量显示标签）。

28. sliderPressed.connect ()：绑定滑块按下信号，触发于点击 / 开始拖动滑块时（如记录调整开始时间）。

29. sliderReleased.connect ()：绑定滑块松开信号，触发于松开滑块时（如确认调整后的数值并执行逻辑）。

30. setMinimumWidth/Height ()：设置滑块最小宽 / 高，防止滑块被过度压缩导致显示不全（水平滑块设最小宽度，垂直滑块设最小高度）。

1. setModel ()：为树形视图绑定数据模型（如 QStandardItemModel），是展示数据的核心方法，无模型则树形视图无内容。

2. model ()：获取当前绑定的数据模型，返回模型对象，用于读取 / 修改模型数据（如新增、删除节点）。

3. setRootIndex ()：设置树形视图的根索引，传入 QModelIndex 对象，可只展示模型中指定节点下的子树（如仅显示某文件夹下的目录）。

4. rootIndex ()：获取当前根索引，返回 QModelIndex 对象，校验根节点范围配置。

5. expand ()：展开指定节点，传入 QModelIndex 对象，显示该节点的子节点（如展开第一个根节点）。

6. expandAll ()：展开所有节点，一次性展示树形视图的全部层级数据，适配需完整展示所有内容的场景。

7. collapse ()：折叠指定节点，传入 QModelIndex 对象，隐藏该节点的子节点。

8. collapseAll ()：折叠所有节点，仅显示根节点，适配需精简展示的场景。

9. isExpanded ()：判断指定节点是否展开，传入 QModelIndex 对象，返回布尔值，校验节点展开状态。

10. setSelectionMode ()：设置选择模式，核心可选值：单选（默认）、扩展选择（Ctrl/Shift 多选）、不可选，控制节点的选择权限。

11. selectionMode ()：获取当前选择模式，返回对应枚举值，校验选择权限配置。

12. selectedIndexes ()：获取所有选中节点的索引列表，返回索引列表，用于读取选中的节点数据。

13. setSelectionBehavior ()：设置选择行为，核心可选值：选中整个节点（默认）、选中整行、选中整列，适配不同的选中交互逻辑。

14. selectionBehavior ()：获取选择行为，返回对应枚举值，校验选中逻辑配置。

15. setHeaderHidden ()：设置表头是否隐藏，True 为隐藏、False 为显示（默认），适配无需展示表头的树形结构（如纯目录展示）。

16. isHeaderHidden ()：判断表头是否隐藏，返回布尔值，校验表头显示状态。

17. setHeaderLabels ()：设置表头列的显示文本，传入字符串列表（如 ["名称", "类型"]），定义表头内容。

18. headerLabels ()：获取表头列的文本列表，返回字符串列表，读取表头配置。

19. setColumnWidth ()：设置指定列的宽度，参数为 (列索引，宽度值)，调整列的显示宽度（如设置第 0 列宽度为 200）。

20. columnWidth ()：获取指定列的宽度，传入列索引，返回整数，校验列宽配置。

21. resizeColumnToContents ()：自动调整指定列的宽度以适配内容，避免内容被截断或留白过多。

22. setEditTriggers ()：设置编辑触发方式，核心可选值：禁止编辑（默认）、双击节点可编辑、按任意键可编辑，控制节点数据的编辑权限。

23. editTriggers ()：获取编辑触发方式，返回对应枚举值，校验编辑权限配置。

24. setIndentation ()：设置节点缩进值，传入整数（默认 20 像素），调整子节点相对于父节点的缩进距离，优化层级视觉效果。

25. indentation ()：获取节点缩进值，返回整数，校验缩进配置。

26. setAnimated ()：设置展开 / 折叠是否启用动画，True 为启用、False 为禁用（默认），提升交互的视觉流畅度。

27. isAnimated ()：判断是否启用动画，返回布尔值，校验动画配置。

28. setSortingEnabled ()：设置是否启用排序，True 为启用、False 为禁用（默认），启用后点击表头可按列排序节点。

29. isSortingEnabled ()：判断是否启用排序，返回布尔值，校验排序功能配置。

30. setStyleSheet ()：通过样式表美化树形视图，可自定义节点文字颜色、选中背景色、表头样式、缩进线等，提升界面视觉效果。

31. setEnabled ()：设置树形视图是否可用，True 为正常交互（可选中 / 展开 / 编辑）、False 为禁用（灰显，无交互），控制核心交互状态。

32. setVisible ()：设置树形视图是否可见，True 为显示、False 为隐藏，适配功能未激活时隐藏控件的场景。

33. clicked.connect ()：绑定 “节点点击” 信号，触发于点击节点时，监听节点点击并执行逻辑（如显示节点详情）。

34. doubleClicked.connect ()：绑定 “节点双击” 信号，触发于双击节点时，如打开选中的文件 / 目录。

35. expanded.connect ()：绑定 “节点展开” 信号，触发于节点展开时，如加载该节点的子数据（懒加载场景）。

1. addTopLevelItem ()：添加顶层节点到树形控件，核心创建根节点的方法，传入 QTreeWidgetItem 对象，如addTopLevelItem(root_item)（root_item 为自定义根节点）。

2. addTopLevelItems ()：批量添加顶层节点，传入 QTreeWidgetItem 列表（如addTopLevelItems([item1, item2])），高效添加多个根节点。

3. insertTopLevelItem ()：在指定索引位置插入顶层节点，参数为(索引, 节点对象)，如insertTopLevelItem(0, new_root)，精准控制根节点排列顺序。

4. takeTopLevelItem ()：移除并返回指定索引的顶层节点，返回 QTreeWidgetItem 对象，用于删除根节点并回收资源（如takeTopLevelItem(1)移除第二个根节点）。

5. topLevelItem ()：根据索引获取顶层节点，传入整数，如topLevelItem(0)获取第一个根节点，用于读取 / 操作指定根节点。

6. topLevelItemCount ()：获取顶层节点总数，返回整数，用于遍历根节点、校验节点数量（如判断是否有根节点）。

7. invisibleRootItem ()：获取树形控件的隐藏根节点，返回 QTreeWidgetItem 对象，可通过该节点统一管理所有顶层节点（如批量添加子节点）。

8. findItems ()：根据文本查找节点，参数为(文本, 匹配列, 匹配规则)，如findItems("文档", Qt.MatchExactly, 0)，精准查找指定文本的节点。

9. expandItem ()：展开指定节点，传入 QTreeWidgetItem 对象，显示该节点的子节点（如展开 “文件” 根节点）。

10. expandAll ()：展开所有节点，一次性展示树形控件的全部层级数据，适配需完整展示所有内容的场景。

11. collapseItem ()：折叠指定节点，传入 QTreeWidgetItem 对象，隐藏该节点的子节点（如折叠 “图片” 根节点）。

12. collapseAll ()：折叠所有节点，仅显示顶层节点，适配需精简展示的场景（如初始界面只显示根目录）。

13. isItemExpanded ()：判断指定节点是否展开，传入 QTreeWidgetItem 对象，返回布尔值，校验节点展开状态。

14. setCurrentItem ()：设置当前选中的节点，传入 QTreeWidgetItem 对象，如setCurrentItem(root_item)，手动指定默认选中节点。

15. currentItem ()：获取当前选中的节点，返回 QTreeWidgetItem 对象，读取选中节点的文本 / 数据（如获取选中文件名称）。

16. selectedItems ()：获取所有选中的节点列表，返回List[QTreeWidgetItem]类型，支持多选场景下读取所有选中节点。

17. setSelectionMode ()：设置选择模式，核心可选值：

    QAbstractItemView.SingleSelection：单选（默认）；

    ExtendedSelection：Ctrl/Shift 多选；

    NoSelection：不可选，控制节点选择权限。

18. selectionMode ()：获取当前选择模式，返回对应枚举值，校验选择权限配置是否符合预期。

19. setSelectionBehavior ()：设置选择行为，核心可选值：选中整个节点（默认）、选中整行、选中整列，适配不同的选中交互逻辑。

20. setHeaderHidden ()：设置表头是否隐藏，True 为隐藏、False 为显示（默认），适配无需展示表头的纯树形结构（如仅显示目录名称）。

21. isHeaderHidden ()：判断表头是否隐藏，返回布尔值，校验表头显示状态。

22. setHeaderLabels ()：设置表头列的显示文本，传入字符串列表（如setHeaderLabels(["名称", "大小", "修改时间"])），定义表头内容。

23. headerLabels ()：获取表头列的文本列表，返回字符串列表，读取表头配置。

24. setColumnWidth ()：设置指定列的宽度，参数为(列索引, 宽度值)，如setColumnWidth(0, 200)，调整列的显示宽度。

25. columnWidth ()：获取指定列的宽度，传入列索引，返回整数，校验列宽配置。

26. resizeColumnToContents ()：自动调整指定列的宽度以适配内容，避免内容被截断或留白过多（如适配长文件名显示）。

27. setEditTriggers ()：设置编辑触发方式，核心可选值：禁止编辑（默认）、双击节点可编辑、按任意键可编辑，控制节点数据的编辑权限。

28. editTriggers ()：获取编辑触发方式，返回对应枚举值，校验编辑权限配置。

29. setIndentation ()：设置节点缩进值，传入整数（默认 20 像素），调整子节点相对于父节点的缩进距离，优化层级视觉效果。

30. indentation ()：获取节点缩进值，返回整数，校验缩进配置。

31. setAnimated ()：设置展开 / 折叠是否启用动画，True 为启用、False 为禁用（默认），提升交互的视觉流畅度。

32. isAnimated ()：判断是否启用动画，返回布尔值，校验动画配置。

33. setSortingEnabled ()：设置是否启用排序，True 为启用、False 为禁用（默认），启用后点击表头可按列排序节点（如按文件名排序）。

34. isSortingEnabled ()：判断是否启用排序，返回布尔值，校验排序功能配置。

35. setStyleSheet ()：通过样式表美化树形控件，可自定义节点文字颜色、选中背景色、表头样式、缩进线等，提升界面视觉效果。

36. setEnabled ()：设置树形控件是否可用，True 为正常交互（可选中 / 展开 / 编辑）、False 为禁用（灰显，无交互），控制核心交互状态。

37. setVisible ()：设置树形控件是否可见，True 为显示、False 为隐藏，适配功能未激活时隐藏控件的场景。

38. clear ()：清空所有节点，快速重置树形控件结构（如切换数据来源时清空旧节点）。

39. itemClicked.connect ()：绑定 “节点点击” 信号，触发于点击节点时，监听节点点击并执行逻辑（如显示节点详情、打开文件）。

40. itemDoubleClicked.connect ()：绑定 “节点双击” 信号，触发于双击节点时，如打开选中的文件 / 目录、编辑节点文本。

1. setFrameStyle ()：设置框架样式（核心方法），组合「边框形状 + 阴影类型」枚举值，如setFrameStyle(QFrame.Box | QFrame.Raised)（矩形凸起边框）；常用形状：Box（矩形框）、HLine（水平分隔线）、VLine（垂直分隔线）；常用阴影：Raised（凸起）、Sunken（凹陷）、Plain（无阴影）。

2. frameStyle ()：获取当前框架样式，返回组合枚举值，校验样式配置是否符合预期（如确认是否为水平分隔线）。

3. setLineWidth ()：设置框架边框线宽度，传入整数（默认 1 像素），如setLineWidth(2)（加粗边框），调整边框视觉粗细。

4. lineWidth ()：获取边框线宽度，返回整数，校验线宽配置是否生效。

5. setMidLineWidth ()：设置框架中线宽度（仅 Box/Panel 样式 + Sunken 阴影生效），传入整数（如setMidLineWidth(1)），为边框增加中线，提升层次感。

6. midLineWidth ()：获取中线宽度，返回整数，校验中线配置。

7. setFrameShape ()：单独设置框架形状（替代 setFrameStyle 的形状部分），可选 Box（矩形）、HLine（水平分隔线）、VLine（垂直分隔线）、Panel（面板）等，精准控制框架形态。

8. frameShape ()：获取框架形状，返回枚举值，校验形状是否为目标类型（如是否为垂直分隔线）。

9. setFrameShadow ()：单独设置框架阴影（替代 setFrameStyle 的阴影部分），可选 Raised（凸起）、Sunken（凹陷）、Plain（无阴影），调整边框视觉效果。

10. frameShadow ()：获取框架阴影类型，返回枚举值，校验阴影配置。

11. setContentsMargins ()：设置框架内边距（左、上、右、下），传入四个整数（如setContentsMargins(10, 8, 10, 8)），调整内部控件与框架边框的间距，避免内容贴边。

12. contentsMargins ()：获取内边距，返回 QMargins 对象，可通过.left()/.top()提取单个方向间距，校验内边距配置。

13. setLayout ()：为框架绑定布局管理器（如 QVBoxLayout/QHBoxLayout），核心容器功能，将按钮、标签等控件添加到框架内，实现界面分区。

14. layout ()：获取框架绑定的布局管理器，返回 QLayout 对象，用于读取 / 修改内部布局（如新增控件、调整布局方向）。

15. setStyleSheet ()：通过样式表美化框架，支持自定义边框颜色、圆角、背景色等，示例：setStyleSheet("QFrame{border:2px solid #4CAF50; border-radius:5px; background:#f5f5f5;}")。

16. setMinimumSize ()：设置框架最小尺寸，传入宽 / 高整数（如setMinimumSize(200, 100)），防止框架被过度压缩导致内部控件显示不全。

17. setMaximumSize ()：设置框架最大尺寸，限制框架不会过度拉伸，适配固定布局场景（如侧边栏框架）。

18. setSizePolicy ()：设置框架尺寸策略，可选QSizePolicy.Expanding（随父控件拉伸）、Fixed（固定尺寸）等，控制框架的大小调整规则。

19. setAlignment ()：设置框架内控件的对齐方式，传入 Qt.Alignment 枚举值（如Qt.AlignCenter居中、Qt.AlignLeft左对齐），适配内部控件的布局需求。

20. alignment ()：获取内部控件对齐方式，返回枚举值，校验对齐配置是否符合预期。

21. setEnabled ()：设置框架是否可用，True 为正常（内部控件可交互）、False 为禁用（框架及内部控件灰显），控制整体交互状态。

22. setVisible ()：设置框架是否可见，True 为显示、False 为隐藏，适配分区显示 / 隐藏场景（如折叠面板、隐藏次要分区）。

23. setAutoFillBackground ()：设置是否自动填充背景，True 为启用，配合样式表 / 背景角色生效，避免背景透明导致样式失效。

24. autoFillBackground ()：判断是否自动填充背景，返回布尔值，校验背景填充配置。

25. setFrameRect ()：设置框架绘制区域，传入 QRect 对象，自定义框架的显示区域（默认与控件矩形一致），适配特殊布局场景。

1. setSizeHint ()：设置占位项的推荐尺寸，传入 QSize 对象（如setSizeHint(QSize(50, 20))），定义占位项的基础大小，布局会优先按此尺寸分配空白空间。

2. sizeHint ()：获取占位项的推荐尺寸，返回 QSize 对象，读取占位项的基础大小配置（如校验是否设为 50×20）。

3. setMinimumSize ()：设置占位项的最小尺寸，传入宽 / 高整数（如setMinimumSize(30, 10)），防止占位项被过度压缩，保障布局中最小空白区域。

4. minimumSize ()：获取占位项的最小尺寸，返回 QSize 对象，校验最小尺寸配置是否生效。

5. setMaximumSize ()：设置占位项的最大尺寸，传入宽 / 高整数（如setMaximumSize(100, 50)），限制占位项不会过度拉伸，避免占用过多布局空间。

6. maximumSize ()：获取占位项的最大尺寸，返回 QSize 对象，校验最大尺寸配置是否符合预期。

7. setSizePolicy ()：设置占位项的尺寸策略（核心方法），传入水平 / 垂直方向的尺寸策略枚举值，如

   setSizePolicy(QSizePolicy.Expanding, QSizePolicy.Fixed)：

   Expanding：随布局拉伸（占满剩余空白）；

   Fixed：固定尺寸（不拉伸 / 收缩）；

   Minimum：仅占用最小尺寸；

   Maximum：仅占用最大尺寸，控制占位项的拉伸 / 收缩规则。

8. sizePolicy ()：获取占位项的尺寸策略，返回 QSizePolicy 对象，读取水平 / 垂直方向的拉伸规则配置。

9. changeSize ()：批量修改占位项的尺寸和策略，参数为(宽, 高, 水平策略, 垂直策略)，如changeSize(80, 40, QSizePolicy.Expanding, QSizePolicy.Expanding)，比单独设置尺寸 / 策略更高效。

10. width ()：快捷获取占位项的当前宽度，返回整数（等效sizeHint().width()），快速读取宽度值。

11. height ()：快捷获取占位项的当前高度，返回整数（等效sizeHint().height()），快速读取高度值。

12. setAlignment ()：设置占位项的对齐方式（部分布局生效），传入 Qt.Alignment 枚举值（如Qt.AlignRight），调整占位项在分配空间内的对齐位置。

13. alignment ()：获取占位项的对齐方式，返回 Qt.Alignment 枚举值，校验对齐配置是否符合布局需求。

1. setValue ()：设置拨号盘当前值，传入整数（需在最小 - 最大值区间内），如setValue(50)（调整到 50），是控制数值的核心方法。

2. value ()：获取拨号盘当前值，返回整数，用于读取实时数值（如音量旋钮读取当前音量值）。

3. setMaximum ()：设置拨号盘最大值，默认 100，如setMaximum(180)（适配角度 0-180 的调整场景）。

4. maximum ()：获取拨号盘最大值，返回整数，校验最大值配置是否符合预期。

5. setMinimum ()：设置拨号盘最小值，默认 0，如setMinimum(10)（适配从 10 开始的参数调整）。

6. minimum ()：获取拨号盘最小值，返回整数，校验最小值配置。

7. setRange ()：一次性设置最小 / 最大值，参数为(min, max)，如setRange(0, 360)，比单独设置 min/max 更便捷高效。

8. setSingleStep ()：设置单次步长（点击拨号盘边缘 / 上下键的调整值），默认 1，如setSingleStep(5)（每次调整 5 个单位），控制精细调整幅度。

9. singleStep ()：获取单次步长，返回整数，校验微调步长配置。

10. setPageStep ()：设置翻页步长（点击拨号盘刻度间空白处的调整值），默认 10，如setPageStep(20)（快速调整幅度），控制快速调整幅度。

11. pageStep ()：获取翻页步长，返回整数，校验快速调整步长配置。

12. setNotchesVisible ()：设置刻度槽是否可见，True 为显示（默认 False），可视化数值参考（如音量旋钮显示刻度）。

13. notchesVisible ()：判断刻度槽是否可见，返回布尔值，校验刻度显示状态。

14. setNotchTarget ()：设置刻度槽的间隔目标值，传入浮点数（如setNotchTarget(10.0)），控制刻度的密度（值越小刻度越密）。

15. notchTarget ()：获取刻度槽间隔目标值，返回浮点数，校验刻度密度配置。

16. setWrapping ()：设置是否启用环绕旋转，True 为启用（数值到最大值后跳回最小值，如角度 0-360 循环），False 为禁用（默认，到极值后无法继续旋转）。

17. wrapping ()：判断是否启用环绕旋转，返回布尔值，校验环绕逻辑配置。

18. setTracking ()：设置是否实时跟踪数值变化，True（默认）= 旋转时实时触发valueChanged信号，False = 仅松开后触发，适配 “旋转确认后生效” 的场景。

19. hasTracking ()：判断是否开启实时跟踪，返回布尔值，校验交互逻辑。

20. setInvertedAppearance ()：设置数值反向显示，True = 顺时针旋转数值减小（默认 False，顺时针增大），适配特殊视觉需求（如反向调节音量）。

21. isInvertedAppearance ()：判断是否反向显示，返回布尔值，校验显示方向。

22. setInvertedControls ()：设置操作反向，True = 鼠标滚轮向上 / 右键点击数值减小（默认 False，向上 / 右键增大），适配反向操作需求。

23. isInvertedControls ()：判断操作是否反向，返回布尔值，校验操作逻辑。

24. setStyleSheet ()：通过样式表美化拨号盘，可自定义盘面背景、旋钮样式、刻度颜色等，示例：setStyleSheet("QDial{background:#f5f5f5; border:1px solid #ccc;} QDial::handle{background:#4CAF50;}")。

25. setEnabled ()：设置拨号盘是否可用，True = 正常旋转 / 点击调整，False = 禁用（灰显，无法操作），控制核心交互状态。

26. setVisible ()：设置拨号盘是否可见，True = 显示，False = 隐藏，适配功能未激活时隐藏控件的场景。

27. setMinimumSize ()：设置拨号盘最小尺寸，传入宽 / 高整数（如setMinimumSize(80, 80)），防止拨号盘被过度压缩导致显示不全。

28. valueChanged.connect ()：绑定 “数值变化” 信号，触发于数值调整时，监听旋钮调整（如音量旋钮联动音量显示标签）。

29. sliderMoved.connect ()：绑定 “旋钮拖动” 信号，触发于旋转拨号盘过程中，实时监听拖动动作（如实时显示调整的数值）。

30. sliderPressed.connect ()：绑定 “旋钮按下” 信号，触发于点击 / 开始旋转拨号盘时，记录调整开始时间。

31. sliderReleased.connect ()：绑定 “旋钮松开” 信号，触发于松开拨号盘时，确认调整后的数值并执行逻辑（如保存参数）。

1. setValue ()：设置滚动条当前值，传入整数（需在最小 - 最大值区间内），如setValue(50)（滚动到 50 位置），是控制滚动位置的核心方法。

2. value ()：获取滚动条当前值，返回整数，用于读取实时滚动位置（如判断是否滚动到内容底部）。

3. setMaximum ()：设置滚动条最大值，默认 100，如setMaximum(200)（适配内容长度对应的滚动范围）。

4. maximum ()：获取滚动条最大值，返回整数，校验最大值配置是否符合预期。

5. setMinimum ()：设置滚动条最小值，默认 0，如setMinimum(10)（适配分段滚动场景，仅在 10 - 最大值区间滚动）。

6. minimum ()：获取滚动条最小值，返回整数，校验最小值配置。

7. setRange ()：一次性设置最小 / 最大值，参数为(min, max)，如setRange(0, 1000)，比单独设置 min/max 更便捷高效。

8. setSingleStep ()：设置单次步长（点击滚动条上下 / 左右箭头的滚动距离），默认 1，如setSingleStep(5)（精细滚动，每次仅滚动 5 个单位）。

9. singleStep ()：获取单次步长，返回整数，校验微调步长配置。

10. setPageStep ()：设置翻页步长（点击滚动条轨道空白处的滚动距离），默认 10，如setPageStep(20)（快速滚动，适配大篇幅内容）。

11. pageStep ()：获取翻页步长，返回整数，校验快速滚动步长配置。

12. setSliderPosition ()：设置滑块的显示位置（临时调整，不触发valueChanged信号），如setSliderPosition(80)，适配预览滚动位置的场景。

13. sliderPosition ()：获取滑块当前显示位置，返回整数，读取滑块的视觉位置。

14. setSliderSize ()：设置滑块的显示大小（像素），如setSliderSize(20)，滑块越大表示可视内容占总内容的比例越高。

15. sliderSize ()：获取滑块大小，返回整数，校验滑块尺寸配置是否生效。

16. setOrientation ()：设置滚动条方向，传入 Qt.Orientation 枚举值：

    Qt.Horizontal：水平方向（默认），适配横向滚动（如长文本行）；

    Qt.Vertical：垂直方向，适配纵向滚动（如长列表）。

17. orientation ()：获取滚动条方向，返回对应的枚举值，校验布局方向是否符合设计。

18. setInvertedAppearance ()：设置滚动条反向显示，True = 最大值在左 / 上（水平 / 垂直），False = 默认（最大值在右 / 下），适配特殊视觉需求（如反向滚动的列表）。

19. isInvertedAppearance ()：判断是否反向显示，返回布尔值，校验显示方向配置。

20. setInvertedControls ()：设置操作反向，True = 点击上 / 右箭头数值减、下 / 左箭头数值加，False = 默认操作逻辑，适配反向滚动需求。

21. isInvertedControls ()：判断操作是否反向，返回布尔值，校验操作逻辑配置。

22. setStyleSheet ()：通过样式表美化滚动条，可自定义轨道、滑块、箭头的样式，

23. setEnabled ()：设置滚动条是否可用，True = 正常滚动 / 点击调整，False = 禁用（灰显，无法操作），控制核心交互状态。

24. setVisible ()：设置滚动条是否可见，True = 显示，False = 隐藏，适配内容未超出显示区域时隐藏滚动条的场景。

25. valueChanged.connect ()：绑定 “数值变化” 信号，触发于滚动条值改变时，监听滚动位置（如联动内容区域同步滚动）。

26. sliderPressed.connect ()：绑定 “滑块按下” 信号，触发于点击 / 开始拖动滑块时，记录滚动操作的开始时间。

27. sliderMoved.connect ()：绑定 “滑块拖动” 信号，触发于拖动滑块过程中，实时监听滚动动作（如实时更新内容显示区域）。

28. sliderReleased.connect ()：绑定 “滑块松开” 信号，触发于松开滑块时，确认滚动位置并执行逻辑（如保存当前滚动位置）。

29. actionTriggered.connect ()：绑定 “操作触发” 信号，触发于点击箭头 / 轨道 / 拖动滑块时，可区分不同滚动操作类型（如箭头点击、轨道点击）。

1. setText ()：设置消息框的主文本内容，传入字符串（如setText("文件保存成功")），是展示核心提示信息的基础方法。

2. text ()：获取消息框的主文本内容，返回字符串，用于读取核心提示信息。

3. setInformativeText ()：设置辅助说明文本（主文本下方的补充信息），如setInformativeText("是否继续编辑？")，提升信息完整性。

4. informativeText ()：获取辅助说明文本，返回字符串，读取补充提示信息。

5. setDetailedText ()：设置详细文本（可展开 / 折叠的额外信息），如setDetailedText("错误码：1001\n原因：文件路径不存在")，适配复杂提示场景。

6. detailedText ()：获取详细文本，返回字符串，读取额外的详细信息。

7. setWindowTitle ()：设置消息框的窗口标题，如setWindowTitle("操作提示")，区分不同类型的消息框。

8. windowTitle ()：获取消息框的窗口标题，返回字符串，校验标题配置是否符合预期。

9. setIcon ()：设置消息框的图标类型，核心枚举值：

   QMessageBox.Icon.Information（信息）、Warning（警告）；

   Critical（错误）、Question（询问）、NoIcon（无图标），可视化区分消息类型。

10. icon ()：获取消息框的图标类型，返回枚举值，校验图标是否匹配消息类型。

11. setStandardButtons ()：设置系统预设的标准按钮，组合枚举值，如setStandardButtons(QMessageBox.StandardButton.Ok | QMessageBox.StandardButton.Cancel)，常用按钮：Ok、Cancel、Yes、No、Retry 等。

12. standardButtons ()：获取已设置的标准按钮，返回组合枚举值，校验按钮配置。

13. addButton ()：添加自定义按钮，参数为(按钮文本, 按钮角色)，如addButton("重试", QMessageBox.ButtonRole.ActionRole)，拓展交互按钮。

14. setDefaultButton ()：设置默认按钮（打开消息框时聚焦的按钮），如setDefaultButton(QMessageBox.StandardButton.Ok)，提升交互便捷性。

15. defaultButton ()：获取默认按钮，返回 QPushButton 对象，校验默认聚焦按钮。

16. setEscapeButton ()：设置 ESC 键触发的按钮（按 ESC 关闭时触发），如setEscapeButton(QMessageBox.StandardButton.Cancel)，适配键盘操作。

17. escapeButton ()：获取 ESC 键触发的按钮，返回 QPushButton 对象，校验键盘交互配置。

18. setButtonText ()：修改标准按钮的显示文本，如setButtonText(QMessageBox.StandardButton.Ok, "确定")，适配中文界面。

19. buttonText ()：获取指定标准按钮的显示文本，如buttonText(QMessageBox.StandardButton.Ok)，读取按钮文字。

20. exec ()：显示模态消息框（阻塞后续代码直到关闭），返回点击的按钮枚举值（如QMessageBox.StandardButton.Ok），是核心显示方法。

21. open ()：显示非模态消息框（不阻塞后续代码），适配无需等待用户操作的场景。

22. setModal ()：设置是否为模态，True 为模态（默认）、False 为非模态，控制是否阻塞父窗口交互。

23. isModal ()：判断是否为模态，返回布尔值，校验窗口交互规则。

24. setStyleSheet ()：通过样式表美化消息框，可自定义文本、按钮、背景样式，如setStyleSheet("QMessageBox{font-size:12px;} QPushButton{background:#4CAF50; color:white;}")。

25. setTextInteractionFlags ()：设置文本交互权限，如setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)，允许用户选中 / 复制消息文本。

26. setCheckBox ()：添加复选框到消息框，如setCheckBox(QCheckBox("不再提示"))，适配 “记住选择” 的场景。

27. checkBox ()：获取消息框中的复选框，返回 QCheckBox 对象，读取是否勾选 “不再提示”。

28. static 快捷方法：无需手动实例化，直接创建常用消息框，如QMessageBox.information(parent, "标题", "内容")（信息框）、warning()（警告框）、critical()（错误框）、question()（询问框），简化开发。

1. setWindowTitle ()：设置文件对话框的窗口标题，如setWindowTitle("选择要打开的图片文件")，区分不同选择场景（打开 / 保存 / 选文件夹）。

2. windowTitle ()：获取对话框窗口标题，返回字符串，校验标题配置是否符合预期。

3. setDirectory ()：设置对话框的默认打开路径，传入字符串（如setDirectory("D:/project")），让用户从常用路径开始选择，提升操作效率。

4. directory ()：获取当前对话框的选中路径，返回 QDir 对象，可通过.absolutePath()读取绝对路径字符串。

5. setNameFilters ()：设置文件类型过滤规则，传入字符串列表（如setNameFilters(["图片文件 (*.png *.jpg)", "所有文件 (*.*)"])），仅显示指定类型文件，避免无效选择。

6. nameFilters ()：获取已设置的文件类型过滤列表，返回字符串列表，校验过滤规则配置。

7. selectNameFilter ()：设置默认选中的文件类型过滤项，如selectNameFilter("图片文件 (*.png *.jpg)")，默认展示指定类型文件。

8. selectedNameFilter ()：获取当前选中的文件类型过滤项，返回字符串，读取用户选择的文件类型。

9. setFileMode ()：设置对话框的选择模式，核心枚举值：

   QFileDialog.FileMode.ExistingFile：选择单个已存在文件（默认）；

   ExistingFiles：选择多个已存在文件；

   Directory：选择文件夹；

   AnyFile：选择任意文件（含新建文件，适配保存场景），精准控制选择范围。

10. fileMode ()：获取当前选择模式，返回枚举值，校验选择规则是否匹配场景（如保存文件需设为 AnyFile）。

11. setAcceptMode ()：设置对话框的确认模式，核心枚举值：

    QFileDialog.AcceptMode.AcceptOpen：打开文件模式（默认）；

    AcceptSave：保存文件模式，适配文件保存场景（自动提示覆盖已存在文件）。

12. acceptMode ()：获取确认模式，返回枚举值，校验是打开还是保存模式。

13. setDefaultSuffix ()：设置保存文件时的默认后缀名，如setDefaultSuffix("txt")，用户未输入后缀时自动补充（如输入 “笔记” 则保存为 “笔记.txt”）。

14. defaultSuffix ()：获取默认后缀名，返回字符串，校验后缀配置是否生效。

15. setViewMode ()：设置对话框的文件展示模式，核心枚举值：

    QFileDialog.ViewMode.List：列表视图（默认）；

    Detail：详情视图（显示文件大小、修改时间等），适配不同查看需求。

16. viewMode ()：获取文件展示模式，返回枚举值，校验视图样式配置。

17. setOption ()：设置对话框的功能选项，核心可选值：

    QFileDialog.Option.ShowDirsOnly：仅显示文件夹（选文件夹场景）；

    DontConfirmOverwrite：保存时不提示覆盖已存在文件；

    ReadOnly：只读模式（无法修改文件名），自定义对话框交互规则。

18. testOption ()：判断是否启用指定功能选项，传入枚举值返回布尔值（如testOption(QFileDialog.Option.ShowDirsOnly)），校验选项配置。

19. exec ()：显示模态文件对话框（阻塞后续代码直到关闭），返回True（用户点击确认）/False（取消），是核心显示方法。

20. selectedFiles ()：获取用户选中的文件 / 文件夹路径列表，返回字符串列表（单文件场景取第一个元素，多文件遍历列表），读取选择结果的核心方法。

21. getOpenFileName ()：静态快捷方法，直接弹出 “打开单个文件” 对话框，返回(选中路径, 选中过滤项)，如QFileDialog.getOpenFileName(parent, "打开文件", "D:/", "文本文件 (*.txt)")，无需手动实例化控件，简化开发。

22. getOpenFileNames ()：静态快捷方法，弹出 “打开多个文件” 对话框，返回(选中路径列表, 选中过滤项)，适配批量选择文件场景。

23. getSaveFileName ()：静态快捷方法，弹出 “保存文件” 对话框，返回(保存路径, 选中过滤项)，自动处理后缀补充、覆盖提示等逻辑。

24. getExistingDirectory ()：静态快捷方法，弹出 “选择文件夹” 对话框，返回选中的文件夹路径字符串，适配文件夹选择场景。

25. setStyleSheet ()：通过样式表美化对话框（部分系统风格对话框样式自定义有限），如setStyleSheet("QFileDialog{font-size:12px;} QListView{background:#f5f5f5;}")，优化非系统风格对话框的视觉效果。

26. setModal ()：设置是否为模态对话框，True 为模态（默认，阻塞父窗口交互）、False 为非模态，控制对话框交互规则。

27. setLabelText ()：修改对话框内置标签的文本，如setLabelText(QFileDialog.DialogLabel.FileName, "目标文件：")，适配中文界面的标签自定义。

1. setWindowTitle ()：设置输入对话框的窗口标题，如setWindowTitle("请输入用户名")，区分不同输入场景（如输入密码、修改名称）。

2. windowTitle ()：获取对话框窗口标题，返回字符串，校验标题配置是否符合预期。

3. setLabelText ()：设置输入框上方的提示文本，如setLabelText("请输入您的年龄：")，告知用户输入内容的用途，是核心提示方法。

4. labelText ()：获取提示文本内容，返回字符串，读取输入提示信息。

5. setInputMode ()：设置输入模式（核心方法），核心枚举值：

   QInputDialog.InputMode.TextInput：文本输入（默认），适配用户名、备注等字符串输入；

   IntInput：整数输入，适配年龄、数量等整数型数据；

   DoubleInput：浮点数输入，适配价格、尺寸等小数型数据，精准控制输入类型。

6. inputMode ()：获取当前输入模式，返回枚举值，校验输入类型是否匹配场景。

7. setTextValue ()：设置文本输入框的默认值，传入字符串（如setTextValue("admin")），为用户提供默认输入内容，提升操作效率。

8. textValue ()：获取文本输入框的用户输入值，返回字符串，读取文本类输入结果。

9. setIntValue ()：设置整数输入框的默认值，传入整数（如setIntValue(20)），适配整数输入场景的默认值配置。

10. intValue ()：获取整数输入框的用户输入值，返回整数，读取整数型输入结果。

11. setDoubleValue ()：设置浮点数输入框的默认值，传入浮点数（如setDoubleValue(99.9)），适配小数输入场景的默认值配置。

12. doubleValue ()：获取浮点数输入框的用户输入值，返回浮点数，读取小数型输入结果。

13. setIntRange ()：设置整数输入的范围，参数为(min, max)（如setIntRange(0, 100)），限制用户只能输入指定区间的整数，避免无效值。

14. intRange ()：获取整数输入的范围，返回(min, max)元组，校验整数输入区间配置。

15. setDoubleRange ()：设置浮点数输入的范围，参数为(min, max)（如setDoubleRange(0.0, 999.99)），限制小数输入区间。

16. doubleRange ()：获取浮点数输入的范围，返回(min, max)元组，校验小数输入区间配置。

17. setDoubleDecimals ()：设置浮点数输入的小数位数，传入整数（如setDoubleDecimals(2)），限制最多输入 2 位小数，适配金额等场景。

18. doubleDecimals ()：获取浮点数的小数位数限制，返回整数，校验小数精度配置。

19. setComboBoxItems ()：设置下拉选择框的选项列表，传入字符串列表（如setComboBoxItems(["Python", "Java", "Go"])），适配固定选项选择场景（替代手动输入）。

20. comboBoxItems ()：获取下拉选择框的选项列表，返回字符串列表，校验下拉选项配置。

21. setTextEchoMode ()：设置文本输入框的回显模式，核心枚举值：

    QLineEdit.EchoMode.Normal：正常显示（默认）；

    Password：密码隐藏（显示●）；

    PasswordEchoOnEdit：编辑时显示、失去焦点隐藏，适配密码输入场景。

22. textEchoMode ()：获取文本回显模式，返回枚举值，校验密码隐藏等配置是否生效。

23. exec ()：显示模态输入对话框（阻塞后续代码直到关闭），返回True（用户点击确认）/False（取消），是核心显示方法。

24. setOkButtonText ()：修改 “确认” 按钮的显示文本，如setOkButtonText("提交")，适配中文界面的按钮文字自定义。

25. setCancelButtonText ()：修改 “取消” 按钮的显示文本，如setCancelButtonText("放弃")，统一界面文字风格。

26. static 快捷方法：无需手动实例化，直接创建常用输入对话框，简化开发：

    getText()：弹出文本输入框，返回(输入文本, 是否确认)；

    getInt()：弹出整数输入框，返回(输入整数, 是否确认)；

    getDouble()：弹出浮点数输入框，返回(输入小数, 是否确认)；

    getItem()：弹拉下选择框，返回(选中选项, 是否确认)。

27. setStyleSheet ()：通过样式表美化对话框，如setStyleSheet("QInputDialog{font-size:12px;} QLineEdit{border:1px solid #ccc;}")，优化输入框、按钮的视觉效果。

28. setModal ()：设置是否为模态对话框，True 为模态（默认，阻塞父窗口交互）、False 为非模态，控制对话框交互规则。

1. setCurrentFont ()：设置对话框默认选中的字体，传入 QFont 对象（如setCurrentFont(QFont("Microsoft YaHei", 12))），为用户提供常用字体默认值，提升操作效率。

2. currentFont ()：获取对话框当前选中的字体，返回 QFont 对象，读取用户选择的字体配置（如字体名称、大小、样式）。

3. setWindowTitle ()：设置字体对话框的窗口标题，如setWindowTitle("选择标题字体")，区分不同字体配置场景（标题 / 正文 / 备注）。

4. windowTitle ()：获取对话框窗口标题，返回字符串，校验标题配置是否符合预期。

5. setOption ()：设置对话框功能选项，核心可选值：

   QFontDialog.Option.NoButtons：隐藏确认 / 取消按钮；

   ShowApplyButton：显示 “应用” 按钮（实时预览字体效果）；

   DontUseNativeDialog：不使用系统原生对话框（使用 Qt 自定义样式），自定义对话框交互规则。

6. testOption ()：判断是否启用指定功能选项，传入枚举值返回布尔值（如testOption(QFontDialog.Option.ShowApplyButton)），校验选项配置。

7. setFont ()：等同于setCurrentFont()，设置默认选中字体，是简化写法，适配不同开发习惯。

8. selectedFont ()：获取用户最终确认的字体，返回 QFont 对象（需在exec()确认后调用），读取最终选择结果的核心方法。

9. exec ()：显示模态字体对话框（阻塞后续代码直到关闭），返回True（用户点击确认）/False（取消），是核心显示方法。

10. open ()：显示非模态字体对话框（不阻塞后续代码），适配无需等待用户确认的实时预览场景。

11. setModal ()：设置是否为模态对话框，True 为模态（默认，阻塞父窗口交互）、False 为非模态，控制对话框交互规则。

12. setStyleSheet ()：通过样式表美化对话框（系统原生对话框样式自定义有限），如setStyleSheet("QFontDialog{font-size:12px;} QListWidget{background:#f5f5f5;}")，优化非系统风格对话框的视觉效果。

13. getFont ()：静态快捷方法，无需手动实例化，直接弹出字体选择对话框，返回(选中的QFont对象, 是否确认)，如font, ok = QFontDialog.getFont(QFont("Arial", 10), parent, "选择正文字体")，简化开发流程。

14. setMinFontSize ()：设置可选字体的最小尺寸，传入整数（如setMinFontSize(8)），限制用户只能选择 8 号及以上字体，避免过小文字无法识别。

15. minFontSize ()：获取字体最小尺寸限制，返回整数，校验尺寸下限配置。

16. setMaxFontSize ()：设置可选字体的最大尺寸，传入整数（如setMaxFontSize(72)），限制用户只能选择 72 号及以下字体，适配界面文字尺寸上限。

17. maxFontSize ()：获取字体最大尺寸限制，返回整数，校验尺寸上限配置。

18. apply.clicked.connect ()：绑定 “应用” 按钮点击信号（需先启用ShowApplyButton选项），触发于点击 “应用” 时，实时预览字体效果（如同步修改界面文字样式）。

19. fontSelected.connect ()：绑定 “字体选中” 信号（未确认前），触发于用户在对话框中切换字体时，实时监听字体选择变化，适配预览场景。

20. setOkButtonText ()：修改 “确认” 按钮的显示文本，如setOkButtonText("确定")，适配中文界面的按钮文字自定义。

21. setCancelButtonText ()：修改 “取消” 按钮的显示文本，如setCancelButtonText("放弃")，统一界面文字风格。

1. setCurrentColor ()：设置对话框默认选中的颜色，传入 QColor 对象（如setCurrentColor(QColor(255, 0, 0))或setCurrentColor(QColor("red"))），为用户提供常用颜色默认值，提升操作效率。

2. currentColor ()：获取对话框当前选中的颜色，返回 QColor 对象，读取用户选择的颜色配置（如 RGB 值、透明度）。

3. setWindowTitle ()：设置颜色对话框的窗口标题，如setWindowTitle("选择按钮背景色")，区分不同颜色配置场景（文字色 / 背景色 / 边框色）。

4. windowTitle ()：获取对话框窗口标题，返回字符串，校验标题配置是否符合预期。

5. setOption ()：设置对话框功能选项，核心可选值：

   QColorDialog.Option.ShowAlphaChannel：显示透明度调节通道（支持 RGBA 颜色）；

   NoButtons：隐藏确认 / 取消按钮；

   DontUseNativeDialog：不使用系统原生对话框（使用 Qt 自定义样式），自定义对话框交互规则。

6. testOption ()：判断是否启用指定功能选项，传入枚举值返回布尔值（如testOption(QColorDialog.Option.ShowAlphaChannel)），校验选项配置。

7. exec ()：显示模态颜色对话框（阻塞后续代码直到关闭），返回True（用户点击确认）/False（取消），是核心显示方法。

8. open ()：显示非模态颜色对话框（不阻塞后续代码），适配无需等待用户确认的实时预览场景。

9. setModal ()：设置是否为模态对话框，True 为模态（默认，阻塞父窗口交互）、False 为非模态，控制对话框交互规则。

10. setStyleSheet ()：通过样式表美化对话框（系统原生对话框样式自定义有限），如setStyleSheet("QColorDialog{font-size:12px;} QPushButton{background:#f5f5f5;}")，优化非系统风格对话框的视觉效果。

11. getColor ()：静态快捷方法，无需手动实例化，直接弹出颜色选择对话框，返回选中的 QColor 对象（取消则返回无效颜色），如color = QColorDialog.getColor(QColor("#4CAF50"), parent, "选择文字颜色")，简化开发流程。

12. setCustomColor ()：设置自定义颜色面板的指定位置颜色，参数为(索引, QColor)（如setCustomColor(0, QColor(100, 149, 237))），添加常用自定义颜色到面板，方便重复选择。

13. customColor ()：获取自定义颜色面板指定位置的颜色，传入索引返回 QColor 对象，读取自定义颜色配置。

14. setStandardColor ()：修改标准颜色面板的指定位置颜色，参数为(索引, QColor)，自定义系统标准颜色面板。

15. standardColor ()：获取标准颜色面板指定位置的颜色，传入索引返回 QColor 对象，校验标准颜色配置。

16. selectedColor ()：获取用户最终确认的颜色，返回 QColor 对象（需在exec()确认后调用），读取最终选择结果的核心方法。

17. colorSelected.connect ()：绑定 “颜色选中” 信号（未确认前），触发于用户在对话框中切换颜色时，实时监听颜色选择变化（如同步预览界面元素颜色）。

18. setOkButtonText ()：修改 “确认” 按钮的显示文本，如setOkButtonText("确定")，适配中文界面的按钮文字自定义。

19. setCancelButtonText ()：修改 “取消” 按钮的显示文本，如setCancelButtonText("放弃")，统一界面文字风格。

20. setDialogLabel ()：修改对话框内置标签的文本，如setDialogLabel(QColorDialog.DialogLabel.Saturation, "饱和度：")，适配中文界面的标签自定义。

1. setRowCount ()：设置表格行数，传入整数（如setRowCount(10)），定义表格的行数量，是构建表格的基础方法。

2. rowCount ()：获取表格当前行数，返回整数，校验行数量配置是否符合预期。

3. setColumnCount ()：设置表格列数，传入整数（如setColumnCount(5)），定义表格的列数量。

4. columnCount ()：获取表格当前列数，返回整数，校验列数量配置。

5. setItem ()：设置指定单元格的内容，参数为(行索引, 列索引, QTableWidgetItem对象)，如setItem(0, 0, QTableWidgetItem("姓名"))，是填充表格数据的核心方法。

6. item ()：获取指定单元格的对象，传入行 / 列索引返回 QTableWidgetItem 对象，读取单元格内容（如item(0,0).text()获取文本）。

7. takeItem ()：移除并返回指定单元格的对象，传入行 / 列索引（如takeItem(1,2)），删除单元格内容并回收资源。

8. setHorizontalHeaderLabels ()：设置水平表头（列标题）的文本，传入字符串列表（如setHorizontalHeaderLabels(["姓名", "年龄", "性别"])），定义列名称。

9. horizontalHeaderLabels ()：获取水平表头文本列表，返回字符串列表，读取列标题配置。

10. setVerticalHeaderLabels ()：设置垂直表头（行标题）的文本，传入字符串列表（如setVerticalHeaderLabels(["行1", "行2"])），定义行名称。

11. verticalHeaderLabels ()：获取垂直表头文本列表，返回字符串列表，读取行标题配置。

12. insertRow ()：在指定索引位置插入行，传入整数（如insertRow(1)在第二行插入空行），动态添加行数据。

13. insertColumn ()：在指定索引位置插入列，传入整数（如insertColumn(2)在第三列插入空列），动态添加列。

14. removeRow ()：删除指定索引的行，传入整数（如removeRow(0)删除第一行），清理行数据。

15. removeColumn ()：删除指定索引的列，传入整数（如removeColumn(1)删除第二列），清理列数据。

16. clear ()：清空表格所有单元格内容（保留表头和行列数），快速重置表格数据。

17. clearContents ()：清空表格单元格内容（仅保留表头），与 clear () 的区别是不影响表头配置。

18. setCurrentCell ()：设置当前选中的单元格，传入行 / 列索引（如setCurrentCell(2,1)），手动指定选中位置。

19. currentCell ()：获取当前选中单元格的行 / 列索引，返回(行, 列)元组，读取选中位置。

20. setCurrentItem ()：设置当前选中的单元格对象，传入 QTableWidgetItem 对象，精准选中指定单元格。

21. currentItem ()：获取当前选中的单元格对象，返回 QTableWidgetItem 实例，读取选中单元格的内容。

22. selectedItems ()：获取所有选中的单元格对象列表，返回List[QTableWidgetItem]，支持多选场景下读取所有选中数据。

23. setSelectionMode ()：设置选择模式，核心可选值：

    QAbstractItemView.SingleSelection：单选（默认）；

    ExtendedSelection：Ctrl/Shift 多选；

    NoSelection：不可选，控制单元格选择权限。

24. setSelectionBehavior ()：设置选择行为，核心可选值：

    QAbstractItemView.SelectItems：选中单个单元格（默认）；

    SelectRows：选中整行；

    SelectColumns：选中整列，适配行 / 列级别的数据操作。

25. setEditTriggers ()：设置单元格编辑触发方式，核心可选值：

    QAbstractItemView.NoEditTriggers：禁止编辑（默认）；

    DoubleClicked：双击可编辑；

    AnyKeyPressed：按任意键可编辑，控制单元格编辑权限。

26. setColumnWidth ()：设置指定列的宽度，参数为(列索引, 宽度值)（如setColumnWidth(0, 100)），调整列的显示宽度。

27. columnWidth ()：获取指定列的宽度，传入列索引返回整数，校验列宽配置。

28. setRowHeight ()：设置指定行的高度，参数为(行索引, 高度值)（如setRowHeight(0, 30)），调整行的显示高度。

29. rowHeight ()：获取指定行的高度，传入行索引返回整数，校验行高配置。

30. resizeColumnsToContents ()：自动调整所有列的宽度以适配内容，避免单元格内容被截断或留白过多。

31. resizeRowsToContents ()：自动调整所有行的高度以适配内容，优化多行文本单元格的显示效果。

32. setSortingEnabled ()：设置是否启用排序，True 为启用、False 为禁用（默认），启用后点击表头可按列排序数据。

33. sortItems ()：手动触发列排序，参数为(列索引, 排序方式)（如sortItems(1, Qt.SortOrder.AscendingOrder)按第二列升序排序），精准控制排序逻辑。

34. setSpan ()：合并单元格，参数为(起始行, 起始列, 合并行数, 合并列数)（如setSpan(0,0,2,3)合并 2 行 3 列），适配表头合并、数据分组展示场景。

35. setStyleSheet ()：通过样式表美化表格，可自定义表头样式、单元格边框、选中背景色等

36. setEnabled ()：设置表格是否可用，True 为正常交互（可选中 / 编辑）、False 为禁用（灰显，无交互），控制核心交互状态。

37. setVisible ()：设置表格是否可见，True 为显示、False 为隐藏，适配数据未加载时隐藏表格的场景。

38. itemClicked.connect ()：绑定 “单元格点击” 信号，触发于点击单元格时，监听点击并执行逻辑（如显示单元格详情）。

39. itemDoubleClicked.connect ()：绑定 “单元格双击” 信号，触发于双击单元格时，如编辑单元格内容、打开关联数据。

40. cellChanged.connect ()：绑定 “单元格内容变化” 信号，触发于单元格内容修改后，监听数据变更并执行保存逻辑。

后续我会持续输出优质、实用的内容，也欢迎大家在评论区留言，说说你们最想学习的内容、遇到的困惑，我们一起交流、一起进步。

愿每一位软件人，都能在这里收获知识、突破自我，在自己的赛道上发光发热✨