Flutter for OpenHarmony 实战：指纹解锁动画：使用 CustomPaint模拟指纹扫描。

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

奇奇怪怪不能退

557人浏览 · 2026-02-08 21:28:26

奇奇怪怪不能退 · 2026-02-08 21:28:26 发布

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

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

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

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

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

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

混合工程结构深度解析

项目目录架构

当前项目的实际结构如下：

fluuter_openHarmony2/
├── lib/                          # Flutter业务代码
│   ├── main.dart                 # 应用入口
│   └── components/
│       └── fingerprint_unlock_component.dart  # 指纹解锁动画组件
├── pubspec.yaml                  # Flutter依赖配置
└── 模版.md                        # 项目文档

展示效果图片

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

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

功能代码实现

指纹解锁动画组件开发

组件设计思路

指纹解锁动画组件是当前项目的核心功能，使用 CustomPaint 模拟指纹扫描效果，设计时重点考虑了以下因素：

视觉效果：通过 CustomPaint 绘制指纹图案、扫描线和波纹效果，模拟真实的指纹解锁过程
交互体验：点击时触发指纹扫描动画，显示扫描过程，增强用户参与感
状态反馈：提供解锁成功和失败的视觉反馈，包括颜色变化和图标显示
可定制性：支持自定义标题、副标题、颜色、大小、动画 duration 等参数
响应式设计：适应不同屏幕尺寸，确保在各种设备上都能良好显示

组件实现代码

import 'package:flutter/material.dart';

class FingerprintUnlockComponent extends StatefulWidget {
  final String title;
  final String subtitle;
  final Color backgroundColor;
  final Color fingerprintColor;
  final Color scanColor;
  final double size;
  final int animationDuration;
  final VoidCallback? onUnlock;
  final VoidCallback? onFailed;

  const FingerprintUnlockComponent({
    Key? key,
    this.title = '指纹解锁',
    this.subtitle = '点击指纹区域解锁',
    this.backgroundColor = Colors.white,
    this.fingerprintColor = Colors.blue,
    this.scanColor = Colors.green,
    this.size = 200.0,
    this.animationDuration = 2000,
    this.onUnlock,
    this.onFailed,
  }) : super(key: key);

  @override
  State<FingerprintUnlockComponent> createState() => _FingerprintUnlockComponentState();
}

class _FingerprintUnlockComponentState extends State<FingerprintUnlockComponent> with SingleTickerProviderStateMixin {
  late AnimationController _controller;
  late Animation<double> _animation;
  bool _isScanning = false;
  bool _isUnlocked = false;
  bool _isFailed = false;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      duration: Duration(milliseconds: widget.animationDuration),
      vsync: this,
    );

    _animation = Tween<double>(begin: 0, end: 1).animate(
      CurvedAnimation(parent: _controller, curve: Curves.easeInOut),
    );

    _controller.addStatusListener((status) {
      if (status == AnimationStatus.completed) {
        setState(() {
          _isScanning = false;
          // 模拟解锁结果，80%概率成功
          if (DateTime.now().millisecond % 10 < 8) {
            _isUnlocked = true;
            if (widget.onUnlock != null) {
              widget.onUnlock!();
            }
          } else {
            _isFailed = true;
            if (widget.onFailed != null) {
              widget.onFailed!();
            }
            // 2秒后重置失败状态
            Future.delayed(const Duration(seconds: 2), () {
              setState(() {
                _isFailed = false;
              });
            });
          }
        });
      }
    });
  }

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

  void startScanning() {
    if (!_isScanning && !_isUnlocked) {
      setState(() {
        _isScanning = true;
        _isFailed = false;
      });
      _controller.reset();
      _controller.forward();
    }
  }

  void resetUnlock() {
    setState(() {
      _isUnlocked = false;
      _isFailed = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: () {
        if (!_isScanning) {
          if (_isUnlocked) {
            resetUnlock();
          } else {
            startScanning();
          }
        }
      },
      child: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(
              widget.title,
              style: TextStyle(
                fontSize: 18,
                fontWeight: FontWeight.bold,
                color: widget.fingerprintColor,
              ),
            ),
            const SizedBox(height: 8),
            Text(
              _isUnlocked ? '解锁成功' : _isFailed ? '解锁失败' : widget.subtitle,
              style: TextStyle(
                fontSize: 14,
                color: _isUnlocked ? Colors.green : _isFailed ? Colors.red : Colors.grey,
              ),
            ),
            const SizedBox(height: 24),
            SizedBox(
              width: widget.size,
              height: widget.size,
              child: AnimatedBuilder(
                animation: _animation,
                builder: (context, child) {
                  return CustomPaint(
                    painter: FingerprintPainter(
                      isScanning: _isScanning,
                      isUnlocked: _isUnlocked,
                      isFailed: _isFailed,
                      progress: _animation.value,
                      fingerprintColor: widget.fingerprintColor,
                      scanColor: widget.scanColor,
                    ),
                  );
                },
              ),
            ),
            if (_isUnlocked)
              Padding(
                padding: const EdgeInsets.only(top: 16),
                child: TextButton(
                  onPressed: resetUnlock,
                  child: const Text('重新解锁'),
                ),
              ),
          ],
        ),
      ),
    );
  }
}

