Flutter for OpenHarmony 实战：掷骰子 - 模拟掷骰子

在移动开发领域，我们总是面临着选择与适配。今天，你的Flutter应用在Android和iOS上跑得正欢，明天可能就需要考虑一个新的平台：HarmonyOS（鸿蒙）。这不是一道选答题，而是很多团队正在面对的现实。Flutter的优势很明确——写一套代码，就能在两个主要平台上运行，开发体验流畅。而鸿蒙代表的是下一个时代的互联生态，它不仅仅是手机系统，更着眼于未来全场景的体验。

fantasy_zzzz

563人浏览 · 2026-02-05 23:39:03

fantasy_zzzz · 2026-02-05 23:39:03 发布

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

前言：跨生态开发的新机遇

在移动开发领域，我们总是面临着选择与适配。今天，你的Flutter应用在Android和iOS上跑得正欢，明天可能就需要考虑一个新的平台：HarmonyOS（鸿蒙）。这不是一道选答题，而是很多团队正在面对的现实。

Flutter的优势很明确——写一套代码，就能在两个主要平台上运行，开发体验流畅。而鸿蒙代表的是下一个时代的互联生态，它不仅仅是手机系统，更着眼于未来全场景的体验。将现有的Flutter应用适配到鸿蒙，听起来像是一个“跨界”任务，但它本质上是一次有价值的技术拓展：让产品触达更多用户，也让技术栈覆盖更广。

不过，这条路走起来并不像听起来那么简单。Flutter和鸿蒙，从底层的架构到上层的工具链，都有着各自的设计逻辑。会遇到一些具体的问题：代码如何组织？原有的功能在鸿蒙上如何实现？那些平台特有的能力该怎么调用？更实际的是，从编译打包到上架部署，整个流程都需要重新摸索。
这篇文章想做的，就是把这些我们趟过的路、踩过的坑，清晰地摊开给你看。我们不会只停留在“怎么做”，还会聊到“为什么得这么做”，以及“如果出了问题该往哪想”。这更像是一份实战笔记，源自真实的项目经验，聚焦于那些真正卡住过我们的环节。

无论你是在为一个成熟产品寻找新的落地平台，还是从一开始就希望构建能面向多端的应用，这里的思路和解决方案都能提供直接的参考。理解了两套体系之间的异同，掌握了关键的衔接技术，不仅能完成这次迁移，更能积累起应对未来技术变化的能力。

混合工程结构深度解析

项目目录架构

当Flutter项目集成鸿蒙支持后，典型的项目结构会发生显著变化。以下是经过ohos_flutter插件初始化后的项目结构：

my_flutter_harmony_app/
├── lib/                          # Flutter业务代码（基本不变）
│   ├── main.dart                 # 应用入口
│   ├── home_page.dart           # 首页
│   └── utils/
│       └── platform_utils.dart  # 平台工具类
├── pubspec.yaml                  # Flutter依赖配置
├── ohos/                         # 鸿蒙原生层（核心适配区）
│   ├── entry/                    # 主模块
│   │   └── src/main/
│   │       ├── ets/              # ArkTS代码
│   │       │   ├── MainAbility/
│   │       │   │   ├── MainAbility.ts       # 主Ability
│   │       │   │   └── MainAbilityContext.ts
│   │       │   └── pages/
│   │       │       ├── Index.ets           # 主页面
│   │       │       └── Splash.ets          # 启动页
│   │       ├── resources/        # 鸿蒙资源文件
│   │       │   ├── base/
│   │       │   │   ├── element/  # 字符串等
│   │       │   │   ├── media/    # 图片资源
│   │       │   │   └── profile/  # 配置文件
│   │       │   └── en_US/        # 英文资源
│   │       └── config.json       # 应用核心配置
│   ├── ohos_test/               # 测试模块
│   ├── build-profile.json5      # 构建配置
│   └── oh-package.json5         # 鸿蒙依赖管理
└── README.md

展示效果图片

flutter 实时预览效果展示
在这里插入图片描述

运行到鸿蒙虚拟设备中效果展示
在这里插入图片描述

功能代码实现

DiceRoller 组件实现

