更新记录

1.0.0（2026-08-04）

• 首发跨端原生震动 UTS 插件。
• 提供点震、单次/长震、延迟、间隔 pattern、有限循环、预设节奏与停止控制。
• 支持 Android、iOS、HarmonyOS、Web、微信小程序，并通过能力快照说明平台限制。
• 修复 Android vibrateOnce 未处理 delay 的问题。
• 对齐 HarmonyOS 循环能力与 isVibrating 文档说明。
• 重构 uni-app / uni-app x 双轨示例：Transfer 风格首页、5 组功能子页（含 preset）、统一结果卡片与 onUnload 停止逻辑。

平台兼容性

uni-app(4.87)

uni-app x(5.0)

xview-vibrate

跨端原生震动与触觉反馈 UTS 插件。统一封装 Android / iOS / HarmonyOS / Web / 微信小程序的震动能力，公共 API 一致；平台差异体现在能力边界与返回错误，不改变调用方式。

支持：点震预设触感、单次/长震、延迟与振幅控制、自定义间隔节奏、有限/无限循环、内置预设节奏、停止控制、运行状态查询与能力快照。

功能特性

• 点震与长震：vibrateClick 预设触感（light / medium / heavy / success / warning / error / selection）；vibrateLong 长震，默认 400ms
• 单次震动：vibrateOnce 控制 delay、duration 与 Android amplitude（1–255）
• 间隔节奏：startVibratePattern 自定义 segments；repeat: -1 请求无限循环，须配合 stopVibrate 停止
• 内置节奏：startVibratePreset 提供 heartbeat、sos、notification、alarm 四种预设
• 停止与查询：stopVibrate(patternId?) 停止指定或全部任务；isVibrating() 查询插件维护的循环任务是否仍活动
• 能力快照：getVibrateCapabilities() 查询当前设备实际支持的能力，不触发震动
• 统一返回：所有异步 API 返回 Promise<XviewVibrateResult>；errCode === 0 表示系统已接受请求
• 诊断能力：统一错误码（不支持端返回 9070001 等，不抛未捕获异常）；完整类型定义见 utssdk/interface.uts

快速使用

import {
  vibrateClick,
  vibrateOnce,
  vibrateLong,
  startVibratePattern,
  startVibratePreset,
  stopVibrate,
  getVibrateCapabilities,
  isVibrating
} from '@/uni_modules/xview-vibrate'

// 点震：各端映射为最接近的系统触觉
await vibrateClick({ style: 'light' })
await vibrateClick({ style: 'success' })

// 单次震动：delay 为等待后再震，不会循环
await vibrateOnce({
  delay: 500,
  duration: 200,
  amplitude: 128  // 仅 Android API 26+ 尝试使用
})

// 长震：默认 400ms
await vibrateLong()
await vibrateLong({ duration: 800 })

// 自定义间隔节奏：repeat=-1 无限循环，页面卸载时必须 stopVibrate
const result = await startVibratePattern({
  segments: [{ duration: 120 }, { delay: 100, duration: 240 }],
  repeat: -1,
  onComplete: () => {
    console.log('有限循环播放完成')
  }
})
console.log('patternId', result.patternId)

// 停止指定或全部循环任务
await stopVibrate(result.patternId)
await stopVibrate()  // 不传 patternId 时停止全部

// 内置预设节奏
await startVibratePreset({ preset: 'heartbeat', repeat: 1 })
await startVibratePreset({ preset: 'alarm', repeat: -1 })  // alarm 适合无限循环

// 查询当前设备能力（不触发震动）
const caps = getVibrateCapabilities()
console.log(caps.platform, caps.hasVibrator, caps.supportsPattern, caps.notes)

// 查询循环任务是否仍活动
console.log('isVibrating', isVibrating())

API

所有异步 API 返回 Promise<XviewVibrateResult>；getVibrateCapabilities() 同步返回能力快照；isVibrating() 同步返回布尔值。完整类型定义见插件内 utssdk/interface.uts。

类型定义

type XviewVibrateStyle =
  | 'light' | 'medium' | 'heavy'
  | 'success' | 'warning' | 'error' | 'selection'

type XviewVibratePreset = 'heartbeat' | 'sos' | 'notification' | 'alarm'

type XviewVibrateSegment = {
  delay?: number      // 该段震动前的等待时间（ms）
  duration: number    // 实际震动时间（ms），必填
  amplitude?: number  // 1–255，仅 Android API 26+ 尝试使用
}

type XviewVibrateClickOptions = {
  style?: XviewVibrateStyle  // 未传时使用 light
}

type XviewVibrateOnceOptions = {
  delay?: number
  duration?: number
  amplitude?: number         // 1–255；其他平台忽略
  style?: XviewVibrateStyle  // 存在时优先使用平台预设触感
}

type XviewVibratePatternOptions = {
  segments: XviewVibrateSegment[]  // 必填，至少一段 duration > 0
  repeat?: number                  // 1 为一次，N 为 N 次，-1 为无限循环
  patternId?: string               // 可选自定义任务标识
  onComplete?: () => void          // 有限循环播放完成时回调
}

type XviewVibratePresetOptions = {
  preset: XviewVibratePreset       // 必填
  repeat?: number
  patternId?: string
  onComplete?: () => void
}

type XviewVibrateResult = {
  errCode: number       // 0 表示请求已被当前平台接受
  errMsg: string
  patternId: string     // 循环任务标识；单次震动通常为空串
  platform: string      // android | ios | harmony | web | mp-weixin
  supported: boolean    // 当前平台是否支持该能力
  triggered: boolean    // 是否实际触发了震动
}

type XviewVibrateCapabilities = {
  errCode: number
  errMsg: string
  platform: string
  hasVibrator: boolean
  supportsDuration: boolean
  supportsPattern: boolean
  supportsLoop: boolean
  supportsAmplitude: boolean
  supportsPresetStyle: boolean
  maxDuration: number
  supportedStyles: XviewVibrateStyle[]
  notes: string         // 平台限制说明
}

vibrateOnce / vibrateLong 参数

startVibratePattern 参数

行为说明：

• 定时间隔循环可用单段 { delay, duration } 配合 repeat 实现「隔多久震一次」。
• repeat: -1 时必须在页面卸载或业务结束时调用 stopVibrate()，示例页已内置该逻辑。
• 返回的 patternId 可用于后续 stopVibrate(patternId) 精确停止。

startVibratePreset 参数

错误码