Android 触感反馈 API 参考文档

本部分介绍了 Android 中提供的各种触感反馈 API。还介绍了何时以及如何检查是否需要任何设备支持，以确保触感反馈效果按预期播放。

您可以通过多种不同的方式创建触感反馈效果，在选择时，请务必考虑 Android 触感反馈设计原则。下表总结了每种方法的这些高级属性：

  • 在规划行为回退时，可用性尤为重要，并且需要结合检查各个设备的支持情况。
  • 清晰的触感反馈可提供清晰干净的触感，让用户感觉更舒适。
  • 丰富的触感反馈具有更强的表现力，通常需要功能更丰富的硬件。
API Surface 可用性 清晰触感反馈 丰富触感反馈
HapticFeedbackConstants Android 1.5 及更高版本
（每个常量）
预定义的 VibrationEffect Android 10+
VibrationEffect 组合 Android 11 及更高版本（按常量）
开启/关闭、单次振动和波形振动 Android 1

此外，您还可以使用本页介绍的通知 API 自定义为传入通知播放的触感反馈效果。

本页面还介绍了涵盖 API 接口的其他概念：

HapticFeedbackConstants

HapticFeedbackConstants 类提供基于操作的常量，以便应用添加在整个设备体验中保持一致的触感反馈，而不是让每个应用针对常见操作提供不同的效果。

兼容性和要求

将 View.performHapticFeedback 方法与这些常量搭配使用时，应用无需任何特殊权限。该方法受 View.hapticFeedbackEnabled 属性的约束，如果将其设置为 false，则会停用视图上的所有触感反馈调用，包括默认调用。主要相关设置是 View.hapticFeedbackEnabled 属性，如果将其设置为 false，则会停用视图上的所有触感反馈调用，包括默认调用。该方法还会遵循用户的系统设置，以启用触摸反馈。

唯一的兼容性注意事项是操作的特定常量的 SDK 级别。

使用 HapticFeedbackConstants 时，无需提供回退行为。

HapticsFeedbackConstants 的使用

如需详细了解如何使用 HapticFeedbackConstants，请参阅为事件添加触感反馈。

预定义的 VibrationEffect

VibrationEffect 类提供了多个预定义常量，例如 CLICK、TICK 和 DOUBLE_CLICK。这些效果可能会针对设备进行优化。

兼容性和要求

如需播放任何 VibrationEffect，应用清单中必须具有 VIBRATE 权限。

使用预定义的 VibrationEffect 时无需提供回退行为，因为没有针对设备进行了优化的实现的常量会回退到标准平台回退。

Vibrator.areEffectsSupported 和 Vibrator.areAllEffectsSupported API 用于确定是否存在针对设备进行了优化的实现。即使未采用经过优化的实现，也可以使用预定义的效果，并使用标准平台回退。因此，只有当应用想要考虑效果是否针对设备进行了优化时，才需要使用这些 areEffectsSupported API。

效果检查方法可以返回以下三个值之一：

由于 UNKNOWN 值表示检查 API 不可用，因此通常会针对所有效果或所有效果返回该值。这些设备会动态回退。

使用预定义的 VibrationEffect

如需详细了解如何使用预定义的 VibrationEffect，请参阅使用预定义的 VibrationEffect 生成触感反馈。

VibrationEffect 组合

VibrationEffect 组合是指使用 VibrationEffect.startComposition API 创建的振动效果。此 API 可通过创建具有自定义延迟和强度的一系列基元来实现富有表现力的丰富触感反馈。不过，请务必确保设备支持要组合的功能，以免整体体验不一致。

兼容性和要求

如需播放任何 VibrationEffect，应用清单中必须具有 VIBRATE 权限。

并非所有设备都支持 Composition API 的所有功能，因此请务必确保基元可用。

检查是否支持振动基元

您可以使用 Vibrator.arePrimitivesSupported 方法检索每个基元支持。或者，您也可以使用 Vibrator.areAllPrimitivesSupported 方法一起检查一组基元，这相当于对每个基元进行 AND 支持。

VibrationEffect 组合的使用

