目录
1 版本概述 2 技术路线 2.1 路线选型 2.2 整体架构 2.3 源码构成 3 核心机制 3.1 叫醒链路 3.2 系统代理提醒设计 3.3 入睡检测 3.4 通知权限闭环 3.5 状态持久化 3.6 服务卡片 4 界面与交互 4.1 页面结构 4.2 圆屏适配 4.3 表冠与焦点 4.4 导航与启动 5 权限与隐私 6 工程与构建 7 关键参数 8 能力边界

午睡叫醒 1.2.2 技术报告

项目内容
应用名称午睡叫醒
版本1.2.2(versionCode 1000013)
包名com.fy77.napwake
应用形态HarmonyOS 穿戴应用(wearable),ArkTS Stage 模型,单 entry 模块
目标设备HUAWEI WATCH 5 圆屏(466 × 466 px),兼容 HarmonyOS 穿戴设备
运行环境HarmonyOS,compileSdk / targetSdk 26.0.0,compatibleSdk 5.1.0(18)
发布范围中国大陆
上架包nap-wake-default-signed.app,1,531,368 B,2026-11-20 11:22 构建
隐私政策https://wuxiu.fy77.cn/

1 版本概述

午睡叫醒是一款运行在智能手表上的午睡定时唤醒应用。与固定时刻闹钟不同,本应用点「开始午睡」即按设定时长开始倒计时,并由手表系统托管代理提醒保证到点唤醒;计时期间继续检测手臂静止,检测到入睡后从入睡时刻重新计时,未检测到则原提醒保持不变。

1.2.2 提供以下能力:


2 技术路线

2.1 路线选型

技术议题选定方案依据
应用模型ArkTS + Stage 模型,UIAbility + FormExtensionAbility穿戴端原生开发模型,可调用系统级后台与通知能力
设备类型单一 wearable 模块,orientation: portrait穿戴屏幕不旋转,竖屏固定表冠方向
叫醒执行者系统代理提醒 reminderAgentManager提醒由系统托管调度,熄屏、应用退出或被回收后仍可触发;应用自身不具备可靠后台常驻能力
本地唤醒vibrator 振动,无音频播放依赖减少运行时依赖,唤醒方式与系统提醒保持一致
入睡判定机载加速度计单一信号;佩戴检测传感器(设备支持时)仅作状态提示穿戴平台未向第三方开放系统级睡眠分期/入睡事件;Health Kit 历史睡眠数据属高阶数据,个人开发者权限不可申请;单一信号避免第二传感器无回调时判定被一票否决
数据存储@kit.ArkData Preferences,设备本地设置项与提醒标识需跨冷启动恢复,无服务端需求
应用间通信AppStorage + @Watch、postCardAction router卡片与 Ability 之间传递一次性触发信号

2.2 整体架构

┌─────────────────────────────────────────────────────────┐
│ 表现层   Index.ets(首页 / 设置 / 滚轮 / 守护 / 隐私门)      │
│          NapCard.ets(2×2 服务卡片)                        │
├─────────────────────────────────────────────────────────┤
│ 业务层   Index.ets 状态机:发布入口、授权闭环、倒计时、返回栈  │
│          EntryAbility.ets:生命周期、跨组件信号、窗口初始化    │
├─────────────────────────────────────────────────────────┤
│ 能力层   NapManager.ets    代理提醒 Timer / Alarm            │
│          SleepDetector.ets 加速度计入睡检测                   │
│          Settings.ets      偏好持久化                       │
│          WakePlayer.ets    本地振动                         │
│          EntryFormAbility.ets 卡片数据刷新                   │
├─────────────────────────────────────────────────────────┤
│ 系统服务 BackgroundTasksKit / SensorServiceKit /             │
│          NotificationKit / ArkData / FormKit / ArkUI        │
└─────────────────────────────────────────────────────────┘

页面全部由 Index.ets 单组件按状态条件渲染,main_pages.json 仅注册 pages/Index;服务卡片为独立卡片窗口,通过路由参数与 Ability 通信。

2.3 源码构成

