# 基础用法
/add-widget-from-prototype <prototype-path>

# 示例：从 card_widgets/widget3 创建组件
/add-widget-from-prototype code_snippet/card_widgets/widget3

import 'package:flutter/material.dart';

/// [组件描述]示例
class [ComponentName]Example extends StatelessWidget {
  const [ComponentName]Example({super.key});

  @override
  Widget build(BuildContext context) {
    final isDark = Theme.of(context).brightness == Brightness.dark;

    return Scaffold(
      appBar: AppBar(title: const Text('[组件标题]')),
      body: Container(
        color: isDark ? Colors.black : const Color(0xFFF2F2F7),
        child: const Center(
          child: [ComponentName]Widget(
            // 示例数据
          ),
        ),
      ),
    );
  }
}

/// [组件描述]小组件
class [ComponentName]Widget extends StatelessWidget {
  // 组件参数
  final [Type] [param1];
  final [Type] [param2];

  const [ComponentName]Widget({
    super.key,
    required this.[param1],
    // ...
  });

  @override
  Widget build(BuildContext context) {
    final isDark = Theme.of(context).brightness == Brightness.dark;
    // 根据原型实现 UI
  }
}

// 辅助类和函数
class _[HelperName] extends StatelessWidget {
  // ...
}

// 文件顶部添加导入
import 'package:Memento/screens/widgets_gallery/screens/[component_name]_example.dart';

// 在 routes 列表中添加（在 half_circle_gauge_widget 后面）
RouteDefinition(
  path: '/widgets_gallery/[route_name]',
  handler: (settings) => RouteHelpers.createRoute(const [ComponentName]Example(), settings: settings),
  description: '[组件描述]',
),

_buildListItem(
  context,
  icon: Icons.[icon_name],
  title: '[中文标题]',
  subtitle: '[ComponentName] - [副标题]',
  route: '/widgets_gallery/[route_name]',
),

// 从 HTML 提取颜色示例
final backgroundColor = isDark ? const Color(0xFF1C1C1E) : Colors.white;
final primaryColor = const Color(0xFF7B57E0);
final textColor = isDark ? Colors.white : Colors.grey.shade900;

// ✅ 推荐：使用主题颜色
final primaryColor = Theme.of(context).colorScheme.primary;

// ❌ 避免：硬编码颜色（除非与主题差异较大）
final primaryColor = const Color(0xFFF43F5E);

// 示例：根据情况选择颜色
final primaryColor = isDark
    ? const Color(0xFFFB7185)  // 深色模式使用原型颜色
    : Theme.of(context).colorScheme.primary;  // 浅色模式使用主题色

// 固定尺寸（桌面小组件风格）
Container(
  width: 280,
  height: 280,
  // ...
)

// 响应式尺寸
LayoutBuilder(
  builder: (context, constraints) {
    return Container(
      width: constraints.maxWidth,
      // ...
    );
  },
)

// fl_chart 示例
import 'package:fl_chart/fl_chart.dart';

PieChart(
  PieChartData(
    sections: [
      PieChartSectionData(value: 30, color: Colors.blue),
      PieChartSectionData(value: 70, color: Colors.green),
    ],
  ),
)

class MyWidget extends StatefulWidget {
  // ...
}

class _MyWidgetState extends State<MyWidget>
    with SingleTickerProviderStateMixin {
  late AnimationController _animationController;
  late Animation<double> _animation;

  @override
  void initState() {
    super.initState();
    _animationController = AnimationController(
      duration: const Duration(milliseconds: 1200),
      vsync: this,
    );
    _animation = CurvedAnimation(
      parent: _animationController,
      curve: Curves.easeOutCubic,
    );
    _animationController.forward();
  }

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

  @override
  Widget build(BuildContext context) {
    return AnimatedBuilder(
      animation: _animation,
      builder: (context, child) {
        return Opacity(
          opacity: _animation.value,
          child: Transform.translate(
            offset: Offset(0, 20 * (1 - _animation.value)),
            child: // 组件内容
          ),
        );
      },
    );
  }
}

