CupertinoScrollbar

Flutter中一个专为iOS风格设计的滚动条组件，主要用于在可滚动区域(如ListView、GridView等)显示一个美观且符合苹果设计语言的滚动指示器

CupertinoScrollbar是Flutter中一个专为iOS风格设计的滚动条组件，主要用于在可滚动区域(如ListView、GridView等)显示一个美观且符合苹果设计语言的滚动指示器。它的核心逻辑是自动监听父级可滚动组件的滚动事件，动态调整滚动条的位置和透明度，提供流畅的用户反馈。与Material风格的Scrollbar不同，CupertinoScrollbar更注重与iOS生态系统的一致性，例如使用细长条状设计和淡入淡出动画。

使用场景

在需要与iOS原生应用风格保持一致的可滚动界面中，如聊天列表、设置页面或新闻feed。
当用户快速滚动长列表时，提供视觉提示以帮助定位内容。
适用于Cupertino主题的应用，确保UI组件符合苹果设计规范。

示例

基础列表滚动条

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

class BasicScrollbarExample extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return CupertinoScrollbar(
      child: ListView.builder(
        itemCount: 50,
        itemBuilder: (context, index) => ListTile(
          title: Text('项目 $index'),
        ),
      ),
    );
  }
}

自定义交互逻辑

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

class InteractiveScrollbarExample extends StatefulWidget {
  @override
  _InteractiveScrollbarExampleState createState() => _InteractiveScrollbarExampleState();
}

class _InteractiveScrollbarExampleState extends State<InteractiveScrollbarExample> {
  final ScrollController _controller = ScrollController();

  void _scrollToTop() {
    _controller.animateTo(0, duration: Duration(seconds: 1), curve: Curves.easeIn);
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        CupertinoButton(
          onPressed: _scrollToTop,
          child: Text('滚动到顶部'),
        ),
        Expanded(
          child: CupertinoScrollbar(
            controller: _controller, // 关联控制器
            child: ListView.builder(
              controller: _controller,
              itemCount: 100,
              itemBuilder: (context, index) => ListTile(
                title: Text('交互项目 $index'),
              ),
            ),
          ),
        ),
      ],
    );
  }
}

适配黑暗主题

import 'package:flutter/cupertino.dart';

class ThemedScrollbarExample extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return CupertinoApp(
      theme: CupertinoThemeData(brightness: Brightness.dark), // 黑暗主题
      home: CupertinoPageScaffold(
        navigationBar: CupertinoNavigationBar(middle: Text('黑暗主题示例')),
        child: CupertinoScrollbar(
          child: ListView.builder(
            itemCount: 30,
            itemBuilder: (context, index) => Padding(
              padding: EdgeInsets.all(8.0),
              child: Text('黑暗模式项目 $index', style: TextStyle(color: CupertinoColors.white)),
            ),
          ),
        ),
      ),
    );
  }
}

注意点

常见问题:
- 性能影响: 如果可滚动区域包含大量复杂子组件(如图片或动画)，滚动条可能加剧渲染负担。建议使用ListView.builder等懒加载组件优化性能。
- 兼容性警告: CupertinoScrollbar仅适用于Cupertino风格的可滚动组件(如CupertinoListView)，与Material组件混用时可能样式不一致。
- 手势冲突: 在嵌套滚动视图(如NestedScrollView)中，滚动条可能无法正确响应触摸事件，需测试交互逻辑。
优化技巧:
- 通过thickness属性调整滚动条宽度，避免在窄屏幕上遮挡内容。
- 使用controller属性与ScrollController绑定，实现程序化滚动控制（如滚动到指定位置）。
- 在黑暗主题下，默认滚动条颜色可能不够明显，可通过thumbColor属性自定义颜色。
最佳实践:
- 在长列表(超过20项)中启用滚动条，提升用户体验。
- 避免过度自定义样式，以保持与iOS设计语言的一致性。
- 测试时确保滚动条在快速滚动和慢速拖动下均能平滑动画。

构造函数

CupertinoScrollbar({
  Key? key,
  ScrollController? controller,         // 可选的滚动控制器，用于监听或控制滚动位置
  ScrollView? child,                    // 必需的子组件，必须是可滚动视图（如ListView）
  bool isAlwaysShown = false,           // 控制滚动条是否始终显示（默认为false，仅在滚动时显示）
  double thickness = 6.0,               // 滚动条的宽度（单位：逻辑像素）
  double thicknessWhileDragging = 8.0,  // 用户拖动时的滚动条宽度
  Color? thumbColor,                    // 滚动条的颜色，默认根据主题自动适配
  Radius radius = Radius.circular(1.5), // 滚动条的圆角半径
  Radius radiusWhileDragging = Radius.circular(4.0), // 拖动时的圆角半径
  Duration fadeDuration = Duration(milliseconds: 300), // 滚动条淡出动画的时长
  Duration timeToFade = Duration(milliseconds: 600),   // 滚动停止后到开始淡出的延迟时间
})

属性

属性名	属性类型	说明
`controller`	ScrollController?	关联的滚动控制器，用于编程控制滚动或监听滚动事件。
`child`	ScrollView	必需的可滚动子组件，如ListView或GridView。
`isAlwaysShown`	bool	是否始终显示滚动条（默认false：仅滚动时显示）。
`thickness`	double	滚动条的默认宽度（单位：逻辑像素）。
`thicknessWhileDragging`	double	用户拖动滚动条时的宽度。
`thumbColor`	Color?	滚动条的颜色，为null时自动适配主题。
`radius`	Radius	滚动条的圆角半径。
`radiusWhileDragging`	Radius	用户拖动时的圆角半径。
`fadeDuration`	Duration	滚动条淡出动画的持续时间。
`timeToFade`	Duration	滚动停止后到开始淡出的等待时间。

关键属性解释
- isAlwaysShown: 若设为true，滚动条将始终可见，适用于需要强调可滚动性的场景(如教程界面)。但可能影响视觉简洁性，需谨慎使用。
- controller: 通过外部ScrollController可实现高级交互(如滚动到指定索引)，是动态控制滚动的核心。
- thickness和thumbColor: 这两个属性直接影响UI美观性。在自定义主题时，调整它们可确保滚动条与整体设计协调，例如在黑暗模式下使用亮色拇指提升可读性。

CupertinoRadio

CupertinoScrollBehavior