Flutter 故事页面展示插件 story_page_view 的使用

特性

story_page_view 是一个高度可定制的 Flutter 实现，用于展示类似 Instagram 故事页面视图。它可以渲染一个页面视图，在给定的时间后自动翻到下一页。此外，还可以包含带有动画计时器的页面指示器。

开始使用

在 pubspec.yaml 文件中添加 story_page_view：

flutter pub add story_page_view

使用方法

基本用法

该组件非常易于使用：

import 'package:flutter/material.dart';
import 'package:story_page_view/story_page_view.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('StoryPageView 示例')),
        body: StoryPageView(
          children: [
            Container(color: Colors.red),
            Container(color: Colors.orange),
            Container(color: Colors.yellow),
            Container(color: Colors.green),
            Container(color: Colors.blue),
            Container(color: Colors.indigo),
            Container(color: Colors.purple),
          ],
        ),
      ),
    );
  }
}

更改故事持续时间

可以轻松更改每页的计时器时间：

StoryPageView(
  storyDuration: const Duration(seconds: 5),
)

程序化控制页面

与 PageView 类似，StoryPageView 使用 StoryPageController 来控制其行为。StoryPageController 是一种特殊的 PageController，它支持所有来自 PageController 的功能。

自定义分页动画

除了 PageController，StoryPageController 还控制分页动画。可以通过 StoryPageController 自定义分页动画：

StoryPageView(
  controller: StoryPageController(
    pagingCurve: Curves.elasticOut,
    pagingDuration: const Duration(milliseconds: 2000),
  ),
)

自定义页面指示器样式

可以自定义页面指示器的样式：

StoryPageView(
  indicatorStyle: StoryPageIndicatorStyle(
    height: 6,
    gap: 12,
    unvisitedColor: Colors.blue.shade200,
    visitedColor: Colors.blue.shade900,
    timerBarBackgroundColor: Colors.blue.shade300, // 默认为 unvisitedColor
    timerBarColor: Colors.blue.shade700, // 默认为 visitedColor
    shape: RoundedRectangleBorder(
      borderRadius: BorderRadius.circular(12),
    ),
  ),
)

将页面指示器作为覆盖层

当 StoryPageIndicatorPosition.overlay 用于 indicatorPosition 时，页面指示器将被渲染为浮动在内容顶部的覆盖层，并且可以通过绝对坐标来定位：

// 对齐到顶部中间
StoryPageView(
  indicatorPosition: StoryPageIndicatorPosition.overlay(
    top: 32,
    left: 12,
    right: 12,
  ),
)

// 或者对齐到底部中间
StoryPageView(
  indicatorPosition: StoryPageIndicatorPosition.overlay(
    bottom: 32,
    left: 12,
    right: 12,
  ),
)

自定义布局

实际上，该组件允许开发者通过使用 StoryPageIndicatorPosition.custom 来完全控制布局。需要声明预期布局的特殊构建函数，PageView 和 StoryPageIndicator 的实例将作为参数传递给构建函数。

例如，以下代码将页面指示器和页面视图放在一个列中：

StoryPageView(
  indicatorPosition: StoryPageIndicatorPosition.custom(
    layoutBuilder: (c, pageView, indicator) => SafeArea(
      child: Column(
        children: [
          Padding(
            padding: const EdgeInsets.symmetric(vertical: 8, horizontal: 12),
            child: indicator, // 页面指示器
          ),
          Expanded(
            child: pageView, // 页面视图
          ),
        ],
      ),
    ),
  ),
)

完全自定义的 StoryPageView

可以完全自定义 StoryPageView：

StoryPageView(
  // 自定义指示器外观
  indicatorStyle: StoryPageIndicatorStyle(
    height: 6,
    gap: 12,
    unvisitedColor: Colors.blue.shade200,
    visitedColor: Colors.blue.shade900,
    timerBarBackgroundColor: Colors.blue.shade300, // 默认为 unvisitedColor
    timerBarColor: Colors.blue.shade700, // 默认为 visitedColor
    shape: RoundedRectangleBorder(
      borderRadius: BorderRadius.circular(12),
    ),
  ),
  controller: StoryPageController(
    // 自定义分页动画样式
    pagingCurve: Curves.elasticOut,
    pagingDuration: const Duration(milliseconds: 2000),
  ),
  storyDuration: const Duration(seconds: 5),
  // 自定义整体布局
  indicatorPosition: StoryPageIndicatorPosition.custom(
    layoutBuilder: (c, pageView, indicator) => SafeArea(
      child: Column(
        children: [
          // 将页面指示器放置在页面上方
          Padding(
            padding: const EdgeInsets.symmetric(vertical: 8, horizontal: 12),
            child: indicator,
          ),
          Expanded(
            child: pageView,
          ),
        ],
      ),
    ),
  ),
  children: [
    Container(color: Colors.red),
    Container(color: Colors.orange),
    Container(color: Colors.yellow),
    Container(color: Colors.green),
    Container(color: Colors.blue),
    Container(color: Colors.indigo),
    Container(color: Colors.purple),
  ],
)

无页面指示器

有时开发者可能想要隐藏页面指示器，这可以通过使用 StoryPageIndicatorPosition.none 来实现：

StoryPageView(
  storyDuration: const Duration(seconds: 1),
  // 无页面指示器，仅显示计时器
  indicatorPosition: const StoryPageIndicatorPosition.none(),
  // 使视口宽度仅为屏幕宽度的 95%
  controller: StoryPageController(
    viewportFraction: 0.95,
  ),
  children: [
    Container(color: Colors.red),
    Container(color: Colors.orange),
    Container(color: Colors.yellow),
    Container(color: Colors.green),
    Container(color: Colors.blue),
    Container(color: Colors.indigo),
    Container(color: Colors.purple),
  ],
),