创建自定义触感效果

本页介绍了如何在 Android 应用中使用不同的触感 API 创建标准振动波形之外的自定义效果示例。

本页包含以下示例

自定义振动模式
- 渐强模式：平缓开始的模式。
- 重复模式：没有尽头的模式。
- 含回退的模式：回退演示。
振动组合
- 阻力：具有动态强度的拖动效果。
- 展开：先增强后减弱的效果。
- 晃动：使用 SPIN 基元创建的晃动效果。
- 弹跳：使用 THUD 基元创建的弹跳效果。
带有包络线的振动波形
- 弹簧弹跳：使用基本包络效果创建的弹簧弹跳效果。
- 火箭发射：使用波形包络效果创建的火箭发射效果。

如需更多示例，请参阅向事件添加触觉反馈，并始终遵循触感设计原则。

使用回退处理设备兼容性

实现任何自定义效果时，请考虑以下几点

该效果需要哪些设备能力
当设备无法播放效果时该怎么办

Android 触感 API 参考提供了有关如何检查您的触感效果所涉及组件支持情况的详细信息，以便您的应用提供一致的整体体验。

根据您的用例，您可能希望禁用自定义效果，或根据不同的潜在能力提供替代的自定义效果。

规划以下设备能力的高级类别

如果您正在使用触感基元：设备支持自定义效果所需的那些基元。（有关基元的详细信息，请参阅下一节。）
具有振幅控制的设备。
具有基本振动支持（开启/关闭）的设备——换句话说，那些缺乏振幅控制的设备。

如果您的应用的触感效果选择考虑了这些类别，那么其触感用户体验在任何单个设备上都应该保持可预测性。

触感基元的使用

Android 包含几种触感基元，它们在振幅和频率上各不相同。您可以单独使用一个基元，或将多个基元组合起来以实现丰富的触感效果。

在两个基元之间使用 50 毫秒或更长的延迟，以实现可辨识的间隔，如果可能，还要考虑primitive duration。
使用差异比率达到或超过 1.4 的缩放比例，以便更好地感知强度的差异。
使用 0.5、0.7 和 1.0 的缩放比例来创建基元的低、中、高强度版本。

注意： 0.0 的 scale 参数表示最低可感知振动，而不是关闭。

创建自定义振动模式

振动模式通常用于注意性触感，例如通知和铃声。Vibrator 服务可以播放长时间的振动模式，这些模式会随时间改变振动振幅。此类效果称为波形。

波形效果通常是可以感知的，但在安静环境下播放突然的长振动可能会惊吓到用户。过快地升高到目标振幅也可能产生可听见的嗡嗡声。设计波形模式以平滑振幅过渡，创建渐强和渐弱效果。

振动模式示例

以下各节提供了几个振动模式示例

渐强模式

波形表示为 VibrationEffect，包含三个参数

计时：每个波形段的持续时间数组，以毫秒为单位。
振幅：第一个参数中指定的每个持续时间的期望振动振幅，表示为一个 0 到 255 的整数值，其中 0 表示振动器“关闭状态”，255 是设备的最大振幅。
重复索引：第一个参数中指定的数组中开始重复波形的索引，如果只播放一次模式，则为 -1。

这里有一个示例波形，它会脉冲两次，两次脉冲之间暂停 350 毫秒。第一次脉冲是平滑地渐强到最大振幅，第二次是快速渐强并保持最大振幅。末尾停止由负重复索引值定义。

Kotlin

val timings: LongArray = longArrayOf(
    50, 50, 50, 50, 50, 100, 350, 25, 25, 25, 25, 200)
val amplitudes: IntArray = intArrayOf(
    33, 51, 75, 113, 170, 255, 0, 38, 62, 100, 160, 255)
val repeatIndex = -1 // Don't repeat.

vibrator.vibrate(VibrationEffect.createWaveform(
    timings, amplitudes, repeatIndex))

Java

long[] timings = new long[] {
    50, 50, 50, 50, 50, 100, 350, 25, 25, 25, 25, 200 };
int[] amplitudes = new int[] {
    33, 51, 75, 113, 170, 255, 0, 38, 62, 100, 160, 255 };
int repeatIndex = -1; // Don't repeat.

vibrator.vibrate(VibrationEffect.createWaveform(
    timings, amplitudes, repeatIndex));

重复模式

波形也可以重复播放，直到取消为止。创建重复波形的方法是设置非负的 repeat 参数。当您播放重复波形时，振动会持续到在服务中明确取消为止

Kotlin

void startVibrating() {
val timings: LongArray = longArrayOf(50, 50, 100, 50, 50)
val amplitudes: IntArray = intArrayOf(64, 128, 255, 128, 64)
val repeat = 1 // Repeat from the second entry, index = 1.
VibrationEffect repeatingEffect = VibrationEffect.createWaveform(
    timings, amplitudes, repeat)
// repeatingEffect can be used in multiple places.

vibrator.vibrate(repeatingEffect)
}

