更新记录

1.0（2025-11-18）

发布初始版本

平台兼容性

华为健康数据（步数 + 心率）UTS 插件使用说明

一、功能简介

• 基于 华为 Health Kit，从本机 华为运动健康 App 读取：
  • 当日步数总数
  • 当日心率（平均 bpm）
• 通过 UTS 实现原生能力，对外暴露 3 个方法：
  • startSignIn：华为账号登录 + Health 授权
  • readTodaySteps：读取今日步数
  • readTodayHeartRate：读取今日心率（平均值）

仅支持 Android + App-Plus，不支持 H5、小程序。

二、前置条件

1. 设备环境

   • 华为 / 荣耀真机
   • 已安装 HMS Core 和 华为运动健康，且登录华为账号

2. 云端配置（宿主 App）

   • 在 AppGallery Connect 中已创建与宿主 包名 一致的应用
   • 已配置签名证书指纹（SHA256）
   • 已开启 Health Kit 服务
   • agconnect-services.json 已按 DCloud 官方文档配置到宿主项目（例如通过 nativeResources/android 等方式），本插件不自带此文件

3. 项目环境

   • uni-app（Vue2）项目
   • HBuilderX 版本满足使用 UTS 插件的最低要求（建议使用官方最新版）

三、安装与启用

1. 在插件市场启用

1. 登录 DCloud 插件市场（ext.dcloud.net.cn）
2. 找到插件：health-huawei-uts（华为健康数据 UTS 插件）
3. 点击「使用 / 购买」，使当前账号可以使用插件

2. 在宿主项目中勾选插件

1. 用 HBuilderX 打开宿主 uni-app 工程
2. 打开 manifest.json
3. 切换到 UTS 插件 配置页
4. 搜索并勾选 health-huawei-uts
5. 保存 manifest.json

四、API 说明

UTS 插件统一从根模块导出：

import {
  startSignIn,
  readTodaySteps,
  readTodayHeartRate
} from '@/uni_modules/health-huawei-uts'

1. startSignIn()

function startSignIn(): Promise<void>

• 功能：
  • 调用华为账号登录，并申请 Health 步数 + 心率读取权限
  • 内部会自动申请运行时权限：
  • android.permission.ACTIVITY_RECOGNITION
  • android.permission.BODY_SENSORS
• 成功：Promise 正常 resolve
• 失败：Promise reject，error.message 中包含错误信息

2. readTodaySteps()

function readTodaySteps(): Promise<number>

• 功能：
  读取当天 0 点到当前时间的 总步数
• 返回值：
  • number 类型，表示总步数
• 失败：
  • Promise reject，错误信息如：
  • HealthDataStore not connected
  • 读取步数失败
  • 解析步数数据失败

3. readTodayHeartRate()

function readTodayHeartRate(): Promise<number>

• 功能：
  读取当天所有心率数据，计算 平均心率（bpm）
• 返回值：
  • number 类型，平均心率值（bpm）
• 失败：
  • Promise reject，错误信息如：
  • HealthDataStore not connected
  • 读取心率失败
  • 解析心率数据失败
  • No heart rate data（无心率数据）

五、uni-app 页面使用示例（Vue2）

示例页面：pages/index.vue

<script>
import {
  startSignIn,
  readTodaySteps,
  readTodayHeartRate
} from '@/uni_modules/health-huawei-uts'

export default {
  data() {
    return {
      todaySteps: 0,
      todayHeartRate: 0,
      lastError: ''
    }
  },
  methods: {
    async startHealth() {
      try {
        // 1. 登录 + 授权
        await startSignIn()

        // 2. 读取当日步数
        const steps = await readTodaySteps()
        this.todaySteps = steps

        // 3. 读取当日心率
        const hr = await readTodayHeartRate()
        this.todayHeartRate = hr

        this.lastError = ''
      } catch (e) {
        const msg = e && e.message ? e.message : String(e)
        this.lastError = msg
        console.error('health-huawei-uts 调用失败：', msg)
      }
    }
  }
}
</script>

简单模板示例：

<template>
  <view class="page">
    <button @click="startHealth">读取今日步数和心率</button>

    <view>今日步数：{{ todaySteps }}</view>
    <view>今日心率：{{ todayHeartRate }} bpm</view>

    <view v-if="lastError" style="color:red;">
      错误：{{ lastError }}
    </view>
  </view>
</template>

六、常见问题

• H5 / 小程序无效？
  该插件仅支持 App-Plus(Android)，H5、小程序环境无法使用。

• 返回 HealthDataStore not connected？
  一般是 Health 服务还没连接完成，可稍后重试，或检查华为运动健康是否安装且运行正常。

• 获取不到步数/心率数据？

  • 确认「华为运动健康」中有当天运动记录；
  • 确认 AGC 中已开启 Health Kit；
  • 确认华为账号授权同意了健康数据读取；
  • 心率需有设备采集（如手表/手环）。

• 云打包失败与 HMS 依赖相关？

  • 插件 config 中已声明依赖：com.huawei.hms:hwid、com.huawei.hms:health；
  • 避免在项目其他地方再手动引入相同版本依赖，防止冲突。