Uniapp 中的 uni.vibrate 震动 API 使用指南

uni.vibrate 是 Uniapp 提供的设备震动 API，可以让移动设备产生振动反馈。这个 API 主要适用于移动端（App 和小程序），在 H5 环境下通常无效。

一、基本用法

1. 短震动（15ms）

javascript 复制代码

uni.vibrateShort({
  success: function() {
    console.log('震动成功');
  },
  fail: function(err) {
    console.log('震动失败:', err);
  }
});

2. 长震动（400ms）

javascript 复制代码

uni.vibrateLong({
  success: function() {
    console.log('震动成功');
  },
  fail: function(err) {
    console.log('震动失败:', err);
  }
});

二、兼容性写法

由于不同平台支持程度不同，推荐使用以下兼容写法：

javascript 复制代码

function vibrate(duration) {
  // #ifdef APP-PLUS || MP-WEIXIN
  if (duration === 'long') {
    uni.vibrateLong();
  } else {
    uni.vibrateShort();
  }
  // #endif
  
  // #ifdef H5
  console.log('H5环境不支持震动');
  // #endif
}

三、平台差异说明

平台	支持情况
微信小程序	支持 `vibrateShort` 和 `vibrateLong`
App	支持 `vibrateShort` 和 `vibrateLong`
H5	不支持
其他小程序	部分支持（支付宝小程序支持，百度小程序部分支持，需实测）

四、实际应用场景

1. 按钮点击反馈

javascript 复制代码

<template>
  <button @click="handleButtonClick">点击我有震动反馈</button>
</template>

<script>
export default {
  methods: {
    handleButtonClick() {
      // 点击时产生短震动
      uni.vibrateShort();
      
      // 其他业务逻辑...
    }
  }
}
</script>

2. 重要操作确认

javascript 复制代码

function confirmDelete() {
  // 先产生长震动提醒用户
  uni.vibrateLong();
  
  uni.showModal({
    title: '警告',
    content: '确定要删除吗？',
    success: function(res) {
      if (res.confirm) {
        // 执行删除操作
      }
    }
  });
}

3. 游戏中的震动反馈

javascript 复制代码

// 游戏角色受到攻击
function characterHurt() {
  uni.vibrateShort();
  // 其他受伤逻辑...
}

// 游戏胜利
function gameWin() {
  // 胜利时产生三次短震动
  for (let i = 0; i < 3; i++) {
    setTimeout(() => {
      uni.vibrateShort();
    }, i * 200);
  }
}

五、注意事项

用户权限：
- 在部分 Android 设备上可能需要振动权限
- iOS 无需特殊权限
震动时长：
- vibrateShort 一般为15ms（微信小程序固定值）
- vibrateLong 一般为400ms（微信小程序固定值）
- App端可以通过原生插件实现自定义时长
频繁调用限制：
- 避免在短时间内频繁调用震动API
- 部分Android设备对频繁震动有限制
用户体验：
- 震动反馈应当适度使用，过度使用会惹恼用户
- 最好在设置中提供关闭震动的选项

H5替代方案：

在H5环境中可以使用CSS动画模拟震动效果

css 复制代码

@keyframes shake {
  0% { transform: translateX(0); }
  25% { transform: translateX(-5px); }
  50% { transform: translateX(5px); }
  75% { transform: translateX(-5px); }
  100% { transform: translateX(0); }
}

.vibrate-effect {
  animation: shake 0.3s linear;
}

六、扩展实现（App端自定义震动时长）

如果需要更灵活的震动控制（特别是App端），可以通过原生插件实现：

1. 创建原生插件

java 复制代码

// Android原生代码
public class VibratePlugin implements UniPlugin {
    public static void vibrate(int duration) {
        Vibrator vibrator = (Vibrator) UniSDKInstance.getContext().getSystemService(Context.VIBRATOR_SERVICE);
        if (vibrator.hasVibrator()) {
            vibrator.vibrate(duration);
        }
    }
    
    // ...其他必要方法
}

2. 在Uniapp中调用

javascript 复制代码

const vibratePlugin = uni.requireNativePlugin('Your-Vibrate-Plugin');

function customVibrate(duration) {
  // #ifdef APP-PLUS
  vibratePlugin.vibrate(duration);
  // #endif
  
  // #ifndef APP-PLUS
  if (duration > 100) {
    uni.vibrateLong();
  } else {
    uni.vibrateShort();
  }
  // #endif
}

七、最佳实践建议

场景选择：
- 重要的用户操作反馈（如支付成功）
- 错误提示（如登录失败）
- 游戏中的特殊事件
适度使用：
- 不要在每个按钮点击时都震动
- 重要的、不常发生的操作才使用震动

用户控制：

javascript 复制代码

// 检查用户是否禁用了震动
function shouldVibrate() {
  const settings = uni.getStorageSync('userSettings') || {};
  return settings.vibration !== false;
}

// 使用示例
if (shouldVibrate()) {
  uni.vibrateShort();
}

组合反馈：

震动可以配合声音、视觉变化一起使用

javascript 复制代码

function combinedFeedback() {
  uni.vibrateShort();
  uni.showToast({ title: '操作成功' });
  // 可以在这里播放提示音
}

通过合理使用 uni.vibrate API，可以显著提升移动端应用的用户体验，特别是在游戏和交互密集型应用中。但切记要适度使用，避免过度振动导致用户体验下降。