更新记录

1.0.0（2026-09-23）

• 新增苹果健康、安卓健康连接、华为健康与鸿蒙健康数据接入；可先查询当前设备实际可用的服务、指标及操作能力。
• 支持步数、步行跑步距离、纯跑步距离、身高、体重、体脂、活动能量、心率、静息心率、血压、血糖、血氧、体温和睡眠等数据类型，各平台实际范围以能力查询结果为准。
• 支持按需申请读写权限、按时间查询明细、原生聚合统计、批量写入，以及按记录 ID 删除本应用创建的健康记录。
• 提供 uni-app / uni-app x 两套中文示例，包含单项授权、全部读取授权、一键自检、查询统计、写入删除和 iOS 全功能测试；测试记录仅按本次写入返回的 ID 清理。
• 修复 iOS 可见范围未知时查询或统计返回无效结果的问题，并修复心率、睡眠等嵌套记录写入时可能闪退的问题。
• 修复 iOS 写入相关的云端编译问题；现有 API 调用方式无需调整。
• 首次使用需完成对应健康服务配置，并重新制作、安装包含本插件的 Android / iOS 自定义基座或正式应用包；HarmonyOS 需重新构建应用包。

平台兼容性

uni-app(5.24)

uni-app x(5.24)

lizhao-health

lizhao-health 用于在 uni-app / uni-app x 中读取手机已有的健康记录，并在获得相应权限后写入和删除自己应用创建的记录。

第一次接入，建议先读取今天的步数记录。读通后，再按下面的业务模块增加身体指标、心率、血压、血糖和记录管理。

这个插件能解决什么问题

• 运动首页：展示步数、距离和活动消耗。
• 身体档案：查看身高、体重、体脂的最新记录与变化。
• 健康记录：查询心率、血压、血糖、血氧和体温。
• 睡眠记录：按时间查看睡眠区间和系统提供的睡眠阶段。
• 数据管理：保存使用者主动录入的数据，并删除本应用保存的指定记录。

下载与导入

1. 使用 HBuilderX 导入完整的 lizhao-health 插件。
2. 按文末对应平台说明完成应用配置，制作并安装包含插件的新原生包。
3. 在页面中从插件根目录导入所需方法。

uni-app 页面：

// 页面通过公开入口使用健康数据能力。
import {
  getHealthCapabilities,
  requestHealthAuthorization,
  queryHealthRecords
} from '@/uni_modules/lizhao-health'

uni-app x 页面：

// 在 script setup lang="uts" 中使用同样的公开入口。
import {
  getHealthCapabilities,
  requestHealthAuthorization,
  queryHealthRecords
} from '@/uni_modules/lizhao-health'

快速开始：读取今天的步数记录

只申请步数读取权限。把下面的函数绑定到页面按钮，由使用者点击后开始。

import {
  getHealthCapabilities,
  requestHealthAuthorization,
  queryHealthRecords
} from '@/uni_modules/lizhao-health'

// 由“读取今日步数”按钮调用。
function readTodaySteps() {
  getHealthCapabilities({
    success(capabilities) {
      // 没有可用服务或需要选择服务时，先显示原因。
      const provider = capabilities.provider
      if (provider == null) {
        console.log('暂时无法读取步数', capabilities.reason)
        return
      }

      requestHealthAuthorization({
        provider,
        readTypes: ['stepCount'],
        writeTypes: [],
        success() {
          // 授权流程结束后再读取；结果仍可能没有可见记录。
          const now = new Date()
          const start = new Date(now.getFullYear(), now.getMonth(), now.getDate())
          queryHealthRecords({
            provider,
            type: 'stepCount',
            startTime: start.getTime(),
            endTime: now.getTime(),
            pageSize: 20,
            success(result) {
              if (result.records.length == 0) {
                console.log('当前没有可读取的步数记录')
                return
              }
              console.log('已读取步数明细，本页记录数', result.records.length)
            },
            fail(error) {
              console.log('读取步数失败', error.errMsg)
            }
          })
        },
        fail(error) {
          console.log('步数授权流程未完成', error.errMsg)
        }
      })
    },
    fail(error) {
      console.log('检查健康服务失败', error.errMsg)
    }
  })
}

