鸿蒙闪控球实战:把番茄钟倒计时挂到任何应用之上

番茄钟有个天然矛盾:你启动它是为了专注,但一旦切去回消息、查文档、翻会议纪要,应用就被压到后台,倒计时也看不见了。等你想起它,一整个番茄已经过期,白专注了。

「不想上班」的番茄钟最初也想自绘一个悬浮球,很快放弃:窗口层级、手势拦截、拖拽吸附、状态栏避让、删除交互,每一件都要自己实现。直到鸿蒙在 API 20 放出闪控球(floatingBall)——系统级悬浮小组件,自带吸附、位置记忆、拖动避让与删除态。本文按官方文档把能力边界讲清,再讲这个倒计时球在「不想上班」里的完整落地与工程取舍。

一、闪控球是什么,能干什么

官方给的定义很克制:

官方原文:闪控球是一种在设备屏幕上悬浮的非全屏应用窗口,为应用提供临时的全局能力,完成跨应用交互。应用可以将关键信息以闪控球模式呈现。切换为闪控球模式后,用户可以进行其他界面操作。

注意三个关键词,它们决定了这个能力适不适合你:

  • 系统级。球由系统窗口服务绘制,不在你的页面树里,所以能浮在其他应用之上;也正因为如此,它的尺寸、字体、圆角都不由你决定。
  • 非全屏、临时。它是一块 40vp 高的信息条,不是第二个应用窗口。
  • 有准入门槛。官方明确列举适用场景:题目搜索、账单记录、商品比价、抢单、翻译、金融实时盯盘等"跨应用悬浮展示关键信息"的用途,并写明超范围使用会被处罚与限制。

与另外两种"浮起来"的方案对比

维度系统闪控球自绘悬浮窗(overlay)闪控窗(floatView)
谁负责窗口系统窗口服务应用自己系统(可绑定闪控球)
尺寸与样式固定规格,字体不可改完全自定义自定义,空间更大
拖拽吸附 / 位置记忆系统提供需自行实现系统提供
交互成本低高(层级、手势、避让)中
适合的内容一两个关键数字任意 UI小面板级 UI

「不想上班」的需求就是"把 24:31 和"专注中"三个字挂出去",第一条路显然是闪控球。

在这里插入图片描述

二、四个模板与硬规格

模板只有四种

枚举值布局必传参数
STATIC1图标 + 标题title、icon
NORMAL2标题 + 内容title
EMPHATIC3图标 + 标题 + 内容title
SIMPLE4仅标题(可双行)title

规格是写死的

官方原文:目前闪控球的规格为:整体尺寸宽为 70vp-98vp 之间,高为 40vp,标题和内容不支持自定义字体大小。

配套还有两条参数硬约束:

  • title 不可为空字符串,不超过 64 字节;
  • content 可选,不超过 64 字节;
  • backgroundColor 必须是不带透明度的十六进制('#008EF5' 或 '#FF008EF5')。

越界不会静默截断,而是直接返回 1300019(闪控球参数校验错误)。

为什么最终选 NORMAL

这是本项目的设计取舍,不是官方推荐:

  1. 40vp 高度里塞图标 + 标题 + 内容,图标会挤占文本宽度,而倒计时最怕被截断;
  2. 时间用 mm:ss(5 个字符)、阶段用 3 个汉字,title + content 刚好两行放下;
  3. SIMPLE 只能放标题,无法同时表达"还剩多久"和"处在什么阶段";
  4. 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。原因是:隐藏会让用户以为计时已经结束,灰球则明确表达"还停在这儿,等你继续"。

把三种状态放在一起看,球的表达其实是紧凑的:

计时状态titlecontent背景色球是否显示
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)。

还有三条绕不过去的限制:

  1. 仅前台可启动。后台服务里调 startFloatingBall 不成立,这是安全设计,不是 bug。
  2. 同一应用只能有一个球,同一设备最多同时两个球,超出时新球替换最早启动的球(1300021 为多球冲突)。
  3. 场景要合规。官方列的是跨应用信息展示类场景;纯粹的"应用内小挂件"不符合准入描述,申报权限时要想清楚理由。

五、踩坑清单

  1. 64 字节不是 64 字符。中文一个字符 3 字节,content 写 21 个汉字就贴边了。越界直接 1300019。
  2. backgroundColor 别带透明度。rgba() 或 8 位带 Alpha 的值都不合规;要么 '#008EF5',要么 '#FF008EF5' 这种形式。
  3. update 不能换模板(1300027)。想从"只有标题"升级成"标题+内容",只能先 stop 再 start。
  4. 静态模板不支持 update(1300028)。如果选了 STATIC 又想着改文案,方向就错了。
  5. 重复启动会报 1300022。这不算失败,按幂等处理更稳。
  6. 球可能被用户删掉。长按进入待删除态后,用户可以直接删球;靠 stateChange 的 STOPPED 同步本地状态,否则后续 update 一路 1300024。
  7. 位置记忆有边界。关闭会记录位置,下次自动回到原处;但旋转屏幕或重启设备会恢复默认右上位置——别在文案里承诺"永远记得你的位置"。
  8. 模拟器版本有门槛。官方说明需 DevEco Studio 6.0.1 Release 及以上版本模拟器;更早的模拟器上跑不出球。
  9. 别和闪控窗抢生命周期。同应用已有闪控窗时启动球可能返回 1300034(与其它悬浮窗口冲突),要么先收窗,要么在业务层做互斥。
  10. 不符合准入场景就别强行接。官方对权限申报场景有明确描述,拿"应用内小挂件"去凑跨应用场景,审核与后续使用都有风险。

六、总结

先说清楚这个能力不适合谁:如果你的需求是"一个高度自定义的悬浮面板",闪控球会让你处处受限——尺寸写死、字体改不了、模板只有四种。这种情况应该看闪控窗或自绘窗口。闪控球适合的是一个关键信息、一眼要看见、还得在别人家应用上也看得见。

这个功能最终只有 160 余行代码,但把闪控球的几个关键点都走了一遍。三条经验可以带走:

  1. 先看规格,再定模板。70-98vp 宽、40vp 高、字体不可改、64 字节上限——这四条决定了你只能做一个"信息条",而不是一个迷你界面。选错模板(比如静态模板)后面全是死路。
  2. 球是有生命周期的外部资源。它不是你自己页面里的一个组件,可能被用户删、被系统停。本地状态必须以 stateChange 为准,启动要幂等,失败要静默。
  3. 把"要不要显示"拆成两个变量。“用户想不想要”(开关)和"此刻该不该显示"(页面是否在前台)分开管理,才能避免页面内外互相打架。

最后是老实的一句话:系统的球不可能长得像你的设计稿,但它能稳定地浮在别人家应用上面、记得上次的位置、拖着不挡状态栏——这些"不酷但麻烦"的事,系统已经替你做了。


参考

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