「不想上班」实战系列:鸿蒙闪控球,把番茄钟倒计时挂到任何应用之上【鸿蒙心迹】
鸿蒙闪控球实战:把番茄钟倒计时挂到任何应用之上
番茄钟有个天然矛盾:你启动它是为了专注,但一旦切去回消息、查文档、翻会议纪要,应用就被压到后台,倒计时也看不见了。等你想起它,一整个番茄已经过期,白专注了。
「不想上班」的番茄钟最初也想自绘一个悬浮球,很快放弃:窗口层级、手势拦截、拖拽吸附、状态栏避让、删除交互,每一件都要自己实现。直到鸿蒙在 API 20 放出闪控球(floatingBall)——系统级悬浮小组件,自带吸附、位置记忆、拖动避让与删除态。本文按官方文档把能力边界讲清,再讲这个倒计时球在「不想上班」里的完整落地与工程取舍。
一、闪控球是什么,能干什么
官方给的定义很克制:
官方原文:闪控球是一种在设备屏幕上悬浮的非全屏应用窗口,为应用提供临时的全局能力,完成跨应用交互。应用可以将关键信息以闪控球模式呈现。切换为闪控球模式后,用户可以进行其他界面操作。
注意三个关键词,它们决定了这个能力适不适合你:
- 系统级。球由系统窗口服务绘制,不在你的页面树里,所以能浮在其他应用之上;也正因为如此,它的尺寸、字体、圆角都不由你决定。
- 非全屏、临时。它是一块 40vp 高的信息条,不是第二个应用窗口。
- 有准入门槛。官方明确列举适用场景:题目搜索、账单记录、商品比价、抢单、翻译、金融实时盯盘等"跨应用悬浮展示关键信息"的用途,并写明超范围使用会被处罚与限制。
与另外两种"浮起来"的方案对比
| 维度 | 系统闪控球 | 自绘悬浮窗(overlay) | 闪控窗(floatView) |
|---|---|---|---|
| 谁负责窗口 | 系统窗口服务 | 应用自己 | 系统(可绑定闪控球) |
| 尺寸与样式 | 固定规格,字体不可改 | 完全自定义 | 自定义,空间更大 |
| 拖拽吸附 / 位置记忆 | 系统提供 | 需自行实现 | 系统提供 |
| 交互成本 | 低 | 高(层级、手势、避让) | 中 |
| 适合的内容 | 一两个关键数字 | 任意 UI | 小面板级 UI |
「不想上班」的需求就是"把 24:31 和"专注中"三个字挂出去",第一条路显然是闪控球。

