Flutter 动画与自定义绘制

目录

• 1. What — Flutter 动画与自定义绘制是什么
• 2. Why — 为什么需要动画与自定义绘制
• 3. How — 如何实现 Flutter 动画与自定义绘制
  • 3.1 Flutter 动画体系概览
  • 3.2 隐式动画 Widget
  • 3.3 AnimatedBuilder 与 AnimatedWidget
  • 3.4 显式动画核心
  • 3.5 常用 Curves 曲线
  • 3.6 Hero 动画
  • 3.7 交错动画
  • 3.8 CustomPainter 自定义绘制
  • 3.9 自定义绘制实战
  • 3.10 Lottie 动画集成
  • 3.11 Rive 动画集成
  • 3.12 物理动画
  • 3.13 动画性能优化
  • 3.14 手势与动画联动
  • 3.15 页面切换动画自定义
• 4. 面试题精选
• 5. 总结

1. What — Flutter 动画与自定义绘制是什么

Flutter 动画体系 是 Flutter 框架中用于创建流畅、高性能视觉过渡与运动效果的一整套机制。它从底层的 Animation 对象到顶层的动画 Widget，提供了多层次的抽象：

┌─────────────────────────────────────────────────────────────────┐
│                    Flutter 动画体系全景                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │  隐式动画     │  │  显式动画     │  │  Hero/共享元素动画    │  │
│  │  Implicit     │  │  Explicit    │  │  Shared Element      │  │
│  │              │  │              │  │                      │  │
│  │ AnimatedXxx  │  │ Animation    │  │ Hero                 │  │
│  │ TweenAnima.. │  │ Controller   │  │ HeroController       │  │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬───────────┘  │
│         │                 │                      │              │
│         └─────────┬───────┴──────────────────────┘              │
│                   ▼                                             │
│         ┌─────────────────────┐                                 │
│         │   Animation<T>      │  ← 核心抽象                     │
│         │   (值 + 状态 + 方向) │                                 │
│         └─────────┬───────────┘                                 │
│                   ▼                                             │
│         ┌─────────────────────┐                                 │
│         │   Ticker            │  ← 帧回调调度                    │
│         │   (vsync 驱动)      │                                 │
│         └─────────────────────┘                                 │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              CustomPainter 自定义绘制                      │   │
│  │  Canvas API + Paint + Path → 任意 2D 图形绘制             │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │  Lottie     │  │  Rive        │  │  物理动画             │   │
│  │  (JSON动画) │  │  (交互动画)  │  │  (Spring/Damping)    │   │
│  └─────────────┘  └──────────────┘  └──────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

自定义绘制（CustomPainter） 是 Flutter 提供的底层 Canvas 绘图能力，通过 CustomPaint + CustomPainter 可以直接操作 Canvas API 绘制任意 2D 图形，突破内置 Widget 的局限。

三大动画类型对比

2. Why — 为什么需要动画与自定义绘制

2.1 动画的核心价值

1. 用户体验提升：动画让界面状态变化可感知、可预测，减少用户认知负担
2. 视觉引导：通过运动方向、速度、缓动曲线引导用户注意力
3. 品牌表达：独特的动画风格是品牌辨识度的重要组成部分
4. 状态反馈：微交互（按压反馈、加载动画）让用户对操作结果有即时感知

2.2 自定义绘制的必要性

1. 突破内置 Widget 限制：进度环、图表、签名板等场景没有对应内置 Widget
2. 极致性能：直接操作 Canvas 避免了 Widget 树的重建开销
3. 精确控制：逐像素控制绘制结果，实现设计师的高保真还原
4. 跨平台一致性：Canvas 绘制不受平台原生控件差异影响

2.3 动画不规范的代价

3. How — 如何实现 Flutter 动画与自定义绘制

3.1 Flutter 动画体系概览

Flutter 动画的核心概念链路：

Ticker → AnimationController → CurvedAnimation → Tween → Widget
  │            │                     │              │          │
  │            │                     │              │          │
  帧回调      0→1 值驱动           曲线映射       值域映射    视觉呈现
  (每帧触发)  (duration控制)       (easeIn等)    (0→1→颜色)  (build)

核心类关系

┌──────────────────────────────────────────────────┐
│              Animation<T> (抽象)                  │
│  ┌ value: T          ← 当前动画值                │
│  ├ status: AnimationStatus ← 当前状态            │
│  └ isCompleted / isDismissed                     │
├──────────────────────────────────────────────────┤
│         ▲           ▲           ▲                │
│         │           │           │                │
│  AnimationController  CurvedAnimation  TweenAnimation│
│  (驱动源)           (曲线包装)      (值域包装)   │
└──────────────────────────────────────────────────┘

AnimationStatus 枚举

enum AnimationStatus {
  dismissed,  // 动画在起点静止（反向播放到头）
  forward,    // 动画正向播放中
  reverse,    // 动画反向播放中
  completed,  // 动画在终点静止（正向播放到头）
}

动画选择决策树

需要动画？
├─ 只是属性值变化过渡？
│  ├─ 是 → 用隐式动画 AnimatedXxx
│  └─ 否 → 需要精确控制？
│     ├─ 否 → 用隐式动画
│     └─ 是 → 需要暂停/反向/交错？
│        ├─ 是 → 显式动画 AnimationController
│        └─ 否 → AnimatedBuilder 封装
├─ 页面间共享元素？
│  └─ 是 → Hero 动画
└─ 需要绘制自定义图形？
   └─ 是 → CustomPainter + Animation

3.2 隐式动画 Widget

隐式动画是 Flutter 中最易用的动画方案。只需修改目标属性值，框架自动在旧值与新值之间创建平滑过渡。

核心原理

隐式动画 Widget 内部管理 AnimationController，在属性变化时自动触发过渡动画。它们都继承自 ImplicitlyAnimatedWidget。

ImplicitlyAnimatedWidget
  ├── AnimatedContainer      ← 容器属性（颜色/边框/圆角/大小/阴影）
  ├── AnimatedOpacity         ← 透明度
  ├── AnimatedPadding         ← 内边距
  ├── AnimatedAlign           ← 对齐方式
  ├── AnimatedPositioned      ← Stack 中的位置
  ├── AnimatedDefaultTextStyle← 默认文字样式
  ├── AnimatedPhysicalModel   ← 物理模型（阴影/圆角）
  ├── AnimatedTheme           ← 主题
  ├── AnimatedCrossFade       ← 两个子 Widget 交叉淡入淡出
  ├── AnimatedSwitcher         ← 任意子 Widget 切换动画
  └── TweenAnimationBuilder   ← 自定义隐式动画（万能）

3.2.1 AnimatedContainer — 万能容器动画

class AnimatedContainerDemo extends StatefulWidget {
  @override
  _AnimatedContainerDemoState createState() => _AnimatedContainerDemoState();
}

