Skip to main content

antd_refresh 1.0.1 copy "antd_refresh: ^1.0.1" to clipboard
antd_refresh: ^1.0.1 copied to clipboard

Ant Design pull-to-refresh for Flutter - indicator states, drag thresholds and smooth scroll integration.

example/lib/main.dart

/// antd_refresh example — AntPullToRefresh / AntInfiniteScroll 演示画廊。
///
/// - 主题经 antd_theme(P03 桥接)注入:`AntThemeData.light/dark().toThemeData()`
/// - 画廊模式:侧栏分区 + 分区内容,覆盖 PullToRefresh 全部关键形态
/// - R34 国际化:语言切换控件演示 `AntPullToRefresh.locale` 文案变化
library;

import 'package:antd_refresh/antd_refresh.dart';
import 'package:antd_theme/antd_theme.dart';
import 'package:material_ui/material_ui.dart';
import 'package:antd_icons_flutter/antd_icons_flutter.dart';

void main() {
  runApp(const AntdRefreshGalleryApp());
}

/// 演示分区定义。
class _Section {
  const _Section(this.title, this.builder);

  final String title;
  final WidgetBuilder builder;
}

/// antd 刷新画廊根组件。
class AntdRefreshGalleryApp extends StatefulWidget {
  const AntdRefreshGalleryApp({super.key});

  @override
  State<AntdRefreshGalleryApp> createState() => _AntdRefreshGalleryAppState();
}

class _AntdRefreshGalleryAppState extends State<AntdRefreshGalleryApp> {
  bool _isDark = false;

  static const List<_Section> _sections = [
    _Section('基础下拉刷新', _basicSection),
    _Section('桌面滚轮刷新', _wheelSection),
    _Section('国际化切换', _localeSection),
    _Section('自定义文案', _customTextSection),
    _Section('自定义 Header', _customHeaderSection),
    _Section('嵌入滚动视图', _scrollViewsSection),
    _Section('多级嵌套', _nestedSection),
    _Section('组合 InfiniteScroll', _comboSection),
  ];

  @override
  Widget build(BuildContext context) {
    final theme = _isDark ? AntThemeData.dark() : AntThemeData.light();
    return AntTheme(
      data: theme,
      child: MaterialApp(
          title: 'Ant Design Refresh',
          debugShowCheckedModeBanner: false,
          themeMode: _isDark ? ThemeMode.dark : ThemeMode.light,
          theme: AntThemeData.light().toThemeData(),
          darkTheme: AntThemeData.dark().toThemeData(),
          home: _GalleryPage(
            sections: _sections,
            isDark: _isDark,
            onToggleDark: () => setState(() => _isDark = !_isDark),
          ),
        ),
    );
  }
}

/// 画廊页面:左侧分区导航 + 右侧内容。
class _GalleryPage extends StatefulWidget {
  const _GalleryPage({
    required this.sections,
    required this.isDark,
    required this.onToggleDark,
  });

  final List<_Section> sections;
  final bool isDark;
  final VoidCallback onToggleDark;

  @override
  State<_GalleryPage> createState() => _GalleryPageState();
}

class _GalleryPageState extends State<_GalleryPage> {
  int _selectedIndex = 0;

  @override
  Widget build(BuildContext context) {
    final theme = AntTheme.of(context);
    final section = widget.sections[_selectedIndex];
    return Scaffold(
      body: Row(
        children: [
          // 侧栏导航
          Container(
            width: 220,
            color: theme.colorBgLayout,
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.stretch,
              children: [
                Padding(
                  padding: const EdgeInsets.all(16),
                  child: Row(
                    children: [
                      Expanded(
                        child: Text(
                          'Refresh 下拉刷新',
                          style: TextStyle(
                            fontSize: 16,
                            fontWeight: FontWeight.w600,
                            color: theme.colorText,
                          ),
                        ),
                      ),
                      IconButton(
                        tooltip: widget.isDark ? '切换亮色' : '切换暗色',
                        icon: Icon(
                          widget.isDark
                              ? AntIcons.sunOutlined
                              : AntIcons.moonOutlined,
                          color: theme.colorText,
                        ),
                        onPressed: widget.onToggleDark,
                      ),
                    ],
                  ),
                ),
                const Divider(height: 1),
                Expanded(
                  child: ListView(
                    children: [
                      for (var i = 0; i < widget.sections.length; i++)
                        Material(
                          color: Colors.transparent,
                          child: ListTile(
                            dense: true,
                            selected: i == _selectedIndex,
                            selectedTileColor: theme.colorPrimaryBg,
                            title: Text(
                              widget.sections[i].title,
                              style: TextStyle(
                                fontSize: 13,
                                color: i == _selectedIndex
                                    ? theme.colorPrimary
                                    : theme.colorText,
                              ),
                            ),
                            onTap: () => setState(() => _selectedIndex = i),
                          ),
                        ),
                    ],
                  ),
                ),
              ],
            ),
          ),
          VerticalDivider(width: 1, color: theme.colorBorderSecondary),
          // 分区内容
          Expanded(
            child: KeyedSubtree(
              key: ValueKey(_selectedIndex),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Padding(
                    padding: const EdgeInsets.fromLTRB(24, 24, 24, 0),
                    child: Text(
                      section.title,
                      style: TextStyle(
                        fontSize: 22,
                        fontWeight: FontWeight.w600,
                        color: theme.colorText,
                      ),
                    ),
                  ),
                  Expanded(
                    child: Builder(key: UniqueKey(), builder: section.builder),
                  ),
                ],
              ),
            ),
          ),
        ],
      ),
    );
  }
}