看到结果后，基础读取流程就跑通了。这里读取的是明细；需要今日总步数时，按模块一使用支持 sum 的统计接口。不同来源明细不能简单相加。

先认识几个常用参数

时间可直接使用 Date.getTime()。例如一天的范围应是“当天零点到次日零点”，不需要写成 23:59:59。

示例中的服务选择、批量授权与自检

示例将服务名称显示为“自动选择、苹果健康、安卓健康连接、华为健康、鸿蒙健康”，对应的接口参数仍为 auto、healthKit、healthConnect、huaweiHealth、harmonyHealth。自动选择只在一个服务可用时生效；有多个可用服务时请明确选择。

• 申请单项读取：只申请当前选中指标的读取权限，例如步数。
• 申请全部读取权限：先重新检查当前服务的能力，再一次申请该服务支持读取的全部指标；不申请写入权限。实际业务只申请需要使用的类型即可。
• 一键自检：检查服务是否可用、支持哪些读取指标，以及系统允许查询的读写授权状态。查看自检详情可看到逐项中文结果；自检不弹出授权、不读取健康明细，也不写入或删除记录，实际读写仍由对应按钮单独验证。
• 全功能测试（iOS）：展开后先申请测试读写权限，再手动开始。按当前能力逐项检查读取、统计和写入回读；每次只创建一条合成测试记录，按本次写入返回的 ID 删除并复查。已有记录不会作为自动删除目标。若中途退出或清理失败，先使用“恢复清理本次测试记录”；写入结果未知且没有 ID 时须人工核对，不自动重复写入。测试日志只记录步骤、数量和结果，不输出健康数值或记录 ID。

需要在业务中一次申请多项时，把所需类型放入同一个 readTypes 数组。例如仅在 iOS 苹果健康中申请步数、身高和心率：

import { requestHealthAuthorization } from '@/uni_modules/lizhao-health'

requestHealthAuthorization({
  provider: 'healthKit',
  readTypes: ['stepCount', 'height', 'heartRate'],
  writeTypes: [],
  success() { console.log('授权流程已结束，请按实际可读取的数据继续处理') },
  fail(error) { console.log('授权流程未完成', error.errMsg) }
})

iOS 的读取授权状态为 notObservable，表示系统不提供该状态，不能据此判断允许或拒绝。系统弹窗的项目与名称由本次请求类型和系统决定；已做过选择的权限再次申请时不一定弹窗，可在系统健康设置中核对。

按业务模块使用

以下模块假设已经完成相应类型的读取或写入授权，并选好了 provider。示例中的 provider、时间与数值由页面传入，每个函数只完成一个目标。

模块一：查看运动距离与活动消耗

适合在运动首页展示今天走了多远、消耗了多少活动能量。

import { aggregateHealthData } from '@/uni_modules/lizhao-health'

// type 选择当前服务支持 sum 的 stepCount、distance、walkingRunningDistance 或 activeEnergyBurned。
// 纯跑步距离通过明细接口读取，不能用通用距离替代。
function readActivityTotal(provider, type, startTime, endTime) {
  aggregateHealthData({
    provider, type, startTime, endTime,
    operation: 'sum',
    bucket: 'none',
    success(result) { console.log('活动统计', result.value, result.unit) },
    fail(error) { console.log('读取活动统计失败', error.errMsg) }
  })
}

distance 表示通用移动距离；walkingRunningDistance 表示步行与跑步合计；runningDistance 只表示能够确认是跑步的距离。当前服务不提供的类型会明确返回不支持。

读取 iOS 跑步记录时，把模块二的 type 改为 runningDistance。返回的是每次跑步训练中系统保存的距离；此类型只读，不提供写入、删除或总量统计。它不会把日常走路算成跑步。

