🌐 语言 / Language: 中文 | English

vela_band

一个基于 openvela 快应用框架的智能手环演示应用，包含多表盘、健康数据、运动记录、消息通知、蓝牙同步和低功耗管理等功能。

目标设备：智能手表 / 手环（deviceTypeList: ["watch"]）
当前状态：面向 AIoT-IDE 模拟器构建和演示，部分系统能力在真机上需根据硬件进一步适配。

---

目录

• 功能概览
• 环境要求
• 快速开始
  • 一键构建
  • 分步构建
  • 在模拟器中运行
• 项目结构
• 主要页面导航
• 控制台模拟通知
• 负责人速查
  • 生命周期要点
  • A/C/D/E 核心文件对应
  • 当前已知边界
  • 常见问题排查
• 模拟器演示清单
• 第三方依赖
• 文档索引
• 开源协议
• 相关链接

---

功能概览

功能	说明
多表盘	3 款表盘（活力数字、极简霓虹、运动仪表），左右滑动切换，长按进入选择页，持久化保存
健康数据	步数、卡路里、站立、心率，支持 7 天历史趋势
运动记录	步行 / 跑步，暂停、继续、结束，记录保存并合并到当日健康数据
消息通知	来电、短信、App 通知全屏覆盖，支持 IDE 控制台模拟和演示页触发
蓝牙同步	模拟 BLE 连接、分包传输、ACK 确认，真机只需替换底层传输层
低功耗管理	ACTIVE / DIM / SLEEP 三级状态，动态刷新率和抬腕唤醒
设置	蓝牙同步、震动、亮度、抬腕、低功耗

---

环境要求

• Node.js（推荐 LTS）
• AIoT-IDE（用于模拟器调试、真机安装）
• Windows / macOS / Ubuntu

---

快速开始

一键构建 (build.bat / build.sh)

项目根目录提供了 一键构建脚本，自动检测依赖并构建 RPK：

Windows：

build.bat

macOS / Linux：

sh build.sh

脚本会自动执行：

1. 检查 node_modules 是否存在，若缺失则自动运行 npm install
2. 运行 npm run build 构建 RPK
3. 打印构建结果（✅ 成功 / ❌ 失败）

构建产物位于 .temp_vela_band/dist/com.application.watch.demo.debug.1.0.0.rpk。

分步构建

# 1. 安装依赖
npm install

# 2. 开发模式（热更新）
npm run start

# 3. 构建开发版 RPK
npm run build
# ✅ build success

# 4. 构建发布版 RPK
npm run release

# 5. 代码规范检查（可选）
npm run lint

在模拟器中运行

1. 打开 AIoT-IDE
2. 导入本仓库
3. 安装依赖后，点击 运行/调试 选择已创建的模拟器
4. 项目入口为 pages/clock（表盘页）

---

项目结构

vela_band
├── LICENSE                    # MIT 开源协议（单独文件）
├── NOTICE                     # 第三方依赖声明
├── README.md                  # 本文件
├── build.bat                  # Windows 一键构建
├── build.sh                   # macOS/Linux 一键构建
├── docs/                      # 详细文档
│   ├── README_EN.md           # 英文版 README
│   ├── TECHNICAL.md           # 技术方案（架构、动画、系统 API）
│   ├── B_F_IMPLEMENTATION.md  # 运动 / 蓝牙模块实现说明
│   └── PROJECT_OWNER_GUIDE.md # 项目负责人口袋手册（语法、排查、学习顺序）
├── src/
│   ├── manifest.json          # 应用配置与页面路由
│   ├── app.ux                 # 应用生命周期
│   ├── common/                # 业务逻辑与工具
│   │   ├── watch_data.js      # 健康 / 历史 / 通知数据
│   │   ├── power_manager.js   # 功耗状态机
│   │   ├── device_settings.js # 设置持久化
│   │   ├── notification_manager.js # 通知接收与演示
│   │   ├── page_motion.js     # 页面转场动画
│   │   ├── workout_manager.js # 运动记录状态机
│   │   ├── sync_protocol.js   # 蓝牙同步协议包
│   │   └── ble_sync.js        # 蓝牙传输适配层
│   ├── components/            # 表盘组件
│   │   └── watchfaces/        # sport / simple / dashboard
│   ├── pages/                 # 页面
│   │   ├── clock/             # 主表盘
│   │   ├── applist/           # 应用列表
│   │   ├── heartrate/         # 心率详情
│   │   ├── steps/             # 今日健康
│   │   ├── history/           # 7 日趋势
│   │   ├── workout_select/    # 运动选择
│   │   ├── workout/           # 运动进行页
│   │   ├── workout_history/   # 运动历史
│   │   ├── watchface_select/  # 表盘选择
│   │   ├── notification_demo/ # 通知演示
│   │   └── settings/          # 设置
│   └── i18n/                  # 国际化（示例）
└── package.json

---

主要页面导航