class FingerprintPainter extends CustomPainter {
  final bool isScanning;
  final bool isUnlocked;
  final bool isFailed;
  final double progress;
  final Color fingerprintColor;
  final Color scanColor;

  FingerprintPainter({
    required this.isScanning,
    required this.isUnlocked,
    required this.isFailed,
    required this.progress,
    required this.fingerprintColor,
    required this.scanColor,
  });

  @override
  void paint(Canvas canvas, Size size) {
    final center = Offset(size.width / 2, size.height / 2);
    final radius = size.width / 2;

    // 绘制指纹外圈
    final outerCirclePaint = Paint()
      ..color = isUnlocked ? scanColor : isFailed ? Colors.red : fingerprintColor
      ..style = PaintingStyle.stroke
      ..strokeWidth = 4
      ..strokeCap = StrokeCap.round;

    canvas.drawCircle(center, radius - 10, outerCirclePaint);

    // 绘制指纹图案
    final fingerprintPaint = Paint()
      ..color = isUnlocked ? scanColor : isFailed ? Colors.red : fingerprintColor
      ..style = PaintingStyle.stroke
      ..strokeWidth = 2
      ..strokeCap = StrokeCap.round;

    // 绘制指纹曲线
    final path = Path();
    path.moveTo(center.dx, center.dy - radius * 0.6);
    
    // 绘制指纹的波浪线
    for (double angle = 0; angle < 3.14159 * 2; angle += 0.1) {
      final r = radius * 0.6 * (1 + 0.2 * (1 - (angle / (3.14159 * 2))));
      final x = center.dx + r * 0.8 * (angle < 3.14159 ? 1 : -1);
      final y = center.dy + r * 0.6 * (angle < 3.14159 ? 1 : -1);
      path.lineTo(x, y);
    }
    
    path.close();
    canvas.drawPath(path, fingerprintPaint);

    // 绘制扫描线
    if (isScanning) {
      final scanLinePaint = Paint()
        ..color = scanColor
        ..style = PaintingStyle.stroke
        ..strokeWidth = 3
        ..strokeCap = StrokeCap.round
        ..shader = LinearGradient(
          colors: [scanColor.withOpacity(0), scanColor, scanColor.withOpacity(0)],
        ).createShader(Rect.fromLTWH(0, 0, size.width, size.height));

      final scanY = center.dy - radius * 0.8 + progress * radius * 1.6;
      canvas.drawLine(
        Offset(center.dx - radius * 0.8, scanY),
        Offset(center.dx + radius * 0.8, scanY),
        scanLinePaint,
      );

      // 绘制扫描波纹
      final ripplePaint = Paint()
        ..color = scanColor.withOpacity(0.3 * (1 - progress))
        ..style = PaintingStyle.stroke
        ..strokeWidth = 2;

      canvas.drawCircle(center, radius * 0.8 * progress, ripplePaint);
    }

    // 绘制解锁成功或失败图标
    if (isUnlocked) {
      final checkPaint = Paint()
        ..color = scanColor
        ..style = PaintingStyle.stroke
        ..strokeWidth = 4
        ..strokeCap = StrokeCap.round
        ..strokeJoin = StrokeJoin.round;

      final checkPath = Path();
      checkPath.moveTo(center.dx - radius * 0.3, center.dy);
      checkPath.lineTo(center.dx - radius * 0.1, center.dy + radius * 0.2);
      checkPath.lineTo(center.dx + radius * 0.3, center.dy - radius * 0.2);
      canvas.drawPath(checkPath, checkPaint);
    } else if (isFailed) {
      final crossPaint = Paint()
        ..color = Colors.red
        ..style = PaintingStyle.stroke
        ..strokeWidth = 4
        ..strokeCap = StrokeCap.round
        ..strokeJoin = StrokeJoin.round;

      canvas.drawLine(
        Offset(center.dx - radius * 0.3, center.dy - radius * 0.3),
        Offset(center.dx + radius * 0.3, center.dy + radius * 0.3),
        crossPaint,
      );
      canvas.drawLine(
        Offset(center.dx + radius * 0.3, center.dy - radius * 0.3),
        Offset(center.dx - radius * 0.3, center.dy + radius * 0.3),
        crossPaint,
      );
    }
  }

