Uniapp 中的 uni.vibrate 震动 API 使用指南
uni.vibrate 是 Uniapp 提供的设备震动 API，可以让移动设备产生振动反馈。这个 API 主要适用于移动端（App 和小程序），在 H5 环境下通常无效。
一、基本用法
1. 短震动（15ms）
uni.vibrateShort({success: function() {console.log('震动成功');},fail: function(err) {console.log('震动失败:', err);}
});
2. 长震动（400ms）
uni.vibrateLong({success: function() {console.log('震动成功');},fail: function(err) {console.log('震动失败:', err);}
});
二、兼容性写法
由于不同平台支持程度不同，推荐使用以下兼容写法：
function vibrate(duration) {// #ifdef APP-PLUS || MP-WEIXINif (duration === 'long') {uni.vibrateLong();} else {uni.vibrateShort();}// #endif// #ifdef H5console.log('H5环境不支持震动');// #endif
}
三、平台差异说明
| 平台 | 支持情况 |
|---|---|
| 微信小程序 | 支持 vibrateShort 和 vibrateLong |
| App | 支持 vibrateShort 和 vibrateLong |
| H5 | 不支持 |
| 其他小程序 | 部分支持（支付宝小程序支持，百度小程序部分支持，需实测） |
四、实际应用场景
1. 按钮点击反馈
<template><button @click="handleButtonClick">点击我有震动反馈</button>
</template><script>
export default {methods: {handleButtonClick() {// 点击时产生短震动uni.vibrateShort();// 其他业务逻辑...}}
}
</script>
2. 重要操作确认
function confirmDelete() {// 先产生长震动提醒用户uni.vibrateLong();uni.showModal({title: '警告',content: '确定要删除吗？',success: function(res) {if (res.confirm) {// 执行删除操作}}});
}
3. 游戏中的震动反馈
// 游戏角色受到攻击
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动画模拟震动效果
@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. 创建原生插件
// 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中调用
const vibratePlugin = uni.requireNativePlugin('Your-Vibrate-Plugin');function customVibrate(duration) {// #ifdef APP-PLUSvibratePlugin.vibrate(duration);// #endif// #ifndef APP-PLUSif (duration > 100) {uni.vibrateLong();} else {uni.vibrateShort();}// #endif
}
七、最佳实践建议
-
场景选择：
- 重要的用户操作反馈（如支付成功）
- 错误提示（如登录失败）
- 游戏中的特殊事件
-
适度使用：
- 不要在每个按钮点击时都震动
- 重要的、不常发生的操作才使用震动
-
用户控制：
// 检查用户是否禁用了震动 function shouldVibrate() {const settings = uni.getStorageSync('userSettings') || {};return settings.vibration !== false; }// 使用示例 if (shouldVibrate()) {uni.vibrateShort(); } -
组合反馈：
- 震动可以配合声音、视觉变化一起使用
function combinedFeedback() {uni.vibrateShort();uni.showToast({ title: '操作成功' });// 可以在这里播放提示音 }
通过合理使用 uni.vibrate API，可以显著提升移动端应用的用户体验，特别是在游戏和交互密集型应用中。但切记要适度使用，避免过度振动导致用户体验下降。