更新记录

1.0.1（2026-10-18）

• 修复鸿蒙端加密插件编译报错。

1.0.0（2026-10-18）

• 支持鸿蒙、安卓、IOS端设置窗口的方向（竖屏、横屏、自动旋转）。

平台兼容性

uni-app x(4.86)

其他

umi-app-orientation

广告：

• 魔法上网35元/月，有需求的可以联系我(稳定，支持 Clash Verge)。
• 售卖CodeX账号，plus代充180元/月，有需求的可以联系我。
• 售卖Claude Code账号以及代充，有需求的可以联系我。
• vx: 781284440

全局横竖屏 UTS API 插件。配套工程提供 uni-app x（.uvue / Vapor）双页面示例。业务层设置一次，后续普通页面沿用策略；可保存并在下次启动恢复。目录名按需求使用 umi-app-orientation。

接入

1. 将 uni_modules/umi-app-orientation 复制到已有项目的 uni_modules 下。
2. 使用支持三端 UTS 的 HBuilderX，建议当前稳定版；本项目要求 HBuilderX 4.86+。Android 最低 API 21；iOS 最低 16；鸿蒙为原生 HarmonyOS，非安卓兼容环境。
3. 当前示例的 App.uvue 不调用方向插件，启动时使用宿主默认方向，进入首页后手动切换方向。若业务需要启动时恢复保存的策略，可自行在 App 的 onShow 中接入一次 initAppOrientation，并增加防重复和窗口未就绪时的重试处理；不要在每次页面 onShow 重置方向。
4. 在设置页调用 setAppOrientation。不要再在各页面配置冲突方向，也不要在页面卸载时恢复竖屏。
5. 作为示例工程运行时：HBuilderX 导入本目录，保留本工程已有 AppID 与 manifest 构建配置，按实际发布账号配置平台包名、签名和鸿蒙工程环境，再运行到相应真机。示例不是已签名安装包。

import {
  initAppOrientation,
  setAppOrientation,
  getAppOrientation
} from '@/uni_modules/umi-app-orientation'

// 可选：需要启动恢复时，在宿主 App.onShow 中接入一次。
// 当前示例 App.uvue 未接入；实际使用需增加防重复和失败重试保护。
initAppOrientation({
  defaultMode: 'portrait',
  fail: error => console.error(error)
})

// 用户设置，任意业务页调用一次。
setAppOrientation({
  mode: 'landscape',
  persist: false, // 默认值；需要保存到下次启动时传 true
  success: result => console.log(result.mode),
  fail: error => console.error(error.errCode, error.errMsg)
})

// 返回策略，未成功设置前为 ''；不是设备实时方向。
console.log(getAppOrientation())

mode：portrait 固定正向竖屏；landscape 横屏（Android/鸿蒙固定系统横屏方向，iOS 允许左右横屏）；auto 允许随传感器旋转。auto 为插件设定的自动模式，不是撤销插件、恢复宿主全部原有页面策略。三端的传感器和系统旋转锁行为可能不同。

persist 默认 false。仅显式传入 true 时保存方向；省略或传入 false 时仅保留当前进程策略，并删除之前的保存值，避免下次启动意外恢复旧设置。保存值不会自动应用，当前示例重启后不会恢复保存的方向。需要恢复时，新进程须显式调用 initAppOrientation；初始化优先读取保存值，否则使用 defaultMode（默认 portrait）。启动画面出现到初始化完成前的方向由打包配置决定，动态设置无法消除这一阶段的方向变化。

success 表示设置成功：Android 接口接受请求；鸿蒙原生 Promise 成功；iOS 场景方向进入允许的方向范围。Android/鸿蒙返回成功不代表页面布局动画已结束，也不能保证系统没有覆盖请求；以页面 /实际窗口尺寸验收。

Android / 鸿蒙跨页面方向适配

Android Vapor 插件的 utssdk/app-android/AndroidManifest.xml 为普通页面容器 io.dcloud.uniappxv.activity.UniPageActivity 设置 android:screenOrientation="behind"，使系统启动新 Activity 时继承前页方向，后续由插件应用全局策略。仅靠 Activity 生命周期恢复方向，可能赶不上系统的启动方向过渡。

新增 Manifest 必须重新制作并安装自定义调试基座，或完整打包安装；标准基座和 JS 热更新不会应用此配置。 验收前检查实际 APK 中该 Activity 的 screenOrientation 为 behind（aapt 输出 0x3），再复测横屏进入第二页和返回。目前新增 Manifest 方案尚待完整打包后的真机验收。

Android Vapor 在 onActivityPreCreated 按 Intent 中的 app/page ID 同步目标原生 UniPage 的 pageOrientation，随后由 Activity 生命周期回调恢复全局方向。原生适配通过反射调用本机 HBuilderX 5.26 运行库的具名 API，版本升级需复验。

Android / 鸿蒙还共用插件目录内的 uni_modules/umi-app-orientation/page-orientation.js，在五类导航执行前同步全局配置、所有路由和已有页面的方向。鸿蒙原生窗口监听保留为兜底。适配依赖 Vapor 内部的 __uniConfig / __uniRoutes，升级 HBuilderX 后需重新验证；跨页面是否闪转需分别进行真机验证。

复制整个插件目录后，在宿主 main.uts 中安装一次：

// #ifdef APP-ANDROID || APP-HARMONY
import { getAppOrientation } from '@/uni_modules/umi-app-orientation'
import { installAppPageOrientation } from '@/uni_modules/umi-app-orientation/page-orientation.js'
installAppPageOrientation((): string => getAppOrientation())
// #endif

打包方向配置

普通 uni-app Android/iOS 在 manifest.json 的 app-plus.screenOrientation 中允许 portrait-primary、landscape-primary、landscape-secondary，普通 uni-app 项目请自行配置；当前 x 工程保留原 manifest，不添加 app-plus 节点。不能只声明竖屏再期待运行时横屏。

iOS 插件自带 info.plist 声明支持竖屏和两个横屏。示例根目录 Info.plist 同时声明 iPhone/iPad 方向，并以 UIRequiresFullScreen=true 选择全屏演示。已有项目自行决定是否关闭 iPad 多任务；多窗口/Stage Manager 环境不能保证强制旋转。不要把示例的全屏限制盲目带入已有产品。

鸿蒙默认启动方向由 EntryAbility 的 module.json5 -> module.abilities 对应条目的 orientation 决定，例如 "orientation": "portrait"。通过项目的鸿蒙原生配置合并机制维护，勿长期修改 unpackage 中会被覆盖的生成文件；运行后由插件设置窗口方向。默认支持的鸿蒙打包流程依赖 HBuilderX/DevEco 配置，本示例不包含证书或完整原生鸿蒙工程。

本目录为实际 uni-app x .uvue 工程，保留原有 Vapor 配置、AppID 和双击返回退出处理。普通 uni-app 项目可以复制 uni_modules 插件并在自己的 App.vue 中初始化；不能直接使用本示例的 App.uvue。两类宿主都需要分别进行实际联编验收。

实现和覆盖范围

适用于当前 APP 普通页面、返回栈和常规容器。系统选图/相机、外部 SDK、原生独立模态页面、视频临时全屏和多场景不是“全部强制覆盖”的承诺范围；这些界面退出后应验收全局策略是否仍有效。若其他代码再次改变方向，需移除冲突或在其退出回调显式重设。

iOS 失败会恢复内存中的上次策略及容器方向支持，但不保证系统旋转动画回滚。鸿蒙/Android 生命周期恢复失败写入原生日志；无长期 JS 回调订阅，不存在保存一次性回调反复通知的问题。

错误码