Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

训练计划

Health Connect 提供 计划锻炼 数据类型，以便训练应用写入训练计划，并让锻炼应用读取训练计划。系统可以回读记录的锻炼，以便进行个性化效果分析，帮助用户实现训练目标。

检查健康数据共享的适用范围

在尝试使用健康数据共享之前，您的应用应验证用户的设备上是否提供健康数据共享。健康数据共享可能未预安装在所有设备上，或者可能已被停用。您可以使用 HealthConnectClient.getSdkStatus() 方法检查适用范围。

如何查看“健康数据共享”的适用范围

fun checkHealthConnectAvailability(context: Context) {
    val providerPackageName = "com.google.android.apps.healthdata" // Or get from HealthConnectClient.DEFAULT_PROVIDER_PACKAGE_NAME
    val availabilityStatus = HealthConnectClient.getSdkStatus(context, providerPackageName)

    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE) {
      // Health Connect is not available. Guide the user to install/enable it.
      // For example, show a dialog.
      return // early return as there is no viable integration
    }
    if (availabilityStatus == HealthConnectClient.SDK_UNAVAILABLE_PROVIDER_UPDATE_REQUIRED) {
      // Health Connect is available but requires an update.
      // Optionally redirect to package installer to find a provider, for example:
      val uriString = "market://details?id=$providerPackageName&url=healthconnect%3A%2F%2Fonboarding"
      context.startActivity(
        Intent(Intent.ACTION_VIEW).apply {
          setPackage("com.android.vending")
          data = Uri.parse(uriString)
          putExtra("overlay", true)
          putExtra("callerId", context.packageName)
        }
      )
      return
    }
    // Health Connect is available, obtain a HealthConnectClient instance
    val healthConnectClient = HealthConnectClient.getOrCreate(context)
    // Issue operations with healthConnectClient
}

根据 getSdkStatus() 返回的状态，您可以引导用户从 Google Play 商店安装或更新健康数据共享（如果需要）。

功能的适用范围

如需确定用户的设备是否支持 Health Connect 上的训练计划，请检查客户端上 FEATURE_PLANNED_EXERCISE 的适用范围：

