# @capgo/capacitor-screen-orientation 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-screen-orientation/

版本：8\.4\.3
npm 元数据更新时间：2026-10-15T02:40:08.762Z
中文译文更新时间：2026-11-09T03:45:44.453Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-screen-orientation
原文对照：https://npmcn.com/package/%40capgo/capacitor-screen-orientation/?lang=original
项目主页：https://capgo.app/docs/plugins/screen-orientation/
源码仓库：https://github.com/Cap-go/capacitor-screen-orientation

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：305 kB，34 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-11-28T15:35:52.823Z
- 最新版本发布：2026-10-15T02:40:08.430Z
- 近 30 天下载量：43411（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 29 个）

## 中文简介

支持绕行方向锁定的屏幕方向插件

## 安装

```sh
npm install @capgo/capacitor-screen-orientation
```

也可以使用：`pnpm add @capgo/capacitor-screen-orientation`、`yarn add @capgo/capacitor-screen-orientation`、`bun add @capgo/capacitor-screen-orientation`

## README

# @ capgo/ 电容器- 屏幕定向

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-screen-orientation)](https://capgo.app/?ref=plugin_screen_orientation)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_screen_orientation)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_screen_orientation) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-screen-orientation` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _添加@capgo/电容-屏幕定向到我的电容软件上并把它接上_ [代理设置指南](https://capgo.app/agents/?ref=plugin_screen_orientation) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_screen_orientation)

用于检测真实物理设备方向的屏幕定向插件

## 特征

-   QQ 全屏幕方向 API 支持
-   🔍 **检测真实物理设备方向** 使用运动传感器(即使在启用方向锁定时)
    -   iOS:使用核心运动框架
    -   Android: 使用加速计传感器
-   🔒 **检测是否启用方向锁定** 通过比较物理对 UI 方向
-   实时定向变化检测
-   QQ 锁定特定模式的方向
-   📖 **可折叠设备** (Galaxy Z Fold/Flip, Pixel Fold, Surface Duo, iPhone Duo):姿势,主线,大小类,活线折叠更新
-   QQ 网络平台支持

**重要说明:** 此插件可以使用运动传感器检测设备的物理方向, 但是它 **无法绕过 UI 方向锁**。屏幕仍将尊重用户的方向锁定设置。 这对了解设备的物理控件对显示UI的方式很有用.

## 可折叠设备

折叠器给你的不只是一个更宽的画布: 链条,封面屏幕,和姿势改变人们持有手机的方式. 此插件在 JavaScript 中报告状态, 这样您就可以调整布局, 控制, 和介质, 而不从窗口大小猜测 。 它针对Galaxy Z Fold and Flip, Pixel Fold, Surface Duo, 和iPhone Duo(iOS 27.1+), 以及本套件中已有的定向API.

**你得到的东西**

-   **设备和姿态**数字 : `isDeviceFoldable()`, (中文(简体) ), `getFoldState()` (单位:千美元)`flat` 编号 : `half-opened`, (中文(简体) ), `posture` `flat` 编号 : `tabletop` 编号 : `book`, 链边, 分离折叠, 酌情被覆盖的链边区域)
-   **兴格角**数字 : `getHingeAngle()` 财务报告和审定财务报表 `hingeAngleChange` (Android上的原生传感器;iOS 27.1+上的iPhone Duo; `null` 网上)
-   **布局信号**数字 : `getSizeClass()` 财务报告和审定财务报表 `sizeClassChange` (Apple Control/正则外加材料宽度/高等)
-   **iPhone Duo 额外费用**数字 : `activeDisplay` (单位:千美元)`inner` 编号 : `outer`, (中文(简体) ), `getReservedRegions()`, (中文(简体) ), `getBarPlacement()`, (中文(简体) ), `setVerticalBarBehavior()`
-   **实时更新**数字 : `foldStateChange` 当姿态或相接几何改变报告的折叠状态时(如果 `devicePosture` 可供使用,但可用的视图段不可用)

**不错**

-   沿着链条而不是固定断点的双平面布局
-   当用户折叠到桌面或书上时移动的工具栏、游戏板或读取器
-   可折叠和iPhone Duo上的封面屏幕对内屏幕流量
-   当用户完全打开设备时反应的大小级驱动 UI

