Android 触感反馈 API 参考文档

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

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

  • 可用性在规划行为回退时尤为重要，需要与检查单个设备支持情况结合使用。
  • 清晰触感反馈是指清晰明了的触感反馈，给用户带来的干扰更小。
  • 丰富触感反馈具有更好的表现力，通常需要更多功能丰富的硬件。
API Surface 提供情况 清晰触感反馈 丰富触感反馈
触感反馈常量 Android 1.5+
（每个常量）
预定义的振动效果 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 不可用，因此系统通常会针对所有效果返回该 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 创建的。

通知 API

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

如前所述，所有这些形式都具有基本的“开-关波形模式”，其中第一个条目是开启振动器之前的延迟。

一般概念

有几个概念适用于上文详述的 API surface。

此设备是否有振动器？

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

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

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

振动属性

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

AudioAttributes 的创建在其类文档中进行了介绍，并且应视为振动而非声音。

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

振幅控制

如果振动器具有振幅控制，那么它可以发出不同强度的振动。对于生成丰富触感反馈而言，这是一项重要功能，并且可能允许用户控制默认触感反馈强度。

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