更新记录

3.1.1（2026-07-27） 下载此版本

2.0.4（2026-06-09） 下载此版本

修复安卓、鸿蒙真机运行缺少模块

2.0.3（2026-06-09） 下载此版本

修复安卓打包接口报错问题

平台兼容性

uni-app(5.0)

uni-app x(5.0)

szy-healthkit 健康数据管理

iOS · Android · HarmonyOS · 7 种小程序 · 跨平台健康数据 UTS 插件

平台支持

安装

将 szy-healthkit 目录放入 uni_modules/ 中即可。

iOS 配置要求

⚠️ iOS 端 HealthKit 需要以下两项配置缺一不可，否则 requestAuthorization 会在 0.0s 内返回失败。

1. UTS.entitlements

在插件目录 utssdk/app-ios/ 下创建 UTS.entitlements 文件：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.healthkit</key>
    <true/>
</dict>
</plist>

此文件随插件分发，云端打包时自动合并到主工程 entitlements。

2. Provisioning Profile 必须含 HealthKit

Apple Developer Center 中，App ID 对应的 Capabilities 必须勾选 HealthKit，重新生成 .mobileprovision 描述文件。否则云打包时报错：

Provisioning profile "xxx" doesn't include the HealthKit capability.

使用

🚨 重要：UTS 插件通过 ES Module 导入，不使用 uni.requireNativePlugin()

// ✅ 正确方式
import { getTodaySteps, requestAuthorization } from '@/uni_modules/szy-healthkit'

// check diagnostics on failure
const authResult = await requestAuthorization(readTypes, writeTypes)
if (authResult !== 'SUCCESS') {
  const diag = getHealthKitDiagnostics()
  console.log('Auth failed:', authResult, 'Diagnostics:', diag)
}

// ❌ 错误方式（无效！UTS 插件不走原生插件注册）
const plugin = uni.requireNativePlugin('szy-healthkit') // 不生效

API 参考

通用

授权管理（App 端）

重要： requestAuthorization iOS 端返回 String 而非 boolean。判断成功需用 result === 'SUCCESS'。

import { requestAuthorization } from '@/uni_modules/szy-healthkit'

const result = await requestAuthorization(
  ['steps', 'heartRate'],
  ['weight', 'height']
)

if (result === 'SUCCESS') {
  console.log('授权成功')
} else {
  console.log('授权失败:', result) // result 包含系统错误详情
}

数据查询（App 端）

Android 专用（v3.0.0+）

iOS 专用（写入）

小程序端

关键类型

/** 健康数据样本 */
type HealthSample = {
  dataType: string
  value: number
  unit: string
  startDate: string   // ISO 8601
  endDate: string     // ISO 8601
  source: string
}

/** 统计查询结果 */
type HealthStatistics = {
  dataType: string
  sum: number | null
  average: number | null
  min: number | null
  max: number | null
  count: number | null
}

/** 授权状态 */
type AuthStatus = "notDetermined" | "authorized" | "denied"

平台差异说明

¹ UTS 桥接层限制，requestPermissionsFromUser 无法弹系统对话框。用户需手动前往「设置 → 应用 → 本应用 → 权限 → 身体活动」开启一次。开启后传感器持续可用。

Android 国内厂商适配说明（v3.0.0）

支持的 18 家厂商

小米/Redmi/POCO、华为、荣耀、OPPO、一加、真我、vivo/iQOO、三星、魅族、联想、摩托罗拉、努比亚/红魔、黑鲨、锤子、HTC、中兴、索尼、Google

多源步数降级策略

优先顺序：缓存 > TYPE_STEP_COUNTER > TYPE_STEP_DETECTOR > 厂商ContentProvider > 返回0

厂商诊断 API 示例

import { getManufacturerName, getDeviceInfo, getBatteryWhitelistGuide } from '@/uni_modules/szy-healthkit'

// 获取厂商名称
const mfr = getManufacturerName() // "小米/Redmi/POCO"
console.log('设备厂商:', mfr)