class _AnimatedContainerDemoState extends State<AnimatedContainerDemo> {
  bool _expanded = false;
  bool _darkMode = false;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: GestureDetector(
          onTap: () {
            setState(() {
              _expanded = !_expanded;
              _darkMode = !_darkMode;
            });
          },
          child: AnimatedContainer(
            duration: const Duration(milliseconds: 500),   // 动画时长
            curve: Curves.easeInOutCubic,                  // 缓动曲线
            // ---- 以下属性变化时会自动动画 ----
            width: _expanded ? 280 : 120,
            height: _expanded ? 280 : 120,
            alignment: Alignment.center,
            decoration: BoxDecoration(
              color: _darkMode ? const Color(0xFF1A1A2E) : const Color(0xFFE8E8E8),
              borderRadius: BorderRadius.circular(_expanded ? 40 : 12),
              boxShadow: [
                BoxShadow(
                  color: Colors.black.withOpacity(_darkMode ? 0.4 : 0.1),
                  blurRadius: _expanded ? 24 : 8,
                  offset: Offset(0, _expanded ? 12 : 4),
                ),
              ],
              border: Border.all(
                color: _darkMode ? Colors.purpleAccent : Colors.grey.shade400,
                width: _expanded ? 3 : 1,
              ),
            ),
            // ---- 动画属性结束 ----
            child: Text(
              _expanded ? 'Expanded' : 'Tap',
              style: TextStyle(
                color: _darkMode ? Colors.white : Colors.black87,
                fontSize: _expanded ? 24 : 16,
                fontWeight: FontWeight.bold,
              ),
            ),
          ),
        ),
      ),
    );
  }
}

关键点：AnimatedContainer 对 decoration、color、width、height、padding、margin、alignment、transform、constraints 等属性都会自动做动画，只要新旧值之间可以插值（即实现了 Tween）。

3.2.2 AnimatedOpacity — 透明度动画

class FadeInOutDemo extends StatefulWidget {
  @override
  _FadeInOutDemoState createState() => _FadeInOutDemoState();
}

class _FadeInOutDemoState extends State<FadeInOutDemo> {
  bool _visible = true;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('AnimatedOpacity')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            AnimatedOpacity(
              opacity: _visible ? 1.0 : 0.0,      // 目标透明度
              duration: const Duration(milliseconds: 600),
              curve: Curves.easeOut,
              // 注意：即使 opacity=0，Widget 仍然占据空间且可点击
              // 需要配合 IgnorePointer 或 Offstage 使用
              child: IgnorePointer(
                ignoring: !_visible,  // 不可见时忽略点击
                child: Container(
                  width: 200,
                  height: 200,
                  decoration: BoxDecoration(
                    gradient: LinearGradient(
                      colors: [Colors.purple, Colors.blue],
                    ),
                    borderRadius: BorderRadius.circular(20),
                  ),
                  child: const Center(
                    child: Text('Fade Me', style: TextStyle(
                      color: Colors.white, fontSize: 24,
                    )),
                  ),
                ),
              ),
            ),
            const SizedBox(height: 40),
            ElevatedButton(
              onPressed: () => setState(() => _visible = !_visible),
              child: Text(_visible ? '隐藏' : '显示'),
            ),
          ],
        ),
      ),
    );
  }
}

3.2.3 AnimatedPadding — 内边距动画

class AnimatedPaddingDemo extends StatefulWidget {
  @override
  _AnimatedPaddingDemoState createState() => _AnimatedPaddingDemoState();
}

class _AnimatedPaddingDemoState extends State<AnimatedPaddingDemo> {
  double _padding = 8.0;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: AnimatedPadding(
          padding: EdgeInsets.all(_padding),
          duration: const Duration(milliseconds: 400),
          curve: Curves.easeOutBack,  // 回弹效果
          child: Container(
            width: 200,
            height: 200,
            color: Colors.teal,
            child: const Center(child: Text('Content')),
          ),
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () {
          setState(() {
            _padding = _padding < 40 ? _padding + 16 : 8;
          });
        },
        child: const Icon(Icons.padding),
      ),
    );
  }
}

3.2.4 AnimatedAlign — 对齐方式动画

class AnimatedAlignDemo extends StatefulWidget {
  @override
  _AnimatedAlignDemoState createState() => _AnimatedAlignDemoState();
}

class _AnimatedAlignDemoState extends State<AnimatedAlignDemo> {
  Alignment _alignment = Alignment.topLeft;

  // 对齐位置列表，点击循环切换
  static const alignments = [
    Alignment.topLeft,
    Alignment.topCenter,
    Alignment.topRight,
    Alignment.centerRight,
    Alignment.bottomRight,
    Alignment.bottomCenter,
    Alignment.bottomLeft,
    Alignment.centerLeft,
    Alignment.center,
  ];
  int _index = 0;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Container(
          width: 300,
          height: 300,
          color: Colors.grey.shade200,
          child: AnimatedAlign(
            alignment: _alignment,
            duration: const Duration(milliseconds: 500),
            curve: Curves.elasticOut,   // 弹性效果
            child: Container(
              width: 60,
              height: 60,
              decoration: const BoxDecoration(
                color: Colors.deepOrange,
                shape: BoxShape.circle,
              ),
            ),
          ),
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () {
          setState(() {
            _index = (_index + 1) % alignments.length;
            _alignment = alignments[_index];
          });
        },
        child: const Icon(Icons.align_horizontal_center),
      ),
    );
  }
}

3.2.5 AnimatedCrossFade — 交叉淡入淡出

class CrossFadeDemo extends StatefulWidget {
  @override
  _CrossFadeDemoState createState() => _CrossFadeDemoState();
}

class _CrossFadeDemoState extends State<CrossFadeDemo> {
  bool _showFirst = true;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            AnimatedCrossFade(
              firstChild: Container(
                width: 200,
                height: 200,
                decoration: BoxDecoration(
                  color: Colors.blue,
                  borderRadius: BorderRadius.circular(20),
                ),
                child: const Center(
                  child: Icon(Icons.wb_sunny, size: 60, color: Colors.white),
                ),
              ),
              secondChild: Container(
                width: 200,
                height: 200,
                decoration: BoxDecoration(
                  color: Colors.indigo,
                  borderRadius: BorderRadius.circular(100), // 变成圆形
                ),
                child: const Center(
                  child: Icon(Icons.nightlight, size: 60, color: Colors.white),
                ),
              ),
              crossFadeState: _showFirst
                  ? CrossFadeState.showFirst
                  : CrossFadeState.showSecond,
              duration: const Duration(milliseconds: 600),
              firstCurve: Curves.easeOut,
              secondCurve: Curves.easeIn,
              sizeCurve: Curves.easeInOut,  // 尺寸变化曲线
            ),
            const SizedBox(height: 32),
            ElevatedButton(
              onPressed: () => setState(() => _showFirst = !_showFirst),
              child: Text(_showFirst ? '切换到夜晚' : '切换到白天'),
            ),
          ],
        ),
      ),
    );
  }
}

注意：AnimatedCrossFade 在两个子 Widget 尺寸不同时会自动做尺寸过渡动画，通过 sizeCurve 控制过渡曲线。但如果两个子 Widget 布局差异很大，可能出现布局跳变，需注意对齐方式。

