cordova-plugin-screen-orientation（屏幕方向控制插件）

一款用于在 Cordova 应用中设置和锁定屏幕方向的插件。该插件提供简洁的 API，可实现屏幕方向控制，包括锁定至特定方向（竖屏、横屏等）以及监听方向变化事件。

1. 概述

cordova-plugin-screen-orientation 插件允许 Cordova 开发者控制移动应用的屏幕方向，支持将屏幕锁定至特定方向（如竖屏、左侧横屏等），并能检测设备方向的变化。本文档主要介绍该插件在OHOS系统中的应用。

1.1 支持的平台

• Android（API 级别 14 及以上）

• iOS（iOS 9.0 及以上）

• Windows（Windows 10 及以上）

• 浏览器（Chrome、Firefox、Safari）

• OHOS（5.0 及以上）

1.2 核心功能

• 锁定屏幕至特定方向模式

• 解锁屏幕方向，允许自动旋转

• 获取当前屏幕方向

• 监听屏幕方向变化事件

• 支持各平台专属配置选项

2. 安装步骤

2.1 安装 Hcordova

npm install -g hcordova

2.2 通过 HCordova CLI 安装

直接通过 HCordova 命令行工具安装：

#全平台安装
hcordova plugin add cordova-plugin-screen-orientation

#指定OHOS平台安装
hcordova plugin add cordova-plugin-screen-orientation --platform ohos

2.3 卸载插件

通过 Cordova CLI 移除插件：

#全平台卸载
hcordova plugin remove cordova-plugin-screen-orientation
#指定OHOS卸载
hcordova plugin remove cordova-plugin-screen-orientation --platform ohos

3. 核心 API

3.1 命名空间

插件所有方法均在全局对象 screen.orientation 下可用。

3.2 锁定屏幕方向

将屏幕锁定至指定的方向模式。

3.2.1 语法

screen.orientation.lock(orientationMode)
 .then(() => {
   // 成功：屏幕方向已锁定
 })
 .catch((error) => {
   // 失败：锁定方向时出错
   console.error('屏幕方向锁定失败：', error);
 });

3.2.2 方向模式

以下方向模式在多数平台中均支持：

| 模式名称 | 描述说明 | | --------------------- | ------------------------ | | portrait-primary | 主竖屏模式（设备默认的竖屏方向） | | portrait-secondary | 副竖屏模式（倒置竖屏，即屏幕上下翻转） | | landscape-primary | 主横屏模式（设备默认的横屏方向，通常为右侧横屏） | | landscape-secondary | 副横屏模式（与主横屏相反的方向，通常为左侧横屏） | | portrait | 锁定至任意竖屏模式（包含主竖屏和副竖屏） | | landscape | 锁定至任意横屏模式（包含主横屏和副横屏） | | any | 允许任意方向（自动旋转，效果等同于解锁方向） |

注意：部分模式并非在所有平台都支持（例如，多数 Android 设备默认不支持 portrait-secondary 倒置竖屏模式）。

3.2.3 示例代码

将屏幕锁定为横屏模式：

// 等待 Cordova 加载完成
document.addEventListener('deviceready', () => {
 // 锁定屏幕为横屏模式
 screen.orientation.lock('landscape')
   .then(() => {
     console.log('屏幕已锁定为横屏');
   })
   .catch((error) => {
     console.error('横屏锁定失败：', error);
   });
}, false);

3.3 解锁屏幕方向

解锁屏幕方向，允许设备根据传感器自动旋转屏幕。

3.3.1 语法

screen.orientation.unlock();

3.3.2 示例代码

5 秒后自动解锁屏幕方向：

document.addEventListener('deviceready', () => {
 // 先将屏幕锁定为竖屏
 screen.orientation.lock('portrait')
   .then(() => {
     console.log('屏幕已锁定为竖屏');
     // 5 秒后解锁方向
     setTimeout(() => {
       screen.orientation.unlock();
       console.log('屏幕方向已解锁（开启自动旋转）');
     }, 5000);
   });
}, false);

3.4 获取当前屏幕方向

获取当前屏幕所处的方向模式。

3.4.1 语法

const currentOrientation = screen.orientation.type;

console.log('当前屏幕方向：', currentOrientation);

screen.orientation.type 属性返回的字符串与 3.2.2 方向模式 中列出的模式名称一致。

3.4.2 示例代码

设备加载完成后，打印当前屏幕方向：

document.addEventListener('deviceready', () => {
 const currentOrientation = screen.orientation.type;
 console.log('当前屏幕方向：', currentOrientation);
 // 示例输出："portrait-primary"（主竖屏）或 "landscape-secondary"（副横屏）
}, false);

3.5 监听屏幕方向变化

注册事件监听器，实时检测屏幕方向的变化。

3.5.1 语法

// 添加监听器

screen.orientation.addEventListener('change', (event) => {
 console.log('屏幕方向已变更为：', event.type);
});

// （可选）移除监听器
const handleOrientationChange = (event) => {
 console.log('屏幕方向变更：', event.type);
};

// 先注册监听器
screen.orientation.addEventListener('change', handleOrientationChange);

// 后续需要时移除监听器
screen.orientation.removeEventListener('change', handleOrientationChange);

event 对象包含 type 属性，该属性值为变更后的方向模式名称。

3.5.2 示例代码

屏幕方向变化时更新页面 UI：

document.addEventListener('deviceready', () => {
 // 添加方向变化监听器
 screen.orientation.addEventListener('change', (event) => {
   const newOrientation = event.type;
   const orientationElement = document.getElementById('orientation-status');
   // 更新 UI 显示当前方向
   orientationElement.textContent = "当前屏幕方向："+newOrientation;
   // 示例：根据方向调整页面布局
   if (newOrientation.includes('portrait')) {
     document.body.classList.add('portrait-layout');
     document.body.classList.remove('landscape-layout');
   } else {
     document.body.classList.add('landscape-layout');
     document.body.classList.remove('portrait-layout');
   }
 });
}, false);

6. 许可证

本插件基于 Apache License 2.0 开源，详情请查看 LICENSE 文件。

9. 联系方式

• GitHub Android/iOS 仓库：apache/cordova-plugin-screen-orientation

• 问题反馈：GitHub Issues

• OHOS：GitCode