DiceRoller 是本次开发的核心组件，用于实现掷骰子的功能。该组件支持自定义面数、大小、颜色等属性，并包含流畅的旋转动画效果。

组件设计思路

可定制性设计：通过构造函数参数实现高度可定制，包括骰子面数、大小、颜色等属性
动画效果：使用 Flutter 动画系统实现 3D 旋转效果，提升用户体验
状态管理：每个骰子组件独立管理自己的状态，包括当前点数和动画状态
交互设计：实现点击交互，点击骰子即可开始掷骰子

核心代码实现

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

class DiceRoller extends StatefulWidget {
  final int sides; // 骰子面数
  final double size; // 骰子大小
  final Color diceColor; // 骰子颜色
  final Color dotColor; // 点数颜色
  final Color textColor; // 文本颜色

  const DiceRoller({
    Key? key,
    this.sides = 6,
    this.size = 150.0,
    this.diceColor = Colors.white,
    this.dotColor = Colors.black,
    this.textColor = Colors.black,
  }) : super(key: key);

  @override
  State<DiceRoller> createState() => _DiceRollerState();
}

class _DiceRollerState extends State<DiceRoller> with SingleTickerProviderStateMixin {
  late int _currentValue; // 当前骰子值
  late AnimationController _controller; // 动画控制器
  late Animation<double> _animation; // 旋转动画
  bool _isRolling = false; // 是否正在掷骰子

  @override
  void initState() {
    super.initState();
    _currentValue = Random().nextInt(widget.sides) + 1; // 初始化随机值
    
    // 初始化动画控制器
    _controller = AnimationController(
      duration: const Duration(milliseconds: 500),
      vsync: this,
    );
    
    // 创建旋转动画
    _animation = Tween<double>(begin: 0, end: 1).animate(
      CurvedAnimation(parent: _controller, curve: Curves.easeInOut),
    );
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  // 掷骰子方法
  void _rollDice() {
    if (_isRolling) return;
    
    setState(() {
      _isRolling = true;
    });

    // 启动动画
    _controller.forward().then((_) {
      // 动画结束后更新骰子值
      setState(() {
        _currentValue = Random().nextInt(widget.sides) + 1;
        _isRolling = false;
      });
      // 重置动画
      _controller.reset();
    });
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        // 骰子标题
        Text(
          '${widget.sides}面骰子',
          style: TextStyle(
            fontSize: 18,
            fontWeight: FontWeight.bold,
            color: widget.textColor,
          ),
        ),
        const SizedBox(height: 20),
        
        // 骰子动画区域
        GestureDetector(
          onTap: _rollDice,
          child: AnimatedBuilder(
            animation: _animation,
            builder: (context, child) {
              return Transform(
                transform: Matrix4.identity()
                  ..rotateX(_animation.value * 2 * pi)
                  ..rotateY(_animation.value * 2 * pi),
                alignment: Alignment.center,
                child: Container(
                  width: widget.size,
                  height: widget.size,
                  decoration: BoxDecoration(
                    color: widget.diceColor,
                    borderRadius: BorderRadius.circular(12),
                    boxShadow: [
                      BoxShadow(
                        color: Colors.grey.withOpacity(0.5),
                        spreadRadius: 2,
                        blurRadius: 5,
                        offset: const Offset(0, 3),
                      ),
                    ],
                  ),
                  child: Center(
                    child: Text(
                      _currentValue.toString(),
                      style: TextStyle(
                        fontSize: widget.size * 0.4,
                        fontWeight: FontWeight.bold,
                        color: widget.dotColor,
                      ),
                    ),
                  ),
                ),
              );
            },
          ),
        ),
        
        const SizedBox(height: 15),
        
        // 当前点数显示
        Text(
          '当前点数: $_currentValue',
          style: TextStyle(
            fontSize: 16,
            color: widget.textColor,
          ),
        ),
        
        const SizedBox(height: 10),
        
        // 提示文本
        Text(
          '点击骰子开始掷',
          style: TextStyle(
            fontSize: 14,
            color: widget.textColor.withOpacity(0.7),
          ),
        ),
      ],
    );
  }
}

组件使用方法