如需详细了解如何使用 VibrationEffect 组合，请参阅创建振动组合。

开启/关闭、单次振动和波形振动

Android 上支持的最早的振动形式是具有可配置时长的简单振动开启-关闭模式。这些 API 通常与触感反馈设计原则不一致，因为它们可能会产生嗡嗡作响的触感反馈；除非万不得已，否则请避免使用它们。

开启/关闭振动的最常见用例是通知，在这种情况下，无论如何都需要振动。波形振动还具有独特的功能，可让模式无限重复，就像您想象的铃声一样。

单次模式是指振动一次，持续时间为 N 毫秒。

波形模式有两种：

  • 仅限时间。这种类型的波形描述了开启和关闭状态的切换时长。计时从关闭时长开始。因此，波形模式通常以零值开头，表示立即开始振动。
  • 时间和振幅。这种类型的波形具有额外的幅度数组，用于与每个时间图形匹配，而不是第一个形式的隐式开启/关闭。不过，请务必检查设备是否支持幅度控制，以确保能够实现预期的缩放。

兼容性和要求

开关式振动是最早的振动形式，几乎所有带有振动器的设备都支持此类振动，如本页面后面所述。

如需播放任何 VibrationEffect 或旧版 vibrate 调用，应用清单中必须具有 VIBRATE 权限。

在波形中使用不同的幅度值时，我们强烈建议您确保设备支持幅度控制。

检查是否支持振幅控制

在没有振幅控制功能的设备上，非零振幅值会向上舍入到 100%，因此请务必使用 Vibrator.hasAmplitudeControl 检查是否支持振幅控制功能。如需了解详情，请参阅幅度控制。

您应仔细考虑您的特效在没有幅度控制的情况下是否具有足够的质量。最好改用明确设计的开启/关闭振动。

开启/关闭振动功能的使用

在较新的 SDK 级别中，所有振动模式都合并到了一个富有表现力的 VibrationEffect 类中，其中使用 VibrationEffect.createOneshot 或 VibrationEffect.createWaveform 创建这些简单的振动。

Notifications API

自定义应用通知时，您可以使用以下任一 API 将模式与每个通知渠道相关联：

所有这些形式都采用基本的开启-关闭波形模式，如前所述，其中第一个条目是开启振动器前的延迟时间。

一般概念

上述 API 接口中有一些概念适用于所有接口。

设备是否有振动器？

您可以从 context.getSystemService(Vibrator.class) 获取非 null 的 Vibrator 类。如果设备没有振动器，对振动 API 的调用不会产生任何效果，因此应用无需根据条件控制所有触感反馈。不过，如果需要，应用可以调用 hasVibrator() 来确定这是真实的振动器 (true) 还是桩 (false)。

用户是否停用了触摸触感反馈？

某些自定义实现可能需要手动检查用户是否已完全停用 Android 的触摸反馈设置，如果已停用，则应抑制触摸反馈效果。您可以使用 HAPTIC_FEEDBACK_ENABLED 键查询此设置，其中值为零表示已停用。

振动属性

您可以提供振动属性（目前采用 AudioAttributes 的形式），以帮助系统了解振动的用途。当应用在后台运行时启动振动时，必须执行此操作，因为后台使用仅支持注意力触感反馈。

AudioAttributes 的创建在其类文档中有所介绍，应被视为振动而非声音。

作为参考，在大多数情况下，内容类型为 CONTENT_TYPE_SONIFICATION，用法可能为 USAGE_ASSISTANCE_SONIFICATION（用于前台触摸反馈）或 USAGE_ALARM（用于后台闹钟）等值。音频标志对振动没有影响。

振幅控制

如果振动器具有振幅控制功能，则可以播放不同强度的振动。这是生成丰富的触感反馈的重要功能，还可能允许用户控制默认触感强度。

您可以通过调用 Vibrator.hasAmplitudeControl 来检查振幅控制支持情况。如果振动器不支持振幅，所有振幅值都将根据其是否为零/非零映射到开启/关闭。因此，如果设备缺少振幅控制功能，使用不同振幅丰富触感反馈的应用应考虑停用这些反馈。