Flutter 自定义 Widget 开发：从基础绘制到复杂交互

在 Flutter 开发中，系统提供的 Widget 虽能满足大部分基础需求，但在实现个性化 UI 或复杂交互逻辑时，自定义 Widget 成为核心技能。本文将从基础的绘制原理出发，逐步深入到复杂交互的实现，帮助开发者完整掌握 Flutter 自定义 Widget 的开发流程与核心技巧。

作者：爱吃大芒果

个人主页爱吃大芒果

本文所属专栏 Flutter

更多专栏

Ascend C 算子开发教程（进阶）
鸿蒙集成
 从0到1自学C++

自定义 Widget 主要用于解决两类问题：一是 UI 个性化，比如实现独特的图形、渐变效果、不规则布局等系统 Widget 无法直接满足的视觉需求；二是交互逻辑定制，比如封装特定的手势响应、状态管理逻辑，形成可复用的功能组件。相比直接使用系统 Widget 组合，自定义 Widget 能提升代码复用性、降低耦合度，同时让 UI 与业务逻辑更贴合产品需求。

Flutter 中的 Widget 本质是"配置信息"，真正负责渲染和布局的是其对应的 RenderObject。自定义 Widget 通常分为两类，开发时需根据需求选择：

组合型 Widget ：通过组合已有的系统 Widget 实现功能，无需直接操作 RenderObject。优点是开发成本低、稳定性高，适合大多数简单个性化需求（如自定义按钮、卡片）。
绘制型 Widget ：通过自定义 RenderObject 或使用 CustomPaint 组件进行手动绘制，可实现任意复杂的图形效果。缺点是需要掌握绘制原理，开发难度较高，适合实现不规则图形、动态绘制等场景。

二、基础绘制：从 CustomPaint 开始

对于需要自定义图形的场景，Flutter 提供了 CustomPaint 组件，它允许开发者通过 Painter 类手动绘制图形，是入门自定义绘制的最佳方式。

2.1 CustomPaint 核心原理

CustomPaint 内部维护了一个画布（Canvas），开发者通过 CustomPainter 子类重写 paint 方法，在画布上执行绘制操作。同时，CustomPainter 需实现 shouldRepaint 方法，用于判断是否需要重新绘制，以优化性能。

核心关系：CustomPaint（容器）→ Canvas（画布）→ CustomPainter（绘制逻辑）→ 图形渲染。

2.2 基础绘制实战：自定义圆形进度条

下面通过实现一个带渐变效果的圆形进度条，掌握 CustomPaint 的基础使用：

2.2.1 步骤 1：创建 CustomPainter 子类

dart 复制代码

import 'package:flutter/material.dart';

class CircleProgressPainter extends CustomPainter {
  // 进度值（0-1）
  final double progress;
  // 进度条宽度
  final double strokeWidth;
  // 渐变颜色
  final List<Color> gradientColors;

  CircleProgressPainter({
    required this.progress,
    this.strokeWidth = 8.0,
    required this.gradientColors,
  });

  // 初始化画笔
  late final Paint _paint = Paint()
    ..isAntiAlias = true // 抗锯齿
    ..style = PaintingStyle.stroke // 描边模式（不填充）
    ..strokeWidth = strokeWidth
    ..strokeCap = StrokeCap.round; // 笔触圆角

  @override
  void paint(Canvas canvas, Size size) {
    // 1. 计算绘制区域（居中）
    final center = Offset(size.width / 2, size.height / 2);
    final radius = (size.width - strokeWidth) / 2;

    // 2. 设置渐变
    final gradient = SweepGradient(
      colors: gradientColors,
      startAngle: 0,
      endAngle: 2 * 3.1415926,
    );
    _paint.shader = gradient.createShader(
      Rect.fromCircle(center: center, radius: radius),
    );

    // 3. 绘制进度圆弧
    final arcRect = Rect.fromCircle(center: center, radius: radius);
    canvas.drawArc(
      arcRect,
      -3.1415926 / 2, // 起始角度（顶部为0点）
      2 * 3.1415926 * progress, // 绘制角度（进度占比）
      false, // 是否连接中心
      _paint,
    );

    // 4. 绘制内部实心圆（装饰）
    final innerPaint = Paint()..color = Colors.white;
    canvas.drawCircle(center, radius - strokeWidth, innerPaint);
  }

  // 判断是否需要重绘：进度、宽度、颜色变化时重绘
  @override
  bool shouldRepaint(covariant CircleProgressPainter oldDelegate) {
    return oldDelegate.progress != progress ||
        oldDelegate.strokeWidth != strokeWidth ||
        !listEquals(oldDelegate.gradientColors, gradientColors);
  }
}

dart 复制代码

class CustomCircleProgress extends StatelessWidget {
  final double progress;
  final double size;
  final double strokeWidth;
  final List<Color> gradientColors;

