Flutter `flutter_statusbarcolor_ns` 在 OpenHarmony 平台的状态栏颜色适配实践

Flutter flutter_statusbarcolor_ns 在 OpenHarmony 平台的状态栏颜色适配实践

引言

OpenHarmony（鸿蒙）生态这几年发展很快，其分布式架构和全场景能力吸引了越来越多开发者的关注。与此同时，Flutter 作为一款高性能的跨平台 UI 框架，凭借优秀的渲染性能和一致的体验，已经成为许多移动开发团队的首选。不过，Flutter 丰富的插件生态主要围绕 Android 和 iOS 构建，当我们需要把应用扩展到 OpenHarmony 平台时，很多核心插件就会遇到兼容性问题。

本文将以常用的状态栏颜色控制插件 flutter_statusbarcolor_ns 为例，和大家一起探讨如何将一个 Flutter 三方插件完整地适配到 OpenHarmony 平台。我们会从 Flutter 插件的通信原理讲起，一步步展示适配的具体实现，并分享一些性能优化和集成实践的经验，希望能为准备进行鸿蒙适配的 Flutter 开发者提供一份实用的参考。

一、技术背景与适配原理

1.1 Flutter 插件架构解析

简单来说，Flutter 插件就是一个"翻译官"：它把 Dart 代码里的功能请求，通过特定的通信机制转发给原生平台（比如 Android、iOS 或 OpenHarmony）去执行，然后再把结果传回来。它的核心架构通常分为三层：

1. Dart 接口层：给 Flutter 应用开发者提供简单好用的 API。
2. 平台通道层（Platform Channel） ：这是通信的桥梁，主要靠 MethodChannel 来实现 Dart 和原生平台之间的异步消息传递。消息会被转换成二进制格式，这样跨语言通信既高效又可靠。
3. 平台实现层：在各个原生平台上，用对应的语言（如 Kotlin、Swift 或 ArkTS）把 Dart 层声明的功能具体实现出来。

以下是一个典型的 Dart 层插件接口代码：

// lib/flutter_statusbarcolor_ns.dart
import 'dart:ui';
import 'package:flutter/services.dart';

/// 提供状态栏颜色控制方法的插件类
class FlutterStatusbarcolorNs {
  // 1. 定义平台通道，名字必须和原生端保持一致
  static const MethodChannel _channel =
      const MethodChannel('com.example/flutter_statusbarcolor_ns');

  /// 设置状态栏背景颜色
  /// [color] 要设置的颜色（Flutter `Color` 类型）
  /// 返回一个 `Future<bool>`，表示操作是否成功
  static Future<bool> setStatusBarColor(Color color) async {
    // 把 Flutter 的 Color 值转成十六进制字符串，方便传输
    String hexColor = color.value.toRadixString(16).padLeft(8, '0');
    
    try {
      // 2. 通过通道调用原生方法，并传入参数
      final bool result = await _channel.invokeMethod('setStatusBarColor', {
        'color': hexColor,
      });
      return result;
    } on PlatformException catch (e) {
      // 3. 做好错误处理，捕获平台调用异常
      print("调用原生方法 'setStatusBarColor' 失败: '${e.message}'.");
      return false;
    }
  }

  /// 设置状态栏内容颜色（浅色或深色）
  /// [isLight] 为 true 时设为浅色图标/文字，false 为深色
  static Future<bool> setStatusBarContentStyle(bool isLight) async {
    try {
      final bool result = await _channel.invokeMethod('setStatusBarContentStyle', {
        'isLight': isLight,
      });
      return result;
    } on PlatformException catch (e) {
      print("调用原生方法 'setStatusBarContentStyle' 失败: '${e.message}'.");
      return false;
    }
  }
}

1.2 OpenHarmony 与 Android 状态栏管理机制对比

flutter_statusbarcolor_ns 在 Android 端的实现，通常依赖于 Window 的 setStatusBarColor 方法和 View 系统的一些标志位（比如 SYSTEM_UI_FLAG_LIGHT_STATUS_BAR）。而在 OpenHarmony 的 ArkUI 框架下，API 就有所不同了：

