更新记录

1.0.0（2026-04-21）

新增功能

• 基于 UTS 原生混编方式实现
• iOS Swift 原生实现（iOS 13.0+）
• Android Kotlin 原生实现（API 21+）

屏幕方向控制

• 支持四种方向：竖屏、竖屏倒置、横屏左、横屏右
• 支持自动旋转模式
• setOrientation - 设置屏幕方向
• getOrientation - 获取当前屏幕方向

状态栏控制

• setStatusBarVisible - 控制状态栏显示/隐藏（支持动画）
• setStatusBarStyle - 设置状态栏样式（深色/浅色/默认）
• getStatusBarInfo - 获取状态栏信息（可见性、样式、高度）

HomeIndicator 控制（仅 iOS）

• setHomeIndicatorVisible - 控制底部横条的显示/隐藏

屏幕旋转监听

• addOrientationChangeListener - 添加屏幕旋转监听器
• removeOrientationChangeListener - 移除屏幕旋转监听器

系统要求

• iOS 13.0+
• Android 5.0+ (API 21+)
• HBuilderX 3.6.8+
• uni-app 3.1.0+

技术实现

• iOS: Swift + UIKit
• Android: Kotlin + AndroidX
• UTS 原生混编

错误处理

• 9040001: 功能不支持
• 9040002: 参数错误
• 9040003: 操作失败
• 9040004: 权限不足

平台兼容性

uni-app(4.84)

mm-screen-toggle

基于 UTS 原生混编实现的屏幕控制插件，支持横竖屏切换、状态栏控制、HomeIndicator 控制。

功能特性

• ✅ 屏幕方向控制（横屏/竖屏/自动旋转，四种方向）
• ✅ 状态栏显示/隐藏
• ✅ 状态栏样式切换（深色/浅色/默认）
• ✅ 获取状态栏信息（可见性、样式、高度）
• ✅ HomeIndicator 显示/隐藏（仅 iOS）
• ✅ 屏幕旋转监听（支持添加/移除监听）

系统要求

• iOS: 13.0+
• Android: API 21+ (Android 5.0+)
• HBuilderX: 3.6.8+
• uni-app: 3.1.0+

导入插件

import {
  setOrientation,
  getOrientation,
  setStatusBarVisible,
  setStatusBarStyle,
  getStatusBarInfo,
  setHomeIndicatorVisible,
  addOrientationChangeListener,
  removeOrientationChangeListener
} from '@/uni_modules/mm-screen-toggle';

API 文档

1. setOrientation(options) - 设置屏幕方向

设置应用的屏幕方向。

参数：

ScreenOrientation 类型：

示例：

setOrientation({
  orientation: 'landscapeLeft',
  success: () => {
    console.log('设置屏幕方向成功');
  },
  fail: (err) => {
    console.error('设置失败:', err.errMsg);
  }
});

2. getOrientation(options) - 获取当前屏幕方向

获取应用当前的屏幕方向。

参数：

GetOrientationResult 结构：

示例：

getOrientation({
  success: (res) => {
    console.log('当前方向:', res.orientation);
  }
});

3. setStatusBarVisible(options) - 设置状态栏可见性

控制状态栏的显示和隐藏。

参数：

示例：

// 隐藏状态栏（带动画）
setStatusBarVisible({
  visible: false,
  animated: true,
  success: () => {
    console.log('状态栏已隐藏');
  }
});

// 显示状态栏
setStatusBarVisible({
  visible: true,
  animated: true
});

4. setStatusBarStyle(options) - 设置状态栏样式

设置状态栏的图标样式。

参数：

StatusBarStyle 类型：

示例：

// 设置为深色图标（白色背景使用）
setStatusBarStyle({
  style: 'dark',
  success: () => {
    console.log('状态栏样式已设置');
  }
});

// 设置为浅色图标（深色背景使用）
setStatusBarStyle({
  style: 'light'
});

5. getStatusBarInfo(options) - 获取状态栏信息

获取状态栏的当前状态信息。

参数：

GetStatusBarInfoResult 结构：

示例：

getStatusBarInfo({
  success: (res) => {
    console.log('状态栏可见:', res.visible);
    console.log('状态栏样式:', res.style);
    console.log('状态栏高度:', res.height);
  }
});

6. setHomeIndicatorVisible(options) - 设置 HomeIndicator 可见性（仅 iOS）

控制 iOS 底部 Home Indicator 的显示和隐藏。

参数：

注意： 此功能仅支持 iOS，Android 调用会返回错误码 9040001（功能不支持）。

示例：

setHomeIndicatorVisible({
  visible: false,
  success: () => {
    console.log('HomeIndicator 已隐藏');
  }
});

7. addOrientationChangeListener(options) - 添加屏幕旋转监听

监听设备屏幕方向的变化。

参数：

OrientationChangeResult 结构：

示例：