class _ProgressPainter extends CustomPainter {
  final double progress;
  final Color progressColor;
  final Color backgroundColor;

  _ProgressPainter({
    required this.progress,
    required this.progressColor,
    required this.backgroundColor,
  });

  @override
  void paint(Canvas canvas, Size size) {
    // 绘制背景圆环
    // 绘制进度圆弧（使用 progress 值）
  }

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

// ✅ 正确：完整的固定尺寸约束模式
SizedBox(
  height: 54,  // 1. 外层 Row 固定高度
  child: Row(
    crossAxisAlignment: CrossAxisAlignment.center,  // 2. 使用 center 而非 baseline
    children: [
      SizedBox(
        width: 160,  // 3. AnimatedFlipCounter 固定宽度和高度
        height: 52,
        child: AnimatedFlipCounter(
          value: data.value * itemAnimation.value,
          fractionDigits: data.value % 1 != 0 ? 2 : 0,
          textStyle: TextStyle(
            fontSize: 48,
            fontWeight: FontWeight.w800,
            height: 1.0,  // 4. 固定行高
          ),
        ),
      ),
      const SizedBox(width: 6),
      SizedBox(
        height: 22,  // 5. 单位 Text 固定高度
        child: Text(
          'unit',
          style: TextStyle(
            fontSize: 14,
            height: 1.0,  // 6. 固定行高
          ),
        ),
      ),
    ],
  ),
)

// ❌ 错误 1: 使用 baseline 对齐
Row(
  crossAxisAlignment: CrossAxisAlignment.baseline,  // 会导致抖动
  textBaseline: TextBaseline.alphabetic,
  children: [
    AnimatedFlipCounter(...),
    Text('unit'),
  ],
)

// ❌ 错误 2: 没有固定宽度
Row(
  children: [
    SizedBox(
      height: 52,  // 只有高度，没有宽度
      child: AnimatedFlipCounter(...),
    ),
    Text('unit'),
  ],
)

// ❌ 错误 3: Text 没有固定高度
Row(
  children: [
    AnimatedFlipCounter(...),
    Text('unit'),  // 没有包裹 SizedBox
  ],
)

// AnimatedFlipCounter 的宽度应足够容纳最大值
final counterWidth = maxWidthDigitCount * fontSize * 0.6 + padding;

// 示例计算：
// fontSize: 48, 最大3位整数 + 1位小数 = 4个字符
// width = 4 * 48 * 0.6 ≈ 115，取安全值 160

// 外层 Row 高度 = max(counterHeight, unitHeight) + alignment
final rowHeight = max(52, 22) = 54;

import 'package:animated_flip_counter/animated_flip_counter.dart';

// 在 AnimatedBuilder 中使用
SizedBox(
  height: 54,
  child: Row(
    crossAxisAlignment: CrossAxisAlignment.center,
    children: [
      SizedBox(
        width: 160,  // 根据最大值计算
        height: 52,
        child: AnimatedFlipCounter(
          value: data.value * itemAnimation.value,  // 从 0 增长到目标值
          fractionDigits: data.value % 1 != 0 ? 2 : 0,  // 自动识别整数/小数
          textStyle: TextStyle(
            color: Colors.white,
            fontSize: 48,
            fontWeight: FontWeight.w800,
            height: 1.0,  // 固定行高防止文字变化影响布局
          ),
        ),
      ),
      const SizedBox(width: 6),
      SizedBox(
        height: 22,  // 单位固定高度
        child: Text(
          'unit',
          style: TextStyle(
            fontSize: 14,
            height: 1.0,  // 固定行高
          ),
        ),
      ),
    ],
  ),
),

for (int i = 0; i < items.length; i++) ...[
  if (i > 0) const SizedBox(height: 24),
  _ItemWidget(
    data: items[i],
    animation: _animation,
    index: i,  // 传递索引用于计算延迟
  ),
]

// 在子组件中
final itemAnimation = CurvedAnimation(
  parent: animation,
  curve: Interval(
    index * 0.15,  // 延迟开始
    0.6 + index * 0.15,  // 延迟结束
    curve: Curves.easeOutCubic,
  ),
);

时间轴 (0-1200ms), 3个元素:
├── 0-180ms:      元素1 开始淡入+上滑
├── 0-930ms:      元素1 进度条/数字增长
├── 180-360ms:    元素2 开始淡入+上滑
├── 180-1110ms:   元素2 进度条/数字增长
├── 360-540ms:    元素3 开始淡入+上滑
└── 360-1200ms:   元素3 进度条/数字增长

import 'package:flutter/material.dart';

/// 分段进度条统计卡片示例
class SegmentedProgressCardExample extends StatelessWidget {
  const SegmentedProgressCardExample({super.key});

