Flutter auto_orientation 插件在鸿蒙系统上的使用指南

auto_orientation 是一个 Flutter 插件，用于控制应用屏幕方向，支持 iOS、Android 和 HarmonyOS 平台。该插件提供了丰富的 API 来手动或自动控制屏幕旋转，适用于视频、游戏等场景。安装需通过 Git 引入依赖，并在 HarmonyOS 中配置网络权限。核心 API 包括 landscapeLeftMode()、portraitUpMode() 等方法，支

b13053810049

798人浏览 · 2025-12-21 21:54:36

b13053810049 · 2025-12-21 21:54:36 发布

一、插件介绍

auto_orientation 是一个用于控制 Flutter 应用屏幕方向的插件，支持 iOS、Android 和 HarmonyOS 平台。它提供了丰富的 API 来实现屏幕方向的手动控制和自动旋转功能，适用于视频播放、游戏、阅读等需要灵活控制屏幕方向的应用场景。

本版本基于 auto_orientation@2.3.1 开发，并针对 HarmonyOS 系统进行了适配，确保在鸿蒙设备上能够正常工作。

二、安装与集成

2.1 依赖配置

由于这是一个自定义修改版本，需要通过 Git 形式引入。在项目的 pubspec.yaml 文件中添加以下依赖配置：

dependencies:
  auto_orientation:
    git:
      url: "https://atomgit.com/openharmony-sig/fluttertpc_auto_orientation.git"

2.2 安装依赖

执行以下命令安装依赖：

flutter pub get

2.3 权限配置

在 HarmonyOS 平台上，使用该插件需要在 entry/src/main/module.json5 文件中添加网络权限（用于插件的正常工作）：

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET",
    "reason": "$string:network_reason",
    "usedScene": {
      "abilities": [
        "EntryAbility"
      ],
      "when":"inuse"
    }
  },
]

同时，在 entry/src/main/resources/base/element/string.json 文件中添加权限申请原因：

{
  "string": [
    {
      "name": "network_reason",
      "value": "使用网络"
    },
  ]
}

三、API 用法

3.1 导入包

在需要使用的 Dart 文件中导入包：

import 'package:auto_orientation/auto_orientation.dart';

3.2 核心 API

方法名	返回值	描述	HarmonyOS 支持
`landscapeLeftMode()`	Future	将设备旋转到向左横向模式	✅
`landscapeRightMode()`	Future	将设备旋转到向右横向模式	✅
`portraitUpMode()`	Future	将设备旋转到纵向向上模式	✅
`portraitDownMode()`	Future	将设备旋转到纵向向下模式	✅
`portraitAutoMode({bool forceSensor = false})`	Future	将设备旋转到纵向自动模式	✅
`landscapeAutoMode({bool forceSensor = false})`	Future	将设备旋转到横向自动模式	✅
`fullAutoMode()`	Future	锁定屏幕旋转后，不随传感器旋转	✅
`setScreenOrientationUser()`	Future	采用用户设置和设备传感器	✅

3.3 使用示例

以下是一个简单的示例，展示如何使用 auto_orientation 插件控制屏幕方向：

import 'package:auto_orientation/auto_orientation.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(
    AutoOrientationDemo(),
  );
}

class AutoOrientationDemo extends StatefulWidget {
  AutoOrientationDemo({this.title = 'Auto Orientation Demo'});

  final String title;

  @override
  State<StatefulWidget> createState() {
    return _AutoOrientationDemoState();
  }
}

class _AutoOrientationDemoState extends State<AutoOrientationDemo> {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: widget.title,
      theme: ThemeData.light(),
      home: Scaffold(
        appBar: AppBar(
          title: Text(widget.title),
        ),
        body: Column(
          children: <Widget>[
            Row(
              children: <Widget>[
                Expanded(
                  child: TextButton(
                    onPressed: () {
                      AutoOrientation.landscapeLeftMode();
                    },
                    child: Padding(
                      child: Text("向左横向模式"),
                      padding: EdgeInsets.symmetric(vertical: 16.0),
                    ),
                  ),
                ),
                Expanded(
                  child: TextButton(
                    onPressed: () {
                      AutoOrientation.landscapeRightMode();
                    },
                    child: Padding(
                      child: Text("向右横向模式"),
                      padding: EdgeInsets.symmetric(vertical: 16.0),
                    ),
                  ),
                ),
              ],
            ),
            Row(
              children: <Widget>[
                Expanded(
                  child: TextButton(
                    onPressed: () {
                      AutoOrientation.portraitUpMode();
                    },
                    child: Padding(
                      child: Text("纵向向上模式"),
                      padding: EdgeInsets.symmetric(vertical: 16.0),
                    ),
                  ),
                ),
                Expanded(
                  child: TextButton(
                    onPressed: () {
                      AutoOrientation.portraitDownMode();
                    },
                    child: Padding(
                      child: Text("纵向向下模式"),
                      padding: EdgeInsets.symmetric(vertical: 16.0),
                    ),
                  ),
                ),
              ],
            ),
            Row(
              children: <Widget>[
                Expanded(
                  child: TextButton(
                    onPressed: () {
                      AutoOrientation.fullAutoMode();
                    },
                    child: Padding(
                      child: Text("自动旋转模式"),
                      padding: EdgeInsets.symmetric(vertical: 16.0),
                    ),
                  ),
                ),
                Expanded(
                  child: TextButton(
                    onPressed: () {
                      AutoOrientation.setScreenOrientationUser();
                    },
                    child: Padding(
                      child: Text("用户设置模式"),
                      padding: EdgeInsets.symmetric(vertical: 16.0),
                    ),
                  ),
                ),
              ],
            ),
            Row(
              children: <Widget>[
                Expanded(
                  child: TextButton(
                    onPressed: () {
                      AutoOrientation.landscapeAutoMode();
                    },
                    child: Padding(
                      child: Text("横向自动模式"),
                      padding: EdgeInsets.symmetric(vertical: 16.0),
                    ),
                  ),
                ),
                Expanded(
                  child: TextButton(
                    onPressed: () {
                      AutoOrientation.portraitAutoMode();
                    },
                    child: Padding(
                      child: Text("纵向自动模式"),
                      padding: EdgeInsets.symmetric(vertical: 16.0),
                    ),
                  ),
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
}

四、注意事项

兼容性：该插件在以下环境中已测试通过：
- Flutter: 3.7.12-ohos-1.0.6
- SDK: 5.0.0(12)
- IDE: DevEco Studio: 5.0.13.200
- ROM: 5.1.0.120 SP3
权限问题：如果在安装 HAP 包时遇到错误代码 9568289，可能是因为应用权限等级问题。默认的应用权限是 normal，而某些系统功能可能需要 system_basic 等级权限，请参考官方文档修改应用权限等级。
API 差异：虽然大部分 API 在各平台上的用法一致，但部分 API 的行为可能会因平台而异，请参考 API 文档了解具体差异。