更新记录

1.0.0（2026-04-03） 下载此版本

解决了 uniapp 在高频横竖屏切换场景下，由于渲染引擎与原生容器布局同步延迟，导致的偶发性视口渲染异常（Viewport Rendering Glitch）及半屏断层问题。

平台兼容性

uni-app(4.52)

uni-app x(4.27)

rs-orientationfix 使用文档

修复 uni-app Android 端横竖屏切换时 WebView 出现半屏显示的问题。

基本信息

目录结构

nativeplugins/
└── rs-orientationfix/
    ├── android/
    │   └── rs-orientationfix.aar   ← Android 原生库文件
    └── package.json                        ← 插件描述配置

第一步：放置插件文件

将插件目录放置在项目根目录的 nativeplugins/ 文件夹下：

项目根目录/
└── nativeplugins/
    └── rs-orientationfix/
        ├── android/
        │   └── rs-orientationfix.aar
        └── package.json

第二步：配置 package.json

nativeplugins/rs-orientationfix/package.json 内容如下：

{
  "name": "rs-orientationfix",
  "id": "rs-orientationfix",
  "version": "1.0.0",
  "description": "修复 uniapp 横竖屏切换时的半屏显示问题",
  "_dp_type": "nativeplugin",
  "_dp_nativeplugin": {
    "android": {
      "plugins": [
        {
          "type": "module",
          "name": "OrientationFix",
          "class": "io.dcloud.uniplugin.OrientationFixModule"
        }
      ],
      "integrateType": "aar"
    }
  }
}

第三步：注册到 manifest.json

在项目的 manifest.json → app-plus → nativePlugins 中添加插件注册信息：

"nativePlugins": {
    "rs-orientationfix": {
        "__plugin_info__": {
            "name": "横竖屏切换修复插件",
            "description": "修复横竖屏切换时的半屏显示问题",
            "platforms": "Android",
            "isCloud": false
        }
    }
}

⚠️ "isCloud": false 表示本地私有插件，不走 DCloud 插件市场，直接读取本地 AAR 文件。

第四步：在页面中调用插件

以下为完整的使用示例（参考 pages/home/home.vue）：

import { onMounted, onUnmounted } from 'vue'

let windowResizeHandler = null
let orientationCheckInterval = null

onMounted(() => {
    // #ifdef APP-PLUS
    // 1. 加载原生插件
    const OrientationFix = uni.requireNativePlugin('OrientationFix')

    if (OrientationFix) {
        console.log('原生插件 OrientationFix 加载成功')

        // 2. 启动屏幕方向监听（只需调用一次）
        OrientationFix.startOrientationMonitor((res) => {
            console.log('原生插件启动结果:', res)
        })

        // 3. 窗口变化时调用布局修复
        windowResizeHandler = () => {
            checkScreenOrientation()  // 自定义的前端方向检测函数

            // 调用原生插件修复 WebView 半屏布局
            OrientationFix.fixWebViewLayout((res) => {
                console.log('原生布局修复结果:', res)
            })
        }
    } else {
        // 插件加载失败时的降级处理
        console.warn('原生插件 OrientationFix 加载失败，使用前端方案')
        windowResizeHandler = () => {
            checkScreenOrientation()
        }
    }
    // #endif

    // 4. 注册窗口变化监听
    if (typeof uni.onWindowResize === 'function') {
        uni.onWindowResize(windowResizeHandler)
    } else {
        // 降级：定时器轮询
        orientationCheckInterval = setInterval(() => {
            checkScreenOrientation()
        }, 1000)
    }
})

onUnmounted(() => {
    // 5. 页面卸载时清理监听
    if (windowResizeHandler) {
        uni.offWindowResize(windowResizeHandler)
    }
    if (orientationCheckInterval) {
        clearInterval(orientationCheckInterval)
    }
})

API 说明

startOrientationMonitor(callback)

启动原生屏幕方向监听器。

• 调用时机：页面 onMounted 时调用一次即可
• 参数：callback(res) — 启动结果回调

OrientationFix.startOrientationMonitor((res) => {
    console.log(res) // 返回启动状态信息
})

fixWebViewLayout(callback)

修复 WebView 布局，解决横竖屏切换后的半屏显示问题。

• 调用时机：每次窗口尺寸变化（onWindowResize）时调用
• 参数：callback(res) — 修复结果回调

OrientationFix.fixWebViewLayout((res) => {
    console.log(res) // 返回修复状态信息
})

配合使用：pages.json 页面方向配置

需要在 pages.json 中开启页面的自动旋转支持，插件才能生效：

{
    "globalStyle": {
        "pageOrientation": "auto"
    },
    "pages": [
        {
            "path": "pages/home/home",
            "style": {
                "screenOrientation": "auto"
            }
        }
    ]
}

工作原理

设备旋转
    │
    ▼
pages.json: screenOrientation = "auto"   ← 允许页面旋转
    │
    ▼
uni.onWindowResize 触发 windowResizeHandler
    │
    ├──→ checkScreenOrientation()              ← 前端检测方向，更新 UI 状态
    │
    └──→ OrientationFix.fixWebViewLayout()     ← 原生插件修复 WebView 半屏问题
              ↑
    uni.requireNativePlugin('OrientationFix')
              ↑
    io.dcloud.uniplugin.OrientationFixModule (AAR)

降级策略

插件内部具备完善的降级机制，即使原生插件加载失败，应用也能正常运行：

注意事项

1. 仅支持 Android，iOS 端不生效（使用 #ifdef APP-PLUS 条件编译包裹调用代码）
2. 插件需要自定义基座或正式打包后才能生效，HBuilderX 标准基座不支持本地原生插件
3. startOrientationMonitor 只需在页面初始化时调用一次
4. fixWebViewLayout 应在每次 onWindowResize 回调中调用
5. 页面卸载时记得调用 uni.offWindowResize 移除监听，避免内存泄漏