• Android : getWindow().setStatusBarColor(color);
• OpenHarmony (ArkUI) : 需要通过 getWindow() 拿到 window 对象，然后调用 setWindowSystemBarProperties() 方法来设置状态栏、导航栏的颜色和内容样式。

这种 API 差异是跨平台适配中最常见的问题。因此，我们适配的核心工作之一，就是在 OpenHarmony 端用不同的原生 API 实现出和 Android 端相同的功能，并确保它们通过统一的 Flutter 通道接口暴露给 Dart 层。

1.3 适配整体设计思路

我们的适配方案遵循一个原则：接口统一，平台实现分离。具体来说：

1. 保持 Dart 接口层不变：Flutter 应用侧的代码完全不需要修改。
2. 新建 OpenHarmony 实现模块 ：在现有的 Flutter 插件工程里，新增一个专门针对 OpenHarmony 的模块（比如叫 ohos/）。
3. 实现平台通道对接 ：在这个模块里，用 ArkTS 写好 MethodChannel 的接收端，解析 Dart 层发来的指令，并调用上面提到的 OpenHarmony 原生 API。
4. 统一打包与发布 ：把 Android、iOS 和 OpenHarmony 的实现都整合到同一个插件包里，通过 pubspec.yaml 里的 platforms 配置，让 Flutter 工具链自动为不同平台选择正确的实现。

二、代码实现：OpenHarmony 原生模块开发

接下来，我们看看如何在 Flutter 插件项目中具体实现 OpenHarmony 端的代码。

2.1 创建 OpenHarmony 模块

首先，在现有 Flutter 插件的根目录下，用 DevEco Studio 或者命令行创建一个新的 "Harmony OS Ability" 模块，可以命名为 ohos/。我们的主要代码会放在这个模块的 entry/src/main/ets/ 目录下。

2.2 实现平台通道与 Ability 生命周期管理

我们需要一个入口 Ability 来管理插件的生命周期，并注册方法调用的处理器。

// entry/src/main/ets/entryability/EntryAbility.ts
import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';
import { FlutterStatusbarcolorPlugin } from '../flutter_statusbarcolor/FlutterStatusbarcolorPlugin';

export default class EntryAbility extends UIAbility {
  private plugin: FlutterStatusbarcolorPlugin | null = null;

  onCreate(want, launchParam) {
    console.info('FlutterStatusbarcolorNs OpenHarmony Plugin Ability onCreate');
    // Ability 创建时初始化插件
    this.plugin = new FlutterStatusbarcolorPlugin(this.context);
    this.plugin.registerMethodCallHandler();
  }

  onWindowStageCreate(windowStage: window.WindowStage) {
    console.info('FlutterStatusbarcolorNs onWindowStageCreate');
    // 插件主要逻辑通常不涉及UI，可以加载一个空页面，或者直接使用 windowStage
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        console.error('加载页面内容失败，原因:' + JSON.stringify(err));
        return;
      }
      console.info('页面内容加载成功');
      // 将 windowStage 传递给插件，后面获取活动窗口时会用到
      if (this.plugin) {
        this.plugin.setWindowStage(windowStage);
      }
    });
  }

  onDestroy() {
    console.info('FlutterStatusbarcolorNs Ability onDestroy');
    // 销毁时清理资源
    if (this.plugin) {
      this.plugin.unregisterMethodCallHandler();
      this.plugin = null;
    }
  }
}

2.3 核心插件逻辑实现

这里是适配工作的核心，负责监听 MethodChannel 并调用 OpenHarmony 的原生 API。

// entry/src/main/ets/flutter_statusbarcolor/FlutterStatusbarcolorPlugin.ts
import plugin from '@ohos.plugin';
import window from '@ohos.window';
import common from '@ohos.app.ability.common';
import { BusinessError } from '@ohos.base';

// 定义从 Dart 端接收的参数结构
interface StatusBarColorParams {
  color: string; // 例如: 'FF2196F3'
}

interface StatusBarStyleParams {
  isLight: boolean;
}

export class FlutterStatusbarcolorPlugin {
  private context: common.Context;
  private windowStage: window.WindowStage | null = null;
  private channel: plugin.MethodChannel | null = null;