二、四个模板与硬规格
模板只有四种
| 枚举 | 值 | 布局 | 必传参数 |
|---|---|---|---|
STATIC | 1 | 图标 + 标题 | title、icon |
NORMAL | 2 | 标题 + 内容 | title |
EMPHATIC | 3 | 图标 + 标题 + 内容 | title |
SIMPLE | 4 | 仅标题(可双行) | title |
规格是写死的
官方原文:目前闪控球的规格为:整体尺寸宽为 70vp-98vp 之间,高为 40vp,标题和内容不支持自定义字体大小。
配套还有两条参数硬约束:
title不可为空字符串,不超过 64 字节;content可选,不超过 64 字节;backgroundColor必须是不带透明度的十六进制('#008EF5'或'#FF008EF5')。
越界不会静默截断,而是直接返回 1300019(闪控球参数校验错误)。
为什么最终选 NORMAL
这是本项目的设计取舍,不是官方推荐:
- 40vp 高度里塞图标 + 标题 + 内容,图标会挤占文本宽度,而倒计时最怕被截断;
- 时间用
mm:ss(5 个字符)、阶段用 3 个汉字,title + content刚好两行放下; SIMPLE只能放标题,无法同时表达"还剩多久"和"处在什么阶段";EMPHATIC多出来的图标对倒计时没有信息增量。
还有一条扩展路线:闪控窗
如果哪天球里要放的不是两个数字,而是一个可交互的小面板(比如暂停/跳过按钮、当前任务名、今日完成数),闪控球就不够用了。官方提供了另一条路:
官方原文:通过 floatView.bind 接口将闪控窗控制器与闪控球控制器绑定后,用户点击闪控球可展开为闪控窗,点击闪控窗左上角的缩小按钮可收起为闪控球,实现两种窗口形态的相互切换。
也就是说,"球"负责常驻提醒,"窗"负责临时操作,两者可以共存。本项目当前只需要一个时间数字,没有引入闪控窗;但如果你在做计时器、盯盘、抢单这类"既要常驻又要操作"的功能,这条组合路线比自绘悬浮窗干净得多。
代价也要提前知道:同一个应用如果已有闪控窗在运行,再启球可能撞上 1300034(与其它悬浮窗口冲突),需要在自己的状态机里做互斥。
三、一个倒计时球的完整生命周期
闪控球在「不想上班」里不是"点一下弹出来"的临时功能,而是跟着番茄钟计时会话走的常驻状态。按生命周期可拆成七步。
3.1 先问设备支不支持
isFloatingBallEnabled() 是同步方法,但没必要每次调用都问系统。这里做了一次懒检测 + 结果缓存:
/** 设备是否支持闪控球(懒检测并缓存) */
private isBallSupported(): boolean {
if (this.ballSupported === undefined) {
try {
this.ballSupported = floatingBall.isFloatingBallEnabled();
} catch (e) {
this.ballSupported = false;
}
if (!this.ballSupported) {
console.info('PomodoroDataManager: floating ball not supported on this device.');
}
}
return this.ballSupported;
}
用 undefined 而非 false 当"未检测"标记,是为了把"没问过"和"问过但不支持"区分开;try/catch 兜住低版本设备上枚举不到模块的情况。
3.2 控制器懒创建 + 双回调
官方开发步骤里,create 之后要注册点击与状态回调。本项目把整个创建过程收敛成一个幂等方法:
/** 懒创建闪控球控制器,并注册点击/状态回调 */
private async ensureBallController(): Promise<boolean> {
if (this.ballController) return true;
if (!this.context) return false;
try {
const config: floatingBall.FloatingBallConfiguration = {
context: this.context as common.UIAbilityContext,
};
this.ballController = await floatingBall.create(config);
// 点击闪控球:先尝试恢复主窗口(后台场景),再发出导航事件
this.ballClickCallback = (): void => {
this.handleBallClick();
};
// 系统侧异常停止时同步本地状态
this.ballStateCallback = (state: floatingBall.FloatingBallState): void => {
if (state === floatingBall.FloatingBallState.STOPPED) {
this.ballActive = false;
}
};
this.ballController.on('click', this.ballClickCallback);
this.ballController.on('stateChange', this.ballStateCallback);
return true;
} catch (e) {
const err = e as BusinessError;
console.error('Failed to create floating ball controller:', err.code, err.message);
this.ballController = undefined;
return false;
}
}
两个细节值得强调:
FloatingBallConfiguration.context不能为空,官方要求传 UIAbilityContext;stateChange回调是本地状态的校准器。球可能被用户长按删掉、被系统回收,本地ballActive若不同步,后续updateFloatingBall就会持续报1300024(窗口状态异常)。收到STOPPED就置 false,是最省事的对齐方式。
3.3 参数构造:一个函数管三种表达
球要同时表达"还剩多久"“在哪个阶段”“现在是什么状态”,全部落在三个字段上:
/** 构造闪控球显示参数:title=倒计时,content=阶段标签,背景色随阶段/状态变化 */
private buildBallParams(): floatingBall.FloatingBallParams {
const params: floatingBall.FloatingBallParams = {
template: floatingBall.FloatingBallTemplate.NORMAL,
title: this.formatBallTitle(),
content: this.getPhaseLabel(),
backgroundColor: this.getBallBackgroundColor(),
};
return params;
}
private formatBallTitle(): string {
const minutes = Math.floor(this.remainingSeconds / 60);
const seconds = this.remainingSeconds % 60;
const mm = minutes < 10 ? `0${minutes}` : `${minutes}`;
const ss = seconds < 10 ? `0${seconds}` : `${seconds}`;
return `${mm}:${ss}`;
}
private getBallBackgroundColor(): string {
// 暂停态用灰色区分;运行态跟随阶段色
if (this.timerState === 'paused') return '#8E8E93';
return this.getPhaseColorHex();
}
getPhaseColorHex() 返回三个不带透明度的十六进制色:专注 #FF4B6E、短休息 #1E9E4B、长休息 #007AFF。这里踩过一个色值问题:短休息原本用系统绿 #34C759,与白字的对比度只有约 2.2:1,不达 3:1,换成更深的 #1E9E4B 才够。
暂停态特意不隐藏球,而是换成灰色 #8E8E93。原因是:隐藏会让用户以为计时已经结束,灰球则明确表达"还停在这儿,等你继续"。
把三种状态放在一起看,球的表达其实是紧凑的:
| 计时状态 | title | content | 背景色 | 球是否显示 |
|---|---|---|---|---|
| idle(准备开始) | 总时长 | 准备开始 | 阶段色 | 不显示 |
| running / work | 剩余 mm:ss | 专注中 | #FF4B6E | 显示 |
| running / shortBreak | 剩余 mm:ss | 短休息中 | #1E9E4B | 显示 |
| running / longBreak | 剩余 mm:ss | 长休息中 | #007AFF | 显示 |
| paused | 剩余 mm:ss | 已暂停 | #8E8E93 | 显示(灰色) |
| 阶段完成 / 重置 | — | — | — | 刷新或停止 |
这张表就是 buildBallParams() 的全部输入来源,没有额外状态。好处是:任何一处计时状态变化,只要最终调一次 updateBall(),球就自动跟上,不会出现"页面显示专注中、球上写着休息中"的分裂。