// 获取设备诊断信息
const info = JSON.parse(getDeviceInfo())
console.log('步数传感器:', info.hasStepCounter)
console.log('是否需白名单:', info.backgroundWhitelist)
console.log('已安装健康App:', info.installedHealthApps)

// 获取白名单设置指引
const guide = getBatteryWhitelistGuide()
console.log('设置指引:', guide)

生命周期管理

在 App.vue 中调用生命周期方法：

import { onAppBackground, onAppForeground } from '@/uni_modules/szy-healthkit'

export default {
  onHide() { onAppBackground() },
  onShow() { onAppForeground() }
}

HarmonyOS 专项说明

核心特性

鸿蒙端使用系统传感器 API（@ohos.sensor），步数和心率传感器为全局 API，无需初始化 Context 即可直接调用，与其他平台体验一致。

import { getTodaySteps, getRecentHeartRate } from '@/uni_modules/szy-healthkit'

// ✅ 零配置，直接可用
const steps = await getTodaySteps()
const hr = await getRecentHeartRate(5)

权限要求

传感器读取需 ohos.permission.ACTIVITY_MOTION 权限。该权限已在插件 module.json5 中声明，HBuilderX 打包时自动合并。

⚠️ 已知限制：UTS 桥接层无法弹出系统权限对话框。首次使用时需引导用户手动前往系统设置开启一次：

设置 → 应用 → 应用管理 → 找到本应用 → 权限 → 身体活动 → 开启

仅需操作一次，开启后传感器持续可用。

Context 机制

插件内置双通道 Context 获取，无需在 EntryAbility 中调用 setGlobalContext：

核心传感器 API（getTodaySteps / getRecentHeartRate / getSupportedDataTypes）不需要 Context，两个通道仅用于权限管理函数。

返回 0 排查

常见问题

Q: 插件在 Android 上未被检测到？

A: 确认使用 ES Module 导入（import { xxx } from '@/uni_modules/szy-healthkit'）而非 uni.requireNativePlugin()。

Q: iOS 上 requestAuthorization 耗时 0.0s 立即返回失败？

A: 0.0s 意味着 HealthKit API 没有被正确调用，常见原因按可能性排序：

1. Provisioning Profile 缺少 HealthKit：Apple Developer Center 中 App ID 未勾选 HealthKit 能力。打包日志会明确报错 Provisioning profile doesn't include the HealthKit capability
2. 缺少 UTS.entitlements：插件 utssdk/app-ios/ 目录下必须存在 UTS.entitlements，内容为 <key>com.apple.developer.healthkit</key><true/>
3. 模拟器：旧版 Xcode 模拟器不支持 HealthKit（Xcode 14 / iOS 16 后的模拟器已支持）。调用 getHealthKitDiagnostics() 查看 HealthKit.available 确认
4. iOS < 14：系统版本低于 iOS 14。调用 getHealthKitDiagnostics() 查看 iOS14Plus

诊断方法：

import { requestAuthorization, getHealthKitDiagnostics } from '@/uni_modules/szy-healthkit'

// 先查看诊断信息
const diag = getHealthKitDiagnostics()
console.log('诊断:', diag)

// 然后请求授权时检查返回值
const result = await requestAuthorization(readTypes, writeTypes)
if (result !== 'SUCCESS') {
  console.log('Swift 返回的错误:', result) // 包含具体系统错误描述
}

Q: iOS 线上包授权正常但本地调试授权失败？

A: 本地调试和云打包的 entitlements 生成机制不同。确认两点：

• 本地调试 → 在 HBuilder X 的 manifest.json → App 模块配置 → iOS Capabilities 中勾选 HealthKit
• 云打包 → 插件内的 UTS.entitlements 会自动合并；但 Provisioning Profile 必须支持 HealthKit，需要去 Apple Developer Center 启用

Q: Android 上步数始终为 0？

A: 该问题有多个可能原因： A: 该问题有多个可能原因：