  constructor(context: common.Context) {
    this.context = context;
  }

  setWindowStage(windowStage: window.WindowStage) {
    this.windowStage = windowStage;
  }

  registerMethodCallHandler() {
    // 1. 创建 MethodChannel，名称要与 Dart 端完全一致
    this.channel = new plugin.MethodChannel(this.context, 'com.example/flutter_statusbarcolor_ns');

    // 2. 设置方法调用监听器
    this.channel.onMethodCall((methodName: string, params: plugin.Params, result: plugin.Result) => {
      console.info(`收到Flutter调用: 方法=${methodName}, 参数=${JSON.stringify(params)}`);
      this.handleMethodCall(methodName, params, result);
    });
  }

  private async handleMethodCall(methodName: string, params: plugin.Params, result: plugin.Result) {
    try {
      switch (methodName) {
        case 'setStatusBarColor':
          await this.handleSetStatusBarColor(params as StatusBarColorParams, result);
          break;
        case 'setStatusBarContentStyle':
          await this.handleSetStatusBarContentStyle(params as StatusBarStyleParams, result);
          break;
        default:
          result.error('UNIMPLEMENTED', `方法 '${methodName}' 未在OpenHarmony端实现。`, null);
      }
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      result.error('EXCEPTION', `执行方法 '${methodName}' 时发生异常: ${err.message}`, err);
    }
  }

  private async handleSetStatusBarColor(params: StatusBarColorParams, result: plugin.Result) {
    if (!this.windowStage) {
      result.error('NO_WINDOW', 'WindowStage未就绪，无法设置状态栏。', null);
      return;
    }

    try {
      // 获取当前活动窗口
      const mainWindow = await this.windowStage.getMainWindow();
      // 解析颜色字符串。Dart 传来的是 ARGB 十六进制，OpenHarmony 需要 RGB 整数值。
      let cleanColor = params.color.replace(/^#|0x/, '');
      if (cleanColor.length === 6) {
        cleanColor = 'FF' + cleanColor; // 默认加上不透明度
      }
      // 这里我们取后6位作为 RGB 值
      const rgbColor = parseInt(cleanColor.slice(2), 16);

      // 准备系统栏属性配置
      const systemBarProperties: window.SystemBarProperties = {
        statusBarColor: rgbColor,
        // 内容颜色先保持不变，由另一个方法单独控制
        isStatusBarLightIcon: (await mainWindow.getWindowSystemBarProperties()).isStatusBarLightIcon
      };

      // 调用 OpenHarmony 原生 API
      await mainWindow.setWindowSystemBarProperties(systemBarProperties);
      console.info(`状态栏颜色已设置为: #${cleanColor}`);
      result.success(true);
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      console.error(`设置状态栏颜色失败: ${JSON.stringify(err)}`);
      result.error('SET_COLOR_FAILED', err.message, null);
    }
  }

  private async handleSetStatusBarContentStyle(params: StatusBarStyleParams, result: plugin.Result) {
    if (!this.windowStage) {
      result.error('NO_WINDOW', 'WindowStage未就绪，无法设置状态栏样式。', null);
      return;
    }

    try {
      const mainWindow = await this.windowStage.getMainWindow();
      const currentProps = await mainWindow.getWindowSystemBarProperties();

      const systemBarProperties: window.SystemBarProperties = {
        statusBarColor: currentProps.statusBarColor,
        isStatusBarLightIcon: params.isLight // true 为浅色图标（深色背景），false 为深色图标（浅色背景）
      };

      await mainWindow.setWindowSystemBarProperties(systemBarProperties);
      console.info(`状态栏内容样式已设置为: ${params.isLight ? '浅色' : '深色'}图标`);
      result.success(true);
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      console.error(`设置状态栏内容样式失败: ${JSON.stringify(err)}`);
      result.error('SET_STYLE_FAILED', err.message, null);
    }
  }

  unregisterMethodCallHandler() {
    if (this.channel) {
      this.channel.offMethodCall();
      this.channel = null;
    }
    this.windowStage = null;
  }
}

三、性能优化与实践指南

3.1 性能优化要点

1. 缓存窗口引用 ：频繁获取 window 对象会有一定开销。如果插件功能被频繁调用，可以考虑在插件初始化时就把 window 对象缓存起来，在 Ability 的生命周期内重复使用。记得在窗口销毁时清理缓存。
2. 支持批量操作 ：如果需要同时设置颜色和样式，可以在 Dart 层设计一个组合 API，这样在原生端只需要调用一次 setWindowSystemBarProperties 就能完成，减少平台通道的通信次数。
3. 做好错误处理与降级 ：把所有原生 API 调用都用 try-catch 包起来，并返回有意义的错误码给 Flutter 层，这样应用侧可以做降级处理（比如用纯色容器模拟状态栏效果）。
4. 注意内存管理 ：一定要在 Ability 的 onDestroy 里注销方法监听器，释放对 windowStage 的引用，避免内存泄漏。

3.2 集成步骤

1. 配置插件依赖 ：在 Flutter 插件的 pubspec.yaml 中，声明对 OpenHarmony 平台的支持。