if (healthConnectClient
     .features
     .getFeatureStatus(
       HealthConnectFeatures.FEATURE_PLANNED_EXERCISE
     ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {

  // Feature is available
} else {
  // Feature isn't available
}

如需了解详情，请参阅检查功能的适用范围。

所需权限

对计划锻炼的访问权限受以下权限保护：

android.permission.health.READ_PLANNED_EXERCISE
android.permission.health.WRITE_PLANNED_EXERCISE

如要向应用添加计划锻炼功能，请先请求 PlannedExerciseSession 数据类型的权限。

您需要声明以下权限才能写入计划锻炼：

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

如需读取计划锻炼，您需要请求以下权限：

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

向用户请求权限

创建客户端实例后，您的应用需要向用户请求权限。用户必须能够随时授予或拒绝权限。为此，请为所需的数据类型创建一个权限集。先确保此集中的权限已在 Android 清单中声明。

val permissions =
    setOf(
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class),
        HealthPermission.getReadPermission(PlannedExerciseSessionRecord::class),
        HealthPermission.getWritePermission(PlannedExerciseSessionRecord::class),
        HealthPermission.getReadPermission(ExerciseSessionRecord::class),
        HealthPermission.getWritePermission(ExerciseSessionRecord::class)
    )HealthConnectManager.kt

使用 getGrantedPermissions 查看您的应用是否已获得所需的权限。如果没有，请使用 createRequestPermissionResultContract 请求这些权限。系统会显示 Health Connect 权限屏幕。

val permissions = setOf(
        HealthPermission.getReadPermission(StepsRecord::class),
        HealthPermission.getWritePermission(StepsRecord::class),
        HealthPermission.getReadPermission(HeartRateRecord::class),
        HealthPermission.getWritePermission(HeartRateRecord::class)
    )

val requestPermissionsLauncher = rememberLauncherForActivityResult(
    contract = PermissionController.createRequestPermissionResultContract()
) { grantedPermissions ->
    if (grantedPermissions.containsAll(permissions)) {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions granted!") }
    } else {
        coroutineScope.launch { snackbarHostState.showSnackbar("Permissions denied.") }
    }
}HealthConnectActivity.kt

由于用户可以随时授予或撤消权限，因此您的应用需要在每次使用权限之前检查权限，并处理权限丢失的情况。

训练计划与 锻炼时段 相关联。因此，用户必须授予使用与训练计划相关的每种记录类型的权限，才能充分利用健康数据共享的此功能。

例如，如果训练计划衡量用户在一系列跑步过程中的心率，则开发者可能需要声明以下权限，并由用户授予这些权限，以便写入锻炼时段并读取结果以供日后评估：

android.permission.health.READ_EXERCISE
android.permission.health.READ_EXERCISE_ROUTES
android.permission.health.READ_HEART_RATE
android.permission.health.WRITE_EXERCISE
android.permission.health.WRITE_EXERCISE_ROUTE
android.permission.health.WRITE_HEART_RATE

不过，创建训练计划并根据计划评估效果的应用通常与使用训练计划并写入实际锻炼数据的应用不同。根据应用类型的不同，并非所有读写权限都是必需的。例如，您可能只需要为每种类型的应用授予以下权限：

训练计划应用	锻炼应用
`WRITE_PLANNED_EXERCISE`	`READ_PLANNED_EXERCISE`
`READ_EXERCISE`	`WRITE_EXERCISE`
`READ_EXERCISE_ROUTES`	`WRITE_EXERCISE_ROUTE`
`READ_HEART_RATE`	`WRITE_HEART_RATE`

计划锻炼时段记录中包含的信息

会话的标题。
计划锻炼块的列表。
会话的开始时间和结束时间。
锻炼类型。
活动的备注。
元数据。
已完成的锻炼时段 ID - 在与此计划锻炼时段相关的锻炼时段完成后，系统会自动写入此 ID。

计划锻炼块记录中包含的信息

计划锻炼块包含锻炼步骤列表，以支持重复执行不同的步骤组（例如，连续五次执行一系列手臂弯举、波比跳和仰卧起坐）。

块的说明。
计划锻炼步骤的列表。
重复次数。

计划锻炼步骤记录中包含的信息

支持的聚合

此数据类型不支持聚合。

用法示例

假设用户计划在两天后跑步 90 分钟。这次跑步将围绕湖跑三圈，目标心率在 90 到 110 bpm 之间。

用户在训练计划应用中定义了具有以下内容的计划锻炼时段：
1. 跑步的计划开始时间和结束时间
2. 锻炼类型（跑步）
3. 圈数（重复次数）
4. 心率效果目标（90 到 110 bpm 之间）
此信息将分组到运动块和步骤中，并由训练计划应用作为 PlannedExerciseSessionRecord 写入健康数据共享。
用户执行计划的时段（跑步）。
与会话相关的锻炼数据记录方式如下：
1. 在会话期间由可穿戴设备记录。例如，心率。此数据将作为活动的记录类型写入健康数据共享。在本例中，为 HeartRateRecord。
2. 由用户在会话结束后手动记录。例如，指明实际跑步的开始时间和结束时间。此数据将作为 ExerciseSessionRecord 写入 Health Connect。
稍后，训练计划应用会从 Health Connect 读取数据，以根据用户在计划锻炼时段中设置的目标评估实际效果。

计划锻炼并设置目标

用户可以计划未来的锻炼并设置目标。将此作为 计划锻炼时段 写入健康数据共享。

在用法示例中所述的示例中，用户计划在两天后跑步 90 分钟。这次跑步将围绕湖跑三圈，目标心率在 90 到 110 bpm 之间。

在将计划锻炼时段记录到 Health Connect 的应用的形式处理程序中，可能会找到类似这样的代码段。它也可能位于集成的接收点中，例如与提供训练的服务集成。

// Verify the user has granted all necessary permissions for this task
val grantedPermissions =
    healthConnectClient.permissionController.getGrantedPermissions()

if (!grantedPermissions.contains(
        HealthPermission.getWritePermission(PlannedExerciseSessionRecord::class))) {
    // The user hasn't granted the app permission to write planned exercise session data.
    Log.w("HealthConnect", "Write permission for PlannedExerciseSessionRecord not granted.")
    return
}

val plannedExerciseSessionRecord = PlannedExerciseSessionRecord(
    startTime = startTime,
    endTime = endTime,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    blocks = listOf(
        PlannedExerciseBlock(
            repetitions = 1, steps = listOf(
                PlannedExerciseStep(
                    exerciseType = ExerciseSegment.EXERCISE_SEGMENT_TYPE_RUNNING,
                    exercisePhase = PlannedExerciseStep.EXERCISE_PHASE_ACTIVE,
                    completionGoal = ExerciseCompletionGoal.RepetitionsGoal(repetitions = 3),
                    performanceTargets = listOf(
                        ExercisePerformanceTarget.HeartRateTarget(
                            minHeartRate = 90.0, maxHeartRate = 110.0
                        )
                    )
                ),
            ), description = "Three laps around the lake"
        )
    ),
    title = "Run at lake",
    notes = null,
    metadata = Metadata(
        device = Device(type = Device.Companion.TYPE_PHONE),
    ),
    startZoneOffset = null,
    endZoneOffset = null,
)

try {
    // Attempt to insert the record
    val response = healthConnectClient.insertRecords(listOf(plannedExerciseSessionRecord))

    // If execution reaches here, the insert succeeded.
    // Safely extract the ID using firstOrNull()
    val insertedPlannedExerciseSessionId = response.recordIdsList.firstOrNull()

    if (insertedPlannedExerciseSessionId != null) {
        Log.d("HealthConnect", "Successfully inserted planned exercise session ID: $insertedPlannedExerciseSessionId")
    } else {
        Log.w("HealthConnect", "Insertion succeeded but no record IDs were returned.")
    }

} catch (e: Exception) {
    // Handle API failures, database errors, or system issues safely without crashing
    Log.e("HealthConnect", "Failed to insert planned exercise session record", e)
}HealthConnectManager.kt

记录锻炼和活动数据

两天后，用户记录实际的锻炼时段。将此计划作为 锻炼时段 写入 Health Connect。

在此示例中，用户会话的时长与计划的时长完全一致。

在将锻炼时段记录到 Health Connect 的应用的形式处理程序中，可能会找到以下代码段。它也可能位于能够检测和记录锻炼时段的可穿戴设备的数据接收和导出处理程序中。

此处的 insertedPlannedExerciseSessionId 重用了上一个示例中的 ID。在实际应用中，ID 将由用户从现有会话列表中选择计划锻炼时段来确定。

// Verify the user has granted all necessary permissions for this task
val grantedPermissions =
    healthConnectClient.permissionController.getGrantedPermissions()
if (!grantedPermissions.contains(
        HealthPermission.getWritePermission(ExerciseSessionRecord::class))) {
    // The user doesn't granted the app permission to write exercise session data.
    return
}

val sessionDuration = Duration.ofMinutes(90)
val sessionEndTime = Instant.now()
val sessionStartTime = sessionEndTime.minus(sessionDuration)

val exerciseSessionRecord = ExerciseSessionRecord(
    startTime = sessionStartTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = sessionEndTime,
    endZoneOffset = ZoneOffset.UTC,
    exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_RUNNING,
    segments = listOf(
        ExerciseSegment(
            startTime = sessionStartTime,
            endTime = sessionEndTime,
            repetitions = 3,
            segmentType = ExerciseSegment.EXERCISE_SEGMENT_TYPE_RUNNING
        )
    ),
    title = "Run at lake",
    plannedExerciseSessionId = insertedPlannedExerciseSessionId,
    metadata = Metadata(
        device = Device(type = Device.Companion.TYPE_PHONE)
    )
)
val insertedExerciseSessions =
    healthConnectClient.insertRecords(listOf(exerciseSessionRecord))HealthConnectManager.kt

可穿戴设备还会记录用户在跑步过程中的心率。以下代码段可用于在目标范围内生成记录。

在实际应用中，此代码段的主要部分可能位于可穿戴设备消息的处理程序中，该处理程序会在收集测量数据后将其写入健康数据共享。

// Verify the user has granted all necessary permissions for this task
val grantedPermissions =
    healthConnectClient.permissionController.getGrantedPermissions()
if (!grantedPermissions.contains(
        HealthPermission.getWritePermission(HeartRateRecord::class))) {
    // The user doesn't granted the app permission to write heart rate record data.
    return
}

val samples = mutableListOf<HeartRateRecord.Sample>()
var currentTime = sessionStartTime
while (currentTime.isBefore(sessionEndTime)) {
    val bpm = Random.nextInt(21) + 90
    val heartRateRecord = HeartRateRecord.Sample(
        time = currentTime,
        beatsPerMinute = bpm.toLong(),
    )
    samples.add(heartRateRecord)
    currentTime = currentTime.plusSeconds(180)
}

val heartRateRecord = HeartRateRecord(
    startTime = sessionStartTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = sessionEndTime,
    endZoneOffset = ZoneOffset.UTC,
    samples = samples,
    metadata = Metadata(
        device = Device(type = Device.Companion.TYPE_WATCH)
    )
)
val insertedHeartRateRecords = healthConnectClient.insertRecords(listOf(heartRateRecord))HealthConnectManager.kt

评估效果目标

在用户锻炼后的第二天，您可以检索记录的锻炼，检查是否有任何计划锻炼目标，并评估其他数据类型以确定是否达到了设置的目标。

在定期作业中评估效果目标时，或者在加载锻炼列表并在应用中显示有关效果目标的通知时，可能会找到类似这样的代码段。

    // Verify the user has granted all necessary permissions for this task
    val grantedPermissions =
        healthConnectClient.permissionController.getGrantedPermissions()
    if (!grantedPermissions.containsAll(
            listOf(
                HealthPermission.getReadPermission(ExerciseSessionRecord::class),
                HealthPermission.getReadPermission(PlannedExerciseSessionRecord::class),
                HealthPermission.getReadPermission(HeartRateRecord::class)
            )
        )
    ) {
        // The user doesn't granted the app permission to read exercise session record data.
        return
    }

    val searchDuration = Duration.ofDays(1)
    val searchEndTime = Instant.now()
    val searchStartTime = searchEndTime.minus(searchDuration)

    val response = healthConnectClient.readRecords(
        ReadRecordsRequest<ExerciseSessionRecord>(
            timeRangeFilter = TimeRangeFilter.between(searchStartTime, searchEndTime)
        )
    )
    for (exerciseRecord in response.records) {
        val plannedExerciseRecordId = exerciseRecord.plannedExerciseSessionId
        val plannedExerciseRecord =
            if (plannedExerciseRecordId == null) null else healthConnectClient.readRecord(
                PlannedExerciseSessionRecord::class, plannedExerciseRecordId
            ).record
        if (plannedExerciseRecord != null) {
            val aggregateRequest = AggregateRequest(
                metrics = setOf(HeartRateRecord.BPM_AVG),
                timeRangeFilter = TimeRangeFilter.between(
                    exerciseRecord.startTime, exerciseRecord.endTime
                ),
            )
            val aggregationResult = healthConnectClient.aggregate(aggregateRequest)

            val maxBpm = aggregationResult[HeartRateRecord.BPM_MAX]
            val minBpm = aggregationResult[HeartRateRecord.BPM_MIN]
            if (maxBpm != null && minBpm != null) {
                plannedExerciseRecord.blocks.forEach { block ->
                    block.steps.forEach { step ->
                        step.performanceTargets.forEach { target ->
                            when (target) {
                                is ExercisePerformanceTarget.HeartRateTarget -> {
                                    val minTarget = target.minHeartRate
                                    val maxTarget = target.maxHeartRate
                                    if(
                                        minBpm >= minTarget && maxBpm <= maxTarget
                                    ) {
                                        // Success!
                                    }
                                }
                                // Handle more target types
                            }
                        }
                    }
                }
            }
        }
    }
}HealthConnectManager.kt

