一、技术栈与环境准备

1. 核心依赖

本次案例使用以下主流依赖,需添加到 pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  # 网络请求
  dio: ^5.4.0
  # 状态管理
  provider: ^6.1.1
  # 图片缓存/加载
  cached_network_image: ^3.3.1
  # 轮播图
  carousel_slider: ^4.2.1
  # 下拉刷新增强
  pull_to_refresh: ^2.0.0
  # 原生交互(分享/相册)
  share_plus: ^7.2.1
  image_gallery_saver: ^2.0.3
  # 屏幕适配
  flutter_screenutil: ^5.9.0

dev_dependencies:
  flutter_test:
    sdk: flutter

执行 flutter pub get 安装依赖。

2. 基础配置

在 main.dart 初始化屏幕适配(以 375x812 设计稿为例):

import 'package:flutter_screenutil/flutter_screenutil.dart';

void main() {
  runApp(
    ScreenUtilInit(
      designSize: const Size(375, 812), // 设计稿尺寸
      minTextAdapt: true,
      splitScreenMode: true,
      child: const MyApp(),
    ),
  );
}

二、核心需求拆解

本次实现的商品详情页包含以下核心功能:

  1. 商品轮播图(自动播放 + 无限循环);
  2. 价格变动动画(原价 / 现价对比);
  3. 下拉刷新重新加载商品数据;
  4. 分享商品图片到系统相册;
  5. 加入购物车(跨组件状态共享);
  6. 沉浸式导航栏(适配状态栏颜色);
  7. 商品规格选择弹窗。

三、实战开发:完整代码实现

1. 数据模型与状态管理(lib/models/)

1.1 商品模型(product_model.dart)
class ProductModel {
  final String id;
  final String name;
  final String desc;
  final double price;
  final double originalPrice;
  final List<String> imageUrls;
  final List<String> specs; // 商品规格

  ProductModel({
    required this.id,
    required this.name,
    required this.desc,
    required this.price,
    required this.originalPrice,
    required this.imageUrls,
    required this.specs,
  });

  // 从JSON解析
  factory ProductModel.fromJson(Map<String, dynamic> json) {
    return ProductModel(
      id: json['id'],
      name: json['name'],
      desc: json['desc'],
      price: json['price'].toDouble(),
      originalPrice: json['originalPrice'].toDouble(),
      imageUrls: List<String>.from(json['imageUrls']),
      specs: List<String>.from(json['specs']),
    );
  }
}
1.2 购物车状态管理(cart_provider.dart)
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'product_model.dart';

class CartProvider with ChangeNotifier {
  final List<ProductModel> _cartList = [];

  // 获取购物车列表
  List<ProductModel> get cartList => _cartList;

  // 获取购物车商品数量
  int get cartCount => _cartList.length;

  // 加入购物车
  void addToCart(ProductModel product) {
    _cartList.add(product);
    notifyListeners();
    // 显示提示
    if (kDebugMode) {
      print('加入购物车成功,当前数量:${_cartList.length}');
    }
  }

  // 清空购物车
  void clearCart() {
    _cartList.clear();
    notifyListeners();
  }
}

2. 网络请求工具(lib/utils/request.dart)

import 'package:dio/dio.dart';
import '../models/product_model.dart';

class RequestUtil {
  static final Dio _dio = Dio(
    BaseOptions(
      baseUrl: 'https://65680f6d9927836bd9745310.mockapi.io/api',
      connectTimeout: const Duration(seconds: 5),
      receiveTimeout: const Duration(seconds: 5),
    ),
  );

  // 获取商品详情
  static Future<ProductModel> getProductDetail(String productId) async {
    try {
      final response = await _dio.get('/products/$productId');
      if (response.statusCode == 200) {
        return ProductModel.fromJson(response.data);
      } else {
        throw Exception('请求失败:${response.statusCode}');
      }
    } catch (e) {
      throw Exception('网络异常:$e');
    }
  }
}

3. 核心页面:商品详情页(lib/pages/product_detail.dart)

import 'dart:typed_data';
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:cached_network_image/cached_network_image.dart';
import 'package:carousel_slider/carousel_slider.dart';
import 'package:pull_to_refresh/pull_to_refresh.dart';
import 'package:share_plus/share_plus.dart';
import 'package:image_gallery_saver/image_gallery_saver.dart';
import 'package:flutter_screenutil/flutter_screenutil.dart';
import '../models/product_model.dart';
import '../utils/request.dart';
import '../providers/cart_provider.dart';

