更新记录

1.1.1（2026-10-31）

支持蒸汽模式

平台兼容性

uni-app(5.26)

uni-app x(5.26)

其他

UTS 震动触感反馈（自定义节奏、强度、滑动刻度）

Android / iOS 原生触感插件，用于按钮点击、操作结果、滑动选值和节奏提醒。业务代码使用同一套 API，具体能力通过返回字段判断。

HBuilderX 5.26+；版本 1.1.1；插件 ID：austin-haptic-x。

不支持 Web、小程序、鸿蒙和 nvue。iOS 需要具备触感硬件的设备；iPad、模拟器等设备可能返回不支持。模拟器可验证页面、参数和返回结果，无法验证真实震感。

第 1 步：放入插件

完整目录放到 你的项目/uni_modules/austin-haptic-x/。uni_modules 与项目的 manifest.json、pages.json 同级。

项目 manifest.json 无需为本插件额外配置权限或模块。

• Android：打包时自动合并插件内的 android.permission.VIBRATE 普通权限，不需要运行时申请授权。
• iOS：无需额外权限或用途说明。插件不依赖第三方 SDK。

保留插件内的 utssdk 等全部文件，无需将插件的 AndroidManifest.xml 复制到项目根目录。

第 2 步：注册演示页

在项目 pages.json 的 pages 数组中追加：

{
  "path": "uni_modules/austin-haptic-x/index",
  "style": { "navigationBarTitleText": "震动触感反馈", "disableScroll": true }
}

在已有页面点击按钮时打开：

uni.navigateTo({ url: '/uni_modules/austin-haptic-x/index' })

uni-app x 自动使用 index.uvue，普通 uni-app Vue3 使用 index.vue。要把演示改成业务页面，可复制相应文件到 pages/haptics/index.uvue 或 pages/haptics/index.vue，注册新路径并保留插件目录；页面中的根目录导入路径无需修改。

第 3 步：制作并运行自定义基座

1. HBuilderX 选中项目，进入 发行 → 原生 App 云打包，选择 Android 或 iOS，勾选 制作自定义调试基座。
2. Android 填写应用包名与签名信息；iOS 真机填写与 Bundle ID 匹配的 P12、密码和 .mobileprovision，调试描述文件需包含测试设备的 UDID。
3. 完成打包后安装新基座，在 运行 菜单选择 自定义基座，再运行项目。

首次导入、更新原生代码后需要重新制作基座；只改页面、参数或文档不需要。使用 HBuilderX 支持的本地模拟器运行方式时，可直接编译到模拟器，无需为模拟器申请真机签名。

第 4 步：打开页面体验

1. 点 按钮点击 / 操作成功 / 警告提醒 / 操作失败，更多预设在“更多触感”中展开。
2. 调整 整体强度，再点反馈按钮；关闭触感开关后不再提交播放。
3. 拖动 滑动刻度，每跨过 10 个数值反馈一次。
4. 选择 连续两下 / 告警节奏，点 播放节奏；也可修改毫秒数组或按时长播放。
5. Android 可选择 循环提醒，本页最多循环 3 秒；点 停止 可提前结束。

页面底部显示本次结果、跳过原因或错误码。离页会停止播放，清理演示刻度状态，并恢复进入前的全局设置。iOS 模拟器显示“不支持”属于预期结果，不代表真机播放失败。

业务代码怎么调用

统一从插件根目录 @/uni_modules/austin-haptic-x 导入。 @/ 表示项目源码目录，对应的实际目录为 你的项目/uni_modules/austin-haptic-x/，不直接导入 utssdk/app-ios 或 utssdk/app-android。

uni-app x 的 <script setup lang="uts">：

import { onShow, onHide, onUnload } from '@dcloudio/uni-app'
import {
  vibrate, cancelVibration, configureHaptics,
  selectionChanged, resetSelectionHaptics,
  VibrateOptions, SelectionHapticsOptions,
} from '@/uni_modules/austin-haptic-x'

function onButtonTap(): void {
  const options: VibrateOptions = { type: 'light' }
  const result = vibrate(options)
  console.log(result.ok, result.skipped, result.errCode, result.errMsg)
}

function onPatternTap(): void {
  const options: VibrateOptions = {
    pattern: [0, 120, 80, 120], intensity: 0.7, sharpness: 0.5,
  }
  vibrate(options)
}

// 先用实际起始值记录选择器，滑动时再传最新值。
let priceValue = 50
const priceOptions: SelectionHapticsOptions = { key: 'price', step: 10 }
onShow(() => { selectionChanged(priceValue, priceOptions) })
function onPriceChange(value: number): void {
  priceValue = value
  selectionChanged(value, priceOptions)
}

function updatePreference(enabled: boolean, intensity: number): void {
  const settings = configureHaptics({ enabled: enabled, intensity: intensity, minIntervalMs: 40 })
  if (!settings.ok) console.log(settings.errCode, settings.errMsg)
}

function cleanup(): void {
  resetSelectionHaptics('price')
  cancelVibration()
}
onHide(() => { cleanup() })
onUnload(() => { cleanup() })

按钮点击时调用 onButtonTap() 或 onPatternTap()；滑动时将当前数值传给 onPriceChange(value)；偏好设置变更时调用 updatePreference(enabled, intensity)。普通 uni-app Vue3 使用相同函数调用，去掉类型标注和类型导入即可。

全局设置仅保存在当前进程，不会自动写入磁盘。需要记住用户偏好时，由业务保存并在下次启动时调用 configureHaptics()。同一进程共用设置；业务页面临时调整后，应恢复原设置。

API

ok=true 表示本次调用被接受；是否实际提交播放还需检查 skipped。系统、马达和设备设置仍会影响最终震感。

可选字段省略或传 null 时使用默认值（配置更新时保留原值）；pattern 数组中的每一项仍须为有效数字。

VibrateOptions

所有字段可选。

设置 duration 或 pattern 后使用自定义播放，type 仅作默认预设，不会叠加播放。部分 iOS 系统预设无法独立调节强度或锐度；Android 无振幅控制的设备使用系统强度。请检查能力及 degraded/note，不要假定不同手机震感一致。

Android 循环示例：

vibrate({ pattern: [0, 120, 80, 120], repeatIndex: 0, maxDurationMs: 3000 })

VibrateResult

HapticsConfigOptions / HapticsSettings

配置参数均可选；enabled 不传或传 null 时保留当前开关。读取与配置结果均包含下列设置值和状态字段。

configureHaptics() 只更新传入字段，先完整校验；无效配置返回原设置值与错误状态，不会部分生效。getHapticsSettings() 读取时返回 ok=true、errCode=0、errMsg=''。

SelectionHapticsOptions

value 必须为有限数字，除以 step 后的刻度需在安全整数范围内。首次调用仅建立起点；同刻度不重复播放，快速跨多个刻度也只尝试当前反馈，不补播历史刻度。进程内最多保存 32 路选择器，超出时移除最早建立的一路；离页调用 resetSelectionHaptics(key) 清理自己使用的 key。

HapticsCapabilities

错误码与使用边界

仅用于前台交互反馈。业务页面应在 onHide / onUnload 调用 cancelVibration()；演示页已接好。iOS 系统中断或切后台会停止当前触感，Android 循环会在设定时限自动停止。新播放会替换此前播放，同一进程不同时播放多组节奏。

iPhone 无震感时，检查 设置 → 辅助功能 → 触控 → 振动 与 设置 → 声音与触感 → 系统触感；Android 检查系统震动设置及设备是否有震动马达。播放返回成功表示已向系统提交，不是对物理马达状态的检测。