**快开始**

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

const fold = await ScreenOrientation.getFoldState();
console.log(fold.posture, fold.hingeBounds);

await ScreenOrientation.addListener('foldStateChange', (state) => {
  document.documentElement.dataset.posture = state.posture;
});
```

**iPhone Duo (iOS 27.1+) (中文(简体) )**

| 宝斯 | `posture` | 兴克(典型) |
| --- | --- | --- |
| 打开平面, 或关闭外显示 | `flat` | `180` 打开, `0` 关闭 |
| 像书一样半开 | `book` | 垂直链条,大约 `20` 改为 `160` |
| 像笔记本电脑一样半开 | `tabletop` | 水平链 |

![iPhone Duo simulator on the cover display, reporting flat posture and outer display](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/screenshots/ios-iphone-duo.webp)

在27.1起停留之前不复制iPhone和iOS `flat` 没有锁链。 Android 使用 Jetpack WindowManager;当浏览器曝光时,Web 使用设备 Posture API 和取景口片段(闪光角度保留) `null` ) (中文(简体) ).

**折叠 API** (全部类型如下): `isDeviceFoldable()`, (中文(简体) ), `getFoldState()`, (中文(简体) ), `getHingeAngle()`, (中文(简体) ), `getReservedRegions()`, (中文(简体) ), `getBarPlacement()`, (中文(简体) ), `setVerticalBarBehavior()`, (中文(简体) ), `getSizeClass()`,听众 `foldStateChange`, (中文(简体) ), `hingeAngleChange`, (中文(简体) ), `sizeClassChange`。 。 。 .

## 文档

这里有最完整的医生: [https://capgo.app/docs/plugins/屏幕定向/](https://capgo.app/docs/plugins/screen-orientation/)

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-screen-orientation` plugin in my project.
```

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capgo/capacitor-screen-orientation
npx cap sync
```

## iOS 配置

要在iOS上使用运动传感器探测物理设备取向,需要将运动用法描述添加到您的 `Info.plist`数字 :

```xml
<key>NSMotionUsageDescription</key>
<string>This app uses motion sensors to detect the true physical orientation of your device.</string>
```

锁定屏幕取向仅默认适用于Capacitor视图控制器. 要将锁应用到显示的视图控制器( 例如浏览器插件显示的), 请将此添加到您的应用程序中 `AppDelegate.swift`数字 :

```swift
func application(_ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask {
  return UIInterfaceOrientationMask(rawValue: (self.window!.rootViewController as! CAPBridgeViewController).supportedInterfaceOrientations.rawValue)
}
```

确保 `UISupportedInterfaceOrientations` 内 `Info.plist` 包含您要锁定的每个方向( 例如, 在锁定时左/ 右侧的地貌) `landscape`) (中文(简体) ).

## 使用量

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

// Get current orientation
const result = await ScreenOrientation.orientation();
console.log('Current orientation:', result.type);

// Lock to landscape
await ScreenOrientation.lock({ orientation: 'landscape' });

// Lock UI orientation and track physical orientation via motion sensors
// Note: UI will still respect user's orientation lock, but you'll get physical orientation events
await ScreenOrientation.lock({
  orientation: 'portrait',
  bypassOrientationLock: true
});

// Listen for orientation changes
const listener = await ScreenOrientation.addListener(
  'screenOrientationChange',
  (result) => {
    console.log('Orientation changed:', result.type);
  }
);

// Unlock orientation
await ScreenOrientation.unlock();

// Start motion-based tracking to detect physical device orientation
// This uses motion sensors to track how the device is actually held
await ScreenOrientation.startOrientationTracking({
  bypassOrientationLock: true
});

// Check if device orientation lock is enabled
// Compares physical device orientation (from sensors) with UI orientation (from system)
const lockStatus = await ScreenOrientation.isOrientationLocked();
if (lockStatus.locked) {
  console.log('Orientation lock is ON!');
  console.log('Physical device orientation:', lockStatus.physicalOrientation);
  console.log('UI orientation:', lockStatus.uiOrientation);
} else {
  console.log('Orientation lock is OFF or motion tracking not active');
}