class ProductDetailPage extends StatefulWidget {
  final String productId;

  const ProductDetailPage({super.key, required this.productId});

  @override
  State<ProductDetailPage> createState() => _ProductDetailPageState();
}

class _ProductDetailPageState extends State<ProductDetailPage>
    with SingleTickerProviderStateMixin {
  // 商品数据
  ProductModel? _product;
  // 加载状态
  bool _isLoading = true;
  // 错误信息
  String? _errorMsg;
  // 轮播控制器
  final CarouselController _carouselController = CarouselController();
  int _currentIndex = 0;
  // 下拉刷新控制器
  final RefreshController _refreshController =
      RefreshController(initialRefresh: false);
  // 价格动画控制器
  late AnimationController _priceAnimationController;
  late Animation<double> _priceAnimation;
  // 选中的规格
  String? _selectedSpec;

  @override
  void initState() {
    super.initState();
    // 初始化价格动画
    _priceAnimationController = AnimationController(
      vsync: this,
      duration: const Duration(milliseconds: 800),
    );
    // 弹性动画曲线
    _priceAnimation = Tween<double>(begin: 0, end: 1).animate(
      CurvedAnimation(
        parent: _priceAnimationController,
        curve: Curves.bounceOut,
      ),
    );
    // 加载商品数据
    _loadProductData();
  }

  @override
  void dispose() {
    _priceAnimationController.dispose();
    _refreshController.dispose();
    super.dispose();
  }

  // 加载商品数据
  Future<void> _loadProductData() async {
    setState(() {
      _isLoading = true;
      _errorMsg = null;
    });
    try {
      final product = await RequestUtil.getProductDetail(widget.productId);
      setState(() {
        _product = product;
        // 启动价格动画
        _priceAnimationController.forward(from: 0);
      });
    } catch (e) {
      setState(() {
        _errorMsg = e.toString();
      });
    } finally {
      setState(() {
        _isLoading = false;
      });
      // 结束刷新
      _refreshController.refreshCompleted();
    }
  }

  // 下拉刷新
  void _onRefresh() {
    _loadProductData();
  }

  // 分享商品图片到相册
  Future<void> _saveImageToGallery(String imageUrl) async {
    try {
      // 下载图片
      final response = await RequestUtil._dio.get(
        imageUrl,
        options: Options(responseType: ResponseType.bytes),
      );
      final Uint8List bytes = response.data;
      // 保存到相册
      final result = await ImageGallerySaver.saveImage(bytes);
      if (result['isSuccess']) {
        if (mounted) {
          ScaffoldMessenger.of(context).showSnackBar(
            const SnackBar(content: Text('图片保存成功')),
          );
        }
      } else {
        throw Exception('保存失败');
      }
    } catch (e) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('保存失败:$e')),
      );
    }
  }

  // 分享商品
  void _shareProduct() {
    if (_product == null) return;
    Share.share(
      '【${_product!.name}】仅售${_product!.price}元,快来抢购!\n图片:${_product!.imageUrls.first}',
      subject: '推荐一款好商品',
    );
  }

  // 选择规格弹窗
  void _showSpecDialog() {
    if (_product == null) return;
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: const Text('选择商品规格'),
        content: SingleChildScrollView(
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: _product!.specs
                .map((spec) => RadioListTile<String>(
                      title: Text(spec),
                      value: spec,
                      groupValue: _selectedSpec,
                      onChanged: (value) {
                        setState(() {
                          _selectedSpec = value;
                        });
                        Navigator.pop(context);
                      },
                    ))
                .toList(),
          ),
        ),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(context),
            child: const Text('取消'),
          ),
        ],
      ),
    );
  }

  // 加入购物车
  void _addToCart() {
    if (_product == null) return;
    if (_selectedSpec == null) {
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('请先选择商品规格')),
      );
      return;
    }
    // 获取购物车Provider
    final cartProvider = Provider.of<CartProvider>(context, listen: false);
    cartProvider.addToCart(_product!);
    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(content: Text('加入购物车成功')),
    );
  }

  // 构建加载中UI
  Widget _buildLoadingUI() {
    return const Center(
      child: CircularProgressIndicator(
        color: Colors.pink,
      ),
    );
  }

  // 构建错误UI
  Widget _buildErrorUI() {
    return Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          Text(
            _errorMsg!,
            style: TextStyle(color: Colors.red, fontSize: 14.sp),
            textAlign: TextAlign.center,
          ),
          SizedBox(height: 20.h),
          ElevatedButton(
            onPressed: _loadProductData,
            child: const Text('重新加载'),
          ),
        ],
      ),
    );
  }

  // 构建商品详情UI
  Widget _buildProductUI() {
    return SmartRefresher(
      controller: _refreshController,
      onRefresh: _onRefresh,
      header: const ClassicHeader(
        refreshingText: '正在刷新...',
        completeText: '刷新完成',
        failedText: '刷新失败',
      ),
      child: SingleChildScrollView(
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            // 商品轮播图
            Stack(
              children: [
                CarouselSlider(
                  items: _product!.imageUrls
                      .map((url) => CachedNetworkImage(
                            imageUrl: url,
                            fit: BoxFit.cover,
                            width: double.infinity,
                            height: 300.h,
                            placeholder: (context, url) => const Center(
                              child: CircularProgressIndicator(),
                            ),
                            errorWidget: (context, url, error) =>
                                const Icon(Icons.error),
                          ))
                      .toList(),
                  carouselController: _carouselController,
                  options: CarouselOptions(
                    height: 300.h,
                    initialPage: 0,
                    viewportFraction: 1.0,
                    autoPlay: true,
                    autoPlayInterval: const Duration(seconds: 3),
                    autoPlayAnimationDuration:
                        const Duration(milliseconds: 800),
                    onPageChanged: (index, reason) {
                      setState(() {
                        _currentIndex = index;
                      });
                    },
                  ),
                ),
                // 轮播指示器
                Positioned(
                  bottom: 10.h,
                  left: 0,
                  right: 0,
                  child: Row(
                    mainAxisAlignment: MainAxisAlignment.center,
                    children: _product!.imageUrls.asMap().entries.map((entry) {
                      return Container(
                        width: 8.w,
                        height: 8.w,
                        margin: EdgeInsets.symmetric(horizontal: 4.w),
                        decoration: BoxDecoration(
                          shape: BoxShape.circle,
                          color: _currentIndex == entry.key
                              ? Colors.white
                              : Colors.white.withOpacity(0.5),
                        ),
                      );
                    }).toList(),
                  ),
                ),
                // 分享按钮
                Positioned(
                  top: 40.h,
                  right: 10.w,
                  child: IconButton(
                    icon: const Icon(Icons.share, color: Colors.white),
                    onPressed: _shareProduct,
                  ),
                ),
                // 保存图片按钮
                Positioned(
                  top: 40.h,
                  left: 10.w,
                  child: IconButton(
                    icon: const Icon(Icons.download, color: Colors.white),
                    onPressed: () => _saveImageToGallery(
                      _product!.imageUrls[_currentIndex],
                    ),
                  ),
                ),
              ],
            ),
            // 商品信息
            Padding(
              padding: EdgeInsets.all(15.w),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  // 商品名称
                  Text(
                    _product!.name,
                    style: TextStyle(
                      fontSize: 18.sp,
                      fontWeight: FontWeight.bold,
                    ),
                    maxLines: 2,
                    overflow: TextOverflow.ellipsis,
                  ),
                  SizedBox(height: 10.h),
                  // 商品描述
                  Text(
                    _product!.desc,
                    style: TextStyle(
                      fontSize: 14.sp,
                      color: Colors.grey[600],
                    ),
                    maxLines: 3,
                    overflow: TextOverflow.ellipsis,
                  ),
                  SizedBox(height: 15.h),
                  // 价格区域(带动画)
                  AnimatedBuilder(
                    animation: _priceAnimation,
                    builder: (context, child) {
                      return Transform.scale(
                        scale: _priceAnimation.value,
                        child: child,
                      );
                    },
                    child: Row(
                      children: [
                        Text(
                          '¥${_product!.price.toStringAsFixed(2)}',
                          style: TextStyle(
                            fontSize: 22.sp,
                            color: Colors.pink,
                            fontWeight: FontWeight.bold,
                          ),
                        ),
                        SizedBox(width: 10.w),
                        Text(
                          '¥${_product!.originalPrice.toStringAsFixed(2)}',
                          style: TextStyle(
                            fontSize: 14.sp,
                            color: Colors.grey[500],
                            decoration: TextDecoration.lineThrough,
                          ),
                        ),
                      ],
                    ),
                  ),
                  SizedBox(height: 20.h),
                  // 规格选择
                  GestureDetector(
                    onTap: _showSpecDialog,
                    child: Container(
                      padding: EdgeInsets.symmetric(
                        horizontal: 15.w,
                        vertical: 12.h,
                      ),
                      decoration: BoxDecoration(
                        border: Border.all(color: Colors.grey[300]!),
                        borderRadius: BorderRadius.circular(8.r),
                      ),
                      child: Row(
                        mainAxisAlignment: MainAxisAlignment.spaceBetween,
                        children: [
                          Text(
                            _selectedSpec ?? '请选择商品规格',
                            style: TextStyle(fontSize: 14.sp),
                          ),
                          const Icon(Icons.arrow_forward_ios, size: 16),
                        ],
                      ),
                    ),
                  ),
                ],
              ),
            ),
          ],
        ),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    // 沉浸式状态栏
    return Scaffold(
      backgroundColor: Colors.white,
      appBar: AppBar(
        title: const Text('商品详情'),
        backgroundColor: Colors.pink,
        elevation: 0,
        // 沉浸式导航栏
        systemOverlayStyle: const SystemUiOverlayStyle(
          statusBarColor: Colors.transparent,
          statusBarIconBrightness: Brightness.light,
        ),
        // 购物车图标(显示数量)
        actions: [
          Consumer<CartProvider>(
            builder: (context, cartProvider, child) {
              return Badge(
                label: Text('${cartProvider.cartCount}'),
                isLabelVisible: cartProvider.cartCount > 0,
                child: IconButton(
                  icon: const Icon(Icons.shopping_cart),
                  onPressed: () {
                    // 可跳转到购物车页面
                    ScaffoldMessenger.of(context).showSnackBar(
                      SnackBar(
                        content: Text('购物车共有 ${cartProvider.cartCount} 件商品'),
                      ),
                    );
                  },
                ),
              );
            },
          ),
          SizedBox(width: 10.w),
        ],
      ),
      // 底部操作栏
      bottomNavigationBar: Container(
        height: 60.h,
        decoration: BoxDecoration(
          border: Border(top: BorderSide(color: Colors.grey[200]!)),
        ),
        child: Row(
          children: [
            // 收藏按钮
            Expanded(
              flex: 1,
              child: IconButton(
                icon: const Icon(Icons.favorite_border, color: Colors.grey),
                onPressed: () {
                  ScaffoldMessenger.of(context).showSnackBar(
                    const SnackBar(content: Text('收藏成功')),
                  );
                },
              ),
            ),
            // 加入购物车
            Expanded(
              flex: 2,
              child: ElevatedButton(
                onPressed: _addToCart,
                style: ElevatedButton.styleFrom(
                  backgroundColor: Colors.orange,
                  elevation: 0,
                  shape: const RoundedRectangleBorder(),
                ),
                child: const Text('加入购物车'),
              ),
            ),
            // 立即购买
            Expanded(
              flex: 2,
              child: ElevatedButton(
                onPressed: () {
                  if (_selectedSpec == null) {
                    ScaffoldMessenger.of(context).showSnackBar(
                      const SnackBar(content: Text('请先选择商品规格')),
                    );
                    return;
                  }
                  ScaffoldMessenger.of(context).showSnackBar(
                    const SnackBar(content: Text('跳转到结算页面')),
                  );
                },
                style: ElevatedButton.styleFrom(
                  backgroundColor: Colors.pink,
                  elevation: 0,
                  shape: const RoundedRectangleBorder(),
                ),
                child: const Text('立即购买'),
              ),
            ),
          ],
        ),
      ),
      body: _isLoading
          ? _buildLoadingUI()
          : (_errorMsg != null ? _buildErrorUI() : _buildProductUI()),
    );
  }
}

