uni-app force-press-gesture-handler 组件完全指南：压力按压手势识别与手势协商
uni-app force-press-gesture-handler 组件完全指南压力按压手势识别与手势协商【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app本文基于 uni-app 开源仓库中的组件文档 docs/component/force-press-gesture-handler.md 编写结合同仓库的组件文档与示例工程系统讲解微信小程序端压力按压手势组件force-press-gesture-handler的属性、回调与手势协商机制。读完本文你将掌握如何在 uni-app 工程中声明压力按压手势节点、读取按压坐标与压力值并通过simultaneous-handlers、should-accept-gesture等属性协调多手势冲突进而实现 3D Touch 风格的按压反馈交互。一、组件概述与定位force-press-gesture-handler是 uni-app 在微信小程序平台基础库 4.41 起提供的手势处理组件属于gesture-handler手势处理器家族。它用于识别“用力按压”这一手势当用户在组件区域内以较大压力按下时触发手势回调并上报按压力度、按压坐标等信息。在 uni-app 文档体系中docs/component/目录下与它同族的组件还包括 double-tap-gesture-handler双击、long-press-gesture-handler长按、tap-gesture-handler点按、pan-gesture-handler平移、scale-gesture-handler缩放以及 horizontal-drag-gesture-handler、vertical-drag-gesture-handler拖拽等参见 docs/component/_sidebar.md。整个家族共享同一套“手势协商 worklet 回调”设计模型本文讲解的force-press正是这套模型在压力维度上的具体应用。二、平台兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | 4.41 | x | x | x |上表来自原文档 兼容性表格该组件当前仅在微信小程序端可用且要求微信基础库版本不低于 4.41Web、Android、iOS、HarmonyOS 均不支持。它对应的微信小程序原生能力是 skyline 渲染引擎下的force-press-gesture-handler组件参见原文档“参见”章节中的微信小程序文档入口。需要特别提醒由于仅微信小程序支持在使用时建议做好条件编译或运行环境判断避免在 Android/iOS App 等其他平台上误用导致编译或运行异常。仓库中examples/hello-uts等示例工程面向多端演示force-press相关的页面仅能在微信小程序开发者工具中验证。三、属性详解force-press-gesture-handler共声明 5 个属性均仅在微信小程序 4.41 起生效| 名称 | 类型 | 兼容性 | 描述 | | :- | :- | :-: | :- | | tag | string | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 声明手势协商时的组件标识 | | worklet:ongesture | eventhandler | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 手势识别成功的回调 | | worklet:should-accept-gesture | callback | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 手势是否应该被识别 | | simultaneous-handlers | Array.string | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 声明可同时触发的手势节点 | | native-view | string | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 代理的原生节点类型 |3.1 tag —— 手势协商的组件标识tag是一个字符串类型的标识用于在手势协商gesture negotiation过程中指代本组件。当多个手势处理器同时存在、互相竞争识别权时通过tag可以在simultaneous-handlers、should-accept-gesture等属性中精确引用目标节点。同类组件如 tap-gesture-handler、pan-gesture-handler的tag属性定义与 force-press 完全一致可见这是 gesture-handler 家族的统一约定每个手势处理器节点都可以通过tag在父级手势系统中被寻址。3.2 worklet:ongesture —— 手势识别成功的回调该属性为事件处理器类型在压力按压手势被识别成功后触发。注意其前缀worklet:表明回调运行在 worklet 环境中即脱离主线程、在手势处理线程同步执行的逻辑因此回调内的代码应避免执行耗时任务或直接依赖页面级状态。回调中可通过事件对象读取以下字段| 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | state | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 手势状态 | | absoluteX | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 相对于全局的 X 坐标 | | absoluteY | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 相对于全局的 Y 坐标 | | pressure | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: x | 压力大小 |这是 force-press 与同族其他组件最大的区别点回调携带pressure压力大小字段用于读取用户按压的力度。对比 tap-gesture-handler 仅提供state、absoluteX、absoluteY以及 pan-gesture-handler 额外提供deltaX/deltaY/velocityX/velocityY可以推断出各手势组件的回调字段是按手势语义定制的压力手势关注“压了多重”移动手势关注“移了多远/多快”。absoluteX、absoluteY均为相对于全局页面坐标系的坐标值而非相对组件自身的偏移。state字段描述手势状态机所处的阶段如识别中、已识别、结束等具体取值与微信小程序 skyline 手势系统保持一致开发者可通过监听不同 state 实现“按压开始 / 按压结束”等分阶段反馈。3.3 worklet:should-accept-gesture —— 手势识别裁决回调callback类型用于决定当前手势是否应该被识别。该回调在 gesture-handler 家族tap、long-press、pan 等中均有定义是手势协商机制的核心入口当多个手势处理器竞争同一触摸序列时系统会调用该回调进行裁决返回是否接受本次手势。典型场景页面内同时存在横向拖拽手势与压力按压手势手指移动触发拖拽、按压达到阈值才触发 force-press开发者可以在should-accept-gesture中结合压力值与位移量决定当前输入流归属哪个手势从而避免手势冲突误触发。3.4 simultaneous-handlers —— 同时触发的手势节点Array.string类型声明可与当前手势同时触发的手势节点集合数组元素为对应节点的tag。默认情况下手势系统遵循“排他”原则一个手势被识别后其他手势会被抑制而声明为 simultaneous 的节点可以并行触发。典型用例滑块slider与轮播swiper嵌套滚动时若不声明同时触发内层手势会阻断外层手势或反之。仓库示例工程 src/pages/component/slider/slider-in-swiper.uvue 处理了类似的嵌套滚动场景并在 src/pages/template/long-list/long-list.uvue 等处注释了微信 skyline 下的滚动行为差异——这些正是手势协商要解决的真实痛点嵌套滚动/嵌套手势之间的优先级分配。3.5 native-view —— 代理的原生节点类型string类型声明该手势处理器代理的原生节点类型。它允许手势处理器挂载到指定的原生组件上将手势识别能力“代理”给该原生节点。该属性与同族组件定义一致用于更精细地控制手势作用范围。四、典型用法示例结合上文属性说明一个典型的压力按压手势节点声明如下该写法与 tap-gesture-handler 等家族成员的用法一致仅回调字段与语义不同force-press-gesture-handler tagforcePress worklet:ongestureonForcePress worklet:should-accept-gestureshouldAccept :simultaneous-handlers[scrollHandler] !-- 需要响应压力按压的视图内容 -- view classpress-area用力按压我/view /force-press-gesture-handler对应的事件处理逻辑worklet 环境可读取压力值与坐标function onForcePress(event) { // event.state 手势状态 // event.absoluteX 相对全局的 X 坐标 // event.absoluteY 相对全局的 Y 坐标 // event.pressure 压力大小force-press 独有字段 const { pressure, absoluteX, absoluteY } event // 根据压力值驱动 UI 反馈例如改变背景透明度或缩放 } function shouldAccept(event) { // 返回 true 表示接受本次手势识别 return true }五、手势协商机制与同类组件对比5.1 协商模型从 docs/component/_sidebar.md 可以看到uni-app 目前一共收录了 8 个 gesture-handler 组件它们共享同一套能力骨架tag寻址所有手势节点均可通过tag被其他节点引用worklet:ongesture回调手势识别成功后的统一入口worklet:should-accept-gesture裁决在识别前决定是否接受实现手势优先级的动态控制simultaneous-handlers并行声明允许指定节点同时触发突破排他默认值native-view代理将手势能力挂到原生节点上。5.2 force-press 的差异化字段| 组件 | 独有回调字段 | 核心语义 | | :- | :- | :- | | force-press-gesture-handler | pressure | 按压力度 | | tap-gesture-handler | —仅 state/absoluteX/absoluteY | 轻点 | | double-tap-gesture-handler | — | 双击 | | long-press-gesture-handler | — | 长按 | | pan-gesture-handler | deltaX / deltaY / velocityX / velocityY | 平移距离与速度 | | horizontal/vertical-drag-gesture-handler | — | 定向拖拽 | | scale-gesture-handler | — | 双指缩放 |上表对比依据force-press 回调字段见本文 3.2 节pan 回调字段见 docs/component/pan-gesture-handler.md#L26-L36tap 回调字段见 docs/component/tap-gesture-handler.md#L26-L32。可以看出pressure是压力手势的“灵魂字段”配合should-accept-gesture设置压力阈值后即可实现“轻按无感、重按触发”的 3D Touch 风格交互。六、使用限制与注意事项平台强约束仅在微信小程序端、基础库 ≥ 4.41 可用其余平台均标记为不支持x跨端工程需做好平台差异化处理。worklet 环境约束worklet:前缀的回调在非主线程环境中执行回调内不应进行耗时计算、网络请求或直接修改页面数据应通过事件通道把必要信息回传主线程。回调字段可用性pressure字段依赖硬件/系统对手指压力的上报能力在不支持压力感应的设备上该值可能恒为同一基准值设计交互时应保留兼容退化路径如结合按压时长兜底。仓库示例说明当前仓库的 examples/hello-uts 与 examples/hello-uvue 示例工程、src/pages 演示页面中未直接收录 force-press 的现成页面使用时可参照同家族组件如 tap-gesture-handler、pan-gesture-handler的声明方式组合使用。七、相关文档同家族组件tap-gesture-handler、double-tap-gesture-handler、long-press-gesture-handler、pan-gesture-handler、scale-gesture-handler、horizontal-drag-gesture-handler、vertical-drag-gesture-handler组件总览docs/component/_sidebar.md、docs/component/README.md相关演示代码src/pages/component/slider/slider-in-swiper.uvue嵌套滚动手势处理、src/pages/template/long-list/long-list.uvueskyline 滚动差异注释关于原文档“参见”中的微信小程序/支付宝/百度/抖音等外部文档入口因本文只输出仓库内部资源不在此重复列出外部链接如需查阅微信小程序 skyline 原生组件定义可直接在微信开发者文档中检索force-press-gesture-handler并关注其与 uni-app 属性命名worklet:ongesture等的对应关系。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考