// Stop motion-based tracking
await ScreenOrientation.stopOrientationTracking();

// Remove listener
await listener.remove();

// iPhone Duo and Android foldables. Flat on phones that do not fold.
const { posture, activeDisplay } = await ScreenOrientation.getFoldState();
const { angle, status } = await ScreenOrientation.getHingeAngle();
const { verticalBarEdge, inset } = await ScreenOrientation.getBarPlacement();
const { widthClass } = await ScreenOrientation.getSizeClass();
```

## API 密码

-   [`orientation()`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-orientation)
-   [`lock(...)`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-lock)
-   [`unlock()`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-unlock)
-   [`startOrientationTracking(...)`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-startorientationtracking)
-   [`stopOrientationTracking()`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-stoporientationtracking)
-   [`isOrientationLocked()`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-isorientationlocked)
-   [`isDeviceFoldable()`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-isdevicefoldable)
-   [`getFoldState()`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-getfoldstate)
-   [`getHingeAngle()`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-gethingeangle)
-   [`getReservedRegions()`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-getreservedregions)
-   [`getBarPlacement()`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-getbarplacement)
-   [`setVerticalBarBehavior(...)`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-setverticalbarbehavior)
-   [`getSizeClass()`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-getsizeclass)
-   [`addListener('screenOrientationChange', ...)`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-addlistenerscreenorientationchange-)
-   [`addListener('foldStateChange', ...)`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-addlistenerfoldstatechange-)
-   [`addListener('hingeAngleChange', ...)`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-addlistenerhingeanglechange-)
-   [`addListener('sizeClassChange', ...)`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-addlistenersizeclasschange-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-removealllisteners)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-getpluginversion)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-type-aliases)

电容屏幕方向插件接口 .

提供检测和控制屏幕取向的方法, 支持使用运动传感器探测真正的物理装置方向.

### 方向( )

```typescript
orientation() => Promise<ScreenOrientationResult>
```

获取当前屏幕方向 .

返回设备屏幕的当前取向.

**回返情况:** `Promise<[ScreenOrientationResult](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-screenorientationresult)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 锁定(...)

```typescript
lock(options: OrientationLockOptions) => Promise<void>
```

锁定屏幕方向为特定类型 .

锁定屏幕到指定方向. 在iOS上,如果绕行方向 锁是真的,它也会开始 利用运动传感器跟踪物理设备的方向.

注:UI仍然会尊重用户的方向锁设置. 运动跟踪允许您检测设备的物理状态 即使UI不旋转.