页面 / 手势	效果
表盘 — 左右滑动	切换 3 款表盘
表盘 — 上滑	进入应用列表
表盘 — 长按	进入表盘选择页
应用列表 — 右滑 / 下滑	返回表盘
应用列表 — 点击心率	进入心率详情
应用列表 — 点击健康	进入今日健康
应用列表 — 点击 7 日趋势	查看历史
应用列表 — 点击运动记录	选择运动类型 → 运动进行页 → 运动历史
应用列表 — 点击通知演示	进入通知演示页
应用列表 — 点击设置	进入设置（蓝牙 / 震动 / 亮度）
通知演示 — 右滑	返回应用列表
子页面 — 右滑 / 返回按钮	返回上一页

---

通知模拟

控制台事件

在 IDE 控制台或扩展控制台发送 system.event：

{
  "eventName": "band.demo.notification",
  "params": {
    "type": "call",
    "contact": "张三",
    "phone": "13900139000"
  }
}

支持 type：call（来电）、sms（短信）、app（应用）。

默认值

未传字段时系统使用以下默认值：

字段	默认值
短信 / 应用内容	测试
来电联系人	未知
来电电话	+86 123456

通知覆盖层采用内联写法（与息屏 / 暗屏遮罩一致），避免自定义组件渲染异常。详见 技术方案 → 通知系统。

本地演示

应用列表 → 通知演示页，点击「短信演示」「电话演示」「应用演示」按钮即可本地触发全屏通知覆盖层。

---

负责人速查

生命周期要点

钩子	时机	主要职责
onInit	页面初始化时	设置初始数据、标题
onReady	初次渲染完成	启动表盘运行时
onShow	每次页面重新显示	重新读取设置、加载健康数据、启动定时器
onHide	被其他页面遮盖	保存数据、停止定时器、取消传感器订阅
onDestroy	页面销毁	清理 setTimeout / setInterval / 传感器 / 事件订阅

不清理会导致重复运行、内存泄漏或返回页面后越来越快。

A/C/D/E 核心文件对应

功能	核心文件
A 多表盘	clock.ux、watchface_select.ux、components/watchfaces/*.ux、watch_data.js
C 消息通知	clock.ux、notification_demo.ux、notification_manager.js、watch_data.js
D 数据持久化	watch_data.js、history.ux、steps.ux
E 低功耗	power_manager.js、clock.ux、brightness.ux、device_settings.js

当前已知边界

1. 健康数据为内存模拟数据，未接真实传感器（需要实机适配）
2. 蓝牙页为流程模拟，无真实 BLE 无线通信（需要实机适配）
3. 自动亮度仅为开关状态，无环境光算法（需要实机适配）
4. 抬腕检测为简化加速度差值阈值，非成熟姿态识别（需要实机适配）
5. DIM 遮罩为模拟器视觉效果，真实背光控制依赖 brightness API
6. 通知覆盖层为页面内联写法
7. 固定 192×490 尺寸，主要适配当前模拟器设备

完整已知不足和排查思路见 项目负责人学习手册。

常见问题排查

现象	排查点
页面跳不过去	manifest.json 是否注册？router.push uri 路径正确？
页面出现 undefined	private 是否有默认值？storage 异步回调是否已完成？
返回表盘后越来越卡	onHide/onDestroy 是否清理了定时器？传感器是否取消订阅？
历史数据不更新	saveTodayHealth 是否调用？日期 key 是今天吗？
暗屏没有出现	低功耗开关是否开启？powerIdleTimer 是否运行？
通知不弹	当前页是否为 clock.ux 或 notification_demo.ux？notificationManager.onChange 是否更新了 visible？

---

模拟器演示清单

功能	演示路径
多表盘	表盘左右滑动 + 长按选择
心率	应用列表 → 心率
健康 / 历史	应用列表 → 健康 → 7 日趋势
运动记录	应用列表 → 运动记录 → 步行 / 跑步
通知	应用列表 → 通知演示，或控制台发送 band.demo.notification
低功耗	表盘静止等待 8s DIM / 15s SLEEP
蓝牙同步	设置 → 蓝牙同步 → 连接 → 开始同步
设置	设置 → 震动 / 亮度

---

第三方依赖

包名	许可证	用途
aiot-toolkit	MIT	快应用构建工具链（编译、打包 RPK）
@aiot-toolkit/jsc	MIT	JavaScript 字节码编译器
eslint-formatter-codeframe	MIT	ESLint 代码规范格式化输出
openvela / Xiaomi Vela	专有	手环运行时框架与系统 API

详细声明见 NOTICE 文件。MIT 协议内容见 LICENSE 文件。

---

文档索引

文档	适合读者	内容概要
技术方案	开发者、答辩准备	架构分层图、页面转场动画、数据流、系统 API 声明、构建 pipeline
B/F 实现说明	运动/蓝牙模块开发者	运动状态机、数据计算公式、蓝牙同步协议、真机替换点
项目负责人学习手册	项目负责人、维护者	.ux 语法、生命周期详解、逐文件功能说明、排查思路、学习顺序
English README	English readers	Full English translation of this README

---

开源协议

本项目采用 MIT License。第三方依赖许可证见 NOTICE。

---

相关链接

• openvela 官方文档
• Xiaomi Vela JS 应用快速入门