3.2.6 AnimatedSwitcher — 通用 Widget 切换动画

class AnimatedSwitcherDemo extends StatefulWidget {
  @override
  _AnimatedSwitcherDemoState createState() => _AnimatedSwitcherDemoState();
}

class _AnimatedSwitcherDemoState extends State<AnimatedSwitcherDemo> {
  int _count = 0;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            // AnimatedSwitcher 核心：根据 key 判断子 Widget 是否变化
            AnimatedSwitcher(
              duration: const Duration(milliseconds: 400),
              // 切换进入的过渡动画
              transitionBuilder: (Widget child, Animation<double> animation) {
                // 淡入 + 缩放
                return FadeTransition(
                  opacity: animation,
                  child: ScaleTransition(
                    scale: animation,
                    child: child,
                  ),
                );
              },
              // 关键：必须为子 Widget 设置不同的 Key
              // 否则 AnimatedSwitcher 无法区分新旧 Widget
              child: Text(
                '$_count',
                key: ValueKey<int>(_count),  // ← 必须设置 Key！
                style: const TextStyle(
                  fontSize: 72,
                  fontWeight: FontWeight.bold,
                ),
              ),
            ),
            const SizedBox(height: 40),
            Row(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                ElevatedButton(
                  onPressed: () => setState(() => _count--),
                  child: const Icon(Icons.remove),
                ),
                const SizedBox(width: 20),
                ElevatedButton(
                  onPressed: () => setState(() => _count++),
                  child: const Icon(Icons.add),
                ),
              ],
            ),
          ],
        ),
      ),
    );
  }
}

3.2.7 AnimatedPositioned — Stack 内位置动画

class AnimatedPositionedDemo extends StatefulWidget {
  @override
  _AnimatedPositionedDemoState createState() => _AnimatedPositionedDemoState();
}

class _AnimatedPositionedDemoState extends State<AnimatedPositionedDemo> {
  bool _moved = false;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        // AnimatedPositioned 必须作为 Stack 的直接子 Widget
        child: Stack(
          children: [
            // 轨道背景
            Container(
              width: 300,
              height: 300,
              decoration: BoxDecoration(
                border: Border.all(color: Colors.grey),
                borderRadius: BorderRadius.circular(16),
              ),
            ),
            AnimatedPositioned(
              left: _moved ? 220 : 20,
              top: _moved ? 220 : 20,
              duration: const Duration(milliseconds: 600),
              curve: Curves.bounceOut,
              child: GestureDetector(
                onTap: () => setState(() => _moved = !_moved),
                child: Container(
                  width: 60,
                  height: 60,
                  decoration: const BoxDecoration(
                    color: Colors.orange,
                    shape: BoxShape.circle,
                  ),
                  child: const Icon(Icons.arrow_forward, color: Colors.white),
                ),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

3.2.8 TweenAnimationBuilder — 万能隐式动画

当内置隐式动画 Widget 无法满足时，TweenAnimationBuilder 允许对任意可插值类型做动画：

class TweenAnimationBuilderDemo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: TweenAnimationBuilder<double>(
          tween: Tween<double>(begin: 0, end: 1),  // 值域：0 → 1
          duration: const Duration(seconds: 2),
          curve: Curves.elasticOut,
          builder: (context, value, child) {
            // value 在 0~1 之间变化，用它来驱动任意属性
            return Transform.scale(
              scale: 0.5 + value * 0.5,  // 缩放：0.5 → 1.0
              child: Opacity(
                opacity: value,            // 透明度：0 → 1
                child: Transform.rotate(
                  angle: value * 0.5,      // 旋转：0 → 0.5 rad
                  child: Container(
                    width: 150,
                    height: 150,
                    decoration: BoxDecoration(
                      gradient: LinearGradient(
                        colors: [
                          Color.lerp(Colors.blue, Colors.purple, value)!,
                          Color.lerp(Colors.purple, Colors.pink, value)!,
                        ],
                      ),
                      borderRadius: BorderRadius.circular(value * 30),
                    ),
                    child: const Center(
                      child: Text('Custom Tween', style: TextStyle(
                        color: Colors.white, fontSize: 18,
                      )),
                    ),
                  ),
                ),
              ),
            );
          },
        ),
      ),
    );
  }
}

隐式动画完整对比表

3.3 AnimatedBuilder 与 AnimatedWidget

这两个是显式动画与 Widget 之间的桥梁。它们监听 Animation 对象的变化并重建 UI。

AnimatedWidget — 继承式封装

/// 自定义旋转过渡 Widget，基于 AnimatedWidget
class SpinTransition extends AnimatedWidget {
  const SpinTransition({
    Key? key,
    required Animation<double> animation,
    this.child,
  }) : super(key: key, listenable: animation);  // 传入 Animation 作为 listenable

  @override
  Widget build(BuildContext context) {
    final animation = listenable as Animation<double>;
    return Transform.rotate(
      angle: animation.value * 2 * pi,  // 0 → 2π 旋转一圈
      child: child,
    );
  }
}

// 使用
class SpinDemo extends StatefulWidget {
  @override
  _SpinDemoState createState() => _SpinDemoState();
}

class _SpinDemoState extends State<SpinDemo> with SingleTickerProviderStateMixin {
  late AnimationController _controller;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      duration: const Duration(seconds: 2),
      vsync: this,
    );
  }

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: SpinTransition(
          animation: _controller,
          child: const FlutterLogo(size: 100),
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () {
          if (_controller.isAnimating) {
            _controller.stop();
          } else {
            _controller.repeat();  // 重复播放
          }
        },
        child: Icon(_controller.isAnimating ? Icons.pause : Icons.play_arrow),
      ),
    );
  }
}

AnimatedBuilder — 组合式封装（推荐）

class AnimatedBuilderDemo extends StatefulWidget {
  @override
  _AnimatedBuilderDemoState createState() => _AnimatedBuilderDemoState();
}

class _AnimatedBuilderDemoState extends State<AnimatedBuilderDemo>
    with SingleTickerProviderStateMixin {
  late AnimationController _controller;
  late Animation<double> _animation;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      duration: const Duration(seconds: 3),
      vsync: this,
    );

    // 曲线 + 值域组合
    _animation = CurvedAnimation(
      parent: _controller,
      curve: Curves.elasticOut,
    );

    _controller.forward();  // 启动动画
  }

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        // AnimatedBuilder：只在动画值变化时重建 builder 内的 Widget
        // child 参数不会重建，提升性能
        child: AnimatedBuilder(
          animation: _animation,
          child: const FlutterLogo(size: 80),  // ← 不变的部分放 child
          builder: (BuildContext context, Widget? child) {
            return Transform.scale(
              scale: _animation.value,         // 0 → 1
              child: Transform.rotate(
                angle: _animation.value * pi,  // 0 → π
                child: Opacity(
                  opacity: _animation.value,   // 0 → 1
                  child: child,                // ← 使用不变的部分
                ),
              ),
            );
          },
        ),
      ),
    );
  }
}