需要趋势图时，可将支持统计的类型设为 bucket: 'day'，同时传 timeZone: 'Asia/Shanghai'，从 result.buckets 读取逐日值。开始和结束日按实际查询范围裁剪，一次最多 366 个日历日。

模块二：查看身高、体重和体脂记录

适合建立身体档案或查看一段时间内的测量历史。

import { queryHealthRecords } from '@/uni_modules/lizhao-health'

// type 使用 height、bodyMass 或 bodyFatPercentage。
function readBodyRecords(provider, type, startTime, endTime) {
  queryHealthRecords({
    provider, type, startTime, endTime,
    pageSize: 20,
    success(result) { console.log('本页身体记录数量', result.records.length) },
    fail(error) { console.log('读取身体记录失败', error.errMsg) }
  })
}

身高统一以厘米返回，体重以千克返回，体脂以百分数返回，例如 18.5 表示 18.5%。

模块三：查看心率、血压、血糖等测量记录

适合展示已有的测量结果。读取健康记录本身不会让手机开始测量。

import { queryHealthRecords } from '@/uni_modules/lizhao-health'

// type 选择 heartRate、restingHeartRate、bloodPressure、bloodGlucose、
// oxygenSaturation 或 bodyTemperature 中当前服务支持的类型。
function readMeasurementRecords(provider, type, startTime, endTime) {
  queryHealthRecords({
    provider, type, startTime, endTime,
    pageSize: 20,
    success(result) { console.log('本页测量记录数量', result.records.length) },
    fail(error) { console.log('读取测量记录失败', error.errMsg) }
  })
}

血压记录包含收缩压和舒张压。若只读取到一侧，缺失的一侧保持空值，不显示为 0。心率记录可能包含多个带测量时间的采样点。

模块四：查看睡眠时间与阶段

适合查看某晚的睡眠记录。建议查询从前一天晚上到第二天中午的范围，避免漏掉跨午夜的记录。

import { queryHealthRecords } from '@/uni_modules/lizhao-health'

// 每条睡眠记录保留实际起止时间及平台提供的阶段。
function readSleepRecords(provider, startTime, endTime) {
  queryHealthRecords({
    provider, type: 'sleep', startTime, endTime,
    pageSize: 50,
    success(result) { console.log('本页睡眠记录数量', result.records.length) },
    fail(error) { console.log('读取睡眠记录失败', error.errMsg) }
  })
}

“卧床”不等于“睡着”。系统没有提供深睡、浅睡等阶段时，插件不会自行推算。

模块五：保存自己录入的一条身高

适合使用者填写身高后，主动保存到所选健康数据服务。执行前先申请 height 写入权限，并检查当前服务支持写入。

import { writeHealthRecords } from '@/uni_modules/lizhao-health'

// heightCm 来自使用者输入，由“保存身高”按钮调用。
function saveHeight(provider, heightCm) {
  const measuredAt = Date.now()
  writeHealthRecords({
    provider,
    records: [{
      type: 'height',
      value: heightCm,
      unit: 'cm',
      startTime: measuredAt,
      endTime: measuredAt
    }],
    success(result) {
      // 保存返回的记录标识，用于之后查询或精确删除。
      console.log('身高保存结果', result.items)
    },
    fail(error) {
      // 批量写入时可能部分成功，应先查看逐条结果再决定如何处理。
      console.log('保存身高失败', error.errMsg)
      if (error.items != null) {
        console.log('逐条处理结果', error.items)
      }
    }
  })
}

步数、活动能量等区间记录需要真实的开始和结束时间；血压需要同时填写收缩压和舒张压。不要把所有数据都当作一条瞬时数值。

模块六：删除本应用保存的指定记录

适合纠正自己应用录入的错误记录。删除前由页面让使用者核对目标，再传入查询结果中的那条记录。

import { deleteHealthRecords } from '@/uni_modules/lizhao-health'