  @override
  Widget build(BuildContext context) {
    final isDark = Theme.of(context).brightness == Brightness.dark;

    return Scaffold(
      appBar: AppBar(title: const Text('分段进度条统计卡片')),
      body: Container(
        color: isDark ? Colors.black : const Color(0xFFF2F2F7),
        child: const Center(
          child: SegmentedProgressCardWidget(
            segments: [
              SegmentData(label: '类别A', value: 45, color: Color(0xFFE14462)),
              SegmentData(label: '类别B', value: 30, color: Color(0xFF7B57E0)),
            ],
            total: 100,
            unit: '单位',
          ),
        ),
      ),
    );
  }
}

/// 分段数据模型
class SegmentData {
  final String label;
  final double value;
  final Color color;

  const SegmentData({
    required this.label,
    required this.value,
    required this.color,
  });
}

/// 分段进度条统计小组件
class SegmentedProgressCardWidget extends StatelessWidget {
  final List<SegmentData> segments;
  final double total;
  final String unit;

  const SegmentedProgressCardWidget({
    super.key,
    required this.segments,
    required this.total,
    this.unit = '',
  });

  @override
  Widget build(BuildContext context) {
    final isDark = Theme.of(context).brightness == Brightness.dark;
    final backgroundColor = isDark ? const Color(0xFF1C1C1E) : Colors.white;

    return Container(
      width: 280,
      height: 280,
      decoration: BoxDecoration(
        color: backgroundColor,
        borderRadius: BorderRadius.circular(24),
      ),
      child: Column(
        children: [
          // 组件内容
        ],
      ),
    );
  }
}

A RenderFlex overflowed by X pixels on the bottom.
The relevant error-causing widget was: Column

// ❌ 错误：使用 Spacer 导致布局不可控
Column(
  children: [
    HeaderWidget(),
    Spacer(),
    ContentWidget(),
    FooterWidget(),
  ],
)

// ✅ 正确：使用固定的 SizedBox
Column(
  mainAxisSize: MainAxisSize.min,  // 让 Column 只占用必需空间
  children: [
    HeaderWidget(),
    const SizedBox(height: 20),  // 固定间距
    ContentWidget(),
    const SizedBox(height: 14),  // 固定间距
    FooterWidget(),
  ],
)

// ❌ 错误 1: 使用 baseline 对齐（最常见错误）
Row(
  crossAxisAlignment: CrossAxisAlignment.baseline,  // ❌ 会导致抖动
  textBaseline: TextBaseline.alphabetic,
  children: [
    AnimatedFlipCounter(value: value * animation.value),
    Text('km'),
  ],
)

// ❌ 错误 2: 只固定高度，没有固定宽度
SizedBox(
  height: 48,  // ❌ 只有高度，宽度仍会变化
  child: Row(
    children: [
      AnimatedFlipCounter(value: value * animation.value),
      Text('km'),
    ],
  ),
)

// ❌ 错误 3: Text 没有固定高度
SizedBox(
  height: 48,
  child: Row(
    children: [
      SizedBox(
        width: 170,
        height: 48,
        child: AnimatedFlipCounter(value: value * animation.value),
      ),
      Text('km'),  // ❌ 没有包裹 SizedBox，高度不固定
    ],
  ),
)

// ✅ 正确：完整固定尺寸约束模式
SizedBox(
  height: 54,  // 1. 外层固定高度（足够容纳最大元素）
  child: Row(
    crossAxisAlignment: CrossAxisAlignment.center,  // 2. 使用 center 而非 baseline
    children: [
      SizedBox(
        width: 160,   // 3. AnimatedFlipCounter 固定宽度（根据最大值计算）
        height: 52,   // 4. AnimatedFlipCounter 固定高度
        child: AnimatedFlipCounter(
          value: value * animation.value,
          textStyle: TextStyle(
            fontSize: 48,
            fontWeight: FontWeight.w800,
            height: 1.0,  // 5. 固定行高（防止文字行高变化）
          ),
        ),
      ),
      const SizedBox(width: 6),
      SizedBox(
        height: 22,  // 6. 单位 Text 固定高度
        child: Text(
          'km',
          style: TextStyle(
            fontSize: 14,
            height: 1.0,  // 7. 固定行高
          ),
        ),
      ),
    ],
  ),
)

// AnimatedFlipCounter 宽度计算
// 预估最大位数 × 字体大小 × 字符宽度系数 + 安全余量
final counterWidth = (maxIntegerDigits + maxFractionDigits + 1) * fontSize * 0.6 + 20;

// 示例：
// 最大值: 999.99 (3位整数 + 2位小数 + 1个小数点 = 6个字符)
// fontSize: 48
// width = 6 * 48 * 0.6 + 20 ≈ 193，取整到 200 或更大安全值

// 外层 Row 高度计算
final rowHeight = max(counterHeight, unitHeight) + verticalPadding;

// 示例：
// counterHeight: 52, unitHeight: 22
// rowHeight = max(52, 22) = 54

// ❌ 错误：点阵可能超出圆角边界
Positioned(
  top: 0,
  right: 0,
  child: Container(
    decoration: BoxDecoration(
      color: primaryColor.withOpacity(0.2),
      borderRadius: BorderRadius.only(topRight: Radius.circular(26)),
    ),
    child: CustomPaint(painter: _DotPatternPainter(...)),
  ),
)

// ✅ 正确：使用 ClipRRect 裁剪 + 将透明度应用到颜色
Positioned(
  top: 0,
  right: 0,
  child: ClipRRect(
    borderRadius: BorderRadius.only(topRight: Radius.circular(26)),
    child: ShaderMask(
      shaderCallback: (bounds) => RadialGradient(...).createShader(bounds),
      blendMode: BlendMode.dstIn,
      child: CustomPaint(
        size: const Size(128, 128),  // 明确指定尺寸
        painter: _DotPatternPainter(
          color: primaryColor.withOpacity(0.2),  // 透明度在颜色上
        ),
      ),
    ),
  ),
)

'package:flutter/src/animation/curves.dart': Failed assertion:
line 180 pos 12: 'end <= 1.0': is not true.

// ❌ 错误：step 太大导致 end 超出 1.0
final step = 0.12;  // 对于 8 个元素，最大 end = 0.6 + 7 * 0.12 = 1.44

// ✅ 正确：计算合适的 step 确保最大 end <= 1.0
// 公式：step <= (1.0 - baseEnd) / (elementCount - 1)
// 示例：8 个元素，baseEnd = 0.6
// step <= (1.0 - 0.6) / 7 = 0.057
final step = 0.05;  // 最大 end = 0.6 + 7 * 0.05 = 0.95

final itemAnimation = CurvedAnimation(
  parent: _animationController,
  curve: Interval(
    index * step,
    0.6 + index * step,
    curve: Curves.easeOutCubic,
  ),
);

// 确保所有 Interval 的 end 值不超过 1.0
final elementCount = items.length;
final baseEnd = 0.6;  // 第一个元素的结束位置
final maxStep = (1.0 - baseEnd) / (elementCount - 1);
final step = maxStep * 0.9;  // 留 10% 安全余量