AnimatedWidget vs AnimatedBuilder 对比

3.4 显式动画核心

显式动画通过 AnimationController 手动控制动画的生命周期，提供暂停、反向、重复等精细控制。

3.4.1 AnimationController — 动画控制器

class ControllerBasicsDemo extends StatefulWidget {
  @override
  _ControllerBasicsDemoState createState() => _ControllerBasicsDemoState();
}

class _ControllerBasicsDemoState extends State<ControllerBasicsDemo>
    with SingleTickerProviderStateMixin {
  late AnimationController _controller;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      duration: const Duration(milliseconds: 1500),
      vsync: this,   // TickerProvider，提供帧回调
      // debugLabel: 'basic-controller',  // 调试标签
      // lowerBound: 0.0,   // 最小值，默认 0
      // upperBound: 1.0,   // 最大值，默认 1
    );

    // 监听动画值变化（每帧触发）
    _controller.addListener(() {
      // print('当前值: ${_controller.value}');
      setState(() {});  // 一般不用，AnimatedBuilder 自动重建
    });

    // 监听动画状态变化
    _controller.addStatusListener((status) {
      switch (status) {
        case AnimationStatus.forward:
          print('开始正向播放');
          break;
        case AnimationStatus.reverse:
          print('开始反向播放');
          break;
        case AnimationStatus.completed:
          print('动画播放完成');
          break;
        case AnimationStatus.dismissed:
          print('动画回到起点');
          break;
      }
    });
  }

  @override
  void dispose() {
    _controller.dispose();  // ← 必须释放！否则内存泄漏
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            // 用 AnimatedBuilder 驱动 UI
            AnimatedBuilder(
              animation: _controller,
              builder: (context, child) {
                return Container(
                  width: 50 + _controller.value * 200,  // 50 → 250
                  height: 50 + _controller.value * 200,
                  decoration: BoxDecoration(
                    color: Color.lerp(Colors.blue, Colors.red, _controller.value),
                    borderRadius: BorderRadius.circular(_controller.value * 125),
                  ),
                );
              },
            ),
            const SizedBox(height: 40),
            // 控制按钮
            Wrap(
              spacing: 8,
              children: [
                ElevatedButton(
                  onPressed: () => _controller.forward(),
                  child: const Text('Forward'),
                ),
                ElevatedButton(
                  onPressed: () => _controller.reverse(),
                  child: const Text('Reverse'),
                ),
                ElevatedButton(
                  onPressed: () => _controller.stop(),
                  child: const Text('Stop'),
                ),
                ElevatedButton(
                  onPressed: () {
                    _controller.repeat(reverse: true);  // 往返重复
                  },
                  child: const Text('Repeat'),
                ),
                ElevatedButton(
                  onPressed: () => _controller.reset(),
                  child: const Text('Reset'),
                ),
              ],
            ),
            const SizedBox(height: 20),
            // 进度条显示当前动画进度
            Padding(
              padding: const EdgeInsets.symmetric(horizontal: 32),
              child: LinearProgressIndicator(value: _controller.value),
            ),
          ],
        ),
      ),
    );
  }
}

AnimationController 常用方法

3.4.2 Tween — 值域映射

Tween 将 [0, 1] 的动画值映射到任意值域：

class TweenDemo extends StatefulWidget {
  @override
  _TweenDemoState createState() => _TweenDemoState();
}

class _TweenDemoState extends State<TweenDemo>
    with SingleTickerProviderStateMixin {
  late AnimationController _controller;
  late Animation<double> _sizeAnimation;
  late Animation<Color?> _colorAnimation;
  late Animation<EdgeInsets> _paddingAnimation;
  late Animation<Alignment> _alignAnimation;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      duration: const Duration(seconds: 2),
      vsync: this,
    );

    final curve = CurvedAnimation(parent: _controller, curve: Curves.easeInOut);

    // 各种 Tween 映射
    _sizeAnimation = Tween<double>(begin: 50, end: 200).animate(curve);
    _colorAnimation = ColorTween(begin: Colors.blue, end: Colors.red).animate(curve);
    _paddingAnimation = EdgeInsetsTween(
      begin: const EdgeInsets.all(8),
      end: const EdgeInsets.all(40),
    ).animate(curve);
    _alignAnimation = AlignmentTween(
      begin: Alignment.topLeft,
      end: Alignment.bottomRight,
    ).animate(curve);

    _controller.repeat(reverse: true);
  }

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: AnimatedBuilder(
        animation: _controller,
        builder: (context, child) {
          return Container(
            alignment: _alignAnimation.value,
            padding: _paddingAnimation.value,
            child: Container(
              width: _sizeAnimation.value,
              height: _sizeAnimation.value,
              decoration: BoxDecoration(
                color: _colorAnimation.value,
                borderRadius: BorderRadius.circular(_sizeAnimation.value / 4),
              ),
            ),
          );
        },
      ),
    );
  }
}

常用 Tween 类型

自定义 Tween

/// 自定义波浪数据 Tween
class WaveData {
  final double amplitude;  // 振幅
  final double frequency;  // 频率
  final double phase;      // 相位

  const WaveData(this.amplitude, this.frequency, this.phase);
}

class WaveDataTween extends Tween<WaveData> {
  WaveDataTween({WaveData? begin, WaveData? end})
      : super(begin: begin, end: end);

  @override
  WaveData lerp(double t) {
    // 自定义插值逻辑
    return WaveData(
      lerpDouble(begin!.amplitude, end!.amplitude, t)!,
      lerpDouble(begin!.frequency, end!.frequency, t)!,
      lerpDouble(begin!.phase, end!.phase, t)!,
    );
  }
}

3.4.3 CurvedAnimation — 曲线包装

// 基本用法
final curvedAnimation = CurvedAnimation(
  parent: _controller,
  curve: Curves.easeInOut,         // 正向曲线
  reverseCurve: Curves.easeIn,     // 反向曲线（可选，默认与 curve 相同）
);

// 组合曲线：先快后慢再快
final complexCurve = CurvedAnimation(
  parent: _controller,
  curve: const Interval(
    0.0, 0.5,          // 只在动画的 0~50% 区间生效
    curve: Curves.easeOut,
  ),
);

3.4.4 多动画控制器管理

当需要同时管理多个动画时，使用 TickerProviderStateMixin 替代 SingleTickerProviderStateMixin：

class MultiAnimationDemo extends StatefulWidget {
  @override
  _MultiAnimationDemoState createState() => _MultiAnimationDemoState();
}