// record 来自查询结果；页面只对当前应用的可删除记录提供此按钮。
function deleteOwnRecord(record) {
  if (!record.ownData) {
    console.log('只能删除本应用写入的记录')
    return
  }
  deleteHealthRecords({
    provider: record.provider,
    type: record.type,
    ids: [record.id],
    success() { console.log('删除请求已完成，请刷新记录列表') },
    fail(error) { console.log('删除失败', error.errMsg) }
  })
}

插件还会核验数据来源，不能通过传入其他应用的记录 ID 绕过限制。部分服务无法返回准确删除条数，遇到空值应刷新列表确认，不把它解释为删除了 0 条。

模块七：继续读取下一页历史记录

适合支持分页服务的记录列表“加载更多”。第一页没有 pageToken；后续页同时传上一页返回的令牌和实际 provider，不能继续使用 auto。iOS 和华为 Android 提供有限明细查询，记录过多时需缩小时间范围，不提供这个翻页入口。

import { queryHealthRecords } from '@/uni_modules/lizhao-health'

// 其他查询条件必须与取得令牌的上一页完全一致。
function readNextPage(provider, type, startTime, endTime, pageToken) {
  queryHealthRecords({
    provider, type, startTime, endTime, pageToken,
    pageSize: 20,
    success(result) {
      console.log('本页记录数量', result.records.length)
      console.log('还有下一页', result.nextPageToken != null)
      if (result.hasMore && !result.paginationSupported) {
        console.log('当前服务还有记录，请缩小查询时间范围')
      }
    },
    fail(error) { console.log('读取下一页失败', error.errMsg) }
  })
}

只有 hasMore=false 才表示当前可见范围已读完。nextPageToken 为空时不要再次请求第一页；若仍有记录但当前服务不支持翻页，请缩小时间范围。

模块八：检查当前服务与权限状态

适合决定页面显示哪些按钮，或排查为什么读不到记录。

import { getHealthAuthorizationStatus } from '@/uni_modules/lizhao-health'

// 分别查看步数的读和写状态，避免只用一个“已授权”开关。
function checkStepAuthorization(provider) {
  getHealthAuthorizationStatus({
    provider,
    types: ['stepCount'],
    success(result) { console.log('步数授权状态', result.items) },
    fail(error) { console.log('查询授权状态失败', error.errMsg) }
  })
}

完整示例

将 uni-app 示例 或 uni-app x 示例 复制到 Vue 3 项目页面并注册路由。示例提供服务选择、按需授权、读取、统计、保存身高、从查询结果选择并删除本应用记录和分页按钮；打开页面不会自动读写健康数据。

常用 API 与配置

每个方法都支持 success / fail / complete。一次调用只会触发 success 或 fail 中的一个，随后触发一次 complete；只使用需要的回调即可。业务数据从 success 或 fail 获取；complete 返回统一的 operation / provider / success / errCode / errMsg 摘要，用于结束加载状态。

通用回调与服务选择

getHealthCapabilities、getHealthDiagnostics 只需上述参数，不弹授权框。getHealthAuthorizationStatus 另传非空且不重复的 types 数组；requestHealthAuthorization 传 readTypes、writeTypes，两者不可同时为空。

queryHealthRecords 的 type、时间与分页参数见前面的常用参数表。区间记录只要与查询范围重叠就可能返回，并保留整条记录的起止时间和值；瞬时记录按测量时间落入范围筛选。明细按时间从早到晚返回。

统计参数

保存记录参数

writeHealthRecords 另传 records 数组，一次 1–100 条。下面是数组中每条记录的字段。

步数为非负整数，心率和静息心率为正整数，距离与活动能量为非负数；百分数范围 0–100，身高、体重、血糖及两侧血压为正数。血糖统一使用 mmol/L；如果输入来自 mg/dL，先由业务确认并转换，插件不会猜测单位。

血压和血糖写入示例中的数值应来自使用者本次录入：

import { writeHealthRecords } from '@/uni_modules/lizhao-health'