锻炼时段

锻炼时段可涵盖跑步、打羽毛球等各种活动。

写入锻炼时段

下面展示了如何构建包含时段的插入请求：

suspend fun writeExerciseSession(healthConnectClient: HealthConnectClient) {
    healthConnectClient.insertRecords(
        listOf(
            ExerciseSessionRecord(
                startTime = START_TIME,
                startZoneOffset = START_ZONE_OFFSET,
                endTime = END_TIME,
                endZoneOffset = END_ZONE_OFFSET,
                exerciseType = ExerciseSessionRecord.ExerciseType.RUNNING,
                title = "My Run",
                metadata = Metadata.manualEntry()
            ),
            // ... other records
        )
    )
}

读取锻炼时段

下面的示例展示了如何读取锻炼时段：

suspend fun readExerciseSessions(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response =
        healthConnectClient.readRecords(
            ReadRecordsRequest(
                ExerciseSessionRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
    for (exerciseRecord in response.records) {
        // Process each exercise record
        // Optionally pull in with other data sources of the same time range.
        val distanceRecord =
            healthConnectClient
                .readRecords(
                    ReadRecordsRequest(
                        DistanceRecord::class,
                        timeRangeFilter =
                            TimeRangeFilter.between(
                                exerciseRecord.startTime,
                                exerciseRecord.endTime
                            )
                    )
                )
                .records
    }
}

写入子类型数据

时段还可由可选的子类型数据组成，这类数据会利用更多信息使时段变得更丰富。

例如，锻炼时段可涵盖 ExerciseSegment、ExerciseLap 和 ExerciseRoute 类：

val segments = listOf(
  ExerciseSegment(
    startTime = Instant.parse("2022-01-02T10:10:10Z"),
    endTime = Instant.parse("2022-01-02T10:10:13Z"),
    segmentType = ActivitySegmentType.BENCH_PRESS,
    repetitions = 373
  )
)

val laps = listOf(
  ExerciseLap(
    startTime = Instant.parse("2022-01-02T10:10:10Z"),
    endTime = Instant.parse("2022-01-02T10:10:13Z"),
    length = 0.meters
  )
)

ExerciseSessionRecord(
  exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_CALISTHENICS,
    startTime = Instant.parse("2022-01-02T10:10:10Z"),
    endTime = Instant.parse("2022-01-02T10:10:13Z"),
  startZoneOffset = ZoneOffset.UTC,
  endZoneOffset = ZoneOffset.UTC,
  segments = segments,
  laps = laps,
  route = route,
  metadata = Metadata.manualEntry()
)