  @override
  bool shouldRepaint(covariant FingerprintPainter oldDelegate) {
    return oldDelegate.isScanning != isScanning ||
           oldDelegate.isUnlocked != isUnlocked ||
           oldDelegate.isFailed != isFailed ||
           oldDelegate.progress != progress ||
           oldDelegate.fingerprintColor != fingerprintColor ||
           oldDelegate.scanColor != scanColor;
  }
}

首页集成实现

import 'package:flutter/material.dart';
import 'components/fingerprint_unlock_component.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),
      ),
      body: SingleChildScrollView(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: <Widget>[
            const Text(
              'Flutter for OpenHarmony 实战：指纹解锁动画',
              style: TextStyle(fontSize: 20, fontWeight: FontWeight.bold),
              textAlign: TextAlign.center,
            ),
            const SizedBox(height: 40),
            
            // 指纹解锁组件
            FingerprintUnlockComponent(
              title: '指纹解锁',
              subtitle: '点击指纹区域解锁',
              fingerprintColor: Colors.blue,
              scanColor: Colors.green,
              size: 200.0,
              animationDuration: 2000,
              onUnlock: () {
                print('指纹解锁成功');
                // 这里可以添加解锁后的逻辑
              },
              onFailed: () {
                print('指纹解锁失败');
                // 这里可以添加解锁失败的逻辑
              },
            ),
            
            const SizedBox(height: 40),
            
            // 不同样式的指纹解锁组件示例
            const Text(
              '不同样式的指纹解锁效果',
              style: TextStyle(fontSize: 16, fontWeight: FontWeight.bold),
              textAlign: TextAlign.center,
            ),
            const SizedBox(height: 20),
            
            Row(
              mainAxisAlignment: MainAxisAlignment.spaceAround,
              children: [
                FingerprintUnlockComponent(
                  title: '绿色主题',
                  subtitle: '点击解锁',
                  fingerprintColor: Colors.green,
                  scanColor: Colors.blue,
                  size: 150.0,
                  animationDuration: 1500,
                ),
                FingerprintUnlockComponent(
                  title: '紫色主题',
                  subtitle: '点击解锁',
                  fingerprintColor: Colors.purple,
                  scanColor: Colors.orange,
                  size: 150.0,
                  animationDuration: 1500,
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
}

组件关键特性

指纹扫描动画：使用 CustomPaint 绘制指纹图案和扫描线，模拟真实的指纹扫描过程
扫描波纹效果：添加扫描波纹动画，增强扫描过程的视觉效果
状态反馈：提供解锁成功（绿色对勾）和失败（红色叉号）的视觉反馈
高度可定制：支持自定义标题、副标题、颜色、大小、动画 duration 等参数
交互体验：点击时触发扫描动画，解锁成功后显示"重新解锁"按钮
响应式设计：使用 SingleChildScrollView 确保在小屏幕上也能完整显示

使用方法

集成组件：在需要使用指纹解锁效果的页面中导入 FingerprintUnlockComponent 组件
配置参数：根据具体需求设置 title、subtitle、fingerprintColor、scanColor、size、animationDuration 等参数
查看效果：应用启动后，指纹解锁组件会正常显示在页面上
交互操作：
- 点击组件会触发指纹扫描动画
- 扫描完成后会显示解锁成功或失败的状态
- 解锁成功后点击"重新解锁"按钮可以重置状态
- 解锁失败后2秒会自动重置状态