| 项目 | 内容 |
|---|---|
| 应用名称 | 午睡叫醒 |
| 版本 | 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.2.2 提供以下能力:
| 技术议题 | 选定方案 | 依据 |
|---|---|---|
| 应用模型 | ArkTS + Stage 模型,UIAbility + FormExtensionAbility | 穿戴端原生开发模型,可调用系统级后台与通知能力 |
| 设备类型 | 单一 wearable 模块,orientation: portrait | 穿戴屏幕不旋转,竖屏固定表冠方向 |
| 叫醒执行者 | 系统代理提醒 reminderAgentManager | 提醒由系统托管调度,熄屏、应用退出或被回收后仍可触发;应用自身不具备可靠后台常驻能力 |
| 本地唤醒 | vibrator 振动,无音频播放依赖 | 减少运行时依赖,唤醒方式与系统提醒保持一致 |
| 入睡判定 | 机载加速度计单一信号;佩戴检测传感器(设备支持时)仅作状态提示 | 穿戴平台未向第三方开放系统级睡眠分期/入睡事件;Health Kit 历史睡眠数据属高阶数据,个人开发者权限不可申请;单一信号避免第二传感器无回调时判定被一票否决 |
| 数据存储 | @kit.ArkData Preferences,设备本地 | 设置项与提醒标识需跨冷启动恢复,无服务端需求 |
| 应用间通信 | AppStorage + @Watch、postCardAction router | 卡片与 Ability 之间传递一次性触发信号 |
┌─────────────────────────────────────────────────────────┐
│ 表现层 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 通信。
| 文件 | 职责 |
|---|---|
entryability/EntryAbility.ets | 生命周期、窗口底色、前后台重检信号、卡片一键开始与通知拉起信号(不申请通知权限) |
pages/Index.ets | 全部界面、状态机、授权闭环、表冠焦点、右滑返回、倒计时 |
utils/NapManager.ets | 主/预备/重复/兜底/每日提醒的发布与取消,通知授权闸 |
utils/SleepDetector.ets | 加速度计订阅与静止判定、佩戴状态订阅、等待页状态上报、传感器无数据诊断、资源释放 |
utils/Settings.ets | nap_settings_v2 偏好读写,含提醒标识与隐私同意状态 |
utils/WakePlayer.ets | 本地振动唤醒 |
napcard/NapCard.ets | 2 × 2 卡片界面与 postCardAction 触发 |
entryformability/EntryFormAbility.ets | 卡片添加、更新、可见性变化时同步已保存时长 |
系统代理提醒为主链路,本地倒计时与振动为辅助链路,两者构成冗余:
主提醒附带提前 1 分钟预备提醒与可选重复提醒。所有已发布提醒标识写入 Preferences,保证应用被回收后重启仍能取消,避免重复响铃。
| 提醒 | 类型 | 触发 | 说明 |
|---|---|---|---|
| 主提醒 | TIMER | 点击开始后设定时长 | 点击即发布,到点唤醒,携带 napKind=wake 供点击后结束守护 |
| 预备提醒 | TIMER | 主提醒前 60 秒 | 时长大于 90 秒时发布 |
| 重复提醒 | TIMER | 主提醒后按间隔 | 最多 3 条,覆盖到点后 1 小时窗口 |
| 重计时批次 | TIMER | 入睡时刻 + 设定时长 | 检测到入睡后整批重发,成功后取消点击时那批;未检测到则不重发 |
| 每日提醒 | ALARM | 每天指定时刻 | daysOfWeek 取 1~7,携带关闭按钮与打开应用跳转 |
TIMER 与 ALARM 均显式设置 ringDuration: 60(秒),保证到点持续振动;通知渠道为 SOCIAL_COMMUNICATION,文案通过 titleResourceId / contentResourceId 引用本地资源。通知标识由递增序列生成,发布失败逐条捕获并输出错误码,单条失败不影响其余提醒;全部失败时界面给出可见提示。
开始午睡后前台订阅加速度计,采样周期 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 时运行时探测并订阅佩戴状态,用于区分「未佩戴」与「已佩戴但未入睡」;未佩戴时内部静止计时照常累计,且不判定入睡,避免手表平放桌面被误判。设备不支持该传感器时退化为纯加速度计判定,静止达标即入睡。加速度计订阅失败或超时无回调时,界面显式提示「未收到传感器数据」,可直接区分权限/硬件问题与阈值未达标。
计时页在尚未检测到入睡时显示「检测入睡中 · 睡着后重新计时」,让用户明确当前倒计时可能因重计时而后移;检测到入睡后标题切换为「已入睡 · 倒计时」。状态机(正在检测传感器/未收到传感器数据/未检测到佩戴/活动中尚未入睡/静止中)与原等待页版式仍保留在代码中作为状态异常兜底,正常流程不再进入。入睡回调与传感器回调均做异常隔离,判定完成后注销订阅释放资源。传感器读数仅在内存中瞬时参与计算,不存储、不上传。
代理提醒依赖通知授权,未授权时 publishReminder 会失败。当前实现把授权处理做成闭环:
isNotificationEnabled,已授权直接发布;未授权尝试系统授权弹窗。notifPrompting 门控);用户直接点「允许」后 notifEnabled 立即置真,首页切回正常功能按钮,全程不出现手动开启页。仅弹窗被拒/不可弹时才显示引导条,固定文案「请手动开启通知后重启应用」+ 手表端手动开启路径 +「关闭应用」按钮(terminateSelf 退出);另设 1.2 s 超时兜底,避免预览器或个别设备上授权 Promise 不回调导致引导条长期不显示。重启后由冷启动重新检测授权状态,不做跨设备设置页跳转。EntryAbility.onForeground 写入重检信号)及页面显示时重新检测授权,已授权则自动补发被拦截的提醒。1600004(已拒绝不再弹窗)、1700001(通知未授权)、1700002(提醒条数超限)。穿戴设备能力集不含 SystemCapability.Notification.NotificationSettings,通知设置类 API 不在本版本调用。通知权限申请的唯一入口是 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 守卫使重复点击不会叠加第二份提醒。未检测到入睡时,整条链路与普通倒计时完全一致,不做任何额外变更。
偏好库 nap_settings_v2 保存以下字段:
| 字段 | 默认值 | 用途 |
|---|---|---|
| minutes | 30 | 每天午睡时长(分钟) |
| repeatInterval | 3 | 重复提醒间隔(分钟,0 为不重复) |
| dailyGuard | true | 每日定时提醒开关 |
| guardHour / guardMinute | 12 / 30 | 每日提醒时刻 |
| dailyGuardId | 0 | 已发布的每日提醒标识,用于冷启动判断是否需补排 |
| napReminderIds | [] | 当前生效的午睡提醒标识列表 |
| estimateId | 0 | 旧版兜底提醒标识,仅用于升级用户清理残留,新流程不再发布 |
| privacyAgreed | false | 隐私政策同意状态 |
每日提醒为系统侧持久调度,应用重启不重复排期,仅在首次安装且开关开启时补排一次。服务卡片侧通过独立偏好实例读取已保存时长,在卡片添加、更新、重新可见时刷新显示。
卡片为 ArkTS 语法的 2 × 2 表单,designWidth: 720 且开启自适应宽度,不启用定时更新。卡片显示已保存午睡时长,主按钮通过 postCardAction 的 router 动作携带 autoStart 分钟数拉起 EntryAbility;Ability 在 onCreate / onNewWant 解析参数后写入 AppStorage 的分钟数与时间戳信号,首页通过 @StorageLink + @Watch 接收并触发立即计时,时间戳保证同一时长重复点击仍可触发。次按钮跳转设置页。
| 页面 | 内容 |
|---|---|
| 隐私门 | 首次启动展示政策摘要、同意/拒绝 |
| 首页 | 标题与副标题、通知权限引导条、开始午睡、午睡设置、每日提醒提示 |
| 设置页 | 午睡时长、提醒间隔、每天提醒三个胶囊入口与返回 |
| 时长/间隔/时刻页 | List 滚轮选择,确定与返回;时刻页为时、分双列滚轮 |
| 午睡页 | 计时中(「午睡中 · 倒计时」+ 剩余时间 + 预计唤醒时刻 + 「检测入睡中 · 睡着后重新计时」+ 结束午睡)/已入睡(标题切换为「已入睡 · 倒计时」) |
页面切换由 @State view(设置/守护)与 @State page(home/main/duration/repeat/time)条件渲染,隐私门与主内容互斥渲染,避免多个默认焦点竞争。
穿戴屏密度 320 dpi,1 vp = 2 px,466 px 圆屏的逻辑宽度为 233 vp,全部尺寸按 233 vp 画布书写。主色 #065279,页面显式声明背景色。滚动内容按圆屏安全区设置上、左、右内边距,行内容整体居中以避免顶部圆边裁切。点开始即进入计时,正常流程不再出现等待页与压暗层;等待页版式仅作为状态异常兜底保留在代码中。
可滚动页面统一使用 List,容器 focusable(true) / defaultFocus(true) / focusOnTouch(true),列表子项 focusable(true);子项不设 focusOnTouch,保证点击不夺走容器焦点,表冠与触摸两种操作并存。由于子页为重复挂载,各滚动容器在 onAppear 中通过 focusControl.requestFocus 显式请求焦点,使首次旋转表冠即可滚动。双列时刻页由主列持有默认焦点,副列通过点击切换焦点。页面级按钮保持不可获焦。
右滑返回按层级逐级回退,仅在首页触发退出应用。启动页图标使用 216 × 216 扁平图,按实际大小居中显示;启动器图标使用分层图标。主窗口在加载内容前设置为应用底色,消除启动过渡阶段的白屏。
| 权限 | 用途 | 使用场景 |
|---|---|---|
| PUBLISH_AGENT_REMINDER | 发布到点唤醒与每日提醒 | 始终 |
| KEEP_BACKGROUND_RUNNING | 守护模式期间维持倒计时与入睡检测 | 始终 |
| VIBRATE | 振动唤醒 | 使用中 |
| ACCELEROMETER | 判定手臂静止状态 | 使用中 |
应用不申请健康数据权限,源码中不含心率相关实现;不读取陀螺仪数据,也不为其声明权限。佩戴状态传感器由系统按需提供,不额外申请权限。不集成统计、广告或数据上报 SDK,不联网传输数据,无服务端后台。传感器读数仅瞬时用于入睡判定,设置项仅保存在设备本地。隐私政策以公网 URL 提供,应用内首次启动设置同意门。
工程为单模块 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 圆盘)。
| 参数 | 取值 |
|---|---|
| 午睡时长范围 | 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 |