更新记录

1.0（2026-07-22）

ios支持监听横竖屏

平台兼容性

uni-app x(4.87)

ansyio-orientation-change 设备方向监听插件

通过 UTS 插件监听 iOS 设备方向变化，封装 UIDevice.orientationDidChangeNotification 通知，使 uvue 页面能够在不直接调用原生 API 的情况下感知横竖屏切换。

平台支持

仅支持 uni-app x 项目，HBuilderX 3.6.8+，uni-app-x 3.1.0+。

目录结构

ansyio-orientation-change/
├── package.json
└── utssdk/
    ├── interface.uts          // 接口与类型声明
    └── app-ios/
        └── index.uts          // iOS 平台原生实现

API

类型定义

DeviceOrientation

设备方向字符串类型，取值如下：

OrientationChangeCallback

type OrientationChangeCallback = (orientation: DeviceOrientation) => void

方向变化回调函数类型。

方法

startListening(callback)

开始监听设备方向变化。

• 调用后会立即触发一次当前方向的回调，便于前端获取初始方向
• 之后每次方向变化都会触发回调
• 若已处于监听状态，会先停止旧监听再重新注册，避免重复注册
• 回调会在主线程执行，可安全更新 UI

参数

返回值

boolean —— 是否成功开始监听。

stopListening()

停止监听设备方向变化，移除通知观察者并释放资源，避免内存泄漏。

返回值

boolean —— 是否成功停止监听（未在监听时返回 false）。

getCurrentOrientation()

获取当前设备方向（不依赖监听状态）。

建议先调用 startListening 以确保方向信息已更新。

返回值

DeviceOrientation —— 当前设备方向。

isListening()

判断当前是否正在监听。

返回值

boolean —— 是否正在监听。

使用示例

基础用法

<template>
  <view>
    <text>当前方向：{{ orientation }}</text>
    <text>监听状态：{{ listening ? '监听中' : '已停止' }}</text>
    <button @click="toggle">{{ listening ? '停止' : '开始' }}</button>
  </view>
</template>

<script setup>
// #ifdef APP-IOS
import {
  startListening,
  stopListening,
  isListening,
  type DeviceOrientation
} from "@/uni_modules/ansyio-orientation-change"
// #endif

const orientation = ref<DeviceOrientation>("unknown")
const listening = ref(false)

const onOrientationChange = (o: DeviceOrientation) => {
  orientation.value = o
  listening.value = isListening()
}

const toggle = () => {
  // #ifdef APP-IOS
  if (listening.value) {
    stopListening()
    listening.value = false
  } else {
    startListening(onOrientationChange)
    listening.value = true
  }
  // #endif
}

onUnmounted(() => {
  // #ifdef APP-IOS
  stopListening()
  // #endif
})
</script>

在页面生命周期中使用

import { startListening, stopListening } from "@/uni_modules/ansyio-orientation-change"

// 进入页面开始监听
onMounted(() => {
  // #ifdef APP-IOS
  startListening((orientation) => {
    // 根据方向处理业务逻辑
    if (orientation === "portrait" || orientation === "portraitUpsideDown") {
      // 竖屏逻辑
    } else if (orientation === "landscapeLeft" || orientation === "landscapeRight") {
      // 横屏逻辑
    }
    // faceUp / faceDown / unknown 通常不改变业务状态
  })
  // #endif
})

// 离开页面停止监听，避免内存泄漏
onBeforeUnmount(() => {
  // #ifdef APP-IOS
  stopListening()
  // #endif
})

注意事项

1. 平台限制：本插件仅支持 iOS 平台，调用代码需用 // #ifdef APP-IOS 条件编译包裹，避免在其他平台编译报错。
2. 必须停止监听：页面卸载时务必调用 stopListening()，否则会持续占用通知中心和设备方向通知生成器，造成内存泄漏和电量消耗。
3. 回调线程：回调通过 DispatchQueue.main.async 派发到主线程执行，可直接操作 UI；切勿在回调中执行耗时同步任务。
4. 初始回调：startListening 调用后会立即触发一次回调以同步当前方向，前端需提前完成状态初始化。
5. faceUp / faceDown / unknown：这三种方向不区分横竖，业务侧通常应忽略，仅处理明确的横屏或竖屏方向。
6. getCurrentOrientation 依赖监听：该方法本身不依赖监听状态，但在未调用 startListening 的情况下返回值可能为 unknown（系统尚未更新方向信息）。
7. 与 pageOrientation 配合：若页面 pages.json 中 pageOrientation 设为 auto，系统会随设备方向自动旋转界面；本插件可在此基础上为业务提供更细粒度的方向感知。