   flutter:
     plugin:
       platforms:
         android:
           package: com.example.flutter_statusbarcolor_ns
           pluginClass: FlutterStatusbarcolorNsPlugin
         ios:
           pluginClass: FlutterStatusbarcolorNsPlugin
         ohos:
           pluginClass: EntryAbility # 指向 OpenHarmony 的入口 Ability

2. 编译 OpenHarmony 模块 ：进入 ohos/ 目录，使用 hb build 命令将 ArkTS 代码编译成 .hap 包。

3. Flutter 应用集成：

   • 在 Flutter 应用的 pubspec.yaml 中依赖这个已经适配好的插件。
   • 在应用的 OpenHarmony 工程配置里，确保引入了该插件的 .hap 模块。
   • 在 Flutter 代码中，就可以像在 Android/iOS 上一样调用 FlutterStatusbarcolorNs.setStatusBarColor() 了。

3.3 调试与验证

• 查看日志 ：充分利用 console.info 和 console.error 输出日志，可以在 DevEco Studio 的 HiLog 或通过 hdc shell hilog 命令查看插件的运行情况。
• 验证通道通信 ：首先确保 Dart 的方法调用能触发 OpenHarmony 端的 onMethodCall 日志，这说明通道是通的。
• 检查权限 ：某些系统栏操作可能需要特定权限，记得在 module.json5 中配置，例如 ohos.permission.SYSTEM_FLOAT_WINDOW（具体需要看 API 要求）。
• 对比性能 ：可以写个简单的测试用例，对比同一操作在 Android 和 OpenHarmony 上的耗时（用 console.time / console.timeEnd），确保没有明显的性能下降。

四、总结

通过以上步骤，我们完成了 flutter_statusbarcolor_ns 插件向 OpenHarmony 平台的适配。回顾整个过程，我们可以总结出 Flutter 三方插件鸿蒙化的一些通用经验：

1. 理解架构是前提：必须吃透 Flutter 插件的三层架构，特别是平台通道的工作原理，这是成功适配的基础。
2. API 映射是核心：适配的关键在于找到 OpenHarmony ArkUI 中与 Android/iOS 对等的功能 API，并处理好参数转换和传递。
3. 工程化保障兼容 ：通过新增 ohos 模块并配置多平台支持，可以实现"一套 Dart 代码，多平台原生实现"的优雅方案，既能最大程度复用代码，也降低了维护成本。
4. 健壮性决定可用性：完善的错误处理、资源的生命周期管理以及性能考量，是确保插件能在生产环境稳定运行的重要保障。

这次实践表明，将 Flutter 生态扩展到 OpenHarmony 在技术上是完全可行的。随着 OpenHarmony 开发者工具的持续完善和 ArkUI 能力的不断增强，未来会有更多成熟的 Flutter 插件可以平滑地迁移到鸿蒙生态中。这不仅仅是技术的融合，更是生态的共建。期待更多开发者能参与到这场跨平台的演进浪潮中来，一起构建更好的应用体验。