横竖屏切换开发实践

横竖屏切换开发实践

在 HarmonyOS 应用开发中，实现横竖屏切换功能需要关注多方面内容。

窗口旋转策略选择

1. module.json5 文件配置：适用于应用启动时就确定横竖屏显示状态的情况。例如竖屏应用可配置 “portrait”；横屏应用若仅支持横屏配置 “landscape”，支持横屏与反向横屏切换则配置 “auto_rotation_landscape”；可旋转应用配置 “auto_rotation_restricted”；直板机和折叠机折叠态竖屏、平板和折叠机展开态可旋转的应用配置 “follow_desktop”。带 “restricted” 字段表示旋转受控制中心按钮控制。

2. setPreferredOrientation 方法调用：用于应用启动后需改变显示方向的场景，如视频类、图片类应用。该方法设置窗口方向后，窗口将保持此状态，即使页面跳转也不变。

视频类应用横竖屏开发

1. 设置窗口旋转策略

2. 启动时根据设备类型设置旋转策略，如设置为 “follow_desktop”。在特定页面（如视频播放页）需支持横竖屏切换，通过getContext等一系列操作获取窗口实例，调用setPreferredOrientation方法，根据用户操作（如点击全屏按钮）及设备状态（如折叠屏状态）选择合适的枚举值（如USER_ROTATION_LANDSCAPE或USER_ROTATION_PORTRAIT）来设置横竖屏，并注意在横竖屏切换时手动调用接口改变窗口方向。

3. 监听窗口变化：通过window.on('windowSizeChange')监听窗口尺寸变化，建议在aboutToAppear中执行，在aboutToDisappear中取消监听。根据窗口宽高关系判断横竖屏状态，因为手动设置横屏时，窗口宽高会改变（宽变为竖屏高，高变为竖屏宽），以此来适配布局。

4. 进行布局适配：利用 UI 状态更新，将视频播放组件尺寸定义为@State状态并绑定到XComponent组件。在监听窗口变化回调中，根据横竖屏状态动态修改XComponent宽高，实现全屏或退出全屏逻辑，注意平板和直板机在旋转时视频播窗全屏处理的差异，可通过设备类型判断或响应式布局断点方式处理。

5. 锁定屏幕功能：部分视频应用支持屏幕锁定，锁定时设置旋转策略为AUTO_ROTATION_LANDSCAPE，解锁时恢复为AUTO_ROTATION_UNSPECIFIED。同时要判断设备控制中心旋转锁定状态，避免重复操作，可通过settings.registerKeyObserver监听控制中心状态。

游戏类应用横屏开发

1. 默认仅为横屏：在module.json5中 “orientation” 字段配置为 “landscape”。

2. 支持横屏和反向横屏：配置为 “auto_rotation_landscape”，若要跟随控制中心旋转锁定，可配置为 “auto_rotation_landscape_restricted”。

3. 支持竖屏切换横屏：类似视频播放横竖屏切换，从竖屏进入横屏需调用设置窗口旋转方法。

性能优化

1. 自定义组件冻结：使用@Component({ freezeWhenInactive: true })冻结不需要因旋转更新 UI 的组件，如视频播放下的详情内容组件。

2. 对图片使用 autoResize：为旋转页面中的图片设置autoResize属性，根据显示区域裁剪图片，减少内存占用。

3. 排查耗时操作：检查页面是否存在冗余OnAreaChange事件、blur模糊或线性变化linearGradient属性等耗时操作，根据必要性优化。

其他常见问题及解决

1. Tabs 栏中的视频横屏播放无法隐藏 Tabs 栏：通过设置Tabs组件的barHeight属性，根据全屏状态隐藏或显示 Tabs 栏。

2. 直板机和平板默认旋转行为不一致：将module.json5文件中 “orientation” 字段设置为 “follow_desktop”。

3. 获取窗口实例延迟：使用windowStage.getMainWindowSync同步方式获取窗口实例，避免因getLastWindow底层查找导致的性能损耗和状态切换延迟问题。

4. 自动旋转和旋转锁定按钮及 Orientation 字段关系：控制中心旋转开关控制是否跟随屏幕旋转，“旋转锁定” 高亮不可旋转，灰色可旋转。希望跟随控制中心旋转开关行为，选择带 “RESTRICTED” 后缀字段的旋转方式，如AUTO_ROTATION_RESTRICTED；否则设置为AUTO_ROTATION等，不同旋转方式同理。