@ capgo/ 电容器- 健康

与Apple HealthKit一起通过一个API在iOS和Health Connect上读取并写入健康数据. 建设健身,健康,医疗应用一次.

🤖 建筑与AI编码代理? 安装 Capgo 技能 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 @capgo/capacitor-health 在您的电容应用程序中: npx skills add Cap-go/capgo-skills。然后问你的经纪人: 添加@capgo/capor-health 到我的 Capacitor app上,并把它连接起来 代理设置指南 • 妇女 主机磁共振

主要特点

• 读取样本数字 : readSamples() 在一定时间范围内的阶梯、心率、睡眠和其他类型.
• 写入样本数字 : saveSample() 存储单个样本.
• 工作与总数数字 : queryWorkouts() 财务报告和审定财务报表 queryAggregated() 供摘要使用.
• 授权数字 : requestAuthorization() 财务报告和审定财务报表 checkAuthorization() 每个数据类型.
• 健康连接帮助者数字 : openHealthConnectSettings() 财务报告和审定财务报表 showPrivacyPolicy() 安卓号.
• 平台: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-21. 一些数据类型和单位在iOS和Android之间有所不同,参见下方所支持的数据类型表. 在网上不可用.

为什么是卫生主管?

唯一一个 免费, (中文(简体) ), 统一 支持最新本地 API 的 Capacitor 健康数据插件 :

• 健康连接(Android) - 使用Google最新的健康平台(取代已贬值的Google Fit)
• 卫生知识(iOS) - 与苹果公司的健康框架充分融合
• 统一 API - 具有一致单元的平台的相同类型脚本接口
• 多种衡量标准 - 步道、距离、卡路里、心率、体重
• 读取和写入 - 查询历史数据并保存新的健康条目
• 现代标准 - 支持Android 8.0+和iOS 14+
• 现代软件包管理 - 支持Swift软件包管理器(SPM)和CocoaPods(SPM-为Capacitor 8准备)

适合健身应用,健康跟踪器,健康平台,医疗应用.

文档

这里有最完整的医生: https://capgo.app/docs/plugins/保健/

兼容性

说明: 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

