haptics - PythonIDE Docs

iOS 触觉反馈：在用户明确操作后触发冲击、选择、通知类震动，或播放 Core Haptics 自定义模式。

边界：触觉是辅助反馈，不能替代文字、颜色或状态变化。无触觉设备或用户关闭系统触觉时，界面仍要有可见反馈。不要在 AppUI body() 里触发，否则刷新时会重复震动。

#模块概览

项	说明
导入	`import haptics`
适合做什么	按钮点击、选项切换、保存成功/失败、危险操作拦截
调用时机	放在按钮或明确事件回调；不要写在 `body()` 中
推荐顺序	用户操作 → `haptics.*` → 同时更新 `State` 文案
两套 API	`impact`/`selection`/`notification` 适合大多数场景；`play` 需先 `is_supported()`

#快速开始

下面脚本依次触发选择、冲击和成功通知反馈：

python

import haptics

haptics.selection()
haptics.impact("medium", intensity=0.8)
haptics.notification("success")

# 快捷方式
haptics.success()
haptics.light()

#AppUI 示例

触觉放在按钮回调里，同时更新界面状态。

python

import appui
import haptics

state = appui.State(
    message="点击按钮体验触觉反馈",
    core_haptics="未检测",
)


def refresh_support():
    state.core_haptics = "支持" if haptics.is_supported() else "不支持"


def choose_item():
    haptics.selection()
    state.message = "选择反馈 · 轻微滴答"


def save_item():
    haptics.success()
    state.message = "成功反馈 · 保存完成"


def show_error():
    haptics.error()
    state.message = "错误反馈 · 请检查输入"


def play_pattern():
    if not haptics.is_supported():
        state.message = "当前设备不支持 Core Haptics"
        return
    events = [
        {"type": "transient", "time": 0.0, "intensity": 1.0, "sharpness": 0.8},
        {"type": "continuous", "time": 0.08, "duration": 0.25, "intensity": 0.5, "sharpness": 0.3},
    ]
    ok = haptics.play(events)
    state.message = "自定义模式已播放" if ok else "播放失败"


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("设备", [
                appui.LabeledContent("Core Haptics", value=state.core_haptics),
                appui.Button("检测支持情况", action=refresh_support),
            ]),
            appui.Section("UIKit 反馈", [
                appui.Button("选择", action=choose_item),
                appui.Button("保存成功", action=save_item)
                .button_style("bordered_prominent"),
                appui.Button("模拟错误", action=show_error, role="destructive"),
            ]),
            appui.Section("自定义", [
                appui.Button("播放短模式", action=play_pattern),
                appui.Text(state.message).foreground_color("secondaryLabel"),
            ]),
        ]).navigation_title("触觉反馈")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`selection()`	选项切换的轻微滴答
`impact(style, intensity=1.0)`	冲击反馈
`notification(type)`	成功/警告/错误通知反馈
`success()` / `warning()` / `error()`	`notification` 快捷方式
`light()` / `medium()` / `heavy()`	`impact` 快捷方式
`is_supported()`	是否支持 Core Haptics
`play(events)`	播放自定义事件列表
`stop()`	停止 Core Haptics 引擎

#UIKit 反馈

适合绝大多数按钮和状态场景：

python

import haptics

haptics.selection()
haptics.impact("medium", intensity=0.8)
haptics.notification("success")

API	参数	说明
`impact(style, intensity=1.0)`	`light` / `medium` / `heavy` / `soft` / `rigid`	点击冲击感
`notification(type)`	`success` / `warning` / `error`	结果类反馈
`selection()`	—	选择变化

#快捷方法

方法	等价于
`success()`	`notification("success")`
`warning()`	`notification("warning")`
`error()`	`notification("error")`
`light()`	`impact("light")`
`medium()`	`impact("medium")`
`heavy()`	`impact("heavy")`

#Core Haptics

is_supported() — 播放自定义模式前先检查。

play(events) — 事件列表，每项为 dict：

python

events = [
    {"type": "transient", "time": 0.0, "intensity": 1.0, "sharpness": 0.8},
    {"type": "continuous", "time": 0.08, "duration": 0.25, "intensity": 0.5, "sharpness": 0.3},
]
if haptics.is_supported():
    haptics.play(events)

字段	说明
`type`	`transient` 或 `continuous`
`time`	开始时间（秒）
`duration`	持续时间（`continuous` 用）
`intensity` / `sharpness`	强度与锐度 0..1

stop() — 退出页面或中断模式时停止引擎。

#常见错误

错误写法	后果	修正
在 `body()` 里调 `haptics.success()`	刷新时重复震动	放进按钮回调
只震动不更新 UI	无触觉设备上无反馈	同时改 `State` 或显示 HUD
不检查就 `play(events)`	部分设备无效	先 `is_supported()`
高频循环触发	体验差、耗电	仅在关键状态变化时触发一次

#相关文档

文档	用途
device	设备能力与系统信息
原生能力入口	MiniApp 场景配方

#预期效果

运行示例后，界面应出现文档描述的目标结果；若与预期不符，先看「失败路径」并按返回值或日志排查。