  const CustomCircleProgress({
    super.key,
    required this.progress,
    this.size = 100,
    this.strokeWidth = 8.0,
    this.gradientColors = const [Colors.blue, Colors.purple],
  });

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: size,
      height: size,
      child: CustomPaint(
        painter: CircleProgressPainter(
          progress: progress.clamp(0, 1), // 限制进度在0-1之间
          strokeWidth: strokeWidth,
          gradientColors: gradientColors,
        ),
      ),
    );
  }
}

2.2.3 步骤 3：使用自定义进度条

dart 复制代码

class ProgressDemo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text("基础绘制示例")),
      body: Center(
        child: CustomCircleProgress(
          progress: 0.6, // 60% 进度
          size: 120,
          gradientColors: [Colors.green, Colors.yellow],
        ),
      ),
    );
  }
}

2.3 核心绘制 API 总结

Canvas 提供了丰富的绘制 API，常用的包括：

基础图形：drawLine（画线）、drawRect（画矩形）、drawCircle（画圆）、drawArc（画圆弧）、drawPath（画任意路径）；
文本绘制：drawText（需配合 TextPainter）；
图像绘制：drawImage（绘制图片）；
渐变与纹理：通过 Paint.shader 设置线性渐变（LinearGradient）、径向渐变（RadialGradient）、扫描渐变（SweepGradient）。

大多数自定义 Widget 都需要响应状态变化（如进度更新、点击状态切换）。Flutter 中，状态管理的核心是 StatefulWidget，通过 setState 触发 UI 重绘。

3.1 基础状态管理：StatefulWidget + setState

以"可点击切换状态的自定义开关"为例，演示状态与绘制的结合：

dart 复制代码

class CustomSwitch extends StatefulWidget {
  final bool isChecked;
  final ValueChanged<bool>? onChanged;

  const CustomSwitch({
    super.key,
    this.isChecked = false,
    this.onChanged,
  });

  @override
  State<CustomSwitch> createState() => _CustomSwitchState();
}

class _CustomSwitchState extends State<CustomSwitch> {
  late bool _isChecked;

  @override
  void initState() {
    super.initState();
    _isChecked = widget.isChecked;
  }

  @override
  void didUpdateWidget(covariant CustomSwitch oldWidget) {
    super.didUpdateWidget(oldWidget);
    // 外部状态变化时同步更新
    if (oldWidget.isChecked != widget.isChecked) {
      _isChecked = widget.isChecked;
    }
  }

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      // 点击切换状态
      onTap: () {
        setState(() {
          _isChecked = !_isChecked;
        });
        widget.onChanged?.call(_isChecked);
      },
      child: CustomPaint(
        size: const Size(60, 30),
        painter: SwitchPainter(isChecked: _isChecked),
      ),
    );
  }
}

// 绘制开关的 Painter
class SwitchPainter extends CustomPainter {
  final bool isChecked;

  SwitchPainter({required this.isChecked});

  final Paint _bgPaint = Paint()..isAntiAlias = true;
  final Paint _thumbPaint = Paint()..color = Colors.white;

  @override
  void paint(Canvas canvas, Size size) {
    // 1. 绘制背景圆角矩形
    final bgRect = RRect.fromRectAndRadius(
      Rect.fromLTWH(0, 0, size.width, size.height),
      const Radius.circular(15),
    );
    _bgPaint.color = isChecked ? Colors.green : Colors.grey[300]!;
    canvas.drawRRect(bgRect, _bgPaint);

    // 2. 绘制滑块（圆形）
    final thumbOffset = isChecked 
        ? Offset(size.width - 15, size.height / 2) 
        : Offset(15, size.height / 2);
    canvas.drawCircle(thumbOffset, 12, _thumbPaint);
  }

  @override
  bool shouldRepaint(covariant SwitchPainter oldDelegate) {
    return oldDelegate.isChecked != isChecked;
  }
}

当自定义 Widget 需跨组件共享状态（如全局主题切换、多组件联动）时，单纯使用 setState 会导致代码冗余。此时可结合 Provider 等状态管理工具，将状态与 UI 分离。

核心思路：将共享状态封装在 ChangeNotifier 子类中，通过 Provider 注入上下文，自定义 Widget 从上下文获取状态并监听变化，状态更新时自动重绘。

四、复杂交互：手势识别与动画

自定义 Widget 的复杂交互通常包含两部分：手势识别（如滑动、缩放、旋转）和动画（如过渡动画、属性动画）。Flutter 提供了完善的手势与动画系统，可与自定义绘制无缝结合。

4.1 手势识别：GestureDetector 与 GestureRecognizer