class _MultiAnimationDemoState extends State<MultiAnimationDemo>
    with TickerProviderStateMixin {  // ← 支持多个 Ticker
  late AnimationController _scaleController;
  late AnimationController _rotateController;
  late AnimationController _colorController;

  @override
  void initState() {
    super.initState();

    _scaleController = AnimationController(
      duration: const Duration(milliseconds: 800),
      vsync: this,
    );

    _rotateController = AnimationController(
      duration: const Duration(seconds: 2),
      vsync: this,
    );

    _colorController = AnimationController(
      duration: const Duration(milliseconds: 1500),
      vsync: this,
    );

    // 按顺序启动：缩放 → 旋转 → 变色
    _scaleController.forward().then((_) {
      _rotateController.repeat();
      _colorController.repeat(reverse: true);
    });
  }

  @override
  void dispose() {
    _scaleController.dispose();
    _rotateController.dispose();
    _colorController.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: AnimatedBuilder(
          animation: Listenable.merge([
            _scaleController,
            _rotateController,
            _colorController,
          ]),
          builder: (context, child) {
            return Transform.scale(
              scale: _scaleController.value,
              child: Transform.rotate(
                angle: _rotateController.value * 2 * pi,
                child: Container(
                  width: 120,
                  height: 120,
                  decoration: BoxDecoration(
                    color: Color.lerp(
                      Colors.blue,
                      Colors.pink,
                      _colorController.value,
                    ),
                    borderRadius: BorderRadius.circular(20),
                  ),
                ),
              ),
            );
          },
        ),
      ),
    );
  }
}

3.5 常用 Curves 曲线

Curves 定义了动画值随时间的变化规律，决定了动画的”手感”。

Curves 曲线效果示意（时间 → 值）

linear:     ┌─────────     easeIn:     ┌──────
           /                         /
          /                         /
         /                    ┌────┘
        /               ┌────┘
  ─────┘          ┌────┘

easeOut:    ─────┐─┘      easeInOut:  ┌─────────
                /                   /
          ┌────┘              ┌────┘
     ┌────┘             ┌────┘
────┘             ─────┘

elasticOut: ──╮  ╭──     bounceOut:  ──╮ ╭─╮ ╭
               ╰╯                      ╰─╯ ╰─╯

完整 Curves 分类表

自定义 Curve

/// 自定义弹簧曲线
class SpringCurve extends Curve {
  final double damping;   // 阻尼系数
  final double frequency; // 频率

  const SpringCurve({
    this.damping = 10,
    this.frequency = 1.0,
  });

  @override
  double transformInternal(double t) {
    // 阻尼弹簧公式
    return -(pow(e, -damping * t) * cos(frequency * t)) + 1;
  }
}

// 使用
final animation = CurvedAnimation(
  parent: _controller,
  curve: const SpringCurve(damping: 8, frequency: 1.5),
);

Interval — 时间区间曲线

// Interval 用于交错动画，指定在动画的哪个时间段生效
// Interval(start, end, curve)
final firstItem = CurvedAnimation(
  parent: _controller,
  curve: const Interval(0.0, 0.3, curve: Curves.easeOut),   // 0%~30%
);
final secondItem = CurvedAnimation(
  parent: _controller,
  curve: const Interval(0.15, 0.45, curve: Curves.easeOut),  // 15%~45%
);
final thirdItem = CurvedAnimation(
  parent: _controller,
  curve: const Interval(0.3, 0.6, curve: Curves.easeOut),    // 30%~60%
);

3.6 Hero 动画

Hero 动画实现两个页面间的共享元素过渡效果，当页面切换时，共享元素会平滑地从源页面飞到目标页面。

Page A                          过渡中                         Page B
┌──────────────┐          ┌──────────────┐          ┌──────────────┐
│              │          │              │          │              │
│   ┌────┐    │          │              │          │    ┌──────┐  │
│   │Hero│    │  ─────>  │   Hero 飞行  │  ─────>  │    │ Hero │  │
│   │ 图片│   │          │   位移+缩放  │          │    │ 图片  │  │
│   └────┘    │          │              │          │    └──────┘  │
│              │          │              │          │              │
└──────────────┘          └──────────────┘          └──────────────┘
  小尺寸位置              过渡动画中间态              大尺寸位置

基本用法

// === 源页面 ===
class SourcePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('图片列表')),
      body: GridView.builder(
        padding: const EdgeInsets.all(8),
        gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
          crossAxisCount: 2,
          mainAxisSpacing: 8,
          crossAxisSpacing: 8,
        ),
        itemCount: 6,
        itemBuilder: (context, index) {
          return GestureDetector(
            onTap: () {
              Navigator.push(
                context,
                MaterialPageRoute(
                  builder: (_) => DetailPage(index: index),
                ),
              );
            },
            child: Hero(
              tag: 'image_$index',  // ← 唯一标识，两个页面必须一致
              child: ClipRRect(
                borderRadius: BorderRadius.circular(8),
                child: Image.asset(
                  'assets/image_$index.jpg',
                  fit: BoxFit.cover,
                ),
              ),
            ),
          );
        },
      ),
    );
  }
}

// === 目标页面 ===
class DetailPage extends StatelessWidget {
  final int index;

  const DetailPage({Key? key, required this.index}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('详情 ${index + 1}')),
      body: Center(
        child: Hero(
          tag: 'image_$index',  // ← 与源页面相同的 tag
          child: Image.asset(
            'assets/image_$index.jpg',
            fit: BoxFit.contain,
          ),
        ),
      ),
    );
  }
}

自定义 Hero 过渡动画

Hero(
  tag: 'custom_hero',
  // 自定义飞行动画构建器
  flightShuttleBuilder: (
    BuildContext flightContext,
    Animation<double> animation,
    HeroFlightDirection flightDirection,
    BuildContext fromHeroContext,
    BuildContext toHeroContext,
  ) {
    // flightDirection: push 或 pop 方向
    return AnimatedBuilder(
      animation: animation,
      builder: (context, child) {
        return Opacity(
          opacity: animation.value,
          child: Transform.scale(
            scale: 0.8 + animation.value * 0.2,
            child: child,
          ),
        );
      },
      child: flightDirection == HeroFlightDirection.push
          ? fromHeroContext.widget
          : toHeroContext.widget,
    );
  },
  child: const FlutterLogo(size: 100),
)

Hero 动画注意事项

1. tag 必须唯一：同一页面内不能有重复 tag
2. 过渡方向：push 和 pop 都会触发 Hero 动画
3. 性能：Hero 动画期间会创建覆盖层（Overlay），避免在 Hero Widget 上做复杂布局
4. 占位处理：可使用 placeholderBuilder 在过渡期间显示占位 Widget

Hero(
  tag: 'hero_placeholder',
  placeholderBuilder: (context, size, child) {
    // 过渡期间在原位显示占位符
    return Container(
      width: size.width,
      height: size.height,
      color: Colors.grey.shade300,
    );
  },
  child: Image.asset('assets/photo.jpg'),
)

3.7 交错动画

交错动画（Staggered Animation）让多个动画按时间顺序依次启动，产生编排效果。

时间轴 (0 ──────────────────────── 1)

缩放:  ████████░░░░░░░░░░░░░░░░░░░   0%~30%
旋转:  ░░░░████████░░░░░░░░░░░░░░░   15%~45%
颜色:  ░░░░░░░░████████░░░░░░░░░░░   30%~60%
位移:  ░░░░░░░░░░░░░░████████░░░░░   50%~80%
透明:  ░░░░░░░░░░░░░░░░░░░░██████   70%~100%