然后使用下列提示:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-health` plugin in my project.

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

npm install @capgo/capacitor-health
npx cap sync

iOS 设置

1. 打开您的 Capacitor 应用程序的 Xcode 工作空间并启用 卫生科 能力.
2. 提供使用描述 Info.plist (更新副本 对于您的产品):

<key>NSHealthShareUsageDescription</key>
<string>This app reads your health data to personalise your experience.</string>
<key>NSHealthUpdateUsageDescription</key>
<string>This app writes new health entries that you explicitly create.</string>

Android 设置

此插件现在使用 健康连接 而不是Google Fit。 (笑声) 确保您的应用程序符合以下要求:

1. Min SDK 26+ (英语). 健康连接仅在Android 8.0(API 26)及以上版本提供. 插件的 Gradle 设置已经针对此关卡 .
2. 申报健康许可. 需要的外掛程式列表船 <uses-permission> 基本数据类型的声明READ_/WRITE_STEPS, (中文(简体) ), READ_/WRITE_DISTANCE, (中文(简体) ), READ_/WRITE_ACTIVE_CALORIES_BURNED, (中文(简体) ), READ_/WRITE_HEART_RATE, (中文(简体) ), READ_/WRITE_WEIGHT, (中文(简体) ), READ_/WRITE_SLEEP, (中文(简体) ), READ_/WRITE_RESPIRATORY_RATE, (中文(简体) ), READ_/WRITE_OXYGEN_SATURATION, (中文(简体) ), READ_/WRITE_RESTING_HEART_RATE, (中文(简体) ), READ_/WRITE_HEART_RATE_VARIABILITY) (中文(简体) ). 您的应用程序不需要复制它们, 但是您必须显示一个用户化的原理, 因为权限被认为是健康敏感 .
3. 确保安装健康连接. Android 14+上的设备默认包括它. 对于较早的版本,用户必须安装 由 Android 创建的健康连接 从游戏商店。 这个 Health.isAvailable() 帮助显示当前状态, 这样您就可以相应提示 .
4. 请求运行时间访问. 插件在您调用时打开健康连接权限UI requestAuthorization。您仍然应当处理拒绝流(例如,如果 checkAuthorization 报告缺少范围.
5. 提供隐私政策. 健康连接需要应用程序显示隐私政策,解释健康数据是如何使用的. 见 隐私政策设置 下节.

如果您已经在您的项目中使用了 Google Fit, 您可以删除相关的依赖性(play-services-fitness, (中文(简体) ), play-services-auth, OAuth 配置等).

隐私政策设置

健康连接需要您的应用程序提供隐私政策,以解释您如何处理健康数据. 当用户在健康连接权限对话框中点击"Privacy Policy"时,您的应用程序必须显示此信息.

备选案文1:资产中的HTML文件(为简单案件推荐)

将 HTML 文件放置在 android/app/src/main/assets/public/privacypolicy.html数字 :

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Privacy Policy</title>
  </head>
  <body>
    <h1>Privacy Policy</h1>
    <p>Your privacy policy content here...</p>
    <h2>Health Data</h2>
    <p>Explain how you collect, use, and protect health data...</p>
  </body>
</html>

备选方案2:自定义 URL(为主机隐私政策推荐)

在您的应用程序中添加字符串资源 android/app/src/main/res/values/strings.xml数字 :

<resources>
    <!-- Your other strings... -->
    <string name="health_connect_privacy_policy_url">https://yourapp.com/privacy-policy</string>
</resources>

当用户要求查看您的隐私政策时, 此 URL 将会被载入 WebView 中 .

程序访问 :

您也可以从您的应用程序中显示隐私政策或打开健康连接设置 :

// Show the privacy policy screen
await Health.showPrivacyPolicy();

// Open Health Connect settings (useful for managing permissions)
await Health.openHealthConnectSettings();

使用量

import { Health } from '@capgo/capacitor-health';

// Verify that the native health SDK is present on this device
const availability = await Health.isAvailable();
if (!availability.available) {
  console.warn('Health access unavailable:', availability.reason);
}

// Ask for separate read/write access scopes
await Health.requestAuthorization({
  read: ['steps', 'heartRate', 'weight'],
  write: ['weight'],
});

// Query the last 50 step samples from the past 24 hours
const { samples } = await Health.readSamples({
  dataType: 'steps',
  startDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
  limit: 50,
});

// Persist a new body-weight entry (kilograms by default)
await Health.saveSample({
  dataType: 'weight',
  value: 74.3,
});

支持的数据类型

所有写入操作都期望上面显示的默认单位. 安卓号上 metadata 选项目前被健康连接忽略.

血压: 血压要求同时有分泌和分泌值:

await Health.saveSample({
  dataType: 'bloodPressure',
  value: 120, // systolic value (used as main value)
  systolic: 120,
  diastolic: 80,
  startDate: new Date().toISOString(),
});

// Reading blood pressure returns samples with systolic/diastolic fields
const { samples } = await Health.readSamples({
  dataType: 'bloodPressure',
  startDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
});

samples.forEach((sample) => {
  console.log(`BP: ${sample.systolic}/${sample.diastolic} mmHg`);
});

关于锻炼的说明: 使用 queryWorkouts(),需要明确请求 workouts 权限 :

await Health.requestAuthorization({
  read: ['steps', 'workouts'], // Include 'workouts' to access workout sessions
});

读取超过30天的数据(Android)

在Android上,健康连接盖读取大致 过去30天 除非你的应用程序持有 android.permission.health.READ_HEALTH_DATA_HISTORY 允许。 阅读旧历史,设定 requestHistoryAccess: true 正常的时候 requestAuthorization() 电话 那么许可 与您的数据类型权限一起出现在首次健康连接授权页中, 而不是强迫用户在健康连接设置中手动授予.

const status = await Health.requestAuthorization({
  read: ['steps', 'heartRate'],
  write: [],
  requestHistoryAccess: true,
});

// On Android, whether the history permission was granted:
console.log(status.historyAccessAuthorized); // true | false
// And whether the provider supports it at all:
console.log(status.historyAccessAvailable); // true | false

结果报告为高层 historyAccessAuthorized 布尔( 仅在 requestHistoryAccess (已设定)。 同一选项与 checkAuthorization()。 。 。 .

这个 READ_HEALTH_DATA_HISTORY 仅允许足够新的健康连接供应商使用 (Android 14扩展13+或健康连接APK 171302+). 年长但得到支持的人 提供者永远不能被授予权限, 因此插件检查 特性可用性 财务报告和审定财务报表 悄悄跳过 在无法使用历史记录时, 您的正常读取/ 写入范围 仍按惯例提出要求。 在这种情况下,情况报告 historyAccessAvailable: false (和 historyAccessAuthorized: false)),可以区分"设备不能做到这一点"和"设备不能做到这一点" 用户否认了",并避免了再发作. historyAccessAvailable 被省略,除非 requestHistoryAccess 在iOS上总是省略.

你必须 (单位:千美元) 在您的应用程序中声明许可 AndroidManifest.xml数字 :

<uses-permission android:name="android.permission.health.READ_HEALTH_DATA_HISTORY" />

健康连接只显示在清单中声明并传递给 许可请求,所以需要此声明 requestHistoryAccess 以生效。 打开 iOS,HealthKit没有相应的许可,也没有30天的读取上限,所以 requestHistoryAccess 实值 忽略和删除 historyAccessAuthorized 从返回状态中删除.

参见 Google 上的文档 读取历史健康连接数据 更多细节.

缓冲示例 : 使用 anchor 通过解决结果粘接的参数 :

// First page: get the first 10 workouts
let result = await Health.queryWorkouts({
  startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(), // Last 30 days
  endDate: new Date().toISOString(),
  limit: 10,
});

console.log(`Found ${result.workouts.length} workouts`);

// If there are more results, the anchor will be set
while (result.anchor) {
  // Next page: use the anchor to continue from where we left off
  result = await Health.queryWorkouts({
    startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
    endDate: new Date().toISOString(),
    limit: 10,
    anchor: result.anchor, // Continue from the last result
  });

  console.log(`Found ${result.workouts.length} more workouts`);
}

新建数据类型示例

睡眠数据 :

// Request permission for sleep data
await Health.requestAuthorization({
  read: ['sleep'],
});

// Read sleep sessions from the past week
const { samples } = await Health.readSamples({
  dataType: 'sleep',
  startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
});

samples.forEach(sample => {
  console.log(`Sleep: ${sample.value} minutes, state: ${sample.sleepState}`);
});

呼吸速率、氧气饱和度和HRV:

// Request permission
await Health.requestAuthorization({
  read: ['respiratoryRate', 'oxygenSaturation', 'restingHeartRate', 'heartRateVariability'],
});

// Read respiratory rate
const { samples: respiratoryRate } = await Health.readSamples({
  dataType: 'respiratoryRate',
  startDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
});

// Read oxygen saturation (SpO2)
const { samples: oxygenSat } = await Health.readSamples({
  dataType: 'oxygenSaturation',
  startDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
});

综合查询

大日期范围, 使用 queryAggregated() 以高效方式获取汇总数据,而不是获取单个样本:

// Get daily step totals for the past month
const { samples } = await Health.queryAggregated({
  dataType: 'steps',
  startDate: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
  bucket: 'day',        // Options: 'hour', 'day', 'week', 'month'
  aggregation: 'sum',   // Options: 'sum', 'average', 'min', 'max'
});

samples.forEach(sample => {
  console.log(`${sample.startDate}: ${sample.value} ${sample.unit}`);
});

// Request several aggregations at once by passing an array. Each result is returned
// in `sample.values`, keyed by aggregation name (`sample.value` holds the first one).
const { samples: hr } = await Health.queryAggregated({
  dataType: 'heartRate',
  startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
  endDate: new Date().toISOString(),
  bucket: 'day',
  aggregation: ['average', 'min', 'max'],
});

hr.forEach(sample => {
  console.log(`${sample.startDate}: avg=${sample.values.average}, min=${sample.values.min}, max=${sample.values.max}`);
});

说明: 综合查询不支持睡眠,呼吸道速率,氧饱和,心率可变性,和VO2最大数据类型. 这些测量应使用 readSamples()没有 queryAggregated()支持综合:步道、距离、卡路里、饮食用水、所消耗的饮食能量、心率、体重和休息心率.

API 密码

• isAvailable()
• requestAuthorization(...)
• checkAuthorization(...)
• readSamples(...)
• saveSample(...)
• getPluginVersion()
• openHealthConnectSettings()
• showPrivacyPolicy()
• queryWorkouts(...)
• queryAggregated(...)
• 接口
• 类型异名

易读 ()

isAvailable() => Promise<AvailabilityResult>

返回当前平台是否支持本地健康 SDK .

回返情况: Promise<AvailabilityResult>

请求认证(...)

requestAuthorization(options: AuthorizationOptions) => Promise<AuthorizationStatus>

请求读取/写入所提供的数据类型.

设定 requestHistoryAccess: true 除了另外请求Android的 READ_HEALTH_DATA_HISTORY 在同一健康连接许可单中的许可 (见qqlink 授权选项。 请求历史访问) (中文(简体) ). 被授予/拒绝的地位是: 回报为 historyAccessAuthorized 在结果.

回返情况: Promise<AuthorizationStatus>

检查认证(...)

checkAuthorization(options: AuthorizationOptions) => Promise<AuthorizationStatus>

检查所提供数据类型的授权状态而不提示用户 .

回返情况: Promise<AuthorizationStatus>

读取样本(...)

readSamples(options: QueryOptions) => Promise<ReadSamplesResult>

在指定时限内读取给定数据类型的样本.

回返情况: Promise<ReadSamplesResult>

保存样本(...)

saveSample(options: WriteSampleOptions) => Promise<void>

将单一样本写入本土保健商店.

获取 PluginVersion ()

getPluginVersion() => Promise<{ version: string; }>

获取本地 Capacitor 插件版本

回返情况: Promise<{ version: string; }>

开放式健康连接设置( )

openHealthConnectSettings() => Promise<void>

打开健康连接设置屏幕(只有Android). 在iOS上,这种方法没有任何作用.

用于引导用户管理其健康连接权限 或安装健康连接(如果没有的话).

显示隐私政策 ()

showPrivacyPolicy() => Promise<void>

显示应用程序的"健康连接"(Android only)隐私政策. 在iOS上,这种方法没有任何作用.

此显示的隐私政策屏幕与健康连接显示的相同 当用户在权限对话框中点击"Privacy Policy"时.

隐私策略 URL 可以通过添加字符串资源来配置 在您的应用字符串. xml 中命名为“ 健康连接 privacy policy url”, 或将 HTML 文件放在www/privacypolicy。 html 在您的资产.

查询工作(...)

queryWorkouts(options: QueryWorkoutsOptions) => Promise<QueryWorkoutsResult>

本地健康商店的查询会. 在iOS(健康Kit)和Android(健康连接)上得到支持.

回返情况: Promise<QueryWorkoutsResult>

查询分类(...)

queryAggregated(options: QueryAggregatedOptions) => Promise<QueryAggregatedResult>

查询汇总了本地保健商店的健康数据. 将数据汇总为时间桶(小时、日、周、月),并进行总和、平均、分或最大等操作. 这比取取出大面积的单个样本更为有效.

在iOS(健康Kit)和Android(健康连接)上得到支持.

回返情况: Promise<QueryAggregatedResult>

接口

可用性

授权现状

授权选项

读取样本结果

健康样板

睡眠状态

平台数据可用时为睡眠样本排放的相位睡眠段.

查询选项

写入示例选项

查询工作结果

工作

解决事件

查询工作选项

查询分类结果

总计样本

查询分离选项

类型异名

卫生数据类型

'steps' | 'distance' | 'calories' | 'heartRate' | 'weight' | 'sleep' | 'respiratoryRate' | 'oxygenSaturation' | 'restingHeartRate' | 'heartRateVariability' | 'vo2Max' | 'bloodPressure' | 'bloodGlucose' | 'bodyTemperature' | 'height' | 'flightsClimbed' | 'exerciseTime' | 'distanceCycling' | 'bodyFat' | 'basalBodyTemperature' | 'appleSleepingWristTemperature' | 'basalCalories' | 'totalCalories' | 'mindfulness' | 'appleStandHour' | 'dietaryWater' | 'dietaryEnergyConsumed' | 'stateOfMind' | 'workouts'

卫生股

'count' | 'meter' | 'kilocalorie' | 'bpm' | 'kilogram' | 'minute' | 'percent' | 'millisecond' | 'mL/min/kg' | 'mmHg' | 'mg/dL' | 'celsius' | 'fahrenheit' | 'centimeter' | 'liter' | 'valence'

睡眠状态

'inBed' | 'asleep' | 'awake' | 'rem' | 'deep' | 'light'

记录

构造 T 类型 K 的一组属性类型

{ [P in K]: T; }

工作类型

'americanFootball' | 'australianFootball' | 'badminton' | 'baseball' | 'basketball' | 'bowling' | 'boxing' | 'climbing' | 'cricket' | 'crossTraining' | 'curling' | 'cycling' | 'dance' | 'elliptical' | 'fencing' | 'functionalStrengthTraining' | 'golf' | 'gymnastics' | 'handball' | 'hiking' | 'hockey' | 'jumpRope' | 'kickboxing' | 'lacrosse' | 'martialArts' | 'pilates' | 'racquetball' | 'rowing' | 'rugby' | 'running' | 'sailing' | 'skatingSports' | 'skiing' | 'snowboarding' | 'soccer' | 'softball' | 'squash' | 'stairClimbing' | 'strengthTraining' | 'surfing' | 'swimming' | 'swimmingPool' | 'swimmingOpenWater' | 'tableTennis' | 'tennis' | 'trackAndField' | 'traditionalStrengthTraining' | 'volleyball' | 'walking' | 'waterFitness' | 'waterPolo' | 'waterSports' | 'weightlifting' | 'wheelchair' | 'yoga' | 'archery' | 'barre' | 'cooldown' | 'coreTraining' | 'crossCountrySkiing' | 'discSports' | 'downhillSkiing' | 'equestrianSports' | 'fishing' | 'fitnessGaming' | 'flexibility' | 'handCycling' | 'highIntensityIntervalTraining' | 'hunting' | 'mindAndBody' | 'mixedCardio' | 'paddleSports' | 'pickleball' | 'play' | 'preparationAndRecovery' | 'snowSports' | 'stairs' | 'stepTraining' | 'surfingSports' | 'taiChi' | 'transition' | 'underwaterDiving' | 'wheelchairRunPace' | 'wheelchairWalkPace' | 'wrestling' | 'cardioDance' | 'socialDance' | 'backExtension' | 'barbellShoulderPress' | 'benchPress' | 'benchSitUp' | 'bikingStationary' | 'bootCamp' | 'burpee' | 'calisthenics' | 'crunch' | 'dancing' | 'deadlift' | 'dumbbellCurlLeftArm' | 'dumbbellCurlRightArm' | 'dumbbellFrontRaise' | 'dumbbellLateralRaise' | 'dumbbellTricepsExtensionLeftArm' | 'dumbbellTricepsExtensionRightArm' | 'dumbbellTricepsExtensionTwoArm' | 'exerciseClass' | 'forwardTwist' | 'frisbeedisc' | 'guidedBreathing' | 'iceHockey' | 'iceSkating' | 'jumpingJack' | 'latPullDown' | 'lunge' | 'meditation' | 'paddling' | 'paraGliding' | 'plank' | 'rockClimbing' | 'rollerHockey' | 'rowingMachine' | 'runningTreadmill' | 'scubaDiving' | 'skating' | 'snowshoeing' | 'stairClimbingMachine' | 'st