/// 分区通用展示容器(标题 + 说明 + 示例区)。
class _DemoCard extends StatelessWidget {
  const _DemoCard({
    required this.title,
    required this.description,
    required this.child,
  });

  final String title;
  final String description;
  final Widget child;

  @override
  Widget build(BuildContext context) {
    final theme = AntTheme.of(context);
    return Container(
      width: double.infinity,
      margin: const EdgeInsets.only(bottom: 24),
      padding: const EdgeInsets.all(24),
      decoration: BoxDecoration(
        color: theme.colorBgContainer,
        borderRadius: BorderRadius.circular(8),
        border: Border.all(color: theme.colorBorderSecondary),
      ),
      // 有界宿主:内容区 Expanded 弹性填充,固定高度 demo 在小窗口下
      // 收缩不溢出;无界宿主(如 _basicSection 的 SingleChildScrollView)
      // 走自然高度分支(无界下 flex 子级会断言崩溃)。
      child: LayoutBuilder(
        builder: (context, constraints) {
          final bool bounded = constraints.maxHeight.isFinite;
          final List<Widget> children = [
            Text(
              title,
              style: TextStyle(
                fontSize: 15,
                fontWeight: FontWeight.w600,
                color: theme.colorText,
              ),
            ),
            const SizedBox(height: 4),
            Text(
              description,
              style: TextStyle(fontSize: 13, color: theme.colorTextSecondary),
            ),
            const SizedBox(height: 16),
            child,
          ];
          if (!bounded) {
            return Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: children,
            );
          }
          return Column(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              ...children.take(4),
              Expanded(child: child),
            ],
          );
        },
      ),
    );
  }
}

// ---------------------------------------------------------------------------
// 刷新演示容器:固定高度 + 说明文字
// ---------------------------------------------------------------------------

/// 模拟刷新耗时。
Future<void> _fakeRefresh() => Future<void>.delayed(const Duration(seconds: 2));

/// 固定高度的刷新演示框。
class _RefreshBox extends StatelessWidget {
  const _RefreshBox({required this.child, this.height = 360});

  final Widget child;
  final double height;

  @override
  Widget build(BuildContext context) {
    final theme = AntTheme.of(context);
    return Container(
      // 高度不超过可用空间:分区内容区受窗口高度限制,固定高度超出时
      // 以可用高度为准(避免 RenderFlex overflow 布局崩溃)。
      height: height <= 0 ? height : null,
      constraints: BoxConstraints(maxHeight: height),
      decoration: BoxDecoration(
        borderRadius: BorderRadius.circular(8),
        border: Border.all(color: theme.colorBorderSecondary),
      ),
      clipBehavior: Clip.antiAlias,
      child: child,
    );
  }
}

/// 列表条目。
class _ItemTile extends StatelessWidget {
  const _ItemTile(this.index);

  final int index;

  @override
  Widget build(BuildContext context) {
    final theme = AntTheme.of(context);
    return Container(
      padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 14),
      decoration: BoxDecoration(
        border: Border(bottom: BorderSide(color: theme.colorBorderSecondary)),
      ),
      child: Row(
        children: [
          Expanded(child: Text('列表条目 ${index + 1}')),
          Icon(AntIcons.rightOutlined, size: 18, color: theme.colorTextQuaternary),
        ],
      ),
    );
  }
}

