Flutter轮播组件插件flutter_carousel_widget的使用

简介

flutter_carousel_widget 是一个为Flutter提供的可定制化轮播组件，它提供了诸如无限滚动、自动滚动、自定义子组件、预构建指示器、可扩展子组件、自动调整大小支持和放大中心页等功能。

更多详情请访问 GitHub项目主页。

安装

在您的 pubspec.yaml 文件中添加依赖：

dependencies:
  flutter_carousel_widget: ^latest_version

然后运行 flutter pub get 来获取包。

使用示例

使用 FlutterCarousel 组件

FlutterCarousel 是一个支持无限滚动、自动滚动、自定义子组件、自定义动画和预构建指示器的轮播组件。

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

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Flutter Carousel Demo')),
        body: Center(
          child: FlutterCarousel(
            options: FlutterCarouselOptions(
              height: 400.0,
              showIndicator: true,
              slideIndicator: CircularSlideIndicator(),
            ),
            items: [1,2,3,4,5].map((i) {
              return Builder(
                builder: (BuildContext context) {
                  return Container(
                    width: MediaQuery.of(context).size.width,
                    margin: EdgeInsets.symmetric(horizontal: 5.0),
                    decoration: BoxDecoration(
                      color: Colors.amber
                    ),
                    child: Text('text $i', style: TextStyle(fontSize: 16.0),)
                  );
                },
              );
            }).toList(),
          ),
        ),
      ),
    );
  }
}

使用 ExpandableCarousel 组件

ExpandableCarousel 是一个可以自动扩展以适应其子组件大小的轮播组件，适用于展示不同大小的子组件。

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

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Expandable Carousel Demo')),
        body: Center(
          child: ExpandableCarousel(
            options: ExpandableCarouselOptions(
              autoPlay: true,
              autoPlayInterval: const Duration(seconds: 2),
            ),
            items: [1,2,3,4,5].map((i) {
              return Builder(
                builder: (BuildContext context) {
                  return Container(
                    width: MediaQuery.of(context).size.width,
                    margin: EdgeInsets.symmetric(horizontal: 5.0),
                    decoration: BoxDecoration(
                      color: Colors.amber
                    ),
                    child: Text('text $i', style: TextStyle(fontSize: 16.0),)
                  );
                },
              );
            }).toList(),
          ),
        ),
      ),
    );
  }
}

自定义选项

您可以根据需要对轮播组件进行详细的配置，例如设置高度、宽高比、视口比例等。以下是一个完整的配置示例：

FlutterCarousel(
  items: items,
  options: FlutterCarouselOptions(
    height: 400.0, // 设置轮播组件的高度
    aspectRatio: 16 / 9, // 定义轮播组件的宽高比
    viewportFraction: 1.0, // 每个页面占据视口的比例
    initialPage: 0, // 初始显示的页面
    enableInfiniteScroll: true, // 启用无限循环
    reverse: false, // 是否反转轮播方向
    autoPlay: true, // 启用自动滚动
    autoPlayInterval: const Duration(seconds: 2), // 自动滚动的时间间隔
    autoPlayAnimationDuration: const Duration(milliseconds: 800), // 自动滚动动画时长
    autoPlayCurve: Curves.fastOutSlowIn, // 自动滚动动画曲线
    enlargeCenterPage: true, // 放大中心页面
    controller: FlutterCarouselController(), // 控制器
    onPageChanged: (index) {}, // 页面变化时的回调函数
    pageSnapping: true, // 启用页面吸附效果
    scrollDirection: Axis.horizontal, // 滚动方向（水平或垂直）
    pauseAutoPlayOnTouch: true, // 触摸时暂停自动滚动
    pauseAutoPlayOnManualNavigate: true, // 手动导航时暂停自动滚动
    pauseAutoPlayInFiniteScroll: false, // 无限滚动模式下暂停自动滚动
    enlargeStrategy: CenterPageEnlargeStrategy.scale, // 中心页面放大策略
    disableCenter: false, // 禁用居中
    showIndicator: true, // 显示指示器
    floatingIndicator: true, // 悬浮指示器
    slideIndicator: CircularSlideIndicator(), // 自定义指示器
  ),
)

动态加载项

为了节省内存，您可以按需构建子组件，只有当它们即将显示时才会创建。

FlutterCarousel.builder(
  itemCount: 15,
  itemBuilder: (BuildContext context, int itemIndex, int pageViewIndex) =>
  Container(
    child: Text(itemIndex.toString()),
  ),
)

轮播控制器

通过 FlutterCarouselController 可以手动控制轮播的位置和行为。

class CarouselDemo extends StatelessWidget {
  final FlutterCarouselController buttonCarouselController = FlutterCarouselController();

  @override
  Widget build(BuildContext context) => Column(
    children: [
      FlutterCarousel(
        items: child,
        options: FlutterCarouselOptions(
          autoPlay: false,
          controller: buttonCarouselController,
          enlargeCenterPage: true,
          viewportFraction: 0.9,
          aspectRatio: 2.0,
          initialPage: 2,
        ),
      ),
      ElevatedButton(
        onPressed: () => buttonCarouselController.nextPage(
            duration: Duration(milliseconds: 300), curve: Curves.linear),
        child: Text('→'),
      )
    ]
  );
}

预定义滑动指示器

flutter_carousel_widget 提供了几种预定义的滑动指示器，每种都有其独特的样式和行为。您可以通过传递 SlideIndicatorOptions 来自定义这些指示器。

FlutterCarousel(
  ...
  options: FlutterCarouselOptions(
    ...
    slideIndicator: CircularSlideIndicator(
      slideIndicatorOptions: SlideIndicatorOptions(
        alignment: Alignment.bottomCenter,
        currentIndicatorColor: Colors.white,
        indicatorBackgroundColor: Colors.white.withOpacity(0.5),
        indicatorBorderColor: Colors.white,
        indicatorBorderWidth: 1,
        indicatorRadius: 6,
        itemSpacing: 20,
        padding: const EdgeInsets.all(8.0),
        haloDecoration: BoxDecoration(
          borderRadius: const BorderRadius.all(Radius.circular(15.0)),
          color: Colors.black.withOpacity(0.5),
        ),
        haloPadding: const EdgeInsets.all(8.0),
        enableHalo: true,
        enableAnimation: true,
      ),
    ),
  ),
);

自定义滑动指示器

如果您想要完全控制滑动指示器的外观或行为，可以通过实现 SlideIndicator 接口来创建自定义指示器。

class SlidePercentageIndicator implements SlideIndicator {
  SlidePercentageIndicator({
    this.decimalPlaces = 0,
    this.style,
  });

  final int decimalPlaces;
  final TextStyle? style;

  @override
  Widget build(int currentPage, double pageDelta, int itemCount) {
    if (itemCount < 2) return const SizedBox.shrink();
    final step = 100 / (itemCount - 1);
    final percentage = step * (pageDelta + currentPage);
    return Center(
      child: Text(
        '${percentage.toStringAsFixed(decimalPlaces)}%',
        style: style ??
            const TextStyle(
              fontSize: 24,
              fontWeight: FontWeight.w600,
            ),
      ),
    );
  }
}

希望这些内容能帮助您更好地理解和使用 flutter_carousel_widget 插件。如果有任何问题或建议，请随时联系我！