基于HarmonyOS 7.0 跨端开发的TRPG跑团战报页面实战

前言

在桌面角色扮演与硬核游戏类应用中，跑团战报是一个为 TRPG（桌面角色扮演游戏，如龙与地下城）玩家管理角色、记录冒险、辅助掷骰的硬核主题功能。跑团是一种充满想象力的协作叙事游戏，玩家扮演角色、用骰子决定行动结果、在主持人引导下经历冒险，而一个能管理角色卡（属性、HP、装备）、记录冒险日志、提供骰子工具的应用，是跑团玩家的得力助手。一个优秀的跑团战报页面，需要展示角色卡（含属性雷达图）、提供多面骰掷骰工具（含动画）、并记录冒险日志。这类页面在技术上的亮点是"属性雷达图自绘加骰子动画加随机掷骰"——它需要用 CustomPaint 自绘六维属性雷达图、用动画控制器实现掷骰滚动效果、用随机数掷骰。当我们把这样一个硬核游戏主题的页面放进 HarmonyOS 7.0 的跨端开发语境时，它就成为检验 Flutter 雷达图自绘、显式动画与随机数跨端一致性的合适样本。本文将以一个真实的 Flutter 跑团战报页面为载体，结合 Flutter 与 HarmonyOS 7.0 的融合架构，深入剖析它的设计思路、核心代码与跨端落地路径。需要在开篇明确：本文涉及的鸿蒙适配全部基于 HarmonyOS 跨平台 SIG 维护的定制版 Flutter SDK，而非 flutter.dev 官方版本，这是所有讨论的前提。

背景

跑团的核心是"角色"和"骰子"。角色卡是 TRPG 的灵魂——记录角色的种族、职业、等级、生命值（HP）、护甲（AC），以及六大属性（力量、敏捷、体质、智力、感知、魅力），这些属性决定角色的能力，最适合用雷达图（六边形）可视化呈现，一眼看出角色是力量型还是智力型。骰子是 TRPG 的决断工具——D4、D6、D8、D10、D12、D20 等多面骰用于判定行动成败（如掷 D20 检定攻击），掷骰的随机性是游戏的核心机制。冒险日志则记录每次跑团（session）的故事、获得的经验值和战利品，是冒险的回忆。从技术上看，这个页面的三大亮点是属性雷达图的 CustomPaint 自绘、骰子的显式动画（AnimationController）和随机掷骰。在传统多端开发中，要在 Android、iOS、HarmonyOS 上分别实现这套自绘、动画和随机，意味着大量重复且易不一致。这种"雷达图自绘一致、动画流畅、随机一致"的要求，正是 Flutter 跨端价值的体现。我们的目标，是用一份 Dart 代码让手机、平板与鸿蒙设备上呈现一致的跑团战报体验。

Flutter × Harmony7.0 跨端开发介绍

跑团战报页面要在 HarmonyOS 7.0 上正确运行，需要理解 Flutter 在鸿蒙上的运行架构。Flutter 由 Framework、Engine、Embedder 三层组成。Framework 层用 Dart 编写，负责组件、状态、布局、动画等，本页面里的角色卡、雷达图、骰子工具、冒险日志都属于这一层，骰子动画用到了 AnimationController。Engine 层是运行时核心，负责 Dart VM、AOT 产物加载、GPU 渲染、文本排版等；Flutter 在鸿蒙上的界面由其自绘引擎绘制，通过接入 HarmonyOS 的 ArkUI RenderingContext 获取 GPU 渲染上下文，再由 ArkTS 容器 FlutterAbility 承载输出。这里的技术核心是 _StatRadarPainter——用 CustomPaint 自绘六维属性雷达图（背景网格加数据多边形加标签），用三角函数定位六个顶点，由 Skia 渲染跨端逐像素一致。骰子掷骰用 AnimationController 显式动画配合 Random，都是纯 Dart/Framework 能力，跨端一致。Embedder 层是 Flutter 与鸿蒙系统的桥梁，由 @ohos/flutter_ohos 提供的 FlutterAbility 实现。在能力接入上，角色卡、雷达图、骰子、日志都是纯 Framework 与 Dart 能力，可零适配复用。编译上，Release 模式的 AOT 提前编译保证了自绘和动画的原生级流畅。

开发核心代码

跑团战报页面的代码可分为三个核心部分。第一部分是属性雷达图的 CustomPaint 自绘。页面以 StatefulWidget 承载，入口类被统一命名为 SearchPage，状态类 _TRPGLogPageState 用 _StatRadarPainter 自绘六维雷达图。

class SearchPage extends StatefulWidget {
  const SearchPage({super.key});
  @override
  State<SearchPage> createState() => _TRPGLogPageState();
}