4. 应用入口(lib/main.dart)

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:flutter_screenutil/flutter_screenutil.dart';
import 'providers/cart_provider.dart';
import 'pages/product_detail.dart';

void main() {
  runApp(
    ScreenUtilInit(
      designSize: const Size(375, 812),
      minTextAdapt: true,
      splitScreenMode: true,
      child: MultiProvider(
        providers: [
          ChangeNotifierProvider(create: (context) => CartProvider()),
        ],
        child: const MyApp(),
      ),
    ),
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter 电商详情页',
      theme: ThemeData(
        primarySwatch: Colors.pink,
        useMaterial3: true,
      ),
      home: const ProductDetailPage(productId: '1'), // 测试商品ID
      debugShowCheckedModeBanner: false,
    );
  }
}

四、核心功能解析

1. 沉浸式 UI 设计

  • 状态栏适配:通过 AppBar 的 systemOverlayStyle 设置状态栏为透明,文字为白色,实现沉浸式导航栏;
  • 屏幕适配:使用 flutter_screenutil 基于设计稿尺寸(375x812)自动适配不同屏幕,避免硬编码尺寸;
  • 底部操作栏:固定底部的购买 / 加购按钮,区分颜色层级,符合电商用户习惯。

2. 流畅动画效果

  • 价格动画:使用 AnimationController + CurvedAnimation 实现价格缩放的弹性动画,增强视觉吸引力;
  • 轮播动画:carousel_slider 自带自动播放、淡入淡出动画,支持无限循环;
  • 下拉刷新动画:pull_to_refresh 提供经典的下拉刷新动效,支持自定义文案。