// ---------------------------------------------------------------------------
// 各分区实现
// ---------------------------------------------------------------------------

/// ① 基础下拉刷新。
Widget _basicSection(BuildContext context) {
  return SingleChildScrollView(
    padding: const EdgeInsets.all(24),
    child: Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        _DemoCard(
          title: '基础用法',
          description: '触摸端:手指按住列表顶部下拉,越过阈值(默认 50)松手即触发刷新。',
          child: _RefreshBox(
            child: AntPullToRefresh(
              onRefresh: _fakeRefresh,
              child: ListView.builder(
                itemCount: 12,
                itemBuilder: (_, i) => _ItemTile(i),
              ),
            ),
          ),
        ),
        _DemoCard(
          title: 'enableRefresh: false',
          description: '禁用下拉刷新,列表可正常滚动但不再响应下拉手势。',
          child: _RefreshBox(
            height: 240,
            child: AntPullToRefresh(
              enableRefresh: false,
              onRefresh: _fakeRefresh,
              child: ListView.builder(
                itemCount: 8,
                itemBuilder: (_, i) => _ItemTile(i),
              ),
            ),
          ),
        ),
      ],
    ),
  );
}

/// ② 桌面端滚轮刷新。
Widget _wheelSection(BuildContext context) {
  return _DemoCard(
    title: '桌面端滚轮刷新',
    description:
        '桌面/触控板重点:列表已滚到顶部后,滚轮继续向上滚(overscroll)即触发刷新,'
        '与移动端下拉为同一手势通路。Web 端可用鼠标滚轮在顶部继续上滚体验。',
    child: _RefreshBox(
      child: AntPullToRefresh(
        onRefresh: _fakeRefresh,
        child: ListView.builder(
          itemCount: 12,
          itemBuilder: (_, i) => _ItemTile(i),
        ),
      ),
    ),
  );
}

/// ③ 国际化切换(R34)。
class _LocaleDemo extends StatefulWidget {
  const _LocaleDemo();

  @override
  State<_LocaleDemo> createState() => _LocaleDemoState();
}

class _LocaleDemoState extends State<_LocaleDemo> {
  /// 可切换语言全集(与 AntRefreshStrings 内置语言对应)。
  static const List<(String, Locale)> _locales = [
    ('中文', Locale('zh')),
    ('English', Locale('en')),
    ('日本語', Locale('ja')),
    ('한국어', Locale('ko')),
    ('Français', Locale('fr')),
    ('Deutsch', Locale('de')),
    ('Español', Locale('es')),
    ('Русский', Locale('ru')),
    ('Português', Locale('pt')),
    ('Italiano', Locale('it')),
    ('العربية', Locale('ar')),
  ];

  Locale _locale = const Locale('zh');

  @override
  Widget build(BuildContext context) {
    final theme = AntTheme.of(context);
    return _DemoCard(
      title: '国际化切换(AntPullToRefresh.locale)',
      description:
          '切换语言后观察刷新各阶段文案变化(下拉中 / 释放刷新 / 加载中 / 刷新完成)。'
          'locale 仅在未显式传入 pullingText 等文案时生效;未命中语言回退中文。',
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Wrap(
            spacing: 8,
            runSpacing: 8,
            children: [
              for (final (label, locale) in _locales)
                ChoiceChip(
                  label: Text(label),
                  selected: _locale == locale,
                  selectedColor: theme.colorPrimary,
                  backgroundColor: theme.colorFillSecondary,
                  labelStyle: TextStyle(
                    color: _locale == locale ? Colors.white : theme.colorText,
                  ),
                  onSelected: (_) => setState(() => _locale = locale),
                ),
            ],
          ),
          const SizedBox(height: 16),
          // 弹性填充:语言 chips 占用高度随窗口变化,RefreshBox 以剩余
          // 空间为准,避免小窗口溢出布局。
          Expanded(
            child: _RefreshBox(
              height: 300,
              child: AntPullToRefresh(
                locale: _locale,
                onRefresh: _fakeRefresh,
                child: ListView.builder(
                  itemCount: 8,
                  itemBuilder: (_, i) => _ItemTile(i),
                ),
              ),
            ),
          ),
        ],
      ),
    );
  }
}

Widget _localeSection(BuildContext context) => const _LocaleDemo();

