更新记录

1.0.0（2026-01-28） 下载此版本

• 初始版本
• 支持订阅握持手状态变化
• 支持取消订阅

平台兼容性

uni-app(4.81)

jack-holding-hand

简介

鸿蒙智感握姿检测插件，用于检测用户握持手机的手势（左手、右手、双手、未握持）。

平台支持

• ✅ 鸿蒙 (HarmonyOS)
• ❌ Android
• ❌ iOS

权限要求

需要在 ohos.permission.DETECT_GESTURE" 权限，默认已经在插件的 module.json5 中配置

API 说明

uni.subscribeHoldingHand(options)

订阅握持手状态变化感知事件。

参数说明：

握持手状态值：

示例代码：

// 导入插件函数
import { subscribeHoldingHand, unsubscribeHoldingHand } from '@/uni_modules/jack-holding-hand'

// 订阅
subscribeHoldingHand({
  onChange: (status) => {
    console.log('握持手状态:', status);
    switch(status) {
      case 0:
        console.log('未握持');
        break;
      case 1:
        console.log('左手握持');
        break;
      case 2:
        console.log('右手握持');
        break;
      case 3:
        console.log('双手握持');
        break;
      case 16:
        console.log('未识别');
        break;
    }
  },
  success: (res) => {
    console.log('订阅成功', res);
  },
  fail: (err) => {
    console.error('订阅失败', err);
  }
});

unsubscribeHoldingHand(options)

取消订阅握持手状态变化感知事件。

参数说明：

示例代码：

import { unsubscribeHoldingHand } from '@/uni_modules/jack-holding-hand'

unsubscribeHoldingHand({
  success: (res) => {
    console.log('取消订阅成功', res);
  },
  fail: (err) => {
    console.error('取消订阅失败', err);
  }
});

使用场景

1. 智能悬浮按钮：根据握持手自动调整悬浮按钮位置（推荐使用 smart-float-button 组件）
2. 单手模式优化：检测单手握持时优化界面布局
3. 游戏控制：根据握持方式调整游戏控制布局
4. 无障碍功能：为不同握持方式提供更好的交互体验

使用方式

方式一：使用智能悬浮按钮组件（推荐）

直接使用封装好的 smart-float-button 组件，无需手动调用插件 API：

<template>
  <!-- #ifdef APP-HARMONY -->
  <smart-float-button @click="handleClick" />
  <!-- #endif -->
</template>

<script>
// #ifdef APP-HARMONY
import SmartFloatButton from '@/components/smart-float-button/smart-float-button.vue'
// #endif

export default {
  // #ifdef APP-HARMONY
  components: {
    SmartFloatButton
  },
  // #endif
  methods: {
    handleClick() {
      console.log('按钮被点击')
    }
  }
}
</script>

方式二：直接使用插件 API

如果需要自定义逻辑，可以直接使用插件 API：

<script>
// #ifdef APP-HARMONY
import { subscribeHoldingHand, unsubscribeHoldingHand } from '@/uni_modules/jack-holding-hand'
// #endif

export default {
  mounted() {
    // #ifdef APP-HARMONY
    subscribeHoldingHand({
      onChange: (status) => {
        console.log('握持手状态:', status);
        // 自定义处理逻辑
      }
    });
    // #endif
  },
  beforeUnmount() {
    // #ifdef APP-HARMONY
    unsubscribeHoldingHand();
    // #endif
  }
}
</script>

注意事项

1. 仅支持鸿蒙系统
2. 需要申请 ohos.permission.DETECT_GESTURE 权限
3. 建议在页面 onLoad 或 onShow 时订阅，在 onHide 或 onUnload 时取消订阅
4. 状态变化会实时回调，注意性能优化