3. 原生能力交互

  • 分享功能:通过 share_plus 调用系统分享面板,支持文本 + 图片分享;
  • 保存图片到相册:image_gallery_saver 结合 Dio 下载图片字节流,保存到系统相册,兼容 iOS/Android;
  • Badge 角标:购物车图标显示商品数量角标,符合原生应用体验。

4. 状态管理与性能优化

  • Provider 跨组件共享:购物车状态全局共享,详情页和 AppBar 可实时获取商品数量;
  • 图片缓存:cached_network_image 缓存网络图片,避免重复请求,提升加载速度;
  • 懒加载列表:SingleChildScrollView 包裹内容,仅渲染可视区域,减少内存占用;
  • 动画资源释放:在 dispose 中销毁动画控制器和刷新控制器,避免内存泄漏。

五、运行与调试

1. 运行前准备

  • 替换 mockapi.io 的测试接口为实际接口(或自行创建 mock 数据)
  • <key>NSPhotoLibraryAddUsageDescription</key>
    <string>需要访问相册以保存商品图片</string>
    
  • Android 需在 AndroidManifest.xml 中添加权限:
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
    

2. 运行效果

  • 页面加载时显示加载动画,失败时展示错误提示和重试按钮;
  • 商品轮播图自动播放,底部指示器同步更新,支持手动滑动;
  • 价格区域有弹性缩放动画,原价划线显示,现价突出展示;
  • 下拉刷新可重新加载商品数据;
  • 点击规格区域弹出选择弹窗,选中后显示当前规格;
  • 点击分享按钮调用系统分享,点击下载按钮保存图片到相册;
  • 加入购物车需先选规格,成功后购物车角标数量增加;
  • 底部立即购买 / 加入购物车按钮区分颜色,交互反馈清晰。