class _StatRadarPainter extends CustomPainter {
  final Map<String, int> stats;
  @override
  void paint(Canvas canvas, Size size) {
    final count = stats.length;  // 6个属性
    // 背景网格（4层六边形）
    for (int level = 1; level <= 4; level++) {
      final path = Path();
      for (int i = 0; i < count; i++) {
        final angle = -pi / 2 + pi * 2 / count * i;  // 从正上方开始均分
        final r = radius * level / 4;
        final x = cx + cos(angle) * r, y = cy + sin(angle) * r;
        i == 0 ? path.moveTo(x, y) : path.lineTo(x, y);
      }
      path.close();
      canvas.drawPath(path, bgPaint);
    }
    // 属性值多边形
    final dataPath = Path();
    for (int i = 0; i < count; i++) {
      final angle = -pi / 2 + pi * 2 / count * i;
      final r = radius * (stats[labels[i]]! / 20.0).clamp(0.1, 1.0);  // 属性值占比
      final x = cx + cos(angle) * r, y = cy + sin(angle) * r;
      i == 0 ? dataPath.moveTo(x, y) : dataPath.lineTo(x, y);
    }
    dataPath.close();
    canvas.drawPath(dataPath, fillPaint);  // 填充
    canvas.drawPath(dataPath, linePaint);  // 描边
    // 标签（用 TextPainter）
    for (int i = 0; i < count; i++) { /* TextPainter 画属性名和值 */ }
  }
}

这段代码是本页面的技术核心——用 CustomPaint 自绘六维属性雷达图。雷达图由三部分组成：背景网格（4层逐渐放大的六边形，用三角函数 cos/sin 算每层六个顶点）、数据多边形（六个属性值按比例确定各顶点的半径，连成不规则多边形并填充）、标签（用 TextPainter 在每个顶点外画属性名和值）。核心是三角函数定位——angle = -pi/2 + pi*2/count*i 从正上方开始把圆均分为6份，cos(angle)、sin(angle) 算出每个方向的顶点坐标。雷达图能直观展现角色的属性分布（哪个属性强哪个弱）。这种复杂的雷达图自绘由 Skia 渲染，鸿蒙上与手机端逐像素一致——这是 Flutter 自绘处理数据可视化图表的有力体现。

第二部分是骰子掷骰，它用 AnimationController 显式动画配合随机数。

late AnimationController _diceAnimController;
@override
void initState() {
  super.initState();
  _diceAnimController = AnimationController(vsync: this, duration: const Duration(milliseconds: 800));
  _diceAnimController.addStatusListener((status) {
    if (status == AnimationStatus.completed) _diceAnimController.reset();
  });
}
@override
void dispose() {
  _diceAnimController.dispose();  // 释放动画控制器
  super.dispose();
}

void _rollDice() {
  if (_rolling) return;
  setState(() => _rolling = true);
  final rng = Random();
  final maxVal = int.parse(_selectedDice.replaceAll('D', ''));  // D20 → 20
  _diceAnimController.addListener(() {
    setState(() => _diceResult = rng.nextInt(maxVal) + 1);  // 动画中快速变化数字
  });
  _diceAnimController.forward().then((_) {
    setState(() { _diceResult = rng.nextInt(maxVal) + 1; _rolling = false; });  // 最终结果
  });
}

这段代码用 AnimationController 实现骰子滚动动画。与塔罗、星座的 AnimatedContainer（隐式动画）不同，这里用显式动画——AnimationController 在 initState 创建（vsync: this 需要 SingleTickerProviderStateMixin），掷骰时通过 addListener 在动画过程中不断刷新随机数字（营造"滚动"的视觉），动画结束（forward().then）后定格最终结果。maxVal 用 replaceAll('D', '') 从"D20"提取20，rng.nextInt(maxVal) + 1 掷出1到maxVal的随机数。关键是 dispose 中 _diceAnimController.dispose() 释放控制器——显式动画必须手动释放，否则内存泄漏。这种显式动画加随机的组合纯 Dart 实现，跨端一致。

第三部分是冒险日志，它用心情图标和经验值展示每次跑团。

Widget _buildLogCard(Map<String, dynamic> log) {
  final moodIcons = {'惊险': '⚡', '悬疑': '🔮', '热血': '🔥', '悲伤': '💧', '欢乐': '🎉'};
  return Card(child: Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
    Row(children: [
      Container(child: Text(log['session'] as String)),  // 第几回
      Text(log['date'] as String),
      Text(moodIcons[log['mood'] as String] ?? ''),  // 心情图标
      const Spacer(),
      Row(children: [const Icon(Icons.auto_awesome), Text('+${log['xp']} XP')]),  // 经验值
    ]),
    Text(log['title'] as String),    // 标题
    Text(log['summary'] as String),  // 剧情概要
    Text('🪙 获得: ${log['loot']}'),  // 战利品
  ]));
}