function saveBloodPressure(provider, systolic, diastolic, measuredAt) {
  writeHealthRecords({
    provider,
    records: [{ type: 'bloodPressure', startTime: measuredAt, endTime: measuredAt,
      unit: 'mmHg', systolic, diastolic }],
    success() { console.log('血压已保存') },
    fail(error) { console.log('血压未全部保存', error.errMsg) }
  })
}

function saveBloodGlucose(provider, glucoseMmolL, measuredAt) {
  writeHealthRecords({
    provider,
    records: [{ type: 'bloodGlucose', startTime: measuredAt, endTime: measuredAt,
      unit: 'mmol/L', value: glucoseMmolL }],
    success() { console.log('血糖已保存') },
    fail(error) { console.log('血糖未全部保存', error.errMsg) }
  })
}

iOS 每条心率仅写入一个 sample，起止时间都等于该 sample 的测量时间；多点分为多条 records。每条睡眠也仅写一个 stage，时间与记录一致。Health Connect 心率使用正长度区间，睡眠不接受仅表示在床的 inBed。iOS 血糖进餐关系仅支持 unknown / beforeMeal / afterMeal，样本来源仅支持 unknown；不支持的字段值会明确失败。

删除参数

删除前先取得相应读写权限，并确认能力表的 delete=true。华为 Android 采样接口不提供精确 ID 删除，本插件对此返回不支持。iOS 血压只删除本插件创建且能完整核验的两侧关联记录。

指标、单位与主要返回值

服务、授权和记录

ownData=true 仅表示已确认记录来源属于本应用，不保证该类型可以删除。id 必须与服务、类型一起保存；有些平台返回的是当前应用会话中的原生记录引用，退出应用后需重新查询，不能把它当作长期业务主键。

统计、保存和删除

有任一失败或无法确认的写入项时走 fail，不会回调整体成功。应先处理 items；written 项不要再次提交，unknown 项先查询确认，避免重复记录。

支持平台

支持范围按原生服务分别提供；设备服务、应用开通和用户授权会影响实际可用性。先用 getHealthCapabilities 判断，再调用所需操作。

uni-app 与 uni-app x 使用同名 API；设备实际可用性以 getHealthCapabilities 返回值为准。Android 应用包最低支持 Android 8，Health Connect 服务本身仍需要 Android 9 及以上。首次接入需使用包含插件和相应健康能力配置的新原生安装包。

各指标能做什么

“读写删”指读取、保存和删除自有记录；“只读”不能保存或删除。“—”表示没有等价实现，会明确报不支持。

统计支持：iOS 的步数、走跑距离和活动能量支持 sum，其他数量测量支持 average/min/max；Health Connect 的步数、通用距离和活动能量支持 sum，身高、体重、心率和静息心率支持 average/min/max；华为 Android 的步数、通用距离支持 sum，体重、心率支持 average/min/max。血压、睡眠、纯跑步训练没有单值统计。最终可用算法仍以能力结果中的 aggregate 数组为准。

华为 Android 明细单次最多查询 31 天，更长范围需分段查询；整段统计最长约 24 天，较长范围可改为按日统计。若原生返回多个独立分组，会明确报不支持，不自行拼成总数。写入血糖的进餐关系仅支持 unknown/general；心率与睡眠每条只写一个测量点或阶段，睡眠仅能写 light/deep/rem/awake。

HarmonyOS 的步数、距离来自日常活动记录，体脂来自体重记录中的体脂字段；这些投影只读，避免写删时影响同条原生记录的其他指标。单点心率的起止时间与采样点时间保持相同。原生记录引用最多保留 1000 条、有效期 10 分钟，应用重启或引用失效后重新查询；查询期间其他来源增删可能使 offset 分页发生重复或遗漏，刷新列表时按当前引用展示，不把它当作固定快照。跑步筛选单次扫描最多 10000 个原生点，超过时缩小查询范围。