对于简单手势（点击、双击、滑动），可直接使用 GestureDetector 包裹 CustomPaint；对于复杂手势（如多点触控、手势竞争），需使用 GestureRecognizer 子类（如 PanGestureRecognizer、ScaleGestureRecognizer）手动管理。

示例：实现可拖动的自定义图形（拖动滑块）：

dart 复制代码

class DraggableWidget extends StatefulWidget {
  @override
  State<DraggableWidget> createState() => _DraggableWidgetState();
}

class _DraggableWidgetState extends State<DraggableWidget> {
  Offset _position = const Offset(100, 100); // 初始位置

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text("手势识别示例")),
      body: GestureDetector(
        // 拖动更新位置
        onPanUpdate: (details) {
          setState(() {
            _position += details.delta;
          });
        },
        child: CustomPaint(
          painter: DraggablePainter(position: _position),
          size: MediaQuery.of(context).size,
        ),
      ),
    );
  }
}

class DraggablePainter extends CustomPainter {
  final Offset position;

  DraggablePainter({required this.position});

  final Paint _paint = Paint()
    ..color = Colors.red
    ..style = PaintingStyle.fill
    ..isAntiAlias = true;

  @override
  void paint(Canvas canvas, Size size) {
    // 绘制可拖动的圆形
    canvas.drawCircle(position, 30, _paint);
  }

  @override
  bool shouldRepaint(covariant DraggablePainter oldDelegate) {
    return oldDelegate.position != position;
  }
}

4.2 动画：结合 Animation 与 CustomPaint

Flutter 动画的核心是 Animation（动画值）和 AnimationController（动画控制器）。自定义 Widget 中，可通过监听动画值变化，触发 CustomPaint 重绘，实现动态效果。

示例：实现圆形进度条的加载动画：

dart 复制代码

class AnimatedCircleProgress extends StatefulWidget {
  @override
  State<AnimatedCircleProgress> createState() => _AnimatedCircleProgressState();
}

class _AnimatedCircleProgressState extends State<AnimatedCircleProgress>
    with SingleTickerProviderStateMixin {
  late AnimationController _controller;
  late Animation<double> _progressAnimation;

  @override
  void initState() {
    super.initState();
    // 初始化动画控制器（时长2秒）
    _controller = AnimationController(
      vsync: this,
      duration: const Duration(seconds: 2),
    );

    // 动画值从0到1渐变
    _progressAnimation = Tween<double>(begin: 0, end: 1).animate(
      CurvedAnimation(parent: _controller, curve: Curves.easeInOut),
    )..addListener(() {
        setState(() {}); // 动画值变化时重绘
      });

    _controller.repeat(reverse: true); // 重复播放（往返）
  }

  @override
  void dispose() {
    _controller.dispose(); // 释放资源
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Center(
      child: CustomCircleProgress(
        progress: _progressAnimation.value,
        size: 120,
      ),
    );
  }
}

自定义绘制若处理不当，易导致性能问题（如卡顿、过度重绘）。以下是核心优化技巧：

5.1 精准控制重绘时机

重写 CustomPainter.shouldRepaint 方法，仅在关键属性变化时返回 true（如进度、颜色、位置变化），避免不必要的重绘。

5.2 使用 RepaintBoundary 隔离重绘区域

将 CustomPaint 包裹在 RepaintBoundary 中，可使该区域的重绘与其他区域隔离，避免因父组件重绘导致自定义 Widget 被连带重绘。

dart 复制代码

RepaintBoundary(
  child: CustomPaint(
    painter: MyPainter(),
  ),
)

5.3 缓存静态绘制内容

对于不变的图形（如背景、固定装饰），可提前绘制到 Picture 或 Image 中，后续直接复用，避免重复绘制。

5.4 减少绘制复杂度

避免在 paint 方法中执行复杂计算（如循环、对象创建），尽量将计算逻辑移到 paint 方法外部；减少不必要的图层叠加，简化路径绘制。

六、总结与进阶方向

Flutter 自定义 Widget 开发的核心流程的是：明确需求（UI/交互）→ 选择实现方式（组合型/绘制型）→ 实现绘制/组合逻辑 → 集成状态管理与交互 → 性能优化。

进阶学习方向：

深入理解 RenderObject：直接自定义RenderObject，实现更底层的布局与绘制控制；
自定义手势识别器：实现复杂的手势逻辑（如多指旋转、手势优先级控制）；
集成硬件加速：利用 Flutter 的硬件加速能力，提升复杂绘制的性能；
跨平台适配：处理不同屏幕尺寸、分辨率下的绘制适配问题。

通过不断实践与总结，开发者可逐步掌握自定义 Widget 的核心技巧，实现各类个性化、复杂的 UI 与交互需求，提升 Flutter 应用的用户体验与竞争力。

Flutter 自定义 Widget 开发：从基础绘制到复杂交互