这段代码用日志卡展示每次跑团的战报——回合数、日期、心情图标（用 Map 映射惊险⚡、悬疑🔮、热血🔥）、获得的经验值、剧情标题、概要和战利品。这种叙事性的日志记录了冒险的精彩瞬间，是跑团回忆的载体。心情用 Map 映射图标。这种日志卡纯 Dart 实现，跨端一致。三部分代码合在一起，构成了一个角色可视、掷骰有动画、冒险有记录的跑团战报页面，其雷达图自绘、骰子动画、冒险日志都不依赖任何平台特性可零适配跨端。

心得

把这个跑团战报页面落地到 HarmonyOS 7.0，让我对 Flutter 的雷达图自绘和显式动画在跨端中的表现有了深入体会，它综合了我在 141-142 组学到的随机、自绘、动画能力。第一点核心体会是属性雷达图的自绘。_StatRadarPainter 用三角函数定位绘制六维雷达图——这是数据可视化图表中较复杂的一种，背景网格、数据多边形、标签都用 cos/sin 三角函数定位顶点。让我赞叹的是，这种复杂的图表自绘在鸿蒙上与手机端逐像素一致。这印证了一个结论：Flutter 用 CustomPaint 能自绘任意数据可视化图表（雷达图、折线图、饼图、柱状图），且都跨端一致——这意味着不依赖第三方图表库也能实现专业图表，且跨端无忧。第二点深的体会是显式动画 AnimationController 与隐式动画 AnimatedContainer 的区别。骰子滚动用 AnimationController 显式动画，因为它需要在动画过程中持续刷新随机数字（addListener），这种"动画过程中执行逻辑"的需求是隐式动画做不到的，必须用显式动画。这让我厘清了两者的适用：简单的状态过渡用隐式（AnimatedContainer），需要精细控制动画过程的用显式（AnimationController）。第三点关键体会是显式动画的资源释放。AnimationController 必须在 dispose 中 dispose() 释放，否则内存泄漏——这是显式动画相比隐式动画多出的责任，也是我在前面动画页面反复强调的资源生命周期管理。第四点体会是随机数掷骰——Random 加 replaceAll 提取骰子面数，纯 Dart 跨端一致。第五点是工程规律的印证：雷达图自绘、骰子动画、冒险日志零成本跨端，CustomPaint 能自绘任意图表跨端一致，显式动画需手动释放控制器。

总结

通过 TRPG 跑团战报页面在 HarmonyOS 7.0 上的实践，我们看到了 Flutter 跨端方案在"硬核游戏工具类应用"上的强大能力。架构上，Framework、Engine、Embedder 三层在鸿蒙平台协同运转，_StatRadarPainter 通过 Skia 自绘六维属性雷达图保证了图表逐像素一致，AnimationController 显式动画配合 Random 实现掷骰且跨端一致，AOT 编译保证了自绘和动画的流畅，FlutterAbility 承载了与鸿蒙系统的交互。代码上，页面通过三角函数定位的雷达图自绘、显式动画的骰子工具、以及叙事性的冒险日志，把跑团战报干净地映射成了硬核专业的界面，整份 Dart 代码无需修改即可在鸿蒙运行，充分印证了高复用率优势。

这次实践展现了两个重要能力：用 CustomPaint 加三角函数自绘复杂数据可视化图表（如六维雷达图），不依赖第三方库也能实现专业图表且跨端逐像素一致；显式动画 AnimationController 适合需要精细控制动画过程的场景（如掷骰滚动），但必须在 dispose 释放控制器避免内存泄漏——这与隐式动画 AnimatedContainer 形成适用区分。跑团战报的雷达图、骰子、日志零成本跨端。这提示我们，需要专业图表的应用可放心用 CustomPaint 自绘，需要精细动画控制时用显式动画并规范释放资源。因此，对准备进入鸿蒙生态的 Flutter 团队，对这类应用完全可以放心地用 CustomPaint 自绘各类图表、按需选择隐式/显式动画并规范管理动画控制器生命周期，信赖其跨端一致，并始终以 HarmonyOS 跨平台 SIG 维护的定制版 Flutter SDK 作为一切工作的起点。唯有如此，才能既享受一次开发、多端部署的红利，又充分发挥 Flutter 自绘图表与动画的能力，让跑团战报这样硬核的游戏工具真正专业、生动地陪伴每一位 TRPG 玩家的冒险。