Flutter轮播图插件 page_swiper 的使用

page_swiper 是一个用于构建多页面滚动UI的Flutter插件，提供了简单的API和充分的自定义选项。它特别适合需要带有标题栏或过渡动画的复杂UI设计。

特性

• 支持创建水平可滚动的 PageView
• 提供持久化的标题栏，并支持每个页面的标题、副标题和操作按钮
• 处理设计和过渡动画，帮助开发者更专注于页面逻辑

示例效果

开始使用

首先，在 pubspec.yaml 文件中添加依赖：

dependencies:
  page_swiper: ^latest_version

然后运行以下命令安装包：

flutter pub add page_swiper

使用方法

初始化控制器

在你的根页面组件中初始化 PageController 和多个 ScrollController，每个页面对应一个 ScrollController。

class MainPage extends StatefulWidget {
  static const pageNum = 2;

  const MainPage({
    this.initialPage = 1,
    this.titleHeight = 250,
    this.titleHeightCollapsed = 100,
    super.key,
  });

  final int initialPage;
  final double titleHeight;
  final double titleHeightCollapsed;

  @override
  State<MainPage> createState() => _MainPageState();
}

class _MainPageState extends State<MainPage> {
  late PageController _pageController;
  late List<ScrollController> _pageScrollControllers;

  @override
  void initState() {
    _pageController = PageController(initialPage: widget.initialPage);
    _pageScrollControllers = [
      for (int i = 0; i < MainPage.pageNum; i++) ScrollController()
    ];
    super.initState();
  }

  @override
  void dispose() {
    _pageController.dispose();
    for (var controller in _pageScrollControllers) {
      controller.dispose();
    }
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: PageSwiper(
        pageNum: 2,
        pageController: _pageController,
        titleHeight: widget.titleHeight,
        titleHeightCollapsed: widget.titleHeightCollapsed,
        titleFilterBackground: Colors.white.withAlpha(150),
        titleFilterSigma: 50,
        blurByPage: false,
        titleMaxExtend: 1.3,
        titles: [
          PageTitle.builder(
            title: "All Photos",
            subtitle: "All photo page",
            actions: [
              TextButton(
                onPressed: () {},
                style: TextButton.styleFrom(tapTargetSize: MaterialTapTargetSize.shrinkWrap),
                child: const Text("Select"),
              ),
            ],
          ),
          PageTitle.builder(
            title: "Albums",
            subtitle: "Photo albums",
          ),
        ],
        pages: [
          PageContainer.childBuilder(
            child: FirstPage(
              controller: _pageScrollControllers[0],
              titleHeight: widget.titleHeight,
            ),
          ),
          PageContainer.childBuilder(
            child: SecondPage(
              controller: _pageScrollControllers[1],
              titleHeight: widget.titleHeight,
            ),
          ),
        ],
        pageScrollControllers: _pageScrollControllers,
      ),
    );
  }
}

设置标题

标题通过 PageTitle.builder 构建，可以在其中设置标题文本、副标题文本以及操作按钮。

PageTitle.builder(
  title: "Page 1",
  subtitle: "Page 1 subtitle",
  actions: [
    TextButton(onPressed: () {}, child: const Text("Push Me")),
  ],
)

设置页面

页面通过 PageContainerBuilder 构建。每个页面应当是一个继承自 CustomScrollView 的组件，并且需要包含一个 PageTitlePlaceholder 来预留标题栏的空间。

import 'package:flutter/material.dart';

class DemoPage extends StatefulWidget {
  const DemoPage({
    required this.controller,
    required this.titleHeight,
    super.key,
  });

  final ScrollController controller;
  final double titleHeight;

  @override
  State<DemoPage> createState() => _DemoPageState();
}

class _DemoPageState extends State<DemoPage> with AutomaticKeepAliveClientMixin {
  @override
  bool get wantKeepAlive => true;

  @override
  Widget build(BuildContext context) {
    super.build(context);
    return Stack(
      children: [
        Positioned.fill(
          child: CustomScrollView(
            controller: widget.controller,
            physics: const BouncingScrollPhysics(parent: AlwaysScrollableScrollPhysics()),
            slivers: [
              PageTitlePlaceholder(height: widget.titleHeight),
              // 其他Sliver组件
            ],
          ),
        ),
      ],
    );
  }
}

最后，使用 PageContainer.childBuilder 将页面加入到 PageSwiper 的 pages 列表中：

PageContainer.childBuilder(
  child: DemoPage(
    controller: _pageScrollControllers[0],
    titleHeight: widget.titleHeight,
  ),
)