企业官网建设流程全解析

Once 是一个小巧的 Android 库，专门用来管理"只执行一次"（one-off）的操作——比如引导教程只显示一次、更新说明每次升级只弹一次、后台请求每小时最多同步一次。本文是一份 Once API 参考手册，带你速查beenDone、markDone、lastDone、clearAll等 9 个核心方法，并讲清 tag 与 scope 的用法，帮助新手快速上手。

先搞懂两个概念：tag 与 scope 🏷️

Once 的设计非常简单，所有 API 都围绕这两个词展开：

三种 scope 常量定义在 Once.java 中：

• THIS_APP_INSTALL：整个安装周期内只一次（卸载重装会重置）
• THIS_APP_VERSION：每个 App 版本内只一次（升级后重置）
• THIS_APP_SESSION：每次启动 App 的会话内只一次

开始前的唯一一步：initialise

Once 是纯静态类，使用任何方法前必须先初始化一次，惯例是放在 Application 的onCreate中：

Once.initialise(this);

完整写法可参考示例工程中的 ExampleApplication.java。

9个核心方法速查清单

1.markDone(String tag)—— 标记完成

把 tag 与"当前时间"关联并持久化。这是所有"只一次"逻辑的落点，核心实现只有 3 行，位于 Once.java：

Once.markDone("phoneHome");

2.beenDone(...)—— 查询是否完成（重载最多）

beenDone是日常使用频率最高的方法，共有 8 个重载，可归纳为三类：

• 按 scope：beenDone(Once.THIS_APP_VERSION, tag)—— 本版本内做过吗？
• 按时间窗口：beenDone(TimeUnit.HOURS, 1, tag)—— 最近 1 小时内做过吗？
• 按次数：beenDone(tag, Amount.exactly(3))—— 恰好做过 3 次吗？

不传次数参数时，默认按Amount.moreThan(0)判断，即"是否做过至少一次"。

3.lastDone(String tag)—— 拿到具体完成时间

时间窗口判断不够用时，可以直接取回上次完成的Date；如果从未完成则返回null：

Date lastDone = Once.lastDone("phoneHome");

4.clearDone(String tag)与 5.clearAll()—— 重置完成记录

• clearDone(tag)：只清除单个 tag，之后beenDone(tag)将返回false，常用于"每 3 次点击弹一次"这类周期性场景。
• clearAll()：清空全部完成记录，适合调试和重置按钮，示例 App 的 reset 按钮就是直接调用它，见 MainActivity.java。

6.toDo(int scope, String tag)—— 标记"待办"

适合"A 功能做完了，才触发 B 功能"的跨界面联动。带 scope 参数的版本可以避免用户反复回看 A 界面时重复记账：

// 基础功能界面中 Once.toDo(Once.THIS_APP_INSTALL, "showFeatureOnboarding"); // 主界面中 if (Once.needToDo("showFeatureOnboarding")) { // 执行引导，完成后 Once.markDone("showFeatureOnboarding"); }

7.needToDo(String tag)—— 检查待办

boolean pending = Once.needToDo("showFeatureOnboarding");

注意：tag 一旦被markDone，会自动从待办集合中移除，之后的needToDo都会返回false。

8.clearToDo(String tag)/ 9.clearAllToDos()—— 清除待办

• clearToDo(tag)：销掉单个待办；
• clearAllToDos()：清空所有待办。

两者都不影响beenDone的完成记录，可以放心用于"用户主动跳过引导"等场景。

次数判断辅助：Amount 与 CountChecker 🎯

beenDone的次数参数类型是 CountChecker.java 定义的函数式接口，实际由 Amount.java 提供三种工厂方法：

配合clearDone就能实现"每 3 次提示一次评分"的经典逻辑，可对照 MainActivity.java 的完整写法。

3 个最典型的使用场景

1. 每次升级弹出更新说明：beenDone(Once.THIS_APP_VERSION, tag)+markDone
2. 限流：每小时最多同步一次：beenDone(TimeUnit.HOURS, 1, tag)
3. 引导教程只展示一次：beenDone(Once.THIS_APP_INSTALL, tag)

三种写法结构完全一致，只是判断条件不同，这也是 Once 最优雅的地方。

常见疑问 FAQ 💬

Q：tag 随便起名行不行？可以，但建议全局唯一且语义清晰（如"NewSessionDialog"），tag 冲突会互相干扰记录。

Q：markDone后还能再检查历史次数吗？可以。每次markDone都会追加一条时间戳，beenDone按次数/时间判断的就是这个历史列表。

Q：数据存在哪里？完成记录与待办集合通过内部持久化类（PersistedMap、PersistedSet）存到 SharedPreferences，卸载 App 才会丢失。

Q：版本要求？支持 API 14 及以上；最新 1.3.1 已改为从 mavenCentral 发布，并在build.gradle中添加依赖即可，版本沿革见 CHANGELOG.md。

相关文件导航

• 核心源码：once/src/main/java/jonathanfinerty/once/Once.java
• 示例 App：once-example/src/main/java/jonathanfinerty/onceexample/MainActivity.java
• 使用说明：README.md

掌握这份清单，配合 scope 与 tag，绝大多数"只发生一次"的需求都能用两三行代码搞定，这就是 Once 的魅力所在。