文件职责
entryability/EntryAbility.ets生命周期、窗口底色、前后台重检信号、卡片一键开始与通知拉起信号(不申请通知权限)
pages/Index.ets全部界面、状态机、授权闭环、表冠焦点、右滑返回、倒计时
utils/NapManager.ets主/预备/重复/兜底/每日提醒的发布与取消,通知授权闸
utils/SleepDetector.ets加速度计订阅与静止判定、佩戴状态订阅、等待页状态上报、传感器无数据诊断、资源释放
utils/Settings.etsnap_settings_v2 偏好读写,含提醒标识与隐私同意状态
utils/WakePlayer.ets本地振动唤醒
napcard/NapCard.ets2 × 2 卡片界面与 postCardAction 触发
entryformability/EntryFormAbility.ets卡片添加、更新、可见性变化时同步已保存时长

3 核心机制

3.1 叫醒链路

系统代理提醒为主链路,本地倒计时与振动为辅助链路,两者构成冗余:

  1. 用户触发开始午睡(首页按钮/卡片一键开始/每日提醒通知)。
  2. 通知授权闸确认授权;未授权则登记待补发任务并引导开启。
  3. 点击瞬间即开始本地倒计时,并按设定时长发布整批代理提醒(主提醒 + 预备提醒 + 重复提醒),不加任何入睡缓冲。
  4. 同时开启常亮、启动前台加速度计入睡检测。
  5. 检测判定入睡后,以入睡时刻为起点重新计时并重发整批提醒;新提醒发布成功后再取消点开始时那批。始终未检测到入睡则原提醒保持不变。
  6. 到点由手表系统发起振动与通知;应用在前台时同步触发本地振动与倒计时显示。
  7. 用户点通知或主动结束午睡时,取消全部未触发提醒并清理持久化标识。

主提醒附带提前 1 分钟预备提醒与可选重复提醒。所有已发布提醒标识写入 Preferences,保证应用被回收后重启仍能取消,避免重复响铃。

3.2 系统代理提醒设计

提醒类型触发说明
主提醒TIMER点击开始后设定时长点击即发布,到点唤醒,携带 napKind=wake 供点击后结束守护
预备提醒TIMER主提醒前 60 秒时长大于 90 秒时发布
重复提醒TIMER主提醒后按间隔最多 3 条,覆盖到点后 1 小时窗口
重计时批次TIMER入睡时刻 + 设定时长检测到入睡后整批重发,成功后取消点击时那批;未检测到则不重发
每日提醒ALARM每天指定时刻daysOfWeek 取 1~7,携带关闭按钮与打开应用跳转

TIMER 与 ALARM 均显式设置 ringDuration: 60(秒),保证到点持续振动;通知渠道为 SOCIAL_COMMUNICATION,文案通过 titleResourceId / contentResourceId 引用本地资源。通知标识由递增序列生成,发布失败逐条捕获并输出错误码,单条失败不影响其余提醒;全部失败时界面给出可见提示。

3.3 入睡检测

开始午睡后前台订阅加速度计,采样周期 200 ms。入睡判定只依赖「手臂持续静止」这一单一信号,不再引入第二传感器作为并列条件,避免其一无回调时判定被一票否决:

参数取值含义
加速度偏差阈值0.9 m/s²单采样「合加速度与 9.8 的偏差」小于该值记为静止采样,放宽以容纳趴睡呼吸级微动
静止窗口15 s(75 采样)窗口内静止采样占比 ≥ 75% 才整体判为静止段,避免单次抖动一票否决
累计静止时长180 s静止段按实际采样间隔累加达标才认定入睡;活动时按 dt 缓慢回退,不清零
最短守护时长120 s进入守护 2 分钟内不判定入睡,避免误触发
采样周期200 ms加速度计与佩戴检测一致
无回调诊断窗口5 s启动后 5 秒未收到加速度数据即上报无数据状态

设备支持 WEAR_DETECTION 时运行时探测并订阅佩戴状态,用于区分「未佩戴」与「已佩戴但未入睡」;未佩戴时内部静止计时照常累计,且不判定入睡,避免手表平放桌面被误判。设备不支持该传感器时退化为纯加速度计判定,静止达标即入睡。加速度计订阅失败或超时无回调时,界面显式提示「未收到传感器数据」,可直接区分权限/硬件问题与阈值未达标。

计时页在尚未检测到入睡时显示「检测入睡中 · 睡着后重新计时」,让用户明确当前倒计时可能因重计时而后移;检测到入睡后标题切换为「已入睡 · 倒计时」。状态机(正在检测传感器/未收到传感器数据/未检测到佩戴/活动中尚未入睡/静止中)与原等待页版式仍保留在代码中作为状态异常兜底,正常流程不再进入。入睡回调与传感器回调均做异常隔离,判定完成后注销订阅释放资源。传感器读数仅在内存中瞬时参与计算,不存储、不上传。