六、进阶优化方向

1. 性能优化

  • 列表优化:商品详情下方的评价 / 参数区域使用 ListView.builder 懒加载;
  • 预加载:提前加载下一张轮播图,避免滑动时卡顿;
  • 内存优化:监听页面可见状态,离开页面时暂停轮播动画。

2. 功能扩展

  • 加入购物车动画:商品图片飞入购物车的抛物线动画;
  • 规格选择优化:自定义规格弹窗,支持多规格组合(如颜色 + 尺寸);
  • 下拉加载更多:商品详情下方加载评价、推荐商品等;
  • 本地缓存:使用 hive/shared_preferences 缓存商品数据,离线也能查看。

3. 原生交互增强

  • 调用相机 / 相册:选择商品规格时支持上传自定义图片;
  • 支付集成:接入微信 / 支付宝支付 SDK;
  • 推送通知:集成 Firebase Cloud Messaging 或极光推送,推送商品优惠信息。

七、总结

本文以电商商品详情页为场景,覆盖了 Flutter 进阶开发的核心能力:

  1. 沉浸式 UI 设计:适配状态栏、屏幕尺寸,符合移动端交互规范;
  2. 动画系统:基础动画、组合动画的实际应用;
  3. 原生交互:调用系统分享、相册等能力,提升原生体验;
  4. 状态管理:Provider 全局状态共享,跨组件通信;
  5. 性能优化:图片缓存、资源释放、懒加载等实战技巧。

该案例可直接作为电商类 App 的基础模板,通过扩展规格选择、评价、推荐商品等模块,可快速落地为生产级应用。Flutter 的优势在于一套代码覆盖 iOS/Android,同时通过原生插件桥接,能充分调用平台能力,兼顾开发效率和用户体验

Logo

电商企业物流数字化转型必备!快递鸟 API 接口,72 小时快速完成物流系统集成。全流程实战1V1指导,营造开放的API技术生态圈。

更多推荐