3.4 启动:三重闸门 + 幂等
启动不是简单调一次 startFloatingBall。本项目在这里设了三道闸门,并把"重复启动"当成正常情况处理:
/** 启动/显示闪控球(异步链,静默失败) */
private showBall(): void {
if (!this.config.ballEnabled) return;
if (!this.isBallSupported()) return;
if (!this.fabDesired || this.fabSuppressed) return;
this.ensureBallController().then((ok: boolean) => {
if (!ok) return;
// 已启动则仅刷新内容
if (this.ballActive) {
this.updateBall();
return;
}
const controller = this.ballController;
if (!controller) return;
controller.startFloatingBall(this.buildBallParams()).then(() => {
this.ballActive = true;
}).catch((err: BusinessError) => {
if (err.code === 1300022) {
// 重复操作:球已在运行,视为成功
this.ballActive = true;
this.updateBall();
} else {
console.error('Failed to start floating ball:', err.code, err.message);
}
});
}).catch((err: BusinessError) => {
console.error('Failed to ensure floating ball controller:', err.code, err.message);
});
}
三道闸门依次是:用户开关(ballEnabled)→ 设备能力(isBallSupported)→ 会话意图(fabDesired && !fabSuppressed)。
1300022(Repeated floating ball operation)被当成成功,因为"球已经在跑"与"我要球在跑"的结果一致。如果按错误处理,会在快速启停、页面来回切换时反复打日志,甚至误把状态置反。
整个链路静默失败:任何一个 catch 都只记日志,不弹 Toast。闪控球是增强体验的旁路功能,它挂了不该打断番茄钟本身。
3.5 每秒刷新,但只在 running 时
倒计时 mm:ss 每秒变一次,意味着球要每秒更新。更新入口挂在计时器的 tick 回调上:
private notifyTick(): void {
const cbs = this.tickCallbacks;
for (let i = 0; i < cbs.length; i++) {
cbs[i]();
}
// running 态每秒刷新闪控球倒计时
if (this.timerState === 'running') {
this.updateBall();
}
}
updateBall() 内部先判 ballActive 与 controller 是否存在,再调用 updateFloatingBall:
/** 刷新闪控球内容(未启动时忽略) */
private updateBall(): void {
if (!this.ballActive) return;
const controller = this.ballController;
if (!controller) return;
controller.updateFloatingBall(this.buildBallParams()).catch((err: BusinessError) => {
console.error('Failed to update floating ball:', err.code, err.message);
});
}
两个设计点:
- 只有 running 才刷。暂停、空闲、阶段结束那一刻都不需要每秒调用;暂停时单独调一次
updateBall把颜色切成灰即可。 - update 不重建。
updateFloatingBall复用同一个球窗口,只换文本与颜色,不会出现"球闪一下重新出现"。
注意 updateFloatingBall 有一条官方限制:调用时 template 字段不可更改(否则 1300027),静态模板(STATIC)甚至完全不支持更新(1300028)。这也是选 NORMAL 的隐性好处——它既支持更新,又不需要一开始就绑定图标资源。
3.6 页面打开时不显示
如果用户已经在番茄钟页面里看着大号倒计时,屏幕上再浮一个小球就是重复信息,而且会遮住页面控件。所以本项目在页面生命周期上做了抑制:
/** 番茄钟页面打开时调用:抑制闪控球显示(计时不受影响) */
suppressFabWindow(): void {
this.fabSuppressed = true;
this.hideBall();
}
/** 离开番茄钟页面时调用:恢复闪控球显示(若计时会话仍在) */
restoreFabWindow(): void {
this.fabSuppressed = false;
if (this.fabDesired) {
this.showBall();
}
}
页面侧只有两行调用:
aboutToAppear(): void {
// 番茄钟页面打开期间不显示闪控球(计时不受影响)
this.manager.suppressFabWindow();
// ...
}
aboutToDisappear(): void {
// ...
// 离开页面后恢复闪控球显示(若计时会话仍在进行)
this.manager.restoreFabWindow();
}
fabSuppressed 是"页面在不在"的标记,fabDesired 是"这次计时要不要球"的意图,两者分开,才不会出现"页面里关掉开关,离开后球又冒出来"的错位。
停止与重置时则是彻底收回意图:
resetTimer(): void {
// ...
this.fabDesired = false;
this.hideBall();
}
hideBall 里先置 ballActive = false 再调 stopFloatingBall(),并保留 controller 复用——下次开始计时不必再走一遍 create。
3.7 点击:先回主窗口,再导航
点击球的处理分两段。第一段是系统层:把应用从后台拉回前台。第二段是应用层:跳到番茄钟页面。
/** 点击闪控球:恢复主窗口(仅点击后允许调用,前台调用失败可忽略)+ 导航回番茄钟页面 */
private async handleBallClick(): Promise<void> {
if (this.ballController && this.context) {
try {
const abilityContext = this.context as common.UIAbilityContext;
const want: Want = {
bundleName: abilityContext.abilityInfo.bundleName,
abilityName: abilityContext.abilityInfo.name,
};
await this.ballController.restoreMainWindow(want);
} catch (e) {
// 应用已在前台时恢复主窗口会报错,忽略即可
}
}
try {
emitter.emit({ eventId: POMODORO_BALL_CLICK_EVENT_ID }, {
data: { value: 'ball_click' }
});
} catch (e) {
console.error('Failed to emit pomodoro ball click event:', JSON.stringify(e));
}
}
两个必须知道的约束:
restoreMainWindow仅支持在点击闪控球后调用(除非应用持有ohos.permission.AUTO_RESTORE_MAIN_WINDOW)。所以它只能放在 click 回调里,不能拿来做"主动拉起应用"。- 应用已在前台时调用会失败,
catch里直接忽略,因为此时用户本来就看得见界面。
第二段的 want 用 abilityInfo 动态取值,而不是写死包名。应用内导航则交给事件总线,由首页接收:
// 监听闪控球点击:导航回番茄钟页面
this.pomodoroBallClickListener = (_eventData: emitter.EventData): void => {
this.navigateToPomodoroPage();
};
emitter.on({ eventId: POMODORO_BALL_CLICK_EVENT_ID }, this.pomodoroBallClickListener);
导航时用 POP_TO_SINGLETON 防止重复入栈:
/** 点击闪控球:导航回番茄钟页面(栈顶已是番茄钟页则忽略) */
navigateToPomodoroPage(): void {
try {
const pathNames = this.pageInfos.getAllPathName();
if (pathNames.length > 0 && pathNames[pathNames.length - 1] === 'PomodoroPage') {
return;
}
this.pageInfos.pushPath({ name: 'PomodoroPage' }, { launchMode: LaunchMode.POP_TO_SINGLETON });
} catch (e) {
console.error('Failed to navigate to PomodoroPage from floating ball:', JSON.stringify(e));
}
}
为什么不用 restoreMainWindow 的 want 直接指定页面?因为官方对 want 的要求是加载指定页面,但应用内页面栈的复用、回退行为更可控——系统只负责把窗口还给我,去哪一页由我自己决定。
四、权限与配置清单
闪控球不是"声明一下就能用"的普通权限,官方把它归到受限权限:
官方原文:基于安全考虑,仅允许应用在前台时启动闪控球,并且需要具有 ohos.permission.USE_FLOAT_BALL 权限。
module.json5 里的声明:
{
"module": {
"requestPermissions": [
{
"name": "ohos.permission.USE_FLOAT_BALL",
"reason": "$string:float_ball_reason",
"usedScene": {
"abilities": [
"EntryAbility"
],
"when": "always"
}
}
]
}
}
注意 reason 必须指向字符串资源,且该权限属于 ACL 受限权限,需要在签名配置里一并申请,否则 startFloatingBall 会直接返回 201(Permission verification failed)。
还有三条绕不过去的限制:
- 仅前台可启动。后台服务里调
startFloatingBall不成立,这是安全设计,不是 bug。 - 同一应用只能有一个球,同一设备最多同时两个球,超出时新球替换最早启动的球(
1300021为多球冲突)。 - 场景要合规。官方列的是跨应用信息展示类场景;纯粹的"应用内小挂件"不符合准入描述,申报权限时要想清楚理由。
五、踩坑清单
- 64 字节不是 64 字符。中文一个字符 3 字节,
content写 21 个汉字就贴边了。越界直接1300019。 backgroundColor别带透明度。rgba()或 8 位带 Alpha 的值都不合规;要么'#008EF5',要么'#FF008EF5'这种形式。- update 不能换模板(
1300027)。想从"只有标题"升级成"标题+内容",只能先 stop 再 start。 - 静态模板不支持 update(
1300028)。如果选了STATIC又想着改文案,方向就错了。 - 重复启动会报
1300022。这不算失败,按幂等处理更稳。 - 球可能被用户删掉。长按进入待删除态后,用户可以直接删球;靠
stateChange的STOPPED同步本地状态,否则后续 update 一路1300024。 - 位置记忆有边界。关闭会记录位置,下次自动回到原处;但旋转屏幕或重启设备会恢复默认右上位置——别在文案里承诺"永远记得你的位置"。
- 模拟器版本有门槛。官方说明需 DevEco Studio 6.0.1 Release 及以上版本模拟器;更早的模拟器上跑不出球。
- 别和闪控窗抢生命周期。同应用已有闪控窗时启动球可能返回
1300034(与其它悬浮窗口冲突),要么先收窗,要么在业务层做互斥。 - 不符合准入场景就别强行接。官方对权限申报场景有明确描述,拿"应用内小挂件"去凑跨应用场景,审核与后续使用都有风险。
六、总结
先说清楚这个能力不适合谁:如果你的需求是"一个高度自定义的悬浮面板",闪控球会让你处处受限——尺寸写死、字体改不了、模板只有四种。这种情况应该看闪控窗或自绘窗口。闪控球适合的是一个关键信息、一眼要看见、还得在别人家应用上也看得见。
这个功能最终只有 160 余行代码,但把闪控球的几个关键点都走了一遍。三条经验可以带走:
- 先看规格,再定模板。70-98vp 宽、40vp 高、字体不可改、64 字节上限——这四条决定了你只能做一个"信息条",而不是一个迷你界面。选错模板(比如静态模板)后面全是死路。
- 球是有生命周期的外部资源。它不是你自己页面里的一个组件,可能被用户删、被系统停。本地状态必须以
stateChange为准,启动要幂等,失败要静默。 - 把"要不要显示"拆成两个变量。“用户想不想要”(开关)和"此刻该不该显示"(页面是否在前台)分开管理,才能避免页面内外互相打架。
最后是老实的一句话:系统的球不可能长得像你的设计稿,但它能稳定地浮在别人家应用上面、记得上次的位置、拖着不挡状态栏——这些"不酷但麻烦"的事,系统已经替你做了。
参考
更多推荐





所有评论(0)