3.4 通知权限闭环

代理提醒依赖通知授权,未授权时 publishReminder 会失败。当前实现把授权处理做成闭环:

通知权限申请的唯一入口是 Index.ets 的 requestNotifOnLaunch(),唯一调用点是首装隐私门「同意」的 onClick;aboutToAppear 的回归用户分支与 EntryAbility 层都不申请。首装严格串行流程:显示隐私门 → 点「同意」→ 弹系统权限框 → 允许则首页显示「开始午睡 / 午睡设置」,拒绝则只显示手动开启引导条与「关闭应用」。后续打开(loadPrivacyAgreed 返回已同意)只由 isNotificationEnabled() 判定:已授权 → 出「开始午睡 / 午睡设置」;未授权 → 只留手动开启引导条与「关闭应用」,全程不弹系统框、无空白过渡帧。隐私门展示期间绝不弹权限框。

运行期行为规格(用户定稿)

用户点「开始午睡」时,beginNap() 同步做三件事:本地倒计时从设定时长开始、发布整批系统代理提醒(startNap(minutes*60),系统侧托管、进程外)、启动前台加速度计入睡检测。此后四种分支:

情形已发布提醒入睡检测叫醒
① 应用在前台点击时那批(设定时长)持续检测判定入睡 → 以入睡时刻重新计时,重发整批;新提醒成功后再取消旧批
② 应用被杀(进程终止)保留,不取消不再恢复(冷启动不自动续检)由系统侧提醒按点击时刻的设定时长叫醒
③ 退后台且无连续任务 → 被杀、传感器回调中断保留,不取消中断同 ②
④ 退后台又恢复(进程存活)保留不动onForeground / onPageShow 触发 resumeGuardIfNeeded() 重新订阅传感器检测到入睡仍重计时并重发

实现要点:onPageHide() 只 detector.stop() 注销订阅,不碰提醒;resumeGuardIfNeeded() 在 view==='guard' && !detectedSleep && !detector.isRunning() 时调 startGuardDetector();detectedSleep 保证重计时只发生一次;beginNap() 与 onFallAsleep() 均先发新提醒、成功后再 cancelNap(旧批),失败则沿用旧批,避免中间出现无提醒空档;sleeping 守卫使重复点击不会叠加第二份提醒。未检测到入睡时,整条链路与普通倒计时完全一致,不做任何额外变更。

3.5 状态持久化

偏好库 nap_settings_v2 保存以下字段:

字段默认值用途
minutes30每天午睡时长(分钟)
repeatInterval3重复提醒间隔(分钟,0 为不重复)
dailyGuardtrue每日定时提醒开关
guardHour / guardMinute12 / 30每日提醒时刻
dailyGuardId0已发布的每日提醒标识,用于冷启动判断是否需补排
napReminderIds[]当前生效的午睡提醒标识列表
estimateId0旧版兜底提醒标识,仅用于升级用户清理残留,新流程不再发布
privacyAgreedfalse隐私政策同意状态

每日提醒为系统侧持久调度,应用重启不重复排期,仅在首次安装且开关开启时补排一次。服务卡片侧通过独立偏好实例读取已保存时长,在卡片添加、更新、重新可见时刷新显示。

3.6 服务卡片

卡片为 ArkTS 语法的 2 × 2 表单,designWidth: 720 且开启自适应宽度,不启用定时更新。卡片显示已保存午睡时长,主按钮通过 postCardAction 的 router 动作携带 autoStart 分钟数拉起 EntryAbility;Ability 在 onCreate / onNewWant 解析参数后写入 AppStorage 的分钟数与时间戳信号,首页通过 @StorageLink + @Watch 接收并触发立即计时,时间戳保证同一时长重复点击仍可触发。次按钮跳转设置页。


4 界面与交互

4.1 页面结构

页面内容
隐私门首次启动展示政策摘要、同意/拒绝
首页标题与副标题、通知权限引导条、开始午睡、午睡设置、每日提醒提示
设置页午睡时长、提醒间隔、每天提醒三个胶囊入口与返回
时长/间隔/时刻页List 滚轮选择,确定与返回;时刻页为时、分双列滚轮
午睡页计时中(「午睡中 · 倒计时」+ 剩余时间 + 预计唤醒时刻 + 「检测入睡中 · 睡着后重新计时」+ 结束午睡)/已入睡(标题切换为「已入睡 · 倒计时」)

