企业官网建设流程全解析

Scratcher 全属性详解：10 个关键参数玩转 Flutter 刮刮卡自定义配置

【免费下载链接】scratcherScratch card widget which temporarily hides content from user.项目地址: https://gitcode.com/gh_mirrors/sc/scratcher

Scratcher是一个轻量级的 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 中的属性表格；想直接看可运行的 Demo，example/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，可选值为：

它的原理是往刮擦区域撒"检查点"（见 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

除了用户手动刮，你还可以通过GlobalKey<ScratcherState>编程控制刮刮卡，实现"一键重置"和"强制揭晓"：

final scratchKey = GlobalKey<ScratcherState>(); 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计数，全部刮完后用缩放动画庆祝。这个思路完全可以迁移到你的抽奖活动页。

四、性能优化与避坑建议

1. 大卡片用 low 精度：检查点数量是精度的平方（100×100 会生成约 1 万个点），卡片越大性能差异越明显。
2. 图片封面注意内存：image使用高分辨率大图时，建议先压缩再加载。
3. 尺寸变化场景保持 rebuildOnResize 为 true：否则刮擦进度可能对不上实际显示区域。
4. 合理设置 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