addOrientationChangeListener({
  callback: (res) => {
    console.log('屏幕方向已变为:', res.orientation);

    // 根据方向调整UI
    if (res.orientation === 'landscapeLeft' || res.orientation === 'landscapeRight') {
      console.log('横屏模式');
    } else {
      console.log('竖屏模式');
    }
  },
  success: () => {
    console.log('监听器已添加');
  }
});

8. removeOrientationChangeListener(options) - 移除屏幕旋转监听

移除之前添加的屏幕旋转监听器。

参数：

示例：

removeOrientationChangeListener({
  success: () => {
    console.log('监听器已移除');
  }
});

错误码

完整使用示例

import {
  setOrientation,
  getOrientation,
  setStatusBarVisible,
  setStatusBarStyle,
  getStatusBarInfo,
  setHomeIndicatorVisible,
  addOrientationChangeListener,
  removeOrientationChangeListener
} from '@/uni_modules/mm-screen-toggle';

export default {
  data() {
    return {
      currentOrientation: 'portrait',
      statusBarHeight: 0
    };
  },

  onLoad() {
    // 获取初始状态栏信息
    this.getStatusBarInfo();

    // 添加屏幕旋转监听
    this.addRotationListener();
  },

  onUnload() {
    // 页面卸载时移除监听
    removeOrientationChangeListener({
      success: () => {
        console.log('监听器已移除');
      }
    });
  },

  methods: {
    // 设置为横屏
    setLandscape() {
      setOrientation({
        orientation: 'landscapeLeft',
        success: () => {
          uni.showToast({ title: '已切换为横屏', icon: 'success' });
        }
      });
    },

    // 设置为竖屏
    setPortrait() {
      setOrientation({
        orientation: 'portrait',
        success: () => {
          uni.showToast({ title: '已切换为竖屏', icon: 'success' });
        }
      });
    },

    // 获取状态栏信息
    getStatusBarInfo() {
      getStatusBarInfo({
        success: (res) => {
          this.statusBarHeight = res.height;
          console.log('状态栏高度:', res.height);
        }
      });
    },

    // 隐藏状态栏
    hideStatusBar() {
      setStatusBarVisible({
        visible: false,
        animated: true,
        success: () => {
          console.log('状态栏已隐藏');
        }
      });
    },

    // 显示状态栏
    showStatusBar() {
      setStatusBarVisible({
        visible: true,
        animated: true
      });
    },

    // 设置深色状态栏
    setDarkStatusBar() {
      setStatusBarStyle({
        style: 'dark',
        success: () => {
          console.log('状态栏样式已设置为深色');
        }
      });
    },

    // 设置浅色状态栏
    setLightStatusBar() {
      setStatusBarStyle({
        style: 'light',
        success: () => {
          console.log('状态栏样式已设置为浅色');
        }
      });
    },

    // 隐藏 Home Indicator（仅 iOS）
    hideHomeIndicator() {
      setHomeIndicatorVisible({
        visible: false,
        success: () => {
          console.log('HomeIndicator 已隐藏');
        },
        fail: (err) => {
          if (err.errCode === 9040001) {
            uni.showToast({ title: '当前设备不支持此功能', icon: 'none' });
          }
        }
      });
    },

    // 添加旋转监听
    addRotationListener() {
      addOrientationChangeListener({
        callback: (res) => {
          this.currentOrientation = res.orientation;
          console.log('屏幕方向变化:', res.orientation);

          // 可以根据方向变化调整UI布局
          this.adjustUIForOrientation(res.orientation);
        },
        success: () => {
          console.log('旋转监听已添加');
        }
      });
    },

    // 根据方向调整UI
    adjustUIForOrientation(orientation) {
      const isLandscape = orientation === 'landscapeLeft' || orientation === 'landscapeRight';

      // 根据横竖屏调整布局
      if (isLandscape) {
        console.log('横屏布局');
      } else {
        console.log('竖屏布局');
      }
    }
  }
};

注意事项

1. iOS 配置

   • 在 iOS 项目中，确保 Info.plist 中配置了支持的屏幕方向
   • HomeIndicator 控制需要 iOS 11.0+

2. Android 配置

   • 在 AndroidManifest.xml 中配置 android:screenOrientation 属性
   • 部分功能需要在 Activity 中设置 FLAG_LAYOUT_NO_LIMITS

3. 生命周期管理

   • 使用 addOrientationChangeListener 添加监听后，在页面卸载时务必调用 removeOrientationChangeListener 移除监听
   • 建议在 onLoad 中添加监听，在 onUnload 中移除监听

4. 状态栏样式

   • dark 表示深色图标，适用于浅色背景
   • light 表示浅色图标，适用于深色背景
   • 设置样式后，状态栏背景颜色需要通过 CSS 单独设置

5. 测试

   • 建议在真机上测试屏幕旋转功能
   • 模拟器可能无法完全模拟所有旋转场景

开发文档

• UTS 语法
• UTS API 插件
• UTS 原生混编

许可证

MIT