@capacitor/screen-orientation

本项目基于 @capacitor/[email protected] 开发。

简介

提供屏幕方向 API 及相关功能，支持获取当前方向、锁定/解锁方向和监听方向变化。本插件是 capacitor 生态系统中的核心插件，为跨平台应用开发提供设备差异化适配能力，兼容 capacitor 的 Android、iOS 等主流移动平台及浏览器环境中使用，本文档仅说明在 OpenHarmony 系统中的使用情况。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @capacitor/screen-orientation

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/screen-orientation

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
  "pkg": "@capacitor/screen-orientation",
  "classpath": "ScreenOrientation"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，找到 capacitor 模块，路径为 target 字段的 CMakeLists.txt 文件，并添加 add_subdirectory 和 target_link_libraries 如下：

// ...
add_subdirectory(ScreenOrientation)
// ...

// ...
target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  ScreenOrientation
  // ...
  "-Wl,--no-whole-archive"
);

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并复制到对应的目录：

将源码中 src/main/cpp/ScreenOrientation 目录下 ScreenOrientation.h、ScreenOrientation.cpp、CMakeLists.txt 文件引入到 capacitor 模块中 src/main/cpp/ScreenOrientation 目录下。

将源码中 src/main/ets/components/ScreenOrientation 目录下 ScreenOrientation.ets 文件引入到 capacitor 模块中 src/main/ets/components/ScreenOrientation 目录下。

在 capacitor 模块下 build-profile.json5 文件中，buildOption/arkOptions/runtimeOnly/sources 配置项数组中加入拷贝的 ets 文件路径：

"buildOption": {
  "arkOptions": {
    "runtimeOnly": {
      "sources": [
        // ...
        "./src/main/ets/components/ScreenOrientation/ScreenOrientation.ets"
        // ...
      ]
    }
  }
}

卸载

# 卸载 screen-orientation 插件
hionic plugin remove @capacitor/screen-orientation

约束与限制

兼容性

在以下版本中已测试通过：

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

不需要额外权限。

使用示例

基础示例：获取屏幕方向、锁定方向、解锁方向并监听方向变化

import { ScreenOrientation } from '@capacitor/screen-orientation';

// 获取当前屏幕方向
const getOrientation = async () => {
  const result = await ScreenOrientation.orientation();
  console.log('Current orientation:', result.type);
};

// 锁定屏幕方向为横屏
const lockLandscape = async () => {
  await ScreenOrientation.lock({
    orientation: 'landscape'
  });
};

// 锁定屏幕方向为竖屏
const lockPortrait = async () => {
  await ScreenOrientation.lock({
    orientation: 'portrait'
  });
};

// 解锁屏幕方向
const unlockOrientation = async () => {
  await ScreenOrientation.unlock();
};

// 监听屏幕方向变化
const listenOrientationChanges = async () => {
  const listener = await ScreenOrientation.addListener(
    'screenOrientationChange',
    (orientation) => {
      console.log('Orientation changed:', orientation.type);
    }
  );

  // 稍后移除监听器
  // listener.remove();
};

// 移除所有监听器
const removeAllListeners = async () => {
  await ScreenOrientation.removeAllListeners();
};

使用说明

接口方法

| 方法名 | 返回类型 | 描述 | | ------------------- | ------------------------------ | ---------------------------------- | | orientation() | Promise<ScreenOrientationResult> | 返回当前屏幕方向 | | lock(options: OrientationLockOptions) | Promise | 锁定屏幕方向 | | unlock() | Promise | 解锁屏幕方向 | | addListener('screenOrientationChange', ...) | Promise<PluginListenerHandle> | 监听屏幕方向变化 | | removeAllListeners() | Promise | 移除所有监听器 |

数据结构

ScreenOrientationResult

export interface ScreenOrientationResult {
  type: OrientationType;
}

OrientationLockOptions

export interface OrientationLockOptions {
  orientation: OrientationLockType;
}

PluginListenerHandle

| 属性 | 类型 | | ------------ | --------------------- | | remove | () => Promise<void> |

OrientationType

export type OrientationType =
  | 'any'
  | 'natural'
  | 'landscape'
  | 'portrait'
  | 'portrait-primary'
  | 'portrait-secondary'
  | 'landscape-primary'
  | 'landscape-secondary';

OrientationLockType

export type OrientationLockType =
  | 'any'
  | 'natural'
  | 'landscape'
  | 'portrait'
  | 'portrait-primary'
  | 'portrait-secondary'
  | 'landscape-primary'
  | 'landscape-secondary';

目录结构

|---- 项目根目录
|     |---- src
|           |---- main
|                 |---- cpp
|                       |---- ScreenOrientation   # 插件核心 C++ 实现
|                             |---- ScreenOrientation.h
|                             |---- ScreenOrientation.cpp
|                             |---- CMakeLists.txt
|                 |---- ets
|                       |---- components
|                             |---- ScreenOrientation   # 插件核心 ArkTS 实现
|                                   |---- ScreenOrientation.ets
|     |---- README.md          # 说明文档
|     |---- package.json       # npm 配置文件
|     |---- plugin.xml         # capacitor 插件配置
|     |---- LICENSE            # 许可证文件

贡献代码

使用过程中发现任何问题都可以提 Issue，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。