void stopVibrating() {
vibrator.cancel()
}

Java

void startVibrating() {
long[] timings = new long[] { 50, 50, 100, 50, 50 };
int[] amplitudes = new int[] { 64, 128, 255, 128, 64 };
int repeat = 1; // Repeat from the second entry, index = 1.
VibrationEffect repeatingEffect = VibrationEffect.createWaveform(
    timings, amplitudes, repeat);
// repeatingEffect can be used in multiple places.

vibrator.vibrate(repeatingEffect);
}

void stopVibrating() {
vibrator.cancel();
}

这对于需要用户操作来确认的间歇性事件非常有用。此类事件的示例包括来电和触发的警报。

含回退的模式

控制振动的振幅是硬件相关能力。在不具备此能力的低端设备上播放波形会导致设备对振幅数组中的每个正值以最大振幅振动。如果您的应用需要兼容此类设备，请使用在此条件下播放时不会产生嗡嗡声效果的模式，或者设计更简单的 ON/OFF 模式作为回退。

Kotlin

if (vibrator.hasAmplitudeControl()) {
  vibrator.vibrate(VibrationEffect.createWaveform(
    smoothTimings, amplitudes, smoothRepeatIdx))
} else {
  vibrator.vibrate(VibrationEffect.createWaveform(
    onOffTimings, onOffRepeatIdx))
}

Java

if (vibrator.hasAmplitudeControl()) {
  vibrator.vibrate(VibrationEffect.createWaveform(
    smoothTimings, amplitudes, smoothRepeatIdx));
} else {
  vibrator.vibrate(VibrationEffect.createWaveform(
    onOffTimings, onOffRepeatIdx));
}

创建振动组合

本节介绍了将振动组合成更长、更复杂的自定义效果的方法，并进一步探讨了如何利用更高级的硬件能力实现丰富的触感。您可以组合不同振幅和频率的效果，在具有更宽频率带宽的触感致动器的设备上创建更复杂的触感效果。

本页前面介绍的创建自定义振动模式过程解释了如何控制振动振幅以创建平滑的渐强和渐弱效果。丰富的触感在此概念基础上进行了改进，通过探索设备振动器更宽的频率范围，使效果更加平滑。这些波形在创建渐强或渐弱效果时尤其有效。

本页前面描述的组合基元由设备制造商实现。它们提供清晰、短暂且令人愉悦的振动，符合清晰触感的触感原则。有关这些功能及其工作原理的更多详细信息，请参阅振动致动器入门。

Android 不为使用不受支持基元的组合提供回退。因此，请执行以下步骤

在激活高级触感之前，检查给定设备是否支持您使用的所有基元。
禁用不受支持的一致体验集，而不仅仅是缺少基元的效果。

有关如何检查设备支持情况的更多信息，请参阅以下各节。

创建组合振动效果

您可以使用 VibrationEffect.Composition 创建组合振动效果。以下是一个缓慢上升的效果，随后是一个清脆的点击效果示例

Kotlin

vibrator.vibrate(
    VibrationEffect.startComposition().addPrimitive(
    VibrationEffect.Composition.PRIMITIVE_SLOW_RISE
    ).addPrimitive(
    VibrationEffect.Composition.PRIMITIVE_CLICK
    ).compose()
)

Java

vibrator.vibrate(
    VibrationEffect.startComposition()
        .addPrimitive(VibrationEffect.Composition.PRIMITIVE_SLOW_RISE)
        .addPrimitive(VibrationEffect.Composition.PRIMITIVE_CLICK)
        .compose());

组合是通过按顺序添加要播放的基元来创建的。每个基元也是可缩放的，因此您可以控制每个基元生成的振动振幅。缩放比例定义为一个 0 到 1 之间的值，其中 0 实际上对应于用户（几乎）无法感知该基元的最低振幅。

创建振动基元的变体

如果您想创建同一基元的弱版本和强版本，请创建 1.4 或更高的强度比率，以便轻松感知强度差异。不要尝试创建同一基元的三种以上强度级别，因为它们在感知上没有区别。例如，使用 0.5、0.7 和 1.0 的缩放比例来创建基元的低、中、高强度版本。

在振动基元之间添加间隔

组合还可以指定在连续基元之间添加延迟。此延迟以毫秒为单位表示，从前一个基元结束开始计算。一般来说，两个基元之间的 5 到 10 毫秒间隔太短，无法检测到。如果您想在两个基元之间创建可辨识的间隔，请使用约 50 毫秒或更长的间隔。这是一个带有延迟的组合示例

Kotlin

val delayMs = 100
vibrator.vibrate(
    VibrationEffect.startComposition().addPrimitive(
    VibrationEffect.Composition.PRIMITIVE_SPIN, 0.8f
    ).addPrimitive(
    VibrationEffect.Composition.PRIMITIVE_SPIN, 0.6f
    ).addPrimitive(
    VibrationEffect.Composition.PRIMITIVE_THUD, 1.0f, delayMs
    ).compose()
)