IOS 15 上没有公开的 API 强制旋转,所以锁限制 允许的方向, 设备时 UI 旋转到它们中 定向允许它。 在iOS 16上,然后立即要求旋转.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[OrientationLockOptions](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-orientationlockoptions)` | 锁定方向的选项 . |

**自:** 1.0.0 (单位:千美元)

* * *

### 解锁( )

```typescript
unlock() => Promise<void>
```

解开屏幕取向.

允许屏幕根据设备位置自由旋转. 如果启用,还停止任何基于运动的定向跟踪.

**自:** 1.0.0 (单位:千美元)

* * *

### 开始方向 跟踪(...)

```typescript
startOrientationTracking(options?: StartOrientationTrackingOptions | undefined) => Promise<void>
```

使用运动传感器开始跟踪设备方向.

如果您想要跟踪设备的物理性能, 这种方法是有用的 方向独立于屏幕方向锁. 它使用iOS上的Core Motion来检测取向变化.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `[StartOrientationTrackingOptions](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-startorientationtrackingoptions)` | 开始定向跟踪的选项. |

**自:** 1.0.0 (单位:千美元)

* * *

### 停止方向跟踪( )

```typescript
stopOrientationTracking() => Promise<void>
```

停止使用运动传感器跟踪设备方向.

启动后停止基于运动的定向跟踪.

**自:** 1.0.0 (单位:千美元)

* * *

### 已锁定

```typescript
isOrientationLocked() => Promise<OrientationLockStatusResult>
```

检查设备方向锁定是否已启用 .

这种方法比较物理设备取向(从运动传感器) 以UI为取向. 如果两者不同,则启用方向锁定.

说明: 这需要运动跟踪通过 启动方向跟踪( ) 或锁定( ) 绕行方向 Lock: true. 在iOS(Core Motion)和Android(加速计)上都工作.

**回返情况:** `Promise<[OrientationLockStatusResult](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-orientationlockstatusresult)>`

**自:** 1.0.0 (单位:千美元)

* * *

### 是DeviceFoldable () (中文(简体) )

```typescript
isDeviceFoldable() => Promise<DeviceFoldableResult>
```

这个设备是否折叠,是否可以像笔记本电脑一样站出半开.

在网络上,两面旗帜都是 `false` 当浏览器缺少折叠 API 或当前读取显示时 无折叠( e)`devicePosture.type` 实值 `continuous` 以单一的取景部分). `foldable` 变成 `true` 当姿态是 `folded` 或取景口分为两段. 网上, `supportsTabletop` 反映当前读取(例如, `false` 在书中 而非永久设备能力.

在Android,两面旗帜都是 `false` 不折叠的电话。 在iOS上,两者都是 `false` 除了iPhone Duo(iOS 27.1或后期).

**回返情况:** `Promise<[DeviceFoldableResult](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-devicefoldableresult)>`

**自:** 8.2.0 (中文(简体) )

* * *

### 获取Fold State ()

```typescript
getFoldState() => Promise<FoldState>
```

读取当前折叠.

当设备没有折叠时决定为平坦状态 。 在网络上, 使用 `navigator.devicePosture` 财务报告和审定财务报表 `window.viewport.segments` 当浏览器提供它们时.

**回返情况:** `Promise<[FoldState](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-foldstate)>`

**自:** 8.2.0 (中文(简体) )

* * *

### 获取 HingeAngle ()

```typescript
getHingeAngle() => Promise<HingeAngleResult>
```

以度读取轴角 .

`0` 关闭和 `180` 这是平地. `angle` 实值 `null` 没有锁链传感器.

**回返情况:** `Promise<[HingeAngleResult](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-hingeangleresult)>`

**自:** 8.2.0 (中文(简体) )

* * *

### 获取保留区 ()

```typescript
getReservedRegions() => Promise<{ regions: ReservedRegion[]; }>
```

读取折叠和任何覆盖屏幕的东西.

iPhone Duo报告折叠,垂直状态栏区域,以及下放相机. 决心在27.1前在Android,web,和iOS上列出一个空列表.

**回返情况:** `Promise<{ regions: ReservedRegion[]; }>`

**自:** 8.2.0 (中文(简体) )

* * *

### 获得巴平面 ()

```typescript
getBarPlacement() => Promise<BarPlacement>
```

读取 iPhone Duo 将本地标签栏和工具栏放在哪里 .

`verticalBarEdge` 实值 `null` 当栏保持水平, 总是在Android和网络上.

**回返情况:** `Promise<[BarPlacement](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-barplacement)>`

**自:** 8.2.0 (中文(简体) )

* * *

### 虚拟Bar Behavior(...)

```typescript
setVerticalBarBehavior(options: { behavior: 'automatic' | 'disabled'; }) => Promise<{ applied: boolean; }>
```

选择 iPhone Duo 是否可以将此应用程序的条移动到侧面 .

决定 `{ applied: false }` 除非应用程序的桥视图控制器选择使用. 机器人和网络总是决心 `{ applied: false }`。 。 。 .

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`options`** | `{ behavior: 'automatic' | 'disabled'; }` | `automatic` 让系统移动栏. `disabled` 保持他们的水平. |

**回返情况:** `Promise<{ applied: boolean; }>`

**自:** 8.2.0 (中文(简体) )

* * *

### 获取SizeClass ()

```typescript
getSizeClass() => Promise<SizeClass>
```

读取窗口大小课.

**回返情况:** `Promise<[SizeClass](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-sizeclass)>`

**自:** 8.2.0 (中文(简体) )

* * *

### 添加倾听器( “ 屏幕方向变化 ” ,...)

```typescript
addListener(eventName: 'screenOrientationChange', listenerFunc: (result: ScreenOrientationResult) => void) => Promise<PluginListenerHandle>
```

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'screenOrientationChange'` |
| **`listenerFunc`** | `(result: [ScreenOrientationResult](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-screenorientationresult)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-pluginlistenerhandle)>`