1. 权限：需在系统设置中开启「身体活动」权限（设置 → 应用 → 本应用 → 权限）
2. 厂商限制：小米/华为等设备需要走几步激活 TYPE_STEP_COUNTER，或降级到 TYPE_STEP_DETECTOR。调用 getManufacturerName() 和 getStepCollectorDiagnostics() 查看诊断信息
3. 后台限制：通过 getBatteryWhitelistGuide() 获取本厂商白名单设置指引

Q: Android 上心率无数据？

A: 大部分手机没有心率传感器。需佩戴穿戴设备（手表/手环）并通过厂商 API 获取。插件只读取系统 TYPE_HEART_RATE 传感器。

Q: requestAuthorization 总是返回 false？

A: Android 运行时权限弹窗需在页面层调用，UTS 插件层只能检测状态。请先调用 uni.authorize()。

Q: 小程序步数需要服务端解密？

A: 微信/支付宝等平台的步数 API 返回加密数据，需配合服务端解密。serverDecryptGuide 提供了各平台的服务端解密指引。

Q: Android 上 getTodaySteps() 返回速度如何？

A: 如果当日已读取过 → 立即返回缓存。首次读取等待约 5-8 秒（TYPE_STEP_DETECTOR 采样周期）。可通过 getStepCollectorDiagnostics() 查看实时诊断状态。

版本历史

3.1.1 (2026-07-27)

• 🦕 鸿蒙传感器深度适配 — 移植自原生 ArkTS 项目，完整验证所有传感器 API
• ⚡ 鸿蒙核心功能零配置可用 — 步数/心率传感器为全局 API，import 即可直接调用，无需 setGlobalContext 初始化
• 🏗️ UTSHarmony Context 自给 — 权限相关函数（requestAuthorization / getAuthorizationStatus）采用 Window 引用模式自动获取 Context
• ACTIVITY_MOTION 权限链路 — checkAccessToken + requestPermissionsFromUser，权限信息透传
• 📝 鸿蒙已知限制文档化 — UTS 环境系统弹窗不可用，ACTIVITY_MOTION 需手动去设置开启（仅一次）
• 🐛 移除 cachedHeartRate 残留代码 — 清理死代码，消除编译警告
• 🧹 Context 双通道保底 — UTSHarmony 主通道 + setGlobalContext 备用通道，EntryAbility 不可用场景也能工作

3.0.0 (2026-06-10)

• ✨ 国内安卓厂商适配引擎：识别 18 家手机厂商，自动适配各 ROM 差异
• ✨ 多源步数降级采集：TYPE_STEP_COUNTER → TYPE_STEP_DETECTOR → ContentProvider → 缓存，自动降级
• ✨ 厂商诊断 API：getManufacturerName() / getDeviceInfo() / getStepCollectorDiagnostics() / getBatteryWhitelistGuide()
• ✨ 生命周期管理：onAppBackground() / onAppForeground() / resetStepCache()
• 🔧 重构：采用 HealthKitBridge 单例架构替代 UTS 层状态管理，彻底解决 UTS 编译兼容问题
• 🐛 修复：SensorHelper.kt 方法签名 onSensorEvent → onSensorChanged

2.1.0 (2026-06-09)

• 🐛 修复：改用 ES Module 导入模式（import 替代 requireNativePlugin），修复"插件未检测到"问题
• 🐛 修复：Android Kotlin Java.extend 实验性 API 兼容性（改用 SensorHelper.kt）
• 🐛 修复：Android 传感器采样率 FASTEST → NORMAL，降低耗电
• 🐛 修复：Android 端类型导入缺失等编译错误
• 🧹 代码审查优化：清理死代码、统一参数类型、修正权限返回

2.0.0 (2024-06-05)

• 三端架构：iOS + Android + HarmonyOS
• 统一 API 接口

1.0.0 (2024-xx-xx)

• 首次发布，仅 iOS HealthKit

许可

MIT License — 作者: szy