Flutter 滑动面板组件（修复版）

Flutter 滑动面板组件 SlidingUpPanel2 详解

本文将介绍一款功能强大的 Flutter 滑动面板组件 SlidingUpPanel2，它支持上下滑动、吸附效果、视差背景等丰富特性，非常适合实现类似地图应用底部信息面板、电商商品详情页等交互场景。

---

一、组件概述

SlidingUpPanel2 是一个高度可定制的滑动面板组件，主要特性包括：

• 支持上下两个方向的滑动
• 可设置最小/最大高度
• 吸附点（snap point）功能
• 背景遮罩与点击关闭
• 视差滚动效果
• 与滚动视图的智能交互
• 丰富的自定义样式（圆角、阴影等）

二、基本使用

PanelController _panelController = PanelController();

SlidingUpPanel(
  controller: _panelController,
  minHeight: 100,
  maxHeight: 500,
  panelBuilder: () => buildPanelContent(),
  body: Scaffold(
    // 主页面内容
  ),
),

控制面板状态：

// 打开面板
_panelController.open(); 

// 关闭面板
_panelController.close();

// 设置面板位置 (0.0-1.0)
_panelController.animatePanelToPosition(0.7);

---

三、核心参数详解

参数	类型	说明
panelBuilder	Widget? Function()?	必填，构建面板内容
minHeight	double	折叠状态高度（默认100）
maxHeight	double	展开状态高度（默认500）
snapPoint	double?	吸附点位置（0.0-1.0）
body	Widget?	主页面内容
collapsed	Widget?	折叠时顶部显示的内容
header/footer	Widget?	固定在面板顶部/底部的组件
slideDirection	SlideDirection	滑动方向（UP/DOWN）
backdropEnabled	bool	启用背景遮罩（默认false）
parallaxEnabled	bool	启用视差效果（默认false）

---

四、高级功能

1. 智能滚动交互

当面板完全展开时，组件会自动检测滚动视图的状态：

SlidingUpPanel(
  disableDraggableOnScrolling: true,
  scrollController: _scrollController,
  //...
)

2. 特殊场景处理

使用辅助组件处理复杂交互：

// 强制允许拖拽区域
ForceDraggableWidget(child: ...)

// 忽略拖拽区域
IgnoreDraggableWidget(child: ...)

// 水平滚动区域
HorizontalScrollableWidget(child: ...)

3. 面板控制器

final PanelController controller = PanelController();

// 强制滚动更新
controller.forseScrollChange(
  _scrollController.animateTo(100, duration: 400.ms)
);

// 获取面板状态
double position = controller.panelPosition;
bool isOpen = controller.isPanelOpen;

---

五、完整示例

PanelController _panelController = PanelController();

@override
Widget build(BuildContext context) {
  return Scaffold(
    body: SlidingUpPanel(
      controller: _panelController,
      minHeight: 80,
      maxHeight: MediaQuery.of(context).size.height * 0.8,
      snapPoint: 0.5,
      backdropEnabled: true,
      borderRadius: BorderRadius.vertical(top: Radius.circular(20)),
      panelBuilder: () => ListView(
        controller: _scrollController,
        children: [/* 面板内容 */],
      ),
      collapsed: Container(
        padding: EdgeInsets.all(15),
        child: Text("上拉查看详情", style: TextStyle(color: Colors.blue)),
      ),
      body: MapWidget(), // 主地图组件
    ),
  );
}

---

六、注意事项

1. 滚动冲突处理 ：当面板包含滚动视图时，原代码有bug，建议设置 disableDraggableOnScrolling: true核心处理代码在_onGestureSlide()方法中

2. 性能优化 ：避免在 panelBuilder 中构建过于复杂的布局

3. 吸附点设置 ：snapPoint 值需在 0.0-1.0 之间（不包括边界值）

4. 方向适配 ：使用 slideDirection 可轻松切换上下滑动方向

完整代码及示例：源文件地址 感谢：sliding_up_panel2: ^3.3.0+1

---