Java

int delayMs = 100;
vibrator.vibrate(
    VibrationEffect.startComposition()
        .addPrimitive(VibrationEffect.Composition.PRIMITIVE_SPIN, 0.8f)
        .addPrimitive(VibrationEffect.Composition.PRIMITIVE_SPIN, 0.6f)
        .addPrimitive(
            VibrationEffect.Composition.PRIMITIVE_THUD, 1.0f, delayMs)
        .compose());

检查支持哪些基元

可以使用以下 API 来验证设备对特定基元的支持

Kotlin

val primitive = VibrationEffect.Composition.PRIMITIVE_LOW_TICK

if (vibrator.areAllPrimitivesSupported(primitive)) {
  vibrator.vibrate(VibrationEffect.startComposition()
        .addPrimitive(primitive).compose())
} else {
  // Play a predefined effect or custom pattern as a fallback.
}

Java

int primitive = VibrationEffect.Composition.PRIMITIVE_LOW_TICK;

if (vibrator.areAllPrimitivesSupported(primitive)) {
  vibrator.vibrate(VibrationEffect.startComposition()
        .addPrimitive(primitive).compose());
} else {
  // Play a predefined effect or custom pattern as a fallback.
}

也可以检查多个基元，然后根据设备支持级别决定组合哪些基元

Kotlin

val effects: IntArray = intArrayOf(
VibrationEffect.Composition.PRIMITIVE_LOW_TICK,
VibrationEffect.Composition.PRIMITIVE_TICK,
VibrationEffect.Composition.PRIMITIVE_CLICK
)
val supported: BooleanArray = vibrator.arePrimitivesSupported(primitives)

Java

int[] primitives = new int[] {
VibrationEffect.Composition.PRIMITIVE_LOW_TICK,
VibrationEffect.Composition.PRIMITIVE_TICK,
VibrationEffect.Composition.PRIMITIVE_CLICK
};
boolean[] supported = vibrator.arePrimitivesSupported(effects);

振动组合示例

以下各节提供了几个振动组合示例，这些示例取自 GitHub 上的触感示例应用。

阻力（带低频滴答声）

您可以控制基元振动的振幅，以便为正在进行的操作传达有用的反馈。间隔较近的缩放值可用于创建基元的平滑渐强效果。连续基元之间的延迟也可以根据用户互动动态设置。以下示例演示了由拖动手势控制并增强触感效果的视图动画。

Animation of a circle being dragged down.

图 1. 此波形代表设备振动的输出加速度。

Kotlin

@Composable
fun ResistScreen() {
    // Control variables for the dragging of the indicator.
    var isDragging by remember { mutableStateOf(false) }
    var dragOffset by remember { mutableStateOf(0f) }

    // Only vibrates while the user is dragging
    if (isDragging) {
        LaunchedEffect(Unit) {
        // Continuously run the effect for vibration to occur even when the view
        // is not being drawn, when user stops dragging midway through gesture.
        while (true) {
            // Calculate the interval inversely proportional to the drag offset.
            val vibrationInterval = calculateVibrationInterval(dragOffset)
            // Calculate the scale directly proportional to the drag offset.
            val vibrationScale = calculateVibrationScale(dragOffset)

            delay(vibrationInterval)
            vibrator.vibrate(
            VibrationEffect.startComposition().addPrimitive(
                VibrationEffect.Composition.PRIMITIVE_LOW_TICK,
                vibrationScale
            ).compose()
            )
        }
        }
    }

    Screen() {
        Column(
        Modifier
            .draggable(
            orientation = Orientation.Vertical,
            onDragStarted = {
                isDragging = true
            },
            onDragStopped = {
                isDragging = false
            },
            state = rememberDraggableState { delta ->
                dragOffset += delta
            }
            )
        ) {
        // Build the indicator UI based on how much the user has dragged it.
        ResistIndicator(dragOffset)
        }
    }
}

Java

class DragListener implements View.OnTouchListener {
    // Control variables for the dragging of the indicator.
    private int startY;
    private int vibrationInterval;
    private float vibrationScale;

    @Override
    public boolean onTouch(View view, MotionEvent event) {
        switch (event.getAction()) {
        case MotionEvent.ACTION_DOWN:
            startY = event.getRawY();
            vibrationInterval = calculateVibrationInterval(0);
            vibrationScale = calculateVibrationScale(0);
            startVibration();
            break;
        case MotionEvent.ACTION_MOVE:
            float dragOffset = event.getRawY() - startY;
            // Calculate the interval inversely proportional to the drag offset.
            vibrationInterval = calculateVibrationInterval(dragOffset);
            // Calculate the scale directly proportional to the drag offset.
            vibrationScale = calculateVibrationScale(dragOffset);
            // Build the indicator UI based on how much the user has dragged it.
            updateIndicator(dragOffset);
            break;
        case MotionEvent.ACTION_CANCEL:
        case MotionEvent.ACTION_UP:
            // Only vibrates while the user is dragging
            cancelVibration();
            break;
        }
        return true;
    }