* * *

### 添加倾听器( “ 重复状态变化 ” ,...)

```typescript
addListener(eventName: 'foldStateChange', listenerFunc: (state: FoldState) => void) => Promise<PluginListenerHandle>
```

听取折叠变化.

在可折叠的上,设备旋转时也会起火,因为锁链 边框随窗口旋转.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'foldStateChange'` | 事件名称. 一定是"双重状态变化". |
| **`listenerFunc`** | `(state: [FoldState](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-foldstate)) => void` | 以新折叠状态引用回调 . |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-pluginlistenerhandle)>`

**自:** 8.2.0 (中文(简体) )

* * *

### 添加倾听器( “ singe AngleChange ” ,...)

```typescript
addListener(eventName: 'hingeAngleChange', listenerFunc: (event: HingeAngleResult) => void) => Promise<PluginListenerHandle>
```

听从链条角度的变化.

在Android上,链路传感器只在至少登记一个听众时运行. 在iOS上,iPhone Duo(iOS 27.1或后期)发生火灾. 在网络上, 锁定角度保留 `null`· ; 使用情况 `foldStateChange` 用于设备 Posture API 的态势更新.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'hingeAngleChange'` | 事件名称. 一定是"闪亮的安格尔". |
| **`listenerFunc`** | `(event: [HingeAngleResult](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-hingeangleresult)) => void` | 以度为角度引用回调 . |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-pluginlistenerhandle)>`

**自:** 8.2.0 (中文(简体) )

* * *

### 添加收听器( 大小为 ClassChange,...)

```typescript
addListener(eventName: 'sizeClassChange', listenerFunc: (sizeClass: SizeClass) => void) => Promise<PluginListenerHandle>
```

听大小类变化,如正在展开,旋转,或重新大小.

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| **`eventName`** | `'sizeClassChange'` | 事件名称. 一定是"大小变化". |
| **`listenerFunc`** | `(sizeClass: [SizeClass](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-sizeclass)) => void` | 与新大小类一起引用回调 . |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-pluginlistenerhandle)>`

**自:** 8.2.0 (中文(简体) )

* * *

### 删除所有收听器( )

```typescript
removeAllListeners() => Promise<void>
```

删除此插件的所有听众 .

删除所有已注册事件听众.

**自:** 1.0.0 (单位:千美元)

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<{ version: string; }>
```

获取本地插件版本 .

返回当前版本的本地插件执行 .

**回返情况:** `Promise<{ version: string; }>`

**自:** 1.0.0 (单位:千美元)

* * *

### 接口

#### 屏幕定向结果

通过方向()方法返回结果 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`type`** | `[OrientationType](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-orientationtype)` | 当前取向类型. | 1.0.0 (单位:千美元) |

#### 方向锁定选项

锁定屏幕方向的选项 .

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`orientation`** | `[OrientationLockType](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-orientationlocktype)` | 要锁定的方向类型 . |  | 1.0.0 (单位:千美元) |
| **`bypassOrientationLock`** | `boolean` | 是否使用运动传感器跟踪物理设备方向. 当属实时,使用设备运动传感器来检测设备的真实物理取向,即使设备取向锁被启用. **重要内容:** 这不会绕过 UI 方向锁 。 屏幕仍然会尊重用户的取向锁设置. 此选项只会影响方向检测/跟踪 - 您会根据设备的物理持有方式接收方向改变事件, 但如果启用方向锁定, UI 将不会旋转 。 在iOS(Core Motion)和Android(加速计)上得到支持. | `false` | 1.0.0 (单位:千美元) |

#### 开始方向 跟踪选项

使用运动传感器开始定向跟踪的选项.

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`bypassOrientationLock`** | `boolean` | 是否使用运动传感器跟踪物理设备方向. 当属实时,使用设备运动传感器来检测设备的真实物理取向,即使设备取向锁被启用. **重要内容:** 这不会绕过 UI 方向锁 。 这只能检测物理方向。 在iOS(Core Motion)和Android(加速计)上得到支持. | `false` | 1.0.0 (单位:千美元) |

