AnimatedBuilder 是 Flutter 显式动画体系的基石。本文从源码原理出发，分析其在 E-Brufen 呼吸球和白噪音中的实战应用，帮你真正理解"为什么要这样写"。

---

一、AnimatedBuilder 解决了什么问题？

1.1 问题场景

当你有一个循环动画（如呼吸球），需要每帧更新球的缩放和透明度。最简单的做法是：

// ❌ 反模式：每帧 setState 重建整个 Widget 树
_controller.addListener(() {
  setState(() {});  // 整个 build() 重新执行！
});

问题：假设这个页面有 30 个 Widget，其中只有呼吸球的 scale 和 opacity 在变化，但 setState 会导致所有 30 个 Widget 重新 build——大部分是无效计算。

1.2 AnimatedBuilder 的解决方案

// ✅ 最佳实践：只重建动画相关的子树
AnimatedBuilder(
  animation: _controller,
  builder: (context, child) {
    // 只有这里面的 Widget 会被重建
    return Transform.scale(
      scale: 1.0 + _controller.value * 0.5,
      child: child,  // ← 传入的 child 不重建！
    );
  },
  child: CircleWidget(),  // 不变的子组件
)

★ Insight ─────────────────────────────────────
AnimatedBuilder 的 child 参数是其性能优化的核心。builder 回调每帧都会执行，但传入的 child 是同一个 Widget 实例。Flutter 的 Element 树 Diff 算法发现 child 引用没变 → 跳过该子树的全部 rebuild → 只重建 builder 中的 Transform 部分。

如果你的 AnimatedBuilder 没有使用 child 参数，那它的性能优化效果就等于零。
─────────────────────────────────────────────────

---

二、工作原理：从源码视角

2.1 简化版 AnimatedBuilder 源码

// Flutter 框架中的实际实现（简化）
class AnimatedBuilder extends AnimatedWidget {
  final TransitionBuilder builder;
  final Widget? child;

  const AnimatedBuilder({
    required Listenable animation,
    required this.builder,
    this.child,
  }) : super(listenable: animation);

  @override
  Widget build(BuildContext context) {
    return builder(context, child);  // 每帧调用 builder，传入缓存的 child
  }
}

AnimatedWidget 内部自动做了 addListener + setState：

abstract class AnimatedWidget extends StatefulWidget {
  @override
  _AnimatedState createState() => _AnimatedState();

  @override
  void initState() {
    super.initState();
    widget.listenable.addListener(_handleChange);  // 自动监听
  }

  void _handleChange() {
    setState(() {});  // 自动 setState
  }

  @override
  void dispose() {
    widget.listenable.removeListener(_handleChange);
    super.dispose();
  }
}

所以你不需要手动 addListener + setState——AnimatedBuilder 全都帮你做了。

---

三、E-Brufen 实战一：呼吸球

// lib/widgets/breathing_circle.dart
@override
Widget build(BuildContext context) {
  return AnimatedBuilder(
    animation: _controller,
    builder: (context, child) {
      final scale = 1.0 + (_controller.value * 0.5);    // 1.0 → 1.5
      final opacity = 0.3 + (_controller.value * 0.4);   // 0.3 → 0.7

      return Transform.scale(
        scale: scale,
        child: Container(
          width: 180, height: 180,
          decoration: BoxDecoration(
            shape: BoxShape.circle,
            color: AppTheme.gentlePurple.withValues(alpha: opacity),
            boxShadow: [
              BoxShadow(
                color: AppTheme.gentlePurple.withValues(alpha: 0.3),
                blurRadius: 30,
                spreadRadius: 5,
              ),
            ],
          ),
        ),
      );
    },
  );
}

每帧都在变化的：scale（1.0→1.5）、opacity（0.3→0.7）
永远不变的：Container 尺寸（180×180）、BoxShadow 参数（blurRadius: 30）

实际生产中，可以把 child 提取出来进一步优化，但对于当前的简单场景，过度提取反而降低可读性。

---

四、E-Brufen 实战二：白噪音脉冲

// lib/pages/soundscape/soundscape_page.dart
AnimatedBuilder(
  animation: _pulse,
  builder: (context, _) {
    return Container(
      width: 120 + _pulse.value * 50,
      height: 120 + _pulse.value * 50,
      decoration: BoxDecoration(
        shape: BoxShape.circle,
        color: scene.color.withValues(
          alpha: _isPlaying ? 0.25 + _pulse.value * 0.2 : 0.08),
        boxShadow: _isPlaying
          ? [BoxShadow(
              color: scene.color.withValues(alpha: 0.3),
              blurRadius: 20 + _pulse.value * 30,
              spreadRadius: 5,
            )]
          : [],
      ),
    );
  },
)

与呼吸球的区别：

• 呼吸球用 Transform.scale（保持布局稳定）
• 脉冲球直接改 width/height（需要影响布局，让周围元素随之调整）

两种方式的选择取决于动画的目的——是"视觉效果"还是"布局效果"。

---

五、AnimatedBuilder vs 隐式动画

特性	AnimatedBuilder	AnimatedContainer	AnimatedScale
需要 Controller?	✅ 需要	❌ 不需要	❌ 不需要
循环动画?	✅ 支持	❌ 不支持	❌ 不支持
多属性同步?	✅ 任意多	仅 Container 属性	仅 scale
代码量	较多	极少	极少
E-Brufen 中用法	呼吸球、脉冲	柱状图柱子	情绪选择器

决策树：

需要连续循环动画？
├─ 是 → AnimatedBuilder + AnimationController
└─ 否 → 简单的属性过渡？
         ├─ 是 → AnimatedContainer / AnimatedScale
         └─ 否，需要自定义逻辑 → AnimatedBuilder

---

六、性能优化 checklist

• 使用了 child 参数缓存不变子树
• AnimationController 在 dispose 中正确释放
• 不是每帧 setState，而是通过 AnimatedBuilder 自动监听
• animationBehavior: AnimationBehavior.preserve（停止时保持位置）
• 复杂动画考虑 RepaintBoundary 隔离重绘区域

---

七、常见错误

错误 1：在 builder 中创建新的 child

// ❌ child 每帧重建，性能优化白做
AnimatedBuilder(
  animation: _controller,
  builder: (context, _) {
    return Transform.scale(
      scale: ...,
      child: CircleWidget(),  // ← 每帧创建新实例！
    );
  },
)

错误 2：忘记 dispose

// ❌ AnimationController 永远不会被释放
@override
void dispose() {
  super.dispose();  // 忘记 _controller.dispose()
}

错误 3：一个 Controller 驱动过多 Widget

// ❌ 一个 Controller 驱动 50 个 AnimatedBuilder
// 每帧 50 个 builder 回调 → 严重掉帧

---

上一篇：Flutter 鸿蒙应用的错误处理与优雅降级
下一篇：AnimatedScale 与 AnimatedContainer 联合实战

---

作者简介：E-Brufen Dev，Flutter & 鸿蒙开发者。动画性能数据在鸿蒙 6.0 模拟器 60fps 条件下测试,项目地址：AtomGit - E-Brufen。