█ = 动画活跃区间   ░ = 空闲

交错动画实现

class StaggeredAnimationDemo extends StatefulWidget {
  @override
  _StaggeredAnimationDemoState createState() => _StaggeredAnimationDemoState();
}

class _StaggeredAnimationDemoState extends State<StaggeredAnimationDemo>
    with SingleTickerProviderStateMixin {
  late AnimationController _controller;

  // 定义各阶段的动画
  late Animation<double> _scale;
  late Animation<double> _rotation;
  late Animation<double> _opacity;
  late Animation<EdgeInsets> _padding;
  late Animation<Color?> _color;
  late Animation<double> _borderRadius;

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

    // 各动画的 Interval 定义了在总时间轴上的区间
    _scale = Tween<double>(begin: 0.0, end: 1.0).animate(
      CurvedAnimation(
        parent: _controller,
        curve: const Interval(0.0, 0.3, curve: Curves.easeOut),  // 0%~30%
      ),
    );

    _rotation = Tween<double>(begin: 0.0, end: 0.5).animate(
      CurvedAnimation(
        parent: _controller,
        curve: const Interval(0.15, 0.45, curve: Curves.easeOut),  // 15%~45%
      ),
    );

    _opacity = Tween<double>(begin: 0.0, end: 1.0).animate(
      CurvedAnimation(
        parent: _controller,
        curve: const Interval(0.25, 0.55, curve: Curves.easeIn),  // 25%~55%
      ),
    );

    _padding = EdgeInsetsTween(
      begin: const EdgeInsets.all(0),
      end: const EdgeInsets.all(40),
    ).animate(
      CurvedAnimation(
        parent: _controller,
        curve: const Interval(0.35, 0.65, curve: Curves.easeOut),  // 35%~65%
      ),
    );

    _color = ColorTween(begin: Colors.blue, end: Colors.orange).animate(
      CurvedAnimation(
        parent: _controller,
        curve: const Interval(0.5, 0.8, curve: Curves.easeInOut),  // 50%~80%
      ),
    );

    _borderRadius = Tween<double>(begin: 0, end: 40).animate(
      CurvedAnimation(
        parent: _controller,
        curve: const Interval(0.7, 1.0, curve: Curves.easeOut),  // 70%~100%
      ),
    );
  }

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            AnimatedBuilder(
              animation: _controller,
              builder: (context, child) {
                return Container(
                  padding: _padding.value,
                  child: Opacity(
                    opacity: _opacity.value,
                    child: Transform.scale(
                      scale: _scale.value,
                      child: Transform.rotate(
                        angle: _rotation.value * 2 * pi,
                        child: Container(
                          width: 150,
                          height: 150,
                          decoration: BoxDecoration(
                            color: _color.value,
                            borderRadius: BorderRadius.circular(
                              _borderRadius.value,
                            ),
                            boxShadow: [
                              BoxShadow(
                                color: Colors.black.withOpacity(0.3),
                                blurRadius: 20,
                                offset: const Offset(0, 10),
                              ),
                            ],
                          ),
                          child: const Center(
                            child: Text('Staggered', style: TextStyle(
                              color: Colors.white, fontSize: 20,
                            )),
                          ),
                        ),
                      ),
                    ),
                  ),
                );
              },
            ),
            const SizedBox(height: 40),
            ElevatedButton(
              onPressed: () {
                if (_controller.isCompleted) {
                  _controller.reverse();
                } else {
                  _controller.forward();
                }
              },
              child: const Text('播放交错动画'),
            ),
          ],
        ),
      ),
    );
  }
}

列表项交错入场动画

class StaggeredListDemo extends StatefulWidget {
  final int itemCount;
  const StaggeredListDemo({Key? key, this.itemCount = 8}) : super(key: key);

  @override
  _StaggeredListDemoState createState() => _StaggeredListDemoState();
}

class _StaggeredListDemoState extends State<StaggeredListDemo>
    with SingleTickerProviderStateMixin {
  late AnimationController _controller;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      duration: const Duration(milliseconds: 1500),
      vsync: this,
    );
    _controller.forward();
  }

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

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      padding: const EdgeInsets.all(16),
      itemCount: widget.itemCount,
      itemBuilder: (context, index) {
        // 每个列表项的延迟 = index / totalCount * 0.6
        // 总动画时间最多覆盖 60%，留 40% 给最后一项完成动画
        final startDelay = (index / widget.itemCount) * 0.6;
        final endDelay = startDelay + 0.4;

        return SlideTransition(
          position: Tween<Offset>(
            begin: const Offset(0, 0.5),  // 从下方偏移
            end: Offset.zero,
          ).animate(CurvedAnimation(
            parent: _controller,
            curve: Interval(startDelay, endDelay, curve: Curves.easeOut),
          )),
          child: FadeTransition(
            opacity: CurvedAnimation(
              parent: _controller,
              curve: Interval(startDelay, endDelay, curve: Curves.easeOut),
            ),
            child: _buildListItem(index),
          ),
        );
      },
    );
  }

  Widget _buildListItem(int index) {
    return Card(
      margin: const EdgeInsets.only(bottom: 12),
      child: ListTile(
        leading: CircleAvatar(
          backgroundColor: Colors.primaries[index % Colors.primaries.length],
          child: Text('${index + 1}'),
        ),
        title: Text('列表项 ${index + 1}'),
        subtitle: Text('这是第 ${index + 1} 个列表项的描述内容'),
        trailing: const Icon(Icons.chevron_right),
      ),
    );
  }
}

3.8 CustomPainter 自定义绘制

CustomPainter 是 Flutter 底层 2D 绘图接口，通过 Canvas API 直接绘制图形。

┌────────────────────────────────────────────┐
│            CustomPaint Widget              │
│  ┌──────────────────────────────────────┐  │
│  │         CustomPainter                │  │
│  │  ┌────────────────────────────────┐  │  │
│  │  │     paint(Canvas, Size)        │  │  │
│  │  │                                │  │  │
│  │  │  Canvas API:                   │  │  │
│  │  │  ├─ drawLine                   │  │  │
│  │  │  ├─ drawRect                   │  │  │
│  │  │  ├─ drawCircle                 │  │  │
│  │  │  ├─ drawArc                    │  │  │
│  │  │  ├─ drawPath                   │  │  │
│  │  │  ├─ drawParagraph (文字)        │  │  │
│  │  │  ├─ drawImage                  │  │  │
│  │  │  ├─ drawShadow                 │  │  │
│  │  │  └─ save/restore/translate/..  │  │  │
│  │  │                                │  │  │
│  │  │  Paint 配置:                   │  │  │
│  │  │  ├─ color / shader             │  │  │
│  │  │  ├─ strokeWidth               │  │  │
│  │  │  ├─ style (fill/stroke)        │  │  │
│  │  │  ├─ strokeCap / strokeJoin     │  │  │
│  │  │  ├─ filterQuality              │  │  │
│  │  │  └─ maskFilter / blendMode     │  │  │
│  │  └────────────────────────────────┘  │  │
│  │                                      │  │
│  │  shouldRepaint(oldDelegate) → bool   │  │
│  └──────────────────────────────────────┘  │
└────────────────────────────────────────────┘