#### 方向锁定状态

以正向锁定方法返回结果 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`locked`** | `boolean` | 目前设备方向锁定是否启用 。 这是通过比较物理设备取向(从运动传感器)和UI取向来确定的. 如果两者不同,则启用方向锁定. 运动跟踪活动时可在iOS(Core Motion)和Android(加速计)上找到. | 1.0.0 (单位:千美元) |
| **`physicalOrientation`** | `[OrientationType](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-orientationtype)` | 由运动传感器传出装置的物理方向. 运动跟踪活动时可用(iOS和Android). | 1.0.0 (单位:千美元) |
| **`uiOrientation`** | `[OrientationType](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-orientationtype)` | 目前该系统报告的UI方向. | 1.0.0 (单位:千美元) |

#### 设备可控结果

此设备能否折叠 .

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`foldable`** | `boolean` | 设备是否有折叠 . | 8.2.0 (中文(简体) ) |
| **`supportsTabletop`** | `boolean` | 能不能像笔记本电脑一样半开. | 8.2.0 (中文(简体) ) |

#### 折叠状态

窗口的当前折叠.

不折叠的电话,和 iOS 前27.1 解决到平地状态. iPhone Duo 报告 `book`, (中文(简体) ), `tabletop`,或 `flat`,在前面显示.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`state`** | `[FoldStateValue](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-foldstatevalue)` | 叠起的姿势. | 8.2.0 (中文(简体) ) |
| **`isSeparating`** | `boolean` | 折叠是否将网页视图分割为两个区域 . | 8.2.0 (中文(简体) ) |
| **`posture`** | `[FoldPosture](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-foldposture)` | 如何是装置所持. | 8.2.0 (中文(简体) ) |
| **`hingeOrientation`** | `[HingeOrientation](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-hingeorientation)` | 链条的方向。 没有折叠的时候就接受. | 8.2.0 (中文(简体) ) |
| **`hingeBounds`** | `[FoldBounds](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-foldbounds)` | CSS 像素中折叠的位置 。 没有折叠的时候就接受. | 8.2.0 (中文(简体) ) |
| **`occludedBounds`** | `[FoldBounds](https://npmcn.com/package/%40capgo/capacitor-screen-orientation/#readme-foldbounds)` | 覆盖链被子 当锁链有物理间隙时就在场. | 8.2.0 (中文(简体) ) |
| **`activeDisplay`** | `'inner' | 'outer'` | 在iPhone Duo上显示应用程序。 在27.1前进入了Android,web,以及iOS. | 8.2.0 (中文(简体) ) |
| **`hingeMargins`** | `{ top: number; right: number; bottom: number; left: number; }` | 系统在折叠处保持清晰的空间,以CSS像素表示. iPhone Duo报告垂直折叠的两侧各有20个. | 8.2.0 (中文(简体) ) |
| **`cameraBounds`** | `FoldBounds[]` | 覆盖显示的区域,如iPhone Duo相机. ⊿Τ碞穦祇瞷. | 8.2.0 (中文(简体) ) |

#### 砖块

CSS像素中的一个矩形,相对于网页视图.

| Prop | 类型 |
| --- | --- |
| **`x`** | `number` |
| **`y`** | `number` |
| **`width`** | `number` |
| **`height`** | `number` |

#### 兴安格勒

在可折叠的两半之间取角,以度为单位.

`0` 关闭和 `180` 这是平地. `angle` 实值 `null` 当设备没有锁链传感器时.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`angle`** | `number | null` | 平方角(以度计),或 `null` 当没有传感器时. | 8.2.0 (中文(简体) ) |
| **`status`** | `'closed' | 'partiallyOpen' | 'fullyOpen' | null` | 正如系统所见,iPhone Duo的开放有多远. `null` 在Android和网络. | 8.2.0 (中文(简体) ) |

#### 保留区域

这个系统保留在iPhone Duo上的区域.