页面切换由 @State view(设置/守护)与 @State page(home/main/duration/repeat/time)条件渲染,隐私门与主内容互斥渲染,避免多个默认焦点竞争。

4.2 圆屏适配

穿戴屏密度 320 dpi,1 vp = 2 px,466 px 圆屏的逻辑宽度为 233 vp,全部尺寸按 233 vp 画布书写。主色 #065279,页面显式声明背景色。滚动内容按圆屏安全区设置上、左、右内边距,行内容整体居中以避免顶部圆边裁切。点开始即进入计时,正常流程不再出现等待页与压暗层;等待页版式仅作为状态异常兜底保留在代码中。

4.3 表冠与焦点

可滚动页面统一使用 List,容器 focusable(true) / defaultFocus(true) / focusOnTouch(true),列表子项 focusable(true);子项不设 focusOnTouch,保证点击不夺走容器焦点,表冠与触摸两种操作并存。由于子页为重复挂载,各滚动容器在 onAppear 中通过 focusControl.requestFocus 显式请求焦点,使首次旋转表冠即可滚动。双列时刻页由主列持有默认焦点,副列通过点击切换焦点。页面级按钮保持不可获焦。

4.4 导航与启动

右滑返回按层级逐级回退,仅在首页触发退出应用。启动页图标使用 216 × 216 扁平图,按实际大小居中显示;启动器图标使用分层图标。主窗口在加载内容前设置为应用底色,消除启动过渡阶段的白屏。


5 权限与隐私

权限用途使用场景
PUBLISH_AGENT_REMINDER发布到点唤醒与每日提醒始终
KEEP_BACKGROUND_RUNNING守护模式期间维持倒计时与入睡检测始终
VIBRATE振动唤醒使用中
ACCELEROMETER判定手臂静止状态使用中

应用不申请健康数据权限,源码中不含心率相关实现;不读取陀螺仪数据,也不为其声明权限。佩戴状态传感器由系统按需提供,不额外申请权限。不集成统计、广告或数据上报 SDK,不联网传输数据,无服务端后台。传感器读数仅瞬时用于入睡判定,设置项仅保存在设备本地。隐私政策以公网 URL 提供,应用内首次启动设置同意门。


6 工程与构建

工程为单模块 Stage 工程,apiType: stageMode,runtimeOS: HarmonyOS,签名算法 SHA256withECDSA,发布使用 release 签名配置与 AGC 发布 Profile。

构建命令:

node build-app-release.js

脚本配置 JAVA_HOME、DEVECO_SDK_HOME 与 JBR 路径后调用 hvigor 执行 assembleApp --mode project -p product=default -p buildMode=release --no-daemon。

构建结果值
编译BUILD SUCCESSFUL
产物nap-wake-default-signed.app
大小1,531,314 B
时间2026-11-20 11:08
包内配置orientation = portrait,startWindowIcon = 216 px 扁平图,icon = 分层图标,deviceTypes = wearable

商店截图 7 张,覆盖首页、设置页、时长选择、提醒间隔、等待入睡、倒计时、服务卡片。其中 shot-5-waiting.png 于 2026-11-14 按 1.2.0 等待页 still 态重做:补上「静止中 · 正在确认是否入睡」状态行与 lie_down 说明,保留「已躺平 42 秒」(仅静止中显示),并保留 STANDBY_DIM = 0.5 整屏微光罩——该罩是真机等待页特性(build() 346–354 行,微光 / OLED 省电 / 保证预览与真机一致),商店截图必须还原真机,不可为了「和其余 6 张一样亮」而去掉;生成脚本 gen_shot5_waiting_120.py(Edge headless,840×840 圆盘)。


7 关键参数

参数取值
午睡时长范围5~120 分钟,步长 5,默认 30
重复提醒间隔0/1/2/3/5/10 分钟,默认 3
每日提醒时刻时 0~23,分 0~55 步长 5,默认 12:30
系统提醒振动时长60 秒
本地振动时长3 秒
提前预备提醒到点前 60 秒
重复提醒上限3 次,覆盖到点后 1 小时
入睡缓冲300 秒
微光待机不透明度0.5
卡片规格2 × 2,ArkTS

8 能力边界