如何使用自定义JSON API实现类似Instagram的Flutter Stories功能

1. 数据层处理 #

你已经可以通过API获取JSON格式数据，第一步先完成数据对接与模型定义：

• 先根据接口返回的字段定义Dart实体类，推荐用json_serializable或freezed自动生成序列化/反序列化代码，避免手动解析出错
• 常规的Stories数据结构至少包含：用户基础信息（ID、昵称、头像、已读状态）、单条故事集合（内容类型、资源地址、时长、发布时间）
• 用dio等网络请求库拉取接口数据后，直接转成对应的Dart模型对象，后续业务逻辑直接操作模型即可

2. 基础UI组件实现 #

• 首页头像滚动条：用横向ListView实现，每个条目展示用户头像+昵称，未读用户的头像外圈加Instagram风格的彩色渐变边框，已读用户显示灰色边框，点击条目跳转到对应Stories播放页
• Stories播放主页面：外层用PageView.builder实现横向滑动切换不同用户的故事集合，禁止页面自动回弹，滑到首尾边界时触发关闭操作
• 单用户故事内容区：每个页面对应用户的所有故事，顶部放一排等宽的线性进度条，数量对应当前用户的故事总数，进度条进度和当前故事的播放进度同步

3. 核心交互与动画实现 #

这部分是和Instagram效果对齐的核心：

• 自动播放控制：用AnimationController实现单条故事的倒计时，图片类故事默认时长设为5秒，视频类故事取视频本身的时长，动画进度同步给顶部进度条，当前故事播放完成后自动切到下一条，当前用户所有故事播放完成后自动滑动到下一个用户的故事集合
• 手势操作：用GestureDetector监听全局手势：
  • 单击左侧1/3屏幕：切换到当前用户的上一条故事，重置动画控制器
  • 单击右侧2/3屏幕：切换到当前用户的下一条故事，重置动画控制器
  • 长按屏幕：暂停动画控制器和视频播放，松开后恢复播放
• 页面过渡：打开Stories页面时用Hero动画，从首页点击的用户头像过渡到Stories页面顶部的用户头像，关闭页面时做反向过渡，完全对齐Instagram的动效

4. 优化与边缘情况处理 #

• 缓存优化：图片类内容用cached_network_image实现本地缓存，视频类内容提前预加载下一条故事的资源，减少加载空白时间；本地用shared_preferences或Hive存储用户的已读状态，打开首页时直接标记已读用户的头像边框
• 异常处理：资源加载失败时显示占位图和重试按钮，网络异常时提示用户重试
• 边界处理：用户在第一个用户的故事左滑、或者最后一个用户的故事右滑时，自动关闭Stories页面回到首页；单用户只有1条故事时，顶部只显示1条进度条

核心进度控制代码参考：

late AnimationController _storyController;

@override
void initState() {
  super.initState();
  // 初始化控制器，时长根据当前故事类型动态设置
  _storyController = AnimationController(
    vsync: this,
    duration: currentStory.type == 'video' 
        ? Duration(seconds: currentStory.duration) 
        : const Duration(seconds: 5),
  );
  // 监听播放完成事件
  _storyController.addListener(() {
    setState(() {});
    if (_storyController.status == AnimationStatus.completed) {
      _switchToNextStory();
    }
  });
  _storyController.forward();
}

// 点击手势处理
void _handleTap(TapDownDetails details) {
  final screenWidth = MediaQuery.of(context).size.width;
  // 点击左侧切上一条
  if (details.localPosition.dx < screenWidth / 3) {
    _switchToPrevStory();
  } 
  // 点击右侧切下一条
  else {
    _switchToNextStory();
  }
}

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

内容的提问来源于stack exchange，提问作者Wasiq Hussain