Android 触感反馈 API 参考

本部分介绍了 Android 中可用的各种触感反馈 API。它还涵盖了何时以及如何检查任何必要的设备支持，以确保你的触感反馈效果按预期播放。

有几种不同的方法可以创建触感反馈效果，在选择这些方法时，重要的是考虑 Android 触感反馈设计原则。下表总结了每种方法的高级属性

  • 规划行为回退时，可用性尤其重要，需要与检查各个设备的支持结合使用。
  • 清晰触感反馈是清脆干净的感觉，对用户来说不那么刺耳。
  • 丰富触感反馈具有更高的表现力，通常需要功能更丰富的硬件。
API 面 可用性 清晰触感反馈 丰富触感反馈
HapticFeedbackConstants Android 1.5+
（每个常量）
预定义 VibrationEffect Android 10+
VibrationEffect Composition 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

基于包络的振动允许通过定义一系列控制点来精确控制振动随时间的振幅和频率。这使开发者能够精心打造更丰富、更细微的触感反馈体验。可以使用 BasicEnvelopeBuilder 和 WaveformEnvelopeBuilder 类创建这些振动。

兼容性和要求

要播放任何振动效果，应用必须在应用清单中声明 VIBRATE 权限。

要检查包络效果支持，请调用 Vibrator.areEnvelopeEffectsSupported()。

基本包络构建器

要创建平滑无缝的触感体验，包络效果必须以强度 \( 0.0 \) 开始和结束。API 通过将起始强度固定为零来强制执行此规定，如果结束强度不为零，则会抛出异常。此约束可防止由于振幅不连续而导致振动中出现不希望的动态效果，这会对用户的触感感知产生负面影响。

为了在不同设备上提供一致的包络效果渲染，框架要求支持此功能的设备可以在控制点之间处理最短 10 ms 的持续时间，并且包络效果至少包含 16 个点。

波形包络构建器

框架不会修改开发者提供的请求的频率和振幅值。但是，API 也会将起始振幅固定为零以创建平滑过渡。

为了帮助你优化应用的波形包络效果并提供跨设备兼容性，Android 提供了用于查询重要设备功能的 API。这些方法提供有关设备限制的信息，例如控制点之间最长和最短的过渡持续时间以及单个效果支持的最大控制点数量

getMaxSize()
检索包络效果支持的最大控制点数量。
getMinControlPointDurationMillis()
检索包络效果内两个控制点之间支持的最短持续时间（以毫秒为单位）。
getMaxControlPointDurationMillis()
检索包络效果内两个控制点之间支持的最长持续时间（以毫秒为单位）。
getMaxDurationMillis()
检索包络效果支持的最长持续时间（以毫秒为单位）。

如果效果超出了设备的限制（例如，允许过多的控制点或持续时间超过最大值），框架会自动调整效果以使其符合允许的边界。此调整过程会尽力保留设计的原始意图和感觉。

包络 VibrationEffects 的用法

有关创建包络波形效果的详细信息，请参阅创建带包络的振动波形。

VibrationEffect Composition

A VibrationEffect Composition 是使用 VibrationEffect.startComposition API 创建的振动效果。此 API 允许通过创建具有自定义延迟和强度的原始序列来实现富有表现力的丰富触感反馈。但是，请特别注意确保设备支持正在组合的功能，以避免整体体验不一致。

兼容性和要求

播放任何 VibrationEffect 需要在应用清单中声明 VIBRATE 权限。

并非所有设备都支持 Composition API 的所有功能，因此确保原始元素可用非常重要。

检查振动原始元素支持

可以使用 Vibrator.arePrimitivesSupported 方法检索每种原始元素的支持。或者，可以使用 Vibrator.areAllPrimitivesSupported 方法一起检查一组原始元素 - 这相当于对每种原始元素的支持进行 AND 运算。

VibrationEffect Compositions 的用法

有关使用 VibrationEffect Composition 的详细信息，请参阅创建振动 Composition。

开/关、单次和波形振动

Android 上支持的最古老的振动形式是具有可配置持续时间的简单振动器开/关模式。这些 API 通常与触感反馈设计原则不太一致，因为它们会产生嘈杂触感反馈；除非万不得已，否则请避免使用它们。

开/关振动最常见的用例是通知，在这种情况下，无论如何都希望有一些振动。波形振动还独特地允许模式无限期地重复，就像你想象的铃声一样。

A 单次模式是指振动一次持续 N 毫秒。

有两种类型的波形模式

  • 仅计时。这种类型的波形描述了交替的关闭持续时间和开启持续时间。计时从关闭持续时间开始。因此，波形模式通常以零值开始，以表示立即开始振动。
  • 计时和振幅。这种类型的波形有一个额外的振幅数组与每个计时数字匹配，而不是第一种形式的隐式开/关。但是，重要的是检查设备是否支持振幅控制，以确保可以实现预期的缩放。

兼容性和要求

由于开/关振动是最古老的振动形式，因此几乎所有带有振动器的设备都支持它们，如本页后面所述。

播放任何 VibrationEffect 或旧式 vibrate 调用都需要在应用清单中声明 VIBRATE 权限。

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

检查振幅控制支持

在不支持振幅控制的设备上，非零振幅值会被向上舍入到 100%，因此使用 Vibrator.hasAmplitudeControl 检查是否存在支持非常重要。有关更多详细信息，请参阅振幅控制。

你应该仔细考虑在没有振幅控制的情况下，你的效果质量是否足够。回退到明确设计的开/关振动可能更好。

开/关振动的用法

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

通知 API

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

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

一般概念

上述 API 面应用了几个概念。

设备是否有振动器？

你可以从 context.getSystemService(Vibrator.class) 获取非空的 Vibrator 类。如果设备没有振动器，调用振动 API 不会产生任何效果，因此应用无需对所有触感反馈进行条件限制。但是，如果需要，应用可以调用 hasVibrator() 来确定这是真振动器（true）还是存根（false）。

用户是否已禁用触摸触感反馈？

某些自定义实现可能需要手动检查用户是否已完全禁用 Android 的触摸反馈设置，在这种情况下应抑制触摸反馈效果。可以使用 HAPTIC_FEEDBACK_ENABLED 键查询此设置，值为零表示禁用。

振动属性

可以提供振动属性（目前以 AudioAttributes 的形式提供），以帮助系统了解振动的用途。当应用在后台时发起振动时，这是必需的，因为后台使用只支持注意性触感反馈。

AudioAttributes 的创建在其类文档中有介绍，应将其视为振动而不是声音。

作为指导，在大多数情况下，内容类型是 CONTENT_TYPE_SONIFICATION，用法可能是诸如用于前景触摸反馈的 USAGE_ASSISTANCE_SONIFICATION，或用于后台警报的 USAGE_ALARM。音频标志对振动没有影响。

振幅控制

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

可以通过调用 Vibrator.hasAmplitudeControl 检查振幅控制支持。如果振动器不支持振幅控制，则所有振幅值将根据其是否为零/非零映射到关闭/开启。因此，使用不同振幅的丰富触感反馈的应用应考虑在设备缺乏振幅控制时禁用它们。

包络效果支持

支持包络效果的振动器能够创建更动态、更细微的振动，从而对强度和锐度提供更精确的控制，带来更丰富的触感体验。使用 Vibration.areEnvelopeEffectsSupported 来确定你的设备是否支持此功能。如果不支持，则基于包络的振动将被忽略。