`division` 是折叠. `occlusion` 是覆盖显示的东西,如相机.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`kind`** | `'division' | 'occlusion'` | 该地区是什么. | 8.2.0 (中文(简体) ) |
| **`isActive`** | `boolean` | 该地区现在是否适用。 非活动分区为平折. | 8.2.0 (中文(简体) ) |
| **`x`** | `number` | 左边缘,在CSS像素中. | 8.2.0 (中文(简体) ) |
| **`y`** | `number` | 顶端,在CSS像素中. | 8.2.0 (中文(简体) ) |
| **`width`** | `number` | CSS像素中的宽度. | 8.2.0 (中文(简体) ) |
| **`height`** | `number` | CSS像素中的高度. | 8.2.0 (中文(简体) ) |
| **`margins`** | `{ top: number; right: number; bottom: number; left: number; }` | 在区域周围保持清晰的空间,在 CSS 像素中. | 8.2.0 (中文(简体) ) |

#### 水泥

IPhone Duo将本地酒吧放入其中.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`verticalBarEdge`** | `'leading' | 'trailing' | null` | 系统移动标签栏和工具栏的边缘 . `null` 当他们保持水平. | 8.2.0 (中文(简体) ) |
| **`inset`** | `number` | 垂直条要多少空间,以分数计. `0` 当栏保持水平时. | 8.2.0 (中文(简体) ) |

#### 大小分类

窗口大小类.

`horizontal` 财务报告和审定财务报表 `vertical` 遵循 Apple 的紧凑/ 定期分拆 . 在Android和网上, `regular` 从600 CSS 像素宽到480高开始. `widthClass` 财务报告和审定财务报表 `heightClass` 遵循材料窗口大小分类.

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`horizontal`** | `'compact' | 'regular'` | 宽度级. `compact` 在电话中, `regular` 在可折叠、平板或窗口内显示至少600 CSS 像素宽度. | 8.2.0 (中文(简体) ) |
| **`vertical`** | `'compact' | 'regular'` | 身高大小课. `regular` 以 480 CSS 像素开始. | 8.2.0 (中文(简体) ) |
| **`widthClass`** | `'compact' | 'medium' | 'expanded' | 'large' | 'extraLarge'` | 材料窗口宽度类. | 8.2.0 (中文(简体) ) |
| **`heightClass`** | `'compact' | 'medium' | 'expanded'` | 材料窗高阶课. | 8.2.0 (中文(简体) ) |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

### 类型异名

#### 方向类型

描述设备方向状态的方向类型 .

`'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary'`

#### 方向锁定Type

方向锁类型,可用于锁定设备方向.

`'any' | 'natural' | 'landscape' | 'portrait' | 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary'`

#### 折叠状态

如何是开可折.

`closed` 预留。 一个设备关闭在其封面显示报告上 `flat`。 。 。 .

`'flat' | 'half-opened'`

#### 折叠

如何是半开可折叠相持.

`tabletop` 就像笔记本电脑一样. `book` 是一个垂直的链条.

`'flat' | 'tabletop' | 'book'`

#### 兴化方向

轴相对于窗口的方向 .

`'horizontal' | 'vertical'`

改造自 [erkamyaman/可复制](https://github.com/erkamyaman/capacitor-foldable) (MIT,版权 (c) Erkam Yaman).

## 常见问题

### @capgo/capacitor-screen-orientation 是什么？

支持绕行方向锁定的屏幕方向插件

### 如何安装 @capgo/capacitor-screen-orientation？

在项目目录运行 npm install @capgo/capacitor-screen-orientation，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capgo/capacitor-screen-orientation 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capgo/capacitor-screen-orientation 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capgo/capacitor-screen-orientation 可以商用吗？

@capgo/capacitor-screen-orientation 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-screen-orientation 的下载量有多少？

根据 npm 官方下载统计，@capgo/capacitor-screen-orientation 在 2026/10/09 – 2026/11/07 这 30 天内被下载 43,411 次，日均约 1,447 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capgo/capacitor-screen-orientation 还在维护吗？

最新版本 8\.4\.3 发布于 2026/10/15（25 天前）；至今共发布 29 个版本，其中过去 12 个月发布了 29 个；首次发布于 2025/11/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。