Flutter 三方库 app_widget 的鸿蒙化适配指南

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

宝子们，今天我要带大家解锁一个超酷的鸿蒙跨平台玩法——用 Flutter 三方库 app_widget 实现 OH 原生桌面卡片！🥳 想象一下，你的 Flutter 应用不仅能在鸿蒙设备上流畅运行，还能把今日待办数量直接展示在手机桌面上，不用点开 app 就能一眼看到任务进度，是不是敲方便？

作为一名沉迷 Flutter 鸿蒙化的小开发，我最近刚完成了这个功能的适配，今天就把踩过的坑、摸透的技巧全部分享给大家，保证宝子们看完就能上手，轻松拥有自己的鸿蒙原生桌面卡片！

为什么要做鸿蒙原生卡片适配？

在鸿蒙生态里，桌面卡片（Widget）是用户和应用互动的重要入口。它能把应用的核心信息直接展示在桌面上，不用打开 app 就能快速获取关键数据，比如待办数量、天气情况或者音乐播放状态。对于我们 Flutter 开发者来说，以前想要实现这个功能，可能需要写不少原生鸿蒙代码，但有了 app_widget 这个三方库，我们只用 Flutter 代码就能搞定原生卡片适配，真正做到“一次开发，多端部署”的跨平台梦想！

准备工作：你需要这些工具

在开始之前，宝子们要确保自己的开发环境已经准备好啦：

1. DevEco Studio 6.0 及以上版本（毕竟最新版才支持最棒的鸿蒙特性嘛）
2. OpenHarmony SDK 20（这个版本对 Flutter 跨平台的支持超友好）
3. Flutter for OpenHarmony 环境（已经配置好的宝子可以跳过这一步哦）
4. 一个鸿蒙设备或者模拟器（用来测试我们的卡片效果）

第一步：引入 app_widget 三方库

首先，我们需要把 app_widget 库添加到 Flutter 项目里。打开项目根目录下的 pubspec.yaml 文件，在 dependencies 部分加上：

dependencies:
  flutter:
    sdk: flutter
  app_widget: ^0.1.0 # 最新版本可以去 
  AtomGit 上查看哦

然后运行 flutter pub get 命令，把库下载到本地。这里要提醒宝子们，一定要去 AtomGit 上获取最新版本的库哦，仓库地址是： https://atomgit.com/flutter-oh/app_widget ，别搞错啦！

第二步：创建桌面卡片提供者

接下来，我们要创建一个卡片提供者类，用来定义桌面卡片的内容和样式。这个类需要继承自 AppWidgetProvider ，并实现 buildWidget 方法，这个方法就是用来构建我们的桌面卡片的。

我这里写了一个显示今日待办数量的卡片提供者，宝子们可以参考一下：

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

class TodoCountWidgetProvider 
extends AppWidgetProvider {
  @override
  Widget buildWidget(BuildContext 
  context, Map<String, dynamic> 
  params) {
    // 这里我们获取待办数量，宝子们可以替
    换成自己的业务逻辑
    int pendingTodos = TodoService.
    getPendingTodoCount();
    
    return Container(
      decoration: BoxDecoration(
        color: Colors.pink[100], // 
        粉粉嫩嫩的背景色，超可爱！
        borderRadius: BorderRadius.
        circular(12),
        boxShadow: [
          BoxShadow(
            color: Colors.grey.
            withOpacity(0.3),
            blurRadius: 4,
            offset: Offset(0, 2),
          )
        ]
      ),
      child: Column(
        mainAxisAlignment: 
        MainAxisAlignment.center,
        children: [
          Text(
            "今日待办",
            style: TextStyle(
              color: Colors.pink
              [800],
              fontSize: 16,
              fontWeight: 
              FontWeight.bold,
            ),
          ),
          SizedBox(height: 8),
          Text(
            "$pendingTodos 📝",
            style: TextStyle(
              color: Colors.pink
              [900],
              fontSize: 24,
              fontWeight: 
              FontWeight.w900,
            ),
          ),
        ],
      ),
    );
  }
}

这个提供者类会构建一个粉色背景的卡片，显示“今日待办”和待办数量，是不是超可爱？宝子们可以根据自己的喜好修改背景色、字体样式和布局哦。

第三步：配置桌面卡片元数据

接下来，我们需要配置桌面卡片的元数据，告诉鸿蒙系统我们的卡片长什么样、用哪个提供者类来构建。在项目的 android/app/src/main/res/xml 目录下（如果没有这个目录就新建一个），创建一个名为 app_widget_info.xml 的文件，内容如下：

<?xml version="1.0" 
encoding="utf-8"?>
<appwidget-provider 
xmlns:ohos="http://schemas.huawei.
com/res/ohos">
    <!-- 卡片的最小尺寸 -->
    <ohos:minWidth>200vp</
    ohos:minWidth>
    <ohos:minHeight>100vp</
    ohos:minHeight>
    <!-- 卡片的更新周期，这里设置为30分
    钟更新一次 -->
    <ohos:updatePeriodMillis>1800000
    </ohos:updatePeriodMillis>
    <!-- 卡片的布局类型，这里我们用 
    Flutter 构建的布局 -->
    <ohos:initialLayout>flutter_widg
    et</ohos:initialLayout>
    <!-- 卡片的提供者类 -->
    <ohos:provider>com.example.todo.
    TodoCountWidgetProvider</
    ohos:provider>
</appwidget-provider>

然后，我们需要在 AndroidManifest.xml 文件中注册这个卡片提供者：

<receiver
    android:name="com.example.todo.
    TodoCountWidgetProvider"
    android:exported="true">
    <intent-filter>
        <action android:name="ohos.
        intent.action.
        APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data
        android:name="ohos.
        appwidget.provider"
        android:resource="@xml/
        app_widget_info" />
</receiver>

这一步很重要哦，宝子们一定要仔细检查配置，不然卡片可能不会显示在桌面上！

第四步：实现待办数量逻辑

现在，我们需要实现获取待办数量的逻辑。我这里写了一个简单的 TodoService 类，用来模拟待办数据：

class TodoService {
  static List<Todo> _todos = [
    Todo(id: 1, title: "学习 
    Flutter 鸿蒙化", completed: 
    false),
    Todo(id: 2, title: "写一篇可爱的技
    术文章", completed: false),
    Todo(id: 3, title: "测试桌面卡片效
    果", completed: false),
  ];

  static int getPendingTodoCount() {
    return _todos.where((todo) => 
    !todo.completed).length;
  }
}

class Todo {
  final int id;
  final String title;
  final bool completed;

  Todo({required this.id, required 
  this.title, required this.
  completed});
}

宝子们可以把这个逻辑替换成自己的业务逻辑，比如从数据库或者网络请求中获取待办数量哦。

第五步：测试桌面卡片效果

现在，我们可以把应用运行到鸿蒙设备上啦！打开 DevEco Studio，连接你的鸿蒙设备或者启动模拟器，然后运行 Flutter 应用。

应用安装完成后，长按桌面空白处，选择“添加卡片”，找到我们的“今日待办”卡片，添加到桌面上。你就能看到一个粉粉嫩嫩的卡片，显示今日待办的数量啦！

运行效果截图

我这里给宝子们描述一下运行效果哦：

常见问题排查

如果宝子们在测试过程中遇到问题，可以试试以下方法：

1. 检查 pubspec.yaml 中的依赖是否正确添加，运行 flutter pub get 是否成功
2. 检查 app_widget_info.xml 和 AndroidManifest.xml 的配置是否正确
3. 确保鸿蒙设备的系统版本支持桌面卡片功能（OpenHarmony 20 及以上版本）
4. 如果卡片不显示，可以重启应用或者设备试试

总结

通过 app_widget 三方库，我们只用 Flutter 代码就能轻松实现鸿蒙原生桌面卡片，是不是超棒？这个库不仅简化了跨平台开发的流程，还让我们能充分利用鸿蒙生态的特性，为用户提供更好的体验。

宝子们，赶紧动手试试吧！如果有什么问题，可以去开源鸿蒙跨平台社区提问哦，地址是： https://openharmonycrossplatform.csdn.net ，那里有很多热心的开发者会帮助你哒！