1. 插件介绍

fluttertpc_auto_orientation 是基于 auto_orientation@2.3.1 开发的一款鸿蒙平台适配的屏幕方向控制插件，它允许 Flutter 应用程序灵活控制设备的屏幕方向，支持固定方向和自动旋转等模式。

该插件为开发者提供了简单易用的 API，能够快速实现屏幕方向的切换和锁定，适用于视频播放器、游戏、阅读应用等需要特定屏幕方向的场景，提升用户体验。

2. 安装与配置

2.1 添加依赖

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

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

然后执行以下命令获取依赖：

flutter pub get

2.2 权限配置

该插件需要在 module.json5 中添加网络权限申请（尽管该插件主要功能是控制屏幕方向，但依赖配置中可能需要网络权限）：

1. 打开 entry/src/main/module.json5 文件，添加权限配置：

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

2. 打开 entry/src/main/resources/base/element/string.json 文件，添加权限说明：

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

2.3 注意事项

• 应用权限等级：由于该插件可能使用了 system_basic 级别的权限，而默认应用权限是 normal，如果安装 HAP 包时出现 9568289 错误，请参考 官方文档 将应用等级修改为 system_basic。

• 兼容性要求：已在以下版本测试通过：

  • Flutter: 3.7.12-ohos-1.0.6
  • HarmonyOS SDK: 5.0.0(12)
  • DevEco Studio: 5.0.13.200
  • HarmonyOS ROM: 5.1.0.120 SP3

3. API 使用指南

3.1 导入包

在需要使用屏幕方向控制功能的文件中导入包：

import 'package:auto_orientation/auto_orientation.dart';

3.2 支持的 API

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

3.3 API 使用示例

以下是各 API 的基本使用方法：

3.3.1 固定方向模式

// 固定为向左横向模式
AutoOrientation.landscapeLeftMode();

// 固定为向右横向模式
AutoOrientation.landscapeRightMode();

// 固定为纵向向上模式
AutoOrientation.portraitUpMode();

// 固定为纵向向下模式
AutoOrientation.portraitDownMode();

3.3.2 自动方向模式

// 允许纵向自动旋转
AutoOrientation.portraitAutoMode();

// 允许横向自动旋转
AutoOrientation.landscapeAutoMode();

// 允许所有方向自动旋转
AutoOrientation.fullAutoMode();

3.3.3 用户设置模式

// 采用用户设置的屏幕方向模式
AutoOrientation.setScreenOrientationUser();

4. 完整示例

以下是一个完整的示例代码，展示如何在 Flutter 应用中使用该插件控制屏幕方向：

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

5. 实际应用场景

该插件适用于多种需要控制屏幕方向的场景，例如：

5.1 视频播放器

在播放视频时，通常需要支持横向全屏模式，而在浏览视频列表时则使用纵向模式：

// 进入视频播放界面，设置为横向自动模式
AutoOrientation.landscapeAutoMode();

// 退出视频播放界面，恢复为纵向模式
AutoOrientation.portraitUpMode();

5.2 游戏应用

游戏通常需要固定的屏幕方向，例如横屏游戏：

// 在游戏启动时设置为横向模式
AutoOrientation.landscapeLeftMode();

// 在游戏退出时恢复为系统默认模式
AutoOrientation.setScreenOrientationUser();

5.3 阅读应用

阅读应用通常使用纵向模式，但在阅读图片或特殊内容时可能需要横向模式：

// 正常阅读时使用纵向模式
AutoOrientation.portraitUpMode();

// 查看图片时切换为横向模式
AutoOrientation.landscapeAutoMode();

6. 约束与限制

1. 权限要求：需要注意应用权限等级问题，如果安装时出现 9568289 错误，需要将应用权限等级修改为 system_basic。

2. 兼容性：已在 Flutter 3.7.12-ohos-1.0.6 和 HarmonyOS SDK 5.0.0(12) 环境下测试通过。

3. 方向控制：所有 API 都需要在应用处于前台时调用，后台应用可能无法控制屏幕方向。

4. 用户设置优先级：系统设置中的屏幕旋转开关可能会影响插件的功能，如果用户关闭了系统的屏幕旋转开关，自动旋转模式可能无法正常工作。

7. 总结

fluttertpc_auto_orientation 是一款功能强大的屏幕方向控制插件，为鸿蒙平台上的 Flutter 应用提供了灵活的屏幕方向管理能力。通过该插件，开发者可以轻松实现：

1. 固定方向控制：支持向左/向右横向、向上/向下纵向等固定方向模式。
2. 自动方向控制：支持纵向自动旋转、横向自动旋转等模式。
3. 用户设置模式：可以尊重用户的系统设置和设备传感器。

该插件的使用方法简单直观，API 设计清晰，适用于视频播放器、游戏、阅读应用等多种需要控制屏幕方向的场景。开发者只需通过简单的方法调用，即可实现复杂的屏幕方向控制需求，提升应用的用户体验。

同时，需要注意权限配置和应用权限等级的问题，以确保插件能够正常工作。

8. 开源协议

本项目基于 MIT License 开源，欢迎开发者自由使用和参与贡献。