一、插件介绍

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),
                    ),
                  ),
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
}

四、注意事项

1. 兼容性：该插件在以下环境中已测试通过：

   • 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

2. 权限问题：如果在安装 HAP 包时遇到错误代码 9568289，可能是因为应用权限等级问题。默认的应用权限是 normal，而某些系统功能可能需要 system_basic 等级权限，请参考 官方文档 修改应用权限等级。

3. API 差异：虽然大部分 API 在各平台上的用法一致，但部分 API 的行为可能会因平台而异，请参考 API 文档了解具体差异。

五、总结

auto_orientation 插件为 Flutter 应用提供了强大的屏幕方向控制能力，通过简单的 API 调用即可实现各种屏幕方向的切换和控制。本版本针对 HarmonyOS 系统进行了适配，确保在鸿蒙设备上能够正常工作。

使用该插件，开发者可以轻松实现：

• 手动控制屏幕方向（横向左、横向右、纵向向上、纵向向下）
• 自动旋转模式（纵向自动、横向自动、完全自动）
• 根据传感器数据自动旋转
• 锁定屏幕旋转

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net