    private void startVibration() {
        vibrator.vibrate(
            VibrationEffect.startComposition()
                .addPrimitive(VibrationEffect.Composition.PRIMITIVE_LOW_TICK,
                        vibrationScale)
                .compose());

        // Continuously run the effect for vibration to occur even when the view
        // is not being drawn, when user stops dragging midway through gesture.
        handler.postDelayed(this::startVibration, vibrationInterval);
    }

    private void cancelVibration() {
        handler.removeCallbacksAndMessages(null);
    }
}

展开（带上升和下降）

有两个基元用于提高感知到的振动强度：PRIMITIVE_QUICK_RISE 和 PRIMITIVE_SLOW_RISE。它们都达到相同的目标，但持续时间不同。只有一个用于降低强度的基元，PRIMITIVE_QUICK_FALL。这些基元协同工作可以更好地创建强度增强然后减弱的波形段。您可以对齐缩放的基元，以防止它们之间出现振幅突变，这对于延长整体效果持续时间也很有效。在感知上，人们总是更容易注意到上升部分而不是下降部分，因此使上升部分比下降部分短，可以将重点转移到下降部分。

这里有一个示例，说明如何将此组合应用于展开和收缩圆圈。上升效果可以增强动画过程中的展开感。上升和下降效果的组合有助于强调动画结束时的收缩。

图 2.此波形代表设备振动的输出加速度。

Kotlin

enum class ExpandShapeState {
    Collapsed,
    Expanded
}

