Scratcher 全属性详解10 个关键参数玩转 Flutter 刮刮卡自定义配置【免费下载链接】scratcherScratch card widget which temporarily hides content from user.项目地址: https://gitcode.com/gh_mirrors/sc/scratcherScratcher是一个轻量级的 Flutter 刮刮卡组件它能在用户手指滑动刮擦时暂时隐藏底层内容非常适合抽奖、红包、签到奖励等营销场景。这个开源库支持 Android、iOS 和 Web 平台核心代码集中在 lib/scratcher.dart 中接口设计得非常简洁。本篇文章将带你逐一拆解 Scratcher 的 10 个关键参数从基础用法到性能调优帮你快速上手 Flutter 刮刮卡开发即使你是新手也能轻松看懂。快速上手3 步集成 Flutter 刮刮卡组件在深入参数之前先用最简单的方式把刮刮卡跑起来。第一步在pubspec.yaml中添加依赖版本要求 Flutter 3.16 以上。dependencies: scratcher: ^2.5.0第二步引入库文件。import package:scratcher/scratcher.dart;第三步把想隐藏的内容包进Scratcher一个可刮擦的卡片就完成了。Scratcher( brushSize: 30, threshold: 50, color: Colors.red, onChange: (value) print(已刮开: $value%), onThreshold: () print(达到阈值恭喜中奖!), child: Container( height: 300, width: 300, color: Colors.blue, ), )如果你想知道完整的参数清单可以参考 README.md 中的属性表格想直接看可运行的 Demoexample/lib/basic.dart 里就是一个带进度显示、重置按钮的完整示例。一、10 个关键参数逐一拆解1. child决定刮开后显示什么child是刮开后被看到的内容可以是任意 Widget——奖品图片、优惠券、中奖文案都可以。它是必填参数所有内容都藏在它下面等用户刮开一定比例后才显现。2. brushSize调节刮擦笔刷大小brushSize控制笔刷直径默认值是 25。数值越大一次划过的面积越大刮得越快数值越小越精细适合需要慢慢刮的玩法。在 example/lib/basic.dart 里作者还专门做了一个滑块来动态调整笔刷大小范围 5~100你可以实时感受不同大小的手感差异。3. threshold设置刮开完成阈值threshold是 0~100 的百分比表示刮开多少面积后算完成。比如设为 50就意味着当 50% 的区域被刮开时触发完成逻辑。它默认是null不启用只有当达到阈值时onThreshold回调才会被触发。4. enabled动态开关刮擦能力enabled是布尔值控制用户当前能否继续刮擦。场景很实用比如用户已经领过奖就把它设为false禁止再刮或者刮开后想锁定结果也可以通过它来禁用。它只阻止新的刮擦操作不会影响已经刮开的效果。5. accuracy精度与性能的取舍accuracy是一个枚举类型ScratchAccuracy可选值为取值采样密度特点low10×10性能最高适合大面积卡片medium30×30性能与精度均衡high100×100进度统计最精确性能开销最大它的原理是往刮擦区域撒检查点见 lib/widgets.dart 中的_calculateCheckpoints通过计算被刮掉的检查点比例来估算进度。默认是high如果你做的是高频刷新的小卡片比如 example/lib/scratch_box.dart 里 80×80 的小方块用low就完全够了流畅度会明显提升。6. color定制覆盖层的纯色背景color是覆盖层的纯色背景默认是黑色。刮开前用户看到的就是这层颜色可以配合品牌主色或主题色使用。它是刮刮卡封面的两种形态之一另一种是下面的image。7. image用图片做更炫酷的封面image允许你用任意图片作为覆盖层比纯色更有视觉冲击力。比如营销活动常用刮开看奖品的底图。它支持BoxFit适配方式默认按BoxFit.cover填充。图片的加载与绘制逻辑可以在 lib/painter.dart 中看到。注意设置图片后color依然作为兜底背景保留。8. rebuildOnResize应对尺寸变化的保险丝rebuildOnResize默认是true当刮刮卡尺寸因布局变化比如横竖屏切换、父容器缩放而改变时它会自动重置刮擦状态避免进度错乱。如果你确定尺寸不会变可以设为false省去重建开销。9. onChange 与 onThreshold进度驱动的两大回调onChange每次刮开面积增加超过 0.1% 时触发回调参数是当前进度百分比0~100适合实时更新进度条。当进度达到 100% 时也会触发。onThreshold当进度达到threshold设定的值时触发通常在这里发放奖励、弹出结果弹窗。整个回调流程和阈值判断逻辑都能在 lib/scratcher.dart 的_addPoint方法里找到。10. onScratchStart / onScratchUpdate / onScratchEnd完整的手势生命周期这三个回调分别对应刮擦的开始、进行中、结束三个阶段非常适合做音效反馈、震动提醒或埋点统计。比如用户开始刮的时候播放沙沙音效结束的时候统计刮擦时长。 小提示以上所有参数的具体类型与默认值都可以在 lib/scratcher.dart 的Scratcher构造方法里直接查看注释非常清晰。二、用代码控制刮刮卡reset 与 reveal除了用户手动刮你还可以通过GlobalKeyScratcherState编程控制刮刮卡实现一键重置和强制揭晓final scratchKey GlobalKeyScratcherState(); Scratcher( key: scratchKey, // 其他参数... ) // 两秒动画过渡重置 scratchKey.currentState?.reset( duration: const Duration(milliseconds: 2000), ); // 直接显示全部结果 scratchKey.currentState?.reveal( duration: const Duration(milliseconds: 2000), );这在没刮完用户直接点查看结果的交互中非常常用。注意reset带动画时长时过渡期间会禁止刮擦动画结束才恢复。三、实战进阶组合参数做出高级玩法在 example/lib/advanced.dart 里作者用三个小刮刮卡做了一个刮齐三个图标才触发动画的玩法每个小卡设置accuracy: ScratchAccuracy.low保证性能、threshold: 60控制完成线配合onThreshold计数全部刮完后用缩放动画庆祝。这个思路完全可以迁移到你的抽奖活动页。四、性能优化与避坑建议大卡片用 low 精度检查点数量是精度的平方100×100 会生成约 1 万个点卡片越大性能差异越明显。图片封面注意内存image使用高分辨率大图时建议先压缩再加载。尺寸变化场景保持 rebuildOnResize 为 true否则刮擦进度可能对不上实际显示区域。合理设置 threshold不要设得太低比如 10%否则用户随便划两下就完成缺少刮擦的乐趣太高90%又会让人刮到不耐烦30%~60% 是常见选择。总结Scratcher 用不到 400 行的核心代码lib/widgets.dart lib/painter.dart就把一个功能完整的 Flutter 刮刮卡组件做到了极致简洁。10 个关键参数中brushSize、threshold、color/image决定了视觉与玩法accuracy决定了性能表现而那一组回调则给了你充分的事件控制能力。下次做抽奖、签到、红包类功能时不妨直接用它快速实现一个体验丝滑的 Flutter 刮刮卡再也不用自己从零手写绘制逻辑了。【免费下载链接】scratcherScratch card widget which temporarily hides content from user.项目地址: https://gitcode.com/gh_mirrors/sc/scratcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考