2025最新uni-app横屏适配方案：微信小程序全平台兼容实战

以下为uni-app实现微信小程序横屏适配技术方案，包含核心原理、配置方法、代码示例和注意事项：

---

一、横屏适配原理

微信小程序默认采用竖屏模式，横屏适配需通过以下机制实现：

1. 全局配置：在app.json中声明支持横屏
2. 页面级配置：在pages.json中单独设置页面方向
3. 动态旋转：通过API动态切换屏幕方向
4. 样式适配：使用CSS响应式布局技术

---

二、基础配置步骤

1. 修改项目配置文件

在pages.json中添加页面方向配置：

{"path": "pages/landscape/index","style": {"navigationBarTitleText": "横屏页面","pageOrientation": "landscape" // 关键配置}
}

2. 微信原生配置

在src/manifest.json中添加：

"mp-weixin": {"appid": "","setting": {"urlCheck": false,"screenOrientation": ["portrait", "landscape"] // 允许横竖屏切换}
}

---

三、动态方向控制

1. 页面级控制

// 在页面onLoad中设置
uni.setScreenOrientation({orientation: 'landscape-primary', // 横屏正向success: () => console.log('横屏设置成功'),fail: (err) => console.error('设置失败', err)
});

2. 组件级控制

<template><view :style="{transform: `rotate(${rotateDeg}deg)`}"><!-- 内容 --></view>
</template><script>
export default {data() {return {rotateDeg: 90 // 旋转角度}}
}
</script>

---

四、布局适配方案

1. 响应式单位

/* 使用视窗单位 */
.container {width: 100vw;height: 100vh;padding: 2vh 5vw;
}/* 媒体查询适配 */
@media (orientation: landscape) {.content {flex-direction: row;}
}

2. 动态尺寸计算

const systemInfo = uni.getSystemInfoSync()
export default {data() {return {screenWidth: systemInfo.windowHeight, // 横屏时宽高互换screenHeight: systemInfo.windowWidth}}
}

---

五、高级功能实现

1. 全屏视频适配

<video :style="{width: screenWidth+'px', height: screenHeight+'px'}":direction="videoDirection"@fullscreenchange="handleFullscreen"
></video><script>
export default {methods: {handleFullscreen(e) {this.videoDirection = e.detail.fullScreen ? 90 : 0}}
}
</script>

2. Canvas绘图适配

const ctx = uni.createCanvasContext('myCanvas')
const dpr = uni.getSystemInfoSync().pixelRatio// 横屏时交换宽高
ctx.canvas.width = screenHeight * dpr
ctx.canvas.height = screenWidth * dpr
ctx.scale(dpr, dpr)

---

六、注意事项

1. 平台差异：

   • 微信小程序：支持完整横屏API
   • H5端：需配合CSS transform实现
   • App端：需使用plus.screen控制

2. 性能优化：

   // 防抖处理方向切换
   let resizeTimer
   window.addEventListener('resize', () => {clearTimeout(resizeTimer)resizeTimer = setTimeout(handleResize, 300)
   })
   

3. 真机调试要点：

   • 必须添加小程序合法域名
   • 需要在微信开发者工具中开启横屏调试
   • 部分安卓机型需要额外配置<meta name="viewport">

---

七、完整示例代码

<template><view class="container" :style="containerStyle"><view class="content-box"><text class="title">横屏演示</text><button @click="toggleOrientation">切换方向</button></view></view>
</template><script>
export default {data() {return {isLandscape: true,screenWidth: 0,screenHeight: 0}},computed: {containerStyle() {return {width: this.screenWidth + 'px',height: this.screenHeight + 'px'}}},mounted() {this.updateScreenSize()window.addEventListener('resize', this.updateScreenSize)},methods: {updateScreenSize() {const info = uni.getSystemInfoSync()this.screenWidth = this.isLandscape ? info.windowHeight : info.windowWidththis.screenHeight = this.isLandscape ? info.windowWidth : info.windowHeight},toggleOrientation() {this.isLandscape = !this.isLandscapeuni.setScreenOrientation({orientation: this.isLandscape ? 'landscape' : 'portrait'})}}
}
</script><style>
.container {display: flex;justify-content: center;align-items: center;background: #f0f0f0;
}.content-box {width: 80vh;height: 60vh;background: white;border-radius: 16rpx;padding: 40rpx;
}@media (orientation: portrait) {.content-box {width: 80vw;height: auto;}
}
</style>

---

八、常见问题解决

1. 内容拉伸问题：

   • 使用aspect-ratio保持比例
   • 添加object-fit: contain属性

2. 键盘弹出异常：

   // 监听键盘高度变化
   uni.onKeyboardHeightChange(res => {this.keyboardHeight = res.height
   })
   

3. 导航栏适配：

   // pages.json
   "navigationStyle": "custom",
   "app-plus": {"titleNView": false
   }
   

---

通过以上方案，开发者可以在uni-app中实现完整的微信小程序横屏适配。建议在实际开发中结合真机测试和性能监控工具，持续优化用户体验。对于复杂场景，可考虑使用CSS Grid布局和WebP图片格式来提升渲染性能。