CustomPainter 基本结构

class MyCustomPainter extends CustomPainter {
  // 绘制逻辑
  @override
  void paint(Canvas canvas, Size size) {
    // size 是 CustomPaint 指定的绘制区域大小
    final width = size.width;
    final height = size.height;
    final center = Offset(width / 2, height / 2);

    // 1. 创建 Paint 对象
    final paint = Paint()
      ..color = Colors.blue
      ..strokeWidth = 4
      ..style = PaintingStyle.stroke  // stroke 描边 / fill 填充
      ..strokeCap = StrokeCap.round   // 线帽样式
      ..isAntiAlias = true;           // 抗锯齿

    // 2. 使用 Canvas 绘制
    canvas.drawLine(
      Offset(0, 0),                   // 起点
      Offset(width, height),          // 终点
      paint,
    );

    // 3. 绘制圆形
    paint.style = PaintingStyle.fill;
    paint.color = Colors.red.withOpacity(0.5);
    canvas.drawCircle(center, 50, paint);

    // 4. 绘制矩形
    paint.color = Colors.green;
    paint.style = PaintingStyle.stroke;
    canvas.drawRect(
      Rect.fromCenter(center: center, width: 100, height: 80),
      paint,
    );

    // 5. 绘制圆角矩形
    canvas.drawRRect(
      RRect.fromRectAndRadius(
        Rect.fromLTWH(20, 20, width - 40, height - 40),
        const Radius.circular(16),
      ),
      paint..color = Colors.orange,
    );
  }

  // 是否需要重绘（性能关键）
  @override
  bool shouldRepaint(covariant MyCustomPainter oldDelegate) {
    // 返回 true → 重绘；返回 false → 跳过
    // 通常比较属性是否变化
    return true;  // 简单场景可直接 true
  }
}

// 使用
CustomPaint(
  size: const Size(300, 300),  // 指定绘制区域大小
  painter: MyCustomPainter(),
)

Canvas API 速查

Path 路径绘制

/// 绘制一个五角星
void drawStar(Canvas canvas, Offset center, double radius, Paint paint) {
  final path = Path();
  const points = 5;
  const innerRadiusRatio = 0.4;  // 内半径比例

  for (int i = 0; i < points * 2; i++) {
    final angle = (i * pi / points) - pi / 2;  // 起始角度在顶部
    final r = i.isEven ? radius : radius * innerRadiusRatio;
    final x = center.dx + r * cos(angle);
    final y = center.dy + r * sin(angle);

    if (i == 0) {
      path.moveTo(x, y);
    } else {
      path.lineTo(x, y);
    }
  }
  path.close();  // 闭合路径

  canvas.drawPath(path, paint);
}

/// 绘制贝塞尔曲线
void drawBezierCurves(Canvas canvas, Size size) {
  final paint = Paint()
    ..color = Colors.purple
    ..strokeWidth = 3
    ..style = PaintingStyle.stroke;

  // 二次贝塞尔曲线 (1 个控制点)
  final quadraticPath = Path();
  quadraticPath.moveTo(0, size.height / 2);
  quadraticPath.quadraticBezierTo(
    size.width / 2, 0,          // 控制点
    size.width, size.height / 2, // 终点
  );
  canvas.drawPath(quadraticPath, paint..color = Colors.blue);

  // 三次贝塞尔曲线 (2 个控制点)
  final cubicPath = Path();
  cubicPath.moveTo(0, size.height * 0.7);
  cubicPath.cubicTo(
    size.width * 0.25, size.height * 0.3,  // 控制点1
    size.width * 0.75, size.height * 0.9,   // 控制点2
    size.width, size.height * 0.5,           // 终点
  );
  canvas.drawPath(cubicPath, paint..color = Colors.red);
}

Paint 高级配置

// 渐变填充
final gradientPaint = Paint()
  ..shader = LinearGradient(
    begin: Alignment.topLeft,
    end: Alignment.bottomRight,
    colors: [Colors.blue, Colors.purple, Colors.pink],
    stops: const [0.0, 0.5, 1.0],
  ).createShader(Rect.fromLTWH(0, 0, size.width, size.height));

// 径向渐变
final radialPaint = Paint()
  ..shader = RadialGradient(
    center: Alignment.center,
    radius: 0.5,
    colors: [Colors.yellow, Colors.orange, Colors.red],
  ).createShader(Rect.fromLTWH(0, 0, size.width, size.height));

// 扫描渐变（饼图常用）
final sweepPaint = Paint()
  ..shader = SweepGradient(
    center: Alignment.center,
    colors: [Colors.red, Colors.yellow, Colors.green, Colors.blue, Colors.red],
  ).createShader(Rect.fromLTWH(0, 0, size.width, size.height));

// 模糊滤镜
final blurPaint = Paint()
  ..color = Colors.blue.withOpacity(0.5)
  ..maskFilter = const MaskFilter.blur(BlurStyle.normal, 10);

// 混合模式
final blendPaint = Paint()
  ..color = Colors.red
  ..blendMode = BlendMode.multiply;

3.9 自定义绘制实战

3.9.1 圆形进度环

class CircularProgressPainter extends CustomPainter {
  final double progress;        // 0.0 ~ 1.0
  final Color progressColor;
  final Color backgroundColor;
  final double strokeWidth;
  final double startAngle;      // 起始角度（弧度）

  CircularProgressPainter({
    required this.progress,
    this.progressColor = Colors.blue,
    this.backgroundColor = Colors.grey,
    this.strokeWidth = 12,
    this.startAngle = -pi / 2,  // 默认从顶部开始
  });

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

    // 背景圆环
    final bgPaint = Paint()
      ..color = backgroundColor
      ..strokeWidth = strokeWidth
      ..style = PaintingStyle.stroke
      ..strokeCap = StrokeCap.round;

    canvas.drawCircle(center, radius, bgPaint);

    // 进度圆弧
    final progressPaint = Paint()
      ..strokeWidth = strokeWidth
      ..style = PaintingStyle.stroke
      ..strokeCap = StrokeCap.round
      ..shader = SweepGradient(
        startAngle: startAngle,
        endAngle: startAngle + 2 * pi * progress,
        colors: [
          progressColor.withOpacity(0.5),
          progressColor,
        ],
      ).createShader(Rect.fromCircle(center: center, radius: radius));

    final sweepAngle = 2 * pi * progress;
    canvas.drawArc(
      Rect.fromCircle(center: center, radius: radius),
      startAngle,
      sweepAngle,
      false,
      progressPaint,
    );

    // 中心文字
    final textSpan = TextSpan(
      text: '${(progress * 100).toInt()}%',
      style: TextStyle(
        color: progressColor,
        fontSize: radius * 0.5,
        fontWeight: FontWeight.bold,
      ),
    );
    final textPainter = TextPainter(
      text: textSpan,
      textDirection: TextDirection.ltr,
    )..layout();

