# flutter_card_banner

**Repository Path**: adaataiamu/flutter_card_banner

## Basic Information

- **Project Name**: flutter_card_banner
- **Description**: 翻转卡片banner库
- **Primary Language**: Dart
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-22
- **Last Updated**: 2025-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flutter Card Banner

A Flutter package providing a customizable card carousel with vertical-axis 3D flip animation effects.

## 功能特点

- 横向切换的轮播图，支持自动轮播和手势操作
- 支持循环和不循环两种模式
- 真正的3D翻转切换效果，以卡片垂直中轴线为旋转轴，类似垃圾桶盖翻转
- 支持为每张卡片设置单独的背面内容
- 手势拖动过程中实时控制卡片翻转角度
- 自定义卡片停留时间和动画时间
- 支持页面变化回调函数

## 安装

在 `pubspec.yaml` 文件中添加依赖:

```yaml
dependencies:
  flutter_card_banner: ^0.0.1
```

## 使用方法

```dart
import 'package:flutter/material.dart';
import 'package:flutter_card_banner/flutter_card_banner.dart';

// 在你的Widget中使用
CardBanner(
  children: <Widget>[
    Card(child: Center(child: Text('卡片 1 正面'))),
    Card(child: Center(child: Text('卡片 2 正面'))),
    Card(child: Center(child: Text('卡片 3 正面'))),
  ],
  backSideChildren: <Widget>[ // 可选的背面内容
    Card(child: Center(child: Text('卡片 1 背面'))),
    Card(child: Center(child: Text('卡片 2 背面'))),
    Card(child: Center(child: Text('卡片 3 背面'))),
  ],
  autoPlay: true,  // 是否自动播放
  loop: true,      // 是否循环
  duration: 3000,  // 停留时间(毫秒)
  animationDuration: 800, // 动画时间(毫秒)
  onPageChanged: (page) {
    print('当前页: $page');
  },
)
```

## 参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| children | List\<Widget\> | 必填 | 轮播的子项目(卡片) |
| backSideChildren | List\<Widget\>? | null | 卡片的背面内容，须与children长度相同 |
| loop | bool | true | 是否循环播放 |
| autoPlay | bool | true | 是否自动播放 |
| duration | int | 3000 | 每个卡片停留的时间(毫秒) |
| animationDuration | int | 800 | 切换动画的时间(毫秒) |
| cardWidth | double? | null | 卡片的宽度，默认撑满容器 |
| cardHeight | double? | null | 卡片的高度，默认撑满容器 |
| padding | EdgeInsetsGeometry? | null | 卡片的边距 |
| onPageChanged | Function(int)? | null | 页面变化回调 |

## 翻转效果说明

与普通的水平滑动轮播不同，这个组件有以下特点：

1. 卡片在垂直中轴线上翻转，不进行水平平移
2. 类似于垃圾桶盖的翻转效果
3. 手指拖动时，卡片翻转角度实时跟随手指移动距离百分比
4. 松开手指后，根据翻转角度决定是否完成翻转或恢复原状

## 示例

查看 `/example` 目录获取完整的示例应用。