npm package: @luqi_test/cordova-plugin-screen-orientation
Description: Cordova Screen Orientation Plugin
Author: Huawei Device, Inc. Ltd. and
Latest version: 3.0.4

# 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


```bash
npm install -g hcordova

```

### 2.2 通过 HCordova CLI 安装

直接通过 HCordova 命令行工具安装：

```bash
#全平台安装
hcordova plugin add cordova-plugin-screen-orientation

#指定OHOS平台安装
hcordova plugin add cordova-plugin-screen-orientation --platform ohos
```

### 2.3 卸载插件

通过 Cordova CLI 移除插件：

```bash
#全平台卸载
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 语法



```js
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 示例代码

将屏幕锁定为横屏模式：

```js
// 等待 Cordova 加载完成
document.addEventListener('deviceready', () => {
 // 锁定屏幕为横屏模式
 screen.orientation.lock('landscape')
   .then(() => {
     console.log('屏幕已锁定为横屏');
   })
   .catch((error) => {
     console.error('横屏锁定失败：', error);
   });
}, false);
```

### 3.3 解锁屏幕方向

解锁屏幕方向，允许设备根据传感器自动旋转屏幕。

#### 3.3.1 语法


```js
screen.orientation.unlock();
```

#### 3.3.2 示例代码

5 秒后自动解锁屏幕方向：


```js
document.addEventListener('deviceready', () => {
 // 先将屏幕锁定为竖屏
 screen.orientation.lock('portrait')
   .then(() => {
     console.log('屏幕已锁定为竖屏');
     // 5 秒后解锁方向
     setTimeout(() => {
       screen.orientation.unlock();
       console.log('屏幕方向已解锁（开启自动旋转）');
     }, 5000);
   });
}, false);
```

### 3.4 获取当前屏幕方向

获取当前屏幕所处的方向模式。

#### 3.4.1 语法

```js
const currentOrientation = screen.orientation.type;

console.log('当前屏幕方向：', currentOrientation);
```

`screen.orientation.type` 属性返回的字符串与 [3.](#322-方向模式)[2.2 方](#322-方向模式)[向模式](#322-方向模式) 中列出的模式名称一致。

#### 3.4.2 示例代码

设备加载完成后，打印当前屏幕方向：


```js
document.addEventListener('deviceready', () => {
 const currentOrientation = screen.orientation.type;
 console.log('当前屏幕方向：', currentOrientation);
 // 示例输出："portrait-primary"（主竖屏）或 "landscape-secondary"（副横屏）
}, false);
```

### 3.5 监听屏幕方向变化

注册事件监听器，实时检测屏幕方向的变化。

#### 3.5.1 语法

```js
// 添加监听器

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：


```js
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](LICENSE) 文件。


## 9. 联系方式

* **GitHub Android/iOS 仓库**：[apache/cordova-plugin-screen-orientation](https://github.com/apache/cordova-plugin-screen-orientation)

* **问题反馈**：[GitHub Issues](https://github.com/apache/cordova-plugin-screen-orientation/issues)

* **OHOS**：[GitCode](https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-screen-orientation)