HarmonyOS 删除体重时会删除该条原生体重记录，其中附带的体脂等字段也会一起移除。选择删除前应向使用者展示完整目标含义；只想删除体脂数值时不要调用体重删除。

按所选服务完成接入

• iOS： 在应用标识与签名中启用 HealthKit，按实际用途调整健康数据读取、写入说明。插件附带所需配置，签名必须允许该能力。
• Health Connect： 设备须有可用 Health Connect，且数据来源已将记录写入该服务。应用需提供自己的健康数据用途和隐私政策说明；可通过 Android manifest 的 lizhao.health.privacyPolicyUrl 设置 HTTPS 隐私政策地址。
• 华为 Android： 在华为开发者后台完成包名、签名、健康服务及所需数据权限申请。用户还需完成账号和运动健康关联授权。在宿主 Android manifest 的 application 中加入下面两项；已有 AGConnect 官方 App ID 配置时可沿用。

<meta-data android:name="com.huawei.hms.client.appid" android:value="appid=你的华为应用AppID" />
<meta-data android:name="lizhao.health.huawei.enabled" android:value="true" />

• HarmonyOS： 完成对应应用的健康服务和数据权限申请，在应用的 module.json5 的 metadata 中配置 client_id。使用自己的应用标识，之后由页面按钮发起用户授权。

"metadata": [
  { "name": "client_id", "value": "你的鸿蒙应用Client ID" }
]

华为服务的配置仅填写公开应用标识，插件不需要 App Secret 或私钥。不同地区、设备、服务版本和数据审批结果可能导致部分指标不可用。更多步骤可查看 Apple HealthKit 接入、Health Connect 接入 和 HarmonyOS 健康服务指南。

错误码

所有错误的 errSubject 均为 lizhao-health。先按 errCode 处理，再将 errMsg 显示给使用者。

常见问题

授权流程成功，为什么没有读到记录

可能没有可见记录、查询时间不正确或读取范围受限。iOS 不会向应用明确公开读授权结果，因此空列表不能直接解释为使用者拒绝授权。

手机健康 App 有数据，插件为什么读不到

插件读取的是选定服务中已开放并授权的数据。不同厂商健康 App 的私有记录不会自动进入同一个数据服务。

为什么距离统计和跑步页面不一样

通用距离、步行跑步合计和纯跑步距离含义不同。先确认页面使用的 type 与业务要求一致。

为什么不能把多条步数记录直接相加

手机、手表或其他来源可能存在重叠记录。展示总步数优先使用统计接口，并保留其来源与时间范围。

为什么有些历史记录没有返回

系统、服务和授权范围可能限制可读历史。更早没有返回记录不代表数据一定不存在。

注意事项

• 只在使用者主动操作时请求需要的健康权限，读取和写入分别申请。
• 写入真实测量或使用者明确录入的数据；示例页面加载时不自动写入测试记录。
• 删除只针对本应用写入的指定记录；不提供清空整个手机健康数据库的入口。
• 不同服务的数据不会自动互相同步，写入成功不代表所有厂商健康 App 都会展示该记录。
• 原生依赖、健康权限或平台配置变化后，需要重新制作并安装包含插件的 Android / iOS 自定义基座或正式包；鸿蒙使用包含最新插件和对应配置的新应用包。
• iOS 需要启用项目 HealthKit 能力并使用匹配签名；华为 Android 与鸿蒙分别完成所选健康服务的应用开通和身份配置。
• Health Connect 使用的依赖要求 Android 编译 SDK 36 与 AGP 8.9.1 或更高；打包服务也必须满足这些要求，单改 targetSdk 不能解决依赖兼容问题。
• iOS 深睡、浅睡、REM 写入需要 iOS 16 及以上；不把未知阶段当成已睡。心率和睡眠的读取结构不一定能直接作为同平台的写入结构，请遵循上方保存参数。
• 健康数据应按业务需要显示和保存，避免把明细、账号或令牌写入公开日志。插件不会自动把各健康服务的数据复制到自己的服务器。

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。