@Composable
fun ExpandScreen() {
    // Control variable for the state of the indicator.
    var currentState by remember { mutableStateOf(ExpandShapeState.Collapsed) }

    // Animation between expanded and collapsed states.
    val transitionData = updateTransitionData(currentState)

    Screen() {
        Column(
        Modifier
            .clickable(
            {
                if (currentState == ExpandShapeState.Collapsed) {
                currentState = ExpandShapeState.Expanded
                vibrator.vibrate(
                    VibrationEffect.startComposition().addPrimitive(
                    VibrationEffect.Composition.PRIMITIVE_SLOW_RISE,
                    0.3f
                    ).addPrimitive(
                    VibrationEffect.Composition.PRIMITIVE_QUICK_FALL,
                    0.3f
                    ).compose()
                )
                } else {
                currentState = ExpandShapeState.Collapsed
                vibrator.vibrate(
                    VibrationEffect.startComposition().addPrimitive(
                    VibrationEffect.Composition.PRIMITIVE_SLOW_RISE
                    ).compose()
                )
            }
            )
        ) {
        // Build the indicator UI based on the current state.
        ExpandIndicator(transitionData)
        }
    }
}

Java

class ClickListener implements View.OnClickListener {
    private final Animation expandAnimation;
    private final Animation collapseAnimation;
    private boolean isExpanded;

    ClickListener(Context context) {
        expandAnimation = AnimationUtils.loadAnimation(context, R.anim.expand);
        expandAnimation.setAnimationListener(new Animation.AnimationListener() {

        @Override
        public void onAnimationStart(Animation animation) {
            vibrator.vibrate(
            VibrationEffect.startComposition()
                .addPrimitive(
                    VibrationEffect.Composition.PRIMITIVE_SLOW_RISE, 0.3f)
                .addPrimitive(
                    VibrationEffect.Composition.PRIMITIVE_QUICK_FALL, 0.3f)
                .compose());
        }
        });

        collapseAnimation = AnimationUtils
                .loadAnimation(context, R.anim.collapse);
        collapseAnimation.setAnimationListener(new Animation.AnimationListener() {

            @Override
            public void onAnimationStart(Animation animation) {
                vibrator.vibrate(
                VibrationEffect.startComposition()
                    .addPrimitive(
                        VibrationEffect.Composition.PRIMITIVE_SLOW_RISE)
                    .compose());
            }
        });
    }

    @Override
    public void onClick(View view) {
        view.startAnimation(isExpanded ? collapseAnimation : expandAnimation);
        isExpanded = !isExpanded;
    }
}

晃动（带旋转）

主要的触感原则之一是让用户感到愉悦。引入令人愉悦的意外振动效果的一种有趣方式是使用 PRIMITIVE_SPIN。当多次调用此基元时，效果最佳。多个旋转连接起来可以创建晃动和不稳定的效果，通过对每个基元应用某种程度的随机缩放可以进一步增强此效果。您还可以尝试调整连续旋转基元之间的间隔。两次旋转之间没有任何间隔（0 毫秒）会产生紧凑的旋转感。将旋转间隔从 10 毫秒增加到 50 毫秒会导致更宽松的旋转感，并且可以用于匹配视频或动画的持续时间。

不要使用超过 100 毫秒的间隔，因为连续旋转无法很好地融合，会开始感觉像是独立的效果。

这里有一个弹性形状的示例，它在被向下拖动然后释放后会弹回。动画通过一对旋转效果得到增强，以与弹跳位移成比例的不同强度播放。

图 3. 此波形代表设备振动的输出加速度。

Kotlin

@Composable
fun WobbleScreen() {
    // Control variables for the dragging and animating state of the elastic.
    var dragDistance by remember { mutableStateOf(0f) }
    var isWobbling by remember { mutableStateOf(false) }

    // Use drag distance to create an animated float value behaving like a spring.
    val dragDistanceAnimated by animateFloatAsState(
        targetValue = if (dragDistance > 0f) dragDistance else 0f,
        animationSpec = spring(
            dampingRatio = Spring.DampingRatioHighBouncy,
            stiffness = Spring.StiffnessMedium
        ),
    )

    if (isWobbling) {
        LaunchedEffect(Unit) {
            while (true) {
                val displacement = dragDistanceAnimated / MAX_DRAG_DISTANCE
                // Use some sort of minimum displacement so the final few frames
                // of animation don't generate a vibration.
                if (displacement > SPIN_MIN_DISPLACEMENT) {
                    vibrator.vibrate(
                        VibrationEffect.startComposition().addPrimitive(
                            VibrationEffect.Composition.PRIMITIVE_SPIN,
                            nextSpinScale(displacement)
                        ).addPrimitive(
                        VibrationEffect.Composition.PRIMITIVE_SPIN,
                        nextSpinScale(displacement)
                        ).compose()
                    )
                }
                // Delay the next check for a sufficient duration until the
                // current composition finishes. Note that you can use
                // Vibrator.getPrimitiveDurations API to calculcate the delay.
                delay(VIBRATION_DURATION)
            }
        }
    }

    Box(
        Modifier
            .fillMaxSize()
            .draggable(
                onDragStopped = {
                    isWobbling = true
                    dragDistance = 0f
                },
                orientation = Orientation.Vertical,
                state = rememberDraggableState { delta ->
                    isWobbling = false
                    dragDistance += delta
                }
            )
    ) {
        // Draw the wobbling shape using the animated spring-like value.
        WobbleShape(dragDistanceAnimated)
    }
}

// Calculate a random scale for each spin to vary the full effect.
fun nextSpinScale(displacement: Float): Float {
    // Generate a random offset in the range [-0.1, +0.1] to be added to the
    // vibration scale so the spin effects have slightly different values.
    val randomOffset: Float = Random.Default.nextFloat() * 0.2f - 0.1f
    return (displacement + randomOffset).absoluteValue.coerceIn(0f, 1f)
}

Java

class AnimationListener implements DynamicAnimation.OnAnimationUpdateListener {
    private final Random vibrationRandom = new Random(seed);
    private final long lastVibrationUptime;

    @Override
    public void onAnimationUpdate(
        DynamicAnimation animation, float value, float velocity) {
        // Delay the next check for a sufficient duration until the current
        // composition finishes. Note that you can use
        // Vibrator.getPrimitiveDurations API to calculcate the delay.
        if (SystemClock.uptimeMillis() - lastVibrationUptime < VIBRATION_DURATION) {
            return;
        }

        float displacement = calculateRelativeDisplacement(value);

        // Use some sort of minimum displacement so the final few frames
        // of animation don't generate a vibration.
        if (displacement < SPIN_MIN_DISPLACEMENT) {
            return;
        }

        lastVibrationUptime = SystemClock.uptimeMillis();
        vibrator.vibrate(
        VibrationEffect.startComposition()
            .addPrimitive(VibrationEffect.Composition.PRIMITIVE_SPIN,
            nextSpinScale(displacement))
            .addPrimitive(VibrationEffect.Composition.PRIMITIVE_SPIN,
            nextSpinScale(displacement))
            .compose());
    }

    // Calculate a random scale for each spin to vary the full effect.
    float nextSpinScale(float displacement) {
        // Generate a random offset in the range [-0.1,+0.1] to be added to
        // the vibration scale so the spin effects have slightly different
        // values.
        float randomOffset = vibrationRandom.nextFloat() * 0.2f - 0.1f
        return MathUtils.clamp(displacement + randomOffset, 0f, 1f)
    }
}

弹跳（带撞击声）

振动效果的另一个高级应用是模拟物理互动。PRIMITIVE_THUD 可以创建强烈且有回响的效果，可以与例如视频或动画中的撞击视觉效果配对，以增强整体体验。

这里有一个球落动画的示例，通过每次球从屏幕底部弹起时播放的撞击效果得到增强

Animation of a dropped ball bouncing off the bottom of the screen.

图 4. 此波形代表设备振动的输出加速度。

Kotlin

enum class BallPosition {
    Start,
    End
}

@Composable
fun BounceScreen() {
    // Control variable for the state of the ball.
    var ballPosition by remember { mutableStateOf(BallPosition.Start) }
    var bounceCount by remember { mutableStateOf(0) }

    // Animation for the bouncing ball.
    var transitionData = updateTransitionData(ballPosition)
    val collisionData = updateCollisionData(transitionData)

    // Ball is about to contact floor, only vibrating once per collision.
    var hasVibratedForBallContact by remember { mutableStateOf(false) }
    if (collisionData.collisionWithFloor) {
        if (!hasVibratedForBallContact) {
        val vibrationScale = 0.7.pow(bounceCount++).toFloat()
        vibrator.vibrate(
            VibrationEffect.startComposition().addPrimitive(
            VibrationEffect.Composition.PRIMITIVE_THUD,
            vibrationScale
            ).compose()
        )
        hasVibratedForBallContact = true
        }
    } else {
        // Reset for next contact with floor.
        hasVibratedForBallContact = false
    }

    Screen() {
        Box(
        Modifier
            .fillMaxSize()
            .clickable {
            if (transitionData.isAtStart) {
                ballPosition = BallPosition.End
            } else {
                ballPosition = BallPosition.Start
                bounceCount = 0
            }
            },
        ) {
        // Build the ball UI based on the current state.
        BouncingBall(transitionData)
        }
    }
}

Java

class ClickListener implements View.OnClickListener {
    @Override
    public void onClick(View view) {
        view.animate()
        .translationY(targetY)
        .setDuration(3000)
        .setInterpolator(new BounceInterpolator())
        .setUpdateListener(new AnimatorUpdateListener() {

            boolean hasVibratedForBallContact = false;
            int bounceCount = 0;

            @Override
            public void onAnimationUpdate(ValueAnimator animator) {
            boolean valueBeyondThreshold = (float) animator.getAnimatedValue() > 0.98;
            if (valueBeyondThreshold) {
                if (!hasVibratedForBallContact) {
                float vibrationScale = (float) Math.pow(0.7, bounceCount++);
                vibrator.vibrate(
                    VibrationEffect.startComposition()
                    .addPrimitive(
                        VibrationEffect.Composition.PRIMITIVE_THUD,
                        vibrationScale)
                    .compose());
                hasVibratedForBallContact = true;
                }
            } else {
                // Reset for next contact with floor.
                hasVibratedForBallContact = false;
            }
            }
        });
    }
}

带有包络线的振动波形

前面介绍的创建自定义振动模式过程允许您控制振动振幅以创建平滑的渐强和渐弱效果。本节介绍如何使用波形包络创建动态触感效果，从而精确控制振动振幅和频率随时间的变化。这使您可以精心打造更丰富、更细微的触感体验。

从 Android 16（API 级别 36）开始，系统提供以下 API，通过定义一系列控制点来创建振动波形包络线

BasicEnvelopeBuilder：一种创建硬件无关触感效果的易于理解的方法。
WaveformEnvelopeBuilder：一种更高级的触感效果创建方法；需要熟悉触感硬件。

Android 不为包络效果提供回退。如果您需要此支持，请完成以下步骤

使用 Vibrator.areEnvelopeEffectsSupported() 检查给定设备是否支持包络效果。
禁用不受支持的一致体验集，或使用自定义振动模式或组合作为回退替代方案。

要创建更基本的包络效果，请使用 BasicEnvelopeBuilder 并指定以下参数

强度值，范围为 \( [0, 1] \)，代表感知到的振动强度。例如，值 \( 0.5 \) 被感知为设备可以达到的全局最大强度的一半。
锐度值，范围为 \( [0, 1] \)，代表振动的清晰度。值越低表示振动越平滑，值越高则产生更尖锐的感觉。

注意： 设置初始锐度是可选的。如果省略，框架会将初始锐度默认为第一个控制点的值。
持续时间值，代表从上一个控制点（即强度和锐度对）过渡到新控制点所需的时间，以毫秒为单位。

这是一个示例波形，它在 500 毫秒内将强度从低音调渐强到高音调、最大强度的振动，然后在 100 毫秒内渐弱回 \( 0 \)（关闭）。

vibrator.vibrate(VibrationEffect.BasicEnvelopeBuilder()
    .setInitialSharpness(0.0f)
    .addControlPoint(1.0f, 1.0f, 500)
    .addControlPoint(0.0f, 1.0f, 100)
    .build()
)

如果您对触感有更深入的了解，可以使用 WaveformEnvelopeBuilder 定义包络效果。使用此对象时，您可以通过 VibratorFrequencyProfile 访问频率到输出加速度映射 (FOAM)。

振幅值，范围为 \( [0, 1] \)，代表在给定频率下可实现的振动强度，由设备 FOAM 决定。例如，值为 \( 0.5 \) 将产生给定频率下可达到的最大输出加速度的一半。
频率值，以赫兹为单位指定。

注意： 为 WaveformEnvelopeBuilder 设置初始频率是可选的。如果省略，框架会将初始频率默认为第一个控制点的值。
持续时间值，代表从上一个控制点过渡到新控制点所需的时间，以毫秒为单位。

以下代码显示了一个示例波形，它定义了一个 400 毫秒的振动效果。它首先在 50 毫秒内以恒定的 60 赫兹频率将振幅从关闭渐强到最大。然后，在接下来的 100 毫秒内频率渐强到 120 赫兹，并保持在该水平 200 毫秒。最后，在最后的 50 毫秒内振幅渐弱到 \( 0 \)，频率回到 60 赫兹。

vibrator.vibrate(VibrationEffect.WaveformEnvelopeBuilder()
    .addControlPoint(1.0f, 60f, 50)
    .addControlPoint(1.0f, 120f, 100)
    .addControlPoint(1.0f, 120f, 200)
    .addControlPoint(0.0f, 60f, 50)
    .build()
)

以下各节提供了几个带有包络线的振动波形示例。

弹簧弹跳

前面的一个示例使用 PRIMITIVE_THUD 来模拟物理弹跳互动。基本包络 API 提供了更精细的控制，使您可以精确调整振动强度和锐度。这使得触觉反馈更准确地跟随动画事件。

这里有一个自由下落弹簧的示例，动画通过每次弹簧从屏幕底部弹起时播放的基本包络效果得到增强

模拟弹簧弹跳的振动输出加速度波形图。

@Composable
fun BouncingSpringAnimation() {
  var springX by remember { mutableStateOf(SPRING_WIDTH) }
  var springY by remember { mutableStateOf(SPRING_HEIGHT) }
  var velocityX by remember { mutableFloatStateOf(INITIAL_VELOCITY) }
  var velocityY by remember { mutableFloatStateOf(INITIAL_VELOCITY) }
  var sharpness by remember { mutableFloatStateOf(INITIAL_SHARPNESS) }
  var intensity by remember { mutableFloatStateOf(INITIAL_INTENSITY) }
  var multiplier by remember { mutableFloatStateOf(INITIAL_MULTIPLIER) }
  var bottomBounceCount by remember { mutableIntStateOf(0) }
  var animationStartTime by remember { mutableLongStateOf(0L) }
  var isAnimating by remember { mutableStateOf(false) }

  val (screenHeight, screenWidth) = getScreenDimensions(context)

  LaunchedEffect(isAnimating) {
    animationStartTime = System.currentTimeMillis()
    isAnimating = true

    while (isAnimating) {
      velocityY += GRAVITY
      springX += velocityX.dp
      springY += velocityY.dp

      // Handle bottom collision
      if (springY > screenHeight - FLOOR_HEIGHT - SPRING_HEIGHT / 2) {
        // Set the spring's y-position to the bottom bounce point, to keep it
        // above the floor.
        springY = screenHeight - FLOOR_HEIGHT - SPRING_HEIGHT / 2

        // Reverse the vertical velocity and apply damping to simulate a bounce.
        velocityY *= -BOUNCE_DAMPING
        bottomBounceCount++

        // Calculate the fade-out duration of the vibration based on the
        // vertical velocity.
        val fadeOutDuration =
            ((abs(velocityY) / GRAVITY) * FRAME_DELAY_MS).toLong()

        // Create a "boing" envelope vibration effect that fades out.
        vibrator.vibrate(
            VibrationEffect.BasicEnvelopeBuilder()
                // Starting from zero sharpness here, will simulate a smoother
                // "boing" effect.
                .setInitialSharpness(0f)

                // Add a control point to reach the desired intensity and
                // sharpness very quickly.
                .addControlPoint(intensity, sharpness, 20L)

                // Add a control point to fade out the vibration intensity while
                // maintaining sharpness.
                .addControlPoint(0f, sharpness, fadeOutDuration)
                .build()
        )

        // Decrease the intensity and sharpness of the vibration for subsequent
        // bounces, and reduce the multiplier to create a fading effect.
        intensity *= multiplier
        sharpness *= multiplier
        multiplier -= 0.1f
      }

      if (springX > screenWidth - SPRING_WIDTH / 2) {
        // Prevent the spring from moving beyond the right edge of the screen.
        springX = screenWidth - SPRING_WIDTH / 2
      }

      // Check for 3 bottom bounces and then slow down.
      if (bottomBounceCount >= MAX_BOTTOM_BOUNCE &&
            System.currentTimeMillis() - animationStartTime > 1000) {
        velocityX *= 0.9f
        velocityY *= 0.9f
      }

      delay(FRAME_DELAY_MS) // Control animation speed.

      // Determine if the animation should continue based on the spring's
      // position and velocity.
      isAnimating = (springY < screenHeight + SPRING_HEIGHT ||
            springX < screenWidth + SPRING_WIDTH)
        && (velocityX >= 0.1f || velocityY >= 0.1f)
    }
  }

  Box(
    modifier = Modifier
      .fillMaxSize()
      .noRippleClickable {
        if (!isAnimating) {
          resetAnimation()
        }
      }
      .width(screenWidth)
      .height(screenHeight)
  ) {
    DrawSpring(mutableStateOf(springX), mutableStateOf(springY))
    DrawFloor()
    if (!isAnimating) {
      DrawText("Tap to restart")
    }
  }
}

火箭发射

前面的一个示例展示了如何使用基本包络 API 模拟弹簧弹跳反应。WaveformEnvelopeBuilder 可以精确控制设备的整个频率范围，从而实现高度定制的触感效果。通过将其与 FOAM 数据结合，您可以根据特定的频率能力调整振动。

以下示例演示了使用动态振动模式模拟火箭发射。效果从最低支持频率的加速度输出（0.1 G）到共振频率，始终保持 10% 的振幅输入。这使得效果以合理的强度输出开始，并增加感知到的强度和锐度，即使驱动振幅相同。达到共振后，效果频率下降回最低值，这被感知为强度和锐度下降。这创造了一种先是初始阻力，然后是释放的感觉，模仿了进入太空的发射过程。

使用基本包络 API 无法实现此效果，因为它抽象了关于设备共振频率和输出加速度曲线的设备特定信息。提高锐度可能会将等效频率推到共振之外，可能导致意外的加速度下降。

模拟火箭发射的振动输出加速度波形图。

@Composable
fun RocketLaunchAnimation() {
  val context = LocalContext.current
  val screenHeight = remember { mutableFloatStateOf(0f) }
  var rocketPositionY by remember { mutableFloatStateOf(0f) }
  var isLaunched by remember { mutableStateOf(false) }
  val animation = remember { Animatable(0f) }

  val animationDuration = 3000
  LaunchedEffect(isLaunched) {
    if (isLaunched) {
      animation.animateTo(
        1.2f, // Overshoot so that the rocket goes off the screen.
        animationSpec = tween(
          durationMillis = animationDuration,
          // Applies an easing curve with a slow start and rapid acceleration
          // towards the end.
          easing = CubicBezierEasing(1f, 0f, 0.75f, 1f)
        )
      ) {
        rocketPositionY = screenHeight.floatValue * value
      }
      animation.snapTo(0f)
      rocketPositionY = 0f;
      isLaunched = false;
    }
  }

  Box(
    modifier = Modifier
      .fillMaxSize()
      .noRippleClickable {
        if (!isLaunched) {
          // Play vibration with same duration as the animation, using 70% of
          // the time for the rise of the vibration, to match the easing curve
          // defined previously.
          playVibration(vibrator, animationDuration, 0.7f)
          isLaunched = true
        }
      }
      .background(Color(context.getColor(R.color.background)))
      .onSizeChanged { screenHeight.floatValue = it.height.toFloat() }
  ) {
    drawRocket(rocketPositionY)
  }
}

private fun playVibration(
  vibrator: Vibrator,
  totalDurationMs: Long,
  riseBias: Float,
  minOutputAccelerationGs: Float = 0.1f,
) {
  require(riseBias in 0f..1f) { "Rise bias must be between 0 and 1." }

  if (!vibrator.areEnvelopeEffectsSupported()) {
    return
  }

  val resonantFrequency = vibrator.resonantFrequency
  if (resonantFrequency.isNaN()) {
    // Device doesn't have or expose a resonant frequency.
    return
  }

  val startFrequency = vibrator.frequencyProfile?.getFrequencyRange(minOutputAccelerationGs)?.lower ?: return

  if (startFrequency >= resonantFrequency) {
    // Vibrator can't generate the minimum required output at lower frequencies.
    return
  }

  val minDurationMs = vibrator.envelopeEffectInfo.minControlPointDurationMillis
  val rampUpDurationMs = (riseBias * totalDurationMs).toLong() - minDurationMs
  val rampDownDurationMs = totalDurationMs - rampUpDuration - minDurationMs

  vibrator.vibrate(
    VibrationEffect.WaveformEnvelopeBuilder()
      // Quickly reach the desired output at the start frequency
      .addControlPoint(0.1f, startFrequency, minDurationMs)
      .addControlPoint(0.1f, resonantFrequency, rampUpDurationMs)
      .addControlPoint(0.1f, startFrequency, rampDownDurationMs)

      // Controlled ramp down to zero to avoid ringing after the vibration.
      .addControlPoint(0.0f, startFrequency, minDurationMs)
      .build()
  )
}

创建自定义触感效果 使用收藏集保持井然有序 根据您的偏好保存和分类内容。

使用回退处理设备兼容性

触感基元的使用

创建自定义振动模式

振动模式示例

渐强模式

Kotlin

Java

重复模式

Kotlin

Java

含回退的模式

Kotlin

Java

创建振动组合

创建组合振动效果

Kotlin

Java

创建振动基元的变体

在振动基元之间添加间隔

Kotlin

Java

检查支持哪些基元

Kotlin

Java

Kotlin

Java

振动组合示例

阻力（带低频滴答声）

Kotlin

Java

展开（带上升和下降）

Kotlin

Java

晃动（带旋转）

Kotlin

Java

弹跳（带撞击声）

Kotlin

Java

带有包络线的振动波形

弹簧弹跳

火箭发射

创建自定义触感效果