猫咪专注 CatFocus 技术博客：一款鸿蒙原生自律计时工具的设计与实现

本文将深入解析 CatFocus（猫咪专注）这款 HarmonyOS 原生应用的技术架构，探讨其在「零功耗冬眠」计时、后台保活、严格模式开发等方面的实践经验。

APP下载地址：

https://appgallery.huawei.com/app/detail?id=com.von.catfocus\&channelId=SHARE\&source=appshare

一、项目初识

CatFocus（猫咪专注） 是一款基于 HarmonyOS NEXT (API 6.0.2) 开发的自律计时工具，用可爱的猫咪陪伴让专注变成一种享受。

属性	值
包名	`com.von.catfocus`
版本	1.0.0 (Build 1000000)
开发语言	ArkTS (ArkUI Stage 模式)
架构模式	响应式声明式 UI + 本地持久化 + 长时任务保活

二、核心技术亮点

2.1 「零功耗冬眠」计时架构

这是 CatFocus 最核心的技术创新点。面对鸿蒙后台任务管理规范，传统做法是持有 RunningLock 保持应用活跃，但这会导致应用市场审核被拒。

CatFocus 的解决方案：

绝对时间戳计时：不依赖定时器增量累加，而是基于「结束时间戳 - 当前时间戳」计算剩余时间，彻底免疫系统杀后台
onPageHide 主动休眠：应用退至后台时释放所有定时器与运行锁，100% 契合应用市场休眠审核规范
onPageShow 前台校准：切回前台时瞬间同步校准时间，确保计时精度

typescript 复制代码

// 核心计时逻辑（简化）
onPageHide() {
  // 主动释放资源，彻底归还系统
  this.timer?.stop();
  this.runningLock?.unpin();
}

onPageShow() {
  // 切回前台时校准时间
  const now = Date.now();
  const remaining = this.endTimestamp - now;
  this.uiState.remainingSeconds = Math.max(0, remaining / 1000);
}

2.2 合规后台保活：Continuous Task

为了在通知栏展示守护卡片，CatFocus 接入了系统级 长时任务 (Continuous Task)：

后台模式	用途
`dataTransfer`	支撑计时状态的后台流转
`audioPlayback`	支撑白噪音的持续播放

在 module.json5 中声明：

json 复制代码

{
  "module": {
    "requestPermissions": [
      { "name": "ohos.permission.KEEP_BACKGROUND_RUNNING" }
    ],
    "abilities": [{
      "backgroundModes": ["dataTransfer", "audioPlayback"]
    }]
  }
}

2.3 严格模式下的数据安全

项目采用 ArkTS Strict 严格模式 ，这意味着更强的类型检查和更严格的编码规范。开发过程中尤其需要注意引用污染问题：

typescript 复制代码

// ❌ 错误：直接返回全局常量引用
getDefaultCats(): Cat[] {
  return DEFAULT_CATS; // 可能被意外修改
}

// ✅ 正确：深拷贝返回
getDefaultCats(): Cat[] {
  return JSON.parse(JSON.stringify(DEFAULT_CATS));
}

PersistenceManager 在返回默认兜底数据时，引入 JSON.parse(JSON.stringify()) 强制深拷贝，斩断全局常量引用污染。

三、UI 架构实现

3.1 页面路由

复制代码

SplashPage (启动页)
    ↓
Index (全局数据初始化)
    ↓
[可选] FocusingPage (专注页) ←→ SuccessPage / FailPage
                              ↓
                          CatDetailPage (图鉴详情)

3.2 响应式状态管理

利用 AppStorage 作为全局响应式状态池：

typescript 复制代码

// 数据写入
AppStorage.setOrCreate('focusState', focusState);

// 页面读取
@StorageLink('focusState') focusState: FocusState = new FocusState();

3.3 语义化深色模式

CatFocus 弃用硬编码 HEX 颜色，全量接入鸿蒙原生语义色阶：

typescript 复制代码

// ❌ 硬编码
backgroundColor: '#000000'

// ✅ 语义化
backgroundColor: $r('sys.color.comp_background_primary')

无论在应用内还是桌面系统，UI 的背景、文字、阴影均能随系统深浅模式无缝翻转。

四、猫咪系统设计

4.1 稀有度体系

稀有度	数量	解锁方式
R	3 只	初始解锁
SR	2 只	番茄钟完成解锁
SSR	1 只	图鉴满级后转化为陪伴次数

4.2 数据模型

typescript 复制代码

interface Cat {
  id: string;
  name: string;
  rarity: 'R' | 'SR' | 'SSR';
  themeColor: string;
  quote: string;        // 专属寄语
  companionCount: number; // 陪伴次数
}

五、白噪音实现

采用 @kit.MediaKit 的 AVPlayer 底层播放能力，支持后台音频播放：

场景	音频
壁炉	~
雷雨	~
森林	~
咖啡馆	~
图书馆	~
海浪	~

单例模式 AudioPlayerService：

typescript 复制代码

// 确保全局唯一音频实例
class AudioPlayerService {
  private static instance: AudioPlayerService;
  private player: AVPlayer;
  
  static getInstance(): AudioPlayerService {
    if (!this.instance) {
      this.instance = new AudioPlayerService();
    }
    return this.instance;
  }
}

卡片	规格	功能
CatCompanionCard	2×2	展示当前陪伴猫咪与今日时长，点击唤起
CatStatsCard	2×4	动态进度条展示今日目标达成率

七、目录结构一览

复制代码

catfocus/
├── AppScope/                     
└── entry/src/main/           
    ├── module.json5             
    ├── ets/
    │   ├── entryability/        # 主入口
    │   ├── entryformability/  # 卡片生命周期
    │   ├── models/           # 数据模型
    │   ├── pages/           # 路由页面
    │   ├── views/           # 视图片段
    │   ├── utils/          # 工具服务
    │   └── widget/pages/   # 桌面卡片
    └── resources/           # 资源配置