    textPainter.paint(
      canvas,
      Offset(
        center.dx - textPainter.width / 2,
        center.dy - textPainter.height / 2,
      ),
    );
  }

  @override
  bool shouldRepaint(covariant CircularProgressPainter oldDelegate) {
    return oldDelegate.progress != progress;
  }
}

// 使用：配合动画
class CircularProgressDemo extends StatefulWidget {
  @override
  _CircularProgressDemoState createState() => _CircularProgressDemoState();
}

class _CircularProgressDemoState extends State<CircularProgressDemo>
    with SingleTickerProviderStateMixin {
  late AnimationController _controller;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      duration: const Duration(seconds: 2),
      vsync: this,
    );
    _controller.forward();
  }

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: AnimatedBuilder(
          animation: _controller,
          builder: (context, child) {
            return CustomPaint(
              size: const Size(200, 200),
              painter: CircularProgressPainter(
                progress: _controller.value,
                progressColor: Colors.deepPurple,
              ),
            );
          },
        ),
      ),
    );
  }
}

3.9.2 柱状图

class BarChartPainter extends CustomPainter {
  final List<double> values;     // 数值列表 (0.0 ~ 1.0)
  final List<String> labels;     // 标签列表
  final List<Color> colors;      // 每根柱子颜色
  final double barWidth;
  final double barSpacing;

  BarChartPainter({
    required this.values,
    required this.labels,
    required this.colors,
    this.barWidth = 30,
    this.barSpacing = 20,
  });

  @override
  void paint(Canvas canvas, Size size) {
    final chartHeight = size.height - 40;  // 留出底部标签空间
    final chartWidth = values.length * (barWidth + barSpacing) - barSpacing;
    final startX = (size.width - chartWidth) / 2;

    // 绘制 Y 轴参考线
    final gridPaint = Paint()
      ..color = Colors.grey.shade300
      ..strokeWidth = 1;

    for (int i = 0; i <= 4; i++) {
      final y = chartHeight * (1 - i / 4);
      canvas.drawLine(
        Offset(startX - 10, y),
        Offset(startX + chartWidth + 10, y),
        gridPaint,
      );
    }

    // 绘制柱子
    for (int i = 0; i < values.length; i++) {
      final x = startX + i * (barWidth + barSpacing);
      final barHeight = chartHeight * values[i];
      final y = chartHeight - barHeight;

      // 柱子渐变
      final barPaint = Paint()
        ..shader = LinearGradient(
          begin: Alignment.topCenter,
          end: Alignment.bottomCenter,
          colors: [
            colors[i % colors.length],
            colors[i % colors.length].withOpacity(0.6),
          ],
        ).createShader(Rect.fromLTWH(x, y, barWidth, barHeight));

      // 绘制圆角柱子
      final rrect = RRect.fromRectAndCorners(
        Rect.fromLTWH(x, y, barWidth, barHeight),
        topLeft: const Radius.circular(6),
        topRight: const Radius.circular(6),
      );
      canvas.drawRRect(rrect, barPaint);

      // 数值标签
      final valueText = TextSpan(
        text: '${(values[i] * 100).toInt()}',
        style: TextStyle(
          color: colors[i % colors.length],
          fontSize: 12,
          fontWeight: FontWeight.bold,
        ),
      );
      final tp = TextPainter(
        text: valueText,
        textDirection: TextDirection.ltr,
      )..layout();
      tp.paint(canvas, Offset(x + barWidth / 2 - tp.width / 2, y - 20));

      // 底部标签
      final labelText = TextSpan(
        text: labels[i],
        style: TextStyle(color: Colors.grey.shade600, fontSize: 11),
      );
      final lp = TextPainter(
        text: labelText,
        textDirection: TextDirection.ltr,
      )..layout();
      lp.paint(
        canvas,
        Offset(x + barWidth / 2 - lp.width / 2, chartHeight + 8),
      );
    }
  }

  @override
  bool shouldRepaint(covariant BarChartPainter oldDelegate) {
    return values != oldDelegate.values;
  }
}

3.9.3 波浪线

class WavePainter extends CustomPainter {
  final double animationValue;  // 动画值 (0.0 ~ 1.0 不断循环)
  final Color waveColor;
  final double waveHeight;      // 波浪高度
  final double waveLength;      // 波浪一个周期的宽度

  WavePainter({
    required this.animationValue,
    this.waveColor = Colors.blue,
    this.waveHeight = 20,
    this.waveLength = 200,
  });

  @override
  void paint(Canvas canvas, Size size) {
    // 绘制多层波浪，由远到近
    _drawWaveLayer(
      canvas, size,
      amplitude: waveHeight * 0.6,
      wavelength: waveLength * 1.5,
      phase: animationValue * 2 * pi * 0.5,
      yOffset: size.height * 0.55,
      color: waveColor.withOpacity(0.2),
    );
    _drawWaveLayer(
      canvas, size,
      amplitude: waveHeight * 0.8,
      wavelength: waveLength,
      phase: animationValue * 2 * pi,
      yOffset: size.height * 0.6,
      color: waveColor.withOpacity(0.4),
    );
    _drawWaveLayer(
      canvas, size,
      amplitude: waveHeight,
      wavelength: waveLength * 0.8,
      phase: -animationValue * 2 * pi * 1.5,  // 反向运动
      yOffset: size.height * 0.65,
      color: waveColor.withOpacity(0.6),
    );
  }

  void _drawWaveLayer(
    Canvas canvas,
    Size size, {
    required double amplitude,
    required double wavelength,
    required double phase,
    required double yOffset,
    required Color color,
  }) {
    final paint = Paint()
      ..color = color
      ..style = PaintingStyle.fill;

    final path = Path();
    path.moveTo(0, yOffset);

    // 使用正弦函数生成波浪路径
    for (double x = 0; x <= size.width; x++) {
      final y = yOffset + amplitude * sin((x / wavelength) * 2 * pi + phase);
      path.lineTo(x, y);
    }

    // 封闭路径到底部
    path.lineTo(size.width, size.height);
    path.lineTo(0, size.height);
    path.close();

    canvas.drawPath(path, paint);
  }

  @override
  bool shouldRepaint(covariant WavePainter oldDelegate) {
    return oldDelegate.animationValue != animationValue;
  }
}

// 波浪动画 Widget
class WaveAnimationWidget extends StatefulWidget {
  @override
  _WaveAnimationWidgetState createState() => _WaveAnimationWidgetState();
}

class _WaveAnimationWidgetState extends State<WaveAnimationWidget>
    with SingleTickerProviderStateMixin {
  late AnimationController _controller;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      duration: const Duration(seconds: 3),
      vsync: this,
    )..repeat();  // 持续循环
  }

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

  @override
  Widget build(BuildContext context) {
    return CustomPaint(
      size: Size(double.infinity, 200),
      painter: WavePainter(animationValue: _controller.value),
    );
  }
}