DiceRoller 组件的使用非常简单，只需要在需要的地方实例化该组件，并根据需要设置相关属性即可。以下是几个常用场景的使用示例：

1. 标准6面骰子

DiceRoller(
  sides: 6,
  size: 150,
  diceColor: Colors.white,
  dotColor: Colors.black,
)

2. 自定义颜色的4面骰子

DiceRoller(
  sides: 4,
  size: 120,
  diceColor: Colors.red,
  dotColor: Colors.white,
  textColor: Colors.white,
)

3. 大型20面骰子

DiceRoller(
  sides: 20,
  size: 160,
  diceColor: Colors.purple,
  dotColor: Colors.white,
  textColor: Colors.white,
)

开发注意事项

动画控制器管理：必须在组件销毁时释放动画控制器，否则会导致内存泄漏
状态管理：每个骰子组件独立管理自己的状态，确保在页面滚动时状态不会丢失
防重复点击：实现了 _isRolling 标志，防止在动画执行过程中重复点击
性能优化：使用 AnimatedBuilder 优化动画性能，避免不必要的重建

主页面集成

主页面是应用的入口点，负责集成和展示多个骰子实例。在本次开发中，我们在主页面直接集成了5个不同配置的骰子实例，以展示组件的灵活性和多样性。

页面设计思路

布局结构：使用 SingleChildScrollView 包装内容，确保在小屏幕设备上也能正常显示
组件排列：使用 Column 布局垂直排列多个骰子实例
视觉层次：通过调整不同骰子的大小和颜色，创建丰富的视觉层次
用户体验：直接在首页显示骰子效果，无需额外导航，提升用户体验

核心代码实现

import 'package:flutter/material.dart';
import 'package:aa/utils/dice_roller.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter for openHarmony',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      debugShowCheckedModeBanner: false,
      home: const MyHomePage(title: 'Flutter for openHarmony'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
      ),
      body: SingleChildScrollView(
        padding: const EdgeInsets.all(20.0),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            // 页面标题
            Text(
              '掷骰子模拟器',
              style: Theme.of(context).textTheme.headlineLarge,
            ),
            const SizedBox(height: 30),
            
            // 标准6面骰子
            DiceRoller(
              sides: 6,
              size: 150,
              diceColor: Colors.white,
              dotColor: Colors.black,
            ),
            const SizedBox(height: 40),
            
            // 4面骰子
            DiceRoller(
              sides: 4,
              size: 120,
              diceColor: Colors.red,
              dotColor: Colors.white,
              textColor: Colors.white,
            ),
            const SizedBox(height: 40),
            
            // 8面骰子
            DiceRoller(
              sides: 8,
              size: 130,
              diceColor: Colors.blue,
              dotColor: Colors.white,
              textColor: Colors.white,
            ),
            const SizedBox(height: 40),
            
            // 12面骰子
            DiceRoller(
              sides: 12,
              size: 140,
              diceColor: Colors.green,
              dotColor: Colors.white,
              textColor: Colors.white,
            ),
            const SizedBox(height: 40),
            
            // 20面骰子
            DiceRoller(
              sides: 20,
              size: 160,
              diceColor: Colors.purple,
              dotColor: Colors.white,
              textColor: Colors.white,
            ),
            const SizedBox(height: 40),
          ],
        ),
      ),
    );
  }
}

开发注意事项

包导入路径：根据 pubspec.yaml 中的项目名称，使用正确的包路径导入 DiceRoller 组件
布局适配：使用 SingleChildScrollView 确保在小屏幕设备上的适配性
间距设置：合理设置组件之间的间距，提升页面美观度
主题一致性：使用 Theme.of(context) 获取应用主题，确保页面风格与应用整体一致

本次开发中容易遇到的问题

动画控制器管理问题
- 问题描述：在使用动画控制器时，如果忘记在组件销毁时释放资源，会导致内存泄漏
- 解决方案：在 StatefulWidget 的 dispose 方法中调用 _controller.dispose() 释放动画资源
- 代码示例：
```
@override
void dispose() {
  _controller.dispose();
  super.dispose();
}
```
状态管理问题
- 问题描述：在滚动页面时，骰子状态可能会丢失或重置
- 解决方案：使用 StatefulWidget 为每个骰子组件独立管理状态，并确保状态变量正确初始化
- 注意事项：避免使用全局状态管理，保持组件的独立性和可复用性
包导入路径问题
- 问题描述：导入 DiceRoller 组件时使用了错误的包名，导致编译失败
- 解决方案：根据 pubspec.yaml 中的项目名称，使用正确的包路径
- 示例：如果项目名称为 aa，则导入路径应为 package:aa/utils/dice_roller.dart
布局适配问题
- 问题描述：在不同屏幕尺寸下，骰子可能显示过大或过小
- 解决方案：为 DiceRoller 组件提供可自定义的 size 参数，并在主页面中根据屏幕尺寸调整大小
- 优化建议：可以考虑使用 MediaQuery 获取屏幕尺寸，动态计算骰子大小
构建失败问题
- 问题描述：执行 flutter build web 时出现 Missing index.html 错误
- 解决方案：执行 flutter create . 命令生成完整的项目结构，包括 web 目录和必要文件
- 注意事项：执行该命令可能会重置部分文件，需要注意备份重要代码

总结本次开发中用到的技术点

Flutter 动画系统
- 核心技术：使用 AnimationController 和 Animation 实现流畅的 3D 旋转动画
- 关键实现：通过 Tween 定义动画范围，CurvedAnimation 实现平滑的动画曲线
- 技术要点：使用 SingleTickerProviderStateMixin 为动画提供 vsync，避免动画卡顿
Flutter 状态管理
- 核心技术：使用 StatefulWidget 和 setState 管理组件状态
- 关键实现：每个骰子组件独立管理自己的点数和动画状态
- 技术要点：通过状态变量 _isRolling 防止重复点击，提升用户体验
随机数生成
- 核心技术：使用 dart:math 库中的 Random 类生成随机骰子点数
- 关键实现：根据骰子面数计算随机范围：Random().nextInt(widget.sides) + 1
- 技术要点：确保生成的随机数在有效范围内，避免越界错误
Flutter 布局系统
- 核心技术：使用 Column、SizedBox、SingleChildScrollView 等布局组件构建页面结构
- 关键实现：通过 Transform 实现 3D 旋转效果，提升视觉体验
- 技术要点：合理设置布局参数，确保在不同屏幕尺寸下的适配性
组件化开发
- 核心技术：将骰子功能抽离为独立的 DiceRoller 组件
- 关键实现：通过构造函数参数实现组件的高度可定制性
- 技术要点：遵循 Flutter 组件设计最佳实践，确保组件的可复用性和可测试性
用户交互
- 核心技术：使用 GestureDetector 实现点击交互
- 关键实现：在点击时触发动画和点数更新
- 技术要点：实现防重复点击机制，确保动画流畅执行
响应式设计
- 核心技术：为组件提供可自定义的参数，适应不同的使用场景
- 关键实现：通过 size 参数调整骰子大小，通过 diceColor、dotColor 等参数调整颜色
- 技术要点：考虑不同屏幕尺寸和设备类型的适配性
跨平台适配
- 核心技术：使用 Flutter 内置的动画和布局系统，确保在不同平台上的一致性
- 关键实现：避免使用平台特定的功能，保证代码的跨平台兼容性
- 技术要点：在鸿蒙平台上测试应用，确保功能正常运行
性能优化
- 核心技术：使用 AnimatedBuilder 优化动画性能
- 关键实现：避免在动画构建过程中执行耗时操作
- 技术要点：合理管理资源，及时释放不再使用的资源
项目构建与部署
- 核心技术：使用 flutter create 和 flutter build 命令管理项目构建
- 关键实现：确保项目结构完整，包含必要的配置文件
- 技术要点：熟悉 Flutter 构建流程，解决构建过程中遇到的问题

通过本次开发，我们成功实现了一个功能完整、交互流畅的掷骰子应用，并将其集成到 Flutter for OpenHarmony 项目中。这个项目展示了如何使用 Flutter 动画系统、状态管理、组件化开发等技术，构建一个跨平台的应用。同时，我们也解决了开发过程中遇到的各种问题，积累了宝贵的开发经验。

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