设置contentOrientation后弹出框出现时调光效果异常如何解决

问题根源 #

Odroid-N2配套2019版Ubuntu镜像搭载的Qt版本（通常为Qt 5.12 LTS分支）存在已知渲染缺陷：设置ApplicationWindow的contentOrientation属性后，模态弹窗的全局调光遮罩（dimming overlay）坐标计算未适配屏幕方向变更，仍默认使用原始竖屏的宽高参数计算遮罩尺寸，最终仅覆盖半屏。同时之前手动给根Page设置rotation:90的逻辑和全局方向设置冲突，会进一步放大渲染异常。

修复步骤 #

• 第一步：删除冗余的根Page旋转配置
  移除之前给根Page设置的rotation:90属性，全局方向统一通过ApplicationWindow的contentOrientation控制，避免两套旋转逻辑冲突。
• 第二步：自定义全局模态遮罩替代默认实现
  在main.qml的ApplicationWindow根节点下添加如下自定义遮罩代码，完全接管模态弹窗的调光效果：

  ApplicationWindow {
      id: mainWindow
      visible: true
      width: Screen.width
      height: Screen.height
      contentOrientation: Qt.LandscapeOrientation
      
      // 自定义全局调光遮罩
      Rectangle {
          id: customDimmingOverlay
          anchors.fill: parent
          color: "#80000000" // 半透明黑色，可根据需求调整透明度
          z: 9998 // 层级低于弹窗，高于所有普通界面元素
          visible: false
          
          // 监听当前窗口的模态弹窗状态
          Connections {
              target: mainWindow
              function onActiveFocusItemChanged() {
                  // 检查当前焦点元素是否为模态弹窗
                  var activeItem = mainWindow.activeFocusItem
                  var isModalPopupActive = false
                  while(activeItem) {
                      if(activeItem.hasOwnProperty("modal") && activeItem.modal) {
                          isModalPopupActive = true
                          break
                      }
                      activeItem = activeItem.parent
                  }
                  customDimmingOverlay.visible = isModalPopupActive
              }
          }
      }
      
      // 你的原有页面内容
      Page {
          // 移除此处的rotation:90配置
          // 其余原有内容保持不变
      }
  }
  

• 第三步：禁用Qt默认调光效果
  给所有弹出框（Popup/Dialog及其子类）添加dim: false属性，关闭Qt自带的调光逻辑，避免和自定义遮罩重叠。如果项目中弹出框较多，可以直接定义全局通用弹窗组件统一配置：

  // 自定义基础弹窗组件 BasePopup.qml
  import QtQuick.Controls 2.x
  Popup {
      dim: false
      z: 9999 // 层级高于自定义遮罩
      // 其余通用弹窗配置可统一在此添加
  }
  

  后续所有业务弹窗直接继承BasePopup即可，无需单独配置。

验证方法 #

部署到设备后触发无效参数输入场景，检查两个核心点：

1. 弹出框正常横屏显示，无内容裁剪
2. 调光遮罩完整覆盖整个应用窗口，无半屏缺失问题

内容的提问来源于stack exchange，提问作者Mohammad Ali