/// ④ 自定义文案。
Widget _customTextSection(BuildContext context) {
  return _DemoCard(
    title: '自定义各阶段文案',
    description:
        'pullingText / releasingText / finishingText / completeText 逐项覆写;'
        '也可用 strings: AntRefreshStrings.copyWith(...) 整体覆写。',
    child: _RefreshBox(
      child: AntPullToRefresh(
        pullingText: '继续拉,别停 ~',
        releasingText: '松手,开始刷新!',
        finishingText: '玩命加载中…',
        completeText: '搞定 ✓',
        onRefresh: _fakeRefresh,
        child: ListView.builder(
          itemCount: 10,
          itemBuilder: (_, i) => _ItemTile(i),
        ),
      ),
    ),
  );
}

/// ⑤ 自定义 Header。
class _CustomHeaderDemo extends StatefulWidget {
  const _CustomHeaderDemo();

  @override
  State<_CustomHeaderDemo> createState() => _CustomHeaderDemoState();
}

class _CustomHeaderDemoState extends State<_CustomHeaderDemo> {
  AntPullToRefreshStatus _status = AntPullToRefreshStatus.idle;

  @override
  Widget build(BuildContext context) {
    final theme = AntTheme.of(context);
    return _DemoCard(
      title: '自定义 Header',
      description:
          'header 传入任意 Widget 替换默认状态提示;配合 pullStatusChange 回调'
          '在自定义头部中渲染状态(idle/pulling/canRelease/refreshing/complete)。',
      child: _RefreshBox(
        child: AntPullToRefresh(
          pullStatusChange: (status) => setState(() => _status = status),
          header: Container(
            height: 40,
            alignment: Alignment.center,
            child: Row(
              mainAxisSize: MainAxisSize.min,
              children: [
                if (_status == AntPullToRefreshStatus.refreshing)
                  const SizedBox(
                    width: 16,
                    height: 16,
                    child: CircularProgressIndicator(strokeWidth: 2),
                  )
                else
                  Icon(
                    _status == AntPullToRefreshStatus.canRelease
                        ? AntIcons.uploadOutlined
                        : AntIcons.arrowDownOutlined,
                    size: 18,
                    color: theme.colorPrimary,
                  ),
                const SizedBox(width: 8),
                Text(
                  switch (_status) {
                    AntPullToRefreshStatus.idle => '自定义头部:待命中',
                    AntPullToRefreshStatus.pulling => '自定义头部:下拉中',
                    AntPullToRefreshStatus.canRelease => '自定义头部:松手吧!',
                    AntPullToRefreshStatus.refreshing => '自定义头部:刷新中',
                    AntPullToRefreshStatus.complete => '自定义头部:完成',
                  },
                  style: TextStyle(
                    fontSize: 13,
                    color: _status == AntPullToRefreshStatus.idle
                        ? theme.colorTextSecondary
                        : theme.colorPrimary,
                  ),
                ),
              ],
            ),
          ),
          onRefresh: _fakeRefresh,
          child: ListView.builder(
            itemCount: 10,
            itemBuilder: (_, i) => _ItemTile(i),
          ),
        ),
      ),
    );
  }
}

Widget _customHeaderSection(BuildContext context) => const _CustomHeaderDemo();

/// ⑥ 嵌入不同滚动视图。
class _ScrollViewsDemo extends StatefulWidget {
  const _ScrollViewsDemo();

  @override
  State<_ScrollViewsDemo> createState() => _ScrollViewsDemoState();
}

class _ScrollViewsDemoState extends State<_ScrollViewsDemo> {
  /// 当前演示的滚动视图类型。
  int _kind = 0;
  static const List<String> _kindNames = [
    'ListView',
    'CustomScrollView',
    'NestedScrollView',
  ];

  @override
  Widget build(BuildContext context) {
    return _DemoCard(
      title: '嵌入不同滚动视图',
      description: 'PullToRefresh 包裹任意可滚动组件:ListView / CustomScrollView / NestedScrollView。',
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Wrap(
            spacing: 8,
            children: [
              for (var i = 0; i < _kindNames.length; i++)
                ChoiceChip(
                  label: Text(_kindNames[i]),
                  selected: _kind == i,
                  onSelected: (_) => setState(() => _kind = i),
                ),
            ],
          ),
          const SizedBox(height: 16),
          // 弹性填充:chips 占用高度随窗口变化,RefreshBox 以剩余空间为准,
          // 避免小窗口溢出布局。
          Expanded(
            child: _RefreshBox(
              child: AntPullToRefresh(
                key: ValueKey(_kind),
                onRefresh: _fakeRefresh,
                child: switch (_kind) {
                  0 => ListView.builder(
                    itemCount: 12,
                    itemBuilder: (_, i) => _ItemTile(i),
                  ),
                  1 => CustomScrollView(
                    slivers: [
                      const SliverAppBar(
                        title: Text('CustomScrollView'),
                        automaticallyImplyLeading: false,
                      ),
                      SliverList.builder(
                        itemCount: 12,
                        itemBuilder: (_, i) => _ItemTile(i),
                      ),
                    ],
                  ),
                  _ => NestedScrollView(
                    headerSliverBuilder: (_, _) => [
                      const SliverAppBar(
                        title: Text('NestedScrollView'),
                        automaticallyImplyLeading: false,
                        pinned: true,
                      ),
                    ],
                    body: ListView.builder(
                      itemCount: 12,
                      itemBuilder: (_, i) => _ItemTile(i),
                    ),
                  ),
                },
              ),
            ),
          ),
        ],
      ),
    );
  }
}

Widget _scrollViewsSection(BuildContext context) => const _ScrollViewsDemo();

/// ⑦ 多级嵌套:PullToRefresh 内嵌 PullToRefresh。
Widget _nestedSection(BuildContext context) {
  return _DemoCard(
    title: '多级嵌套(内层优先)',
    description:
        'PullToRefresh 内嵌 PullToRefresh:手指在内层列表上时由内层消费下拉手势并触发内层刷新;'
        '滚到外层列表顶部再下拉触发外层刷新。',
    child: _RefreshBox(
      height: 420,
      child: AntPullToRefresh(
        onRefresh: _fakeRefresh,
        child: ListView(
          children: [
            Container(
              padding: const EdgeInsets.all(12),
              margin: const EdgeInsets.all(12),
              decoration: BoxDecoration(borderRadius: BorderRadius.circular(8)),
              height: 260,
              clipBehavior: Clip.antiAlias,
              child: AntPullToRefresh(
                onRefresh: _fakeRefresh,
                child: ListView.builder(
                  itemCount: 8,
                  itemBuilder: (_, i) => _ItemTile(i),
                ),
              ),
            ),
            for (var i = 8; i < 14; i++) _ItemTile(i),
          ],
        ),
      ),
    ),
  );
}

/// ⑧ 组合使用:下拉刷新 + 上拉加载。
class _ComboDemo extends StatefulWidget {
  const _ComboDemo();

  @override
  State<_ComboDemo> createState() => _ComboDemoState();
}

class _ComboDemoState extends State<_ComboDemo> {
  int _pageStart = 0;

  Future<void> _refresh() async {
    await _fakeRefresh();
    setState(() => _pageStart = 0);
  }

  Future<bool> _loadMore() async {
    await Future<void>.delayed(const Duration(seconds: 1));
    // 第 4 页之后没有更多数据。
    if (_pageStart >= 30) {
      return false;
    }
    setState(() => _pageStart += 10);
    return true;
  }

  @override
  Widget build(BuildContext context) {
    return _DemoCard(
      title: 'PullToRefresh + AntInfiniteScroll',
      description:
          '下拉刷新重置数据、上拉自动加载下一页(第 4 页后提示「没有更多了」)。'
          'AntInfiniteScroll 与 PullToRefresh 同包(antd_refresh)直接使用。',
      child: _RefreshBox(
        // 高度自适应:窗口分区不足 460 时以可用高度为准,避免溢出布局。
        height: 460,
        child: LayoutBuilder(
          builder: (context, constraints) {
            final double maxH = constraints.maxHeight;
            final double boxHeight = maxH.isFinite && maxH < 460 ? maxH : 460;
            return SizedBox(
              height: boxHeight,
              child: AntPullToRefresh(
                onRefresh: _refresh,
                child: AntInfiniteScroll(
                  loadMore: _loadMore,
                  child: ListView(
                    children: [
                      for (var i = 0; i < _pageStart + 10; i++) _ItemTile(i),
                    ],
                  ),
                ),
              ),
            );
          },
        ),
      ),
    );
  }
}

Widget _comboSection(BuildContext context) => const _ComboDemo();
1
likes
160
points
0
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

Ant Design pull-to-refresh for Flutter - indicator states, drag thresholds and smooth scroll integration.

Homepage
Repository (GitHub)
View/report issues

Topics

#ui #components #design-system #ant-design #pull-to-refresh

License

(pending) (license)

Dependencies

antd_icons_flutter, antd_theme, flutter, material_ui

More

Packages that depend on antd_refresh