react-native-holding-hand

📖 概述

react-native-holding-hand 是一个 React Native 插件，封装了 HarmonyOS 的 智感握姿（Multimodal Awareness Kit）能力，提供握持手和操作手状态的实时感知。

通过该插件，开发者可以根据用户握持设备的方式动态调整 UI 布局，实现更符合人体工学的交互体验。

核心能力

| 能力 | API 版本 | 说明 | |------|---------|------| | holdingHandChanged | API 20+ | 订阅握持手状态变化 | | getHoldingHandStatus | API 20+ | 一次性获取握持手状态 | | operatingHandChanged | API 15+ | 订阅操作手状态变化 | | getOperatingHandStatus | API 15+ | 一次性获取操作手状态 |

🔧 安装

npm install @nutpi/react-native-holding-hand

📋 权限配置

在宿主应用的 module.json5 中添加权限：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.DETECT_GESTURE"
      }
    ]
  }
}

🚀 使用

导入

import HoldingHand, {
  HoldingHandStatus,
  OperatingHandStatus,
} from '@nutpi/react-native-holding-hand';

订阅握持手状态变化

const unsubscribe = HoldingHand.onHoldingHandChanged((status) => {
  switch (status) {
    case HoldingHandStatus.NONE:
      console.log('未握持');
      break;
    case HoldingHandStatus.LEFT:
      console.log('左手握持 → UI 靠左布局');
      break;
    case HoldingHandStatus.RIGHT:
      console.log('右手握持 → UI 靠右布局');
      break;
    case HoldingHandStatus.BOTH:
      console.log('双手握持');
      break;
    case HoldingHandStatus.UNKNOWN:
      console.log('未识别');
      break;
  }
});

// 取消订阅
unsubscribe();

订阅操作手状态变化

const unsubscribe = HoldingHand.onOperatingHandChanged((status) => {
  switch (status) {
    case OperatingHandStatus.LEFT:
      console.log('左手操作');
      break;
    case OperatingHandStatus.RIGHT:
      console.log('右手操作');
      break;
    // ...
  }
});

// 取消订阅
unsubscribe();

一次性查询

// 获取当前握持手状态
const holdingStatus = await HoldingHand.getHoldingHandStatus();

// 获取当前操作手状态
const operatingStatus = await HoldingHand.getOperatingHandStatus();

在 React 组件中使用

import React, { useState, useEffect } from 'react';
import { View, Text, StyleSheet } from 'react-native';
import HoldingHand, { HoldingHandStatus } from '@nutpi/react-native-holding-hand';

export default function App() {
  const [holdingStatus, setHoldingStatus] = useState(HoldingHandStatus.UNKNOWN);

  useEffect(() => {
    const unsubscribe = HoldingHand.onHoldingHandChanged((status) => {
      setHoldingStatus(status);
    });
    return unsubscribe;
  }, []);

  return (
    <View style={[
      styles.container,
      holdingStatus === HoldingHandStatus.LEFT && styles.containerLeft,
      holdingStatus === HoldingHandStatus.RIGHT && styles.containerRight,
    ]}>
      <Text>握持状态: {HoldingHandStatus[holdingStatus]}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: 'center', alignItems: 'center' },
  containerLeft: { alignItems: 'flex-start', paddingLeft: 20 },
  containerRight: { alignItems: 'flex-end', paddingRight: 20 },
});

📡 API

HoldingHand.onHoldingHandChanged(callback)

订阅握持手状态变化（API 20+）。

| 参数 | 类型 | 说明 | |------|------|------| | callback | (status: HoldingHandStatus) => void | 状态变化回调 | | 返回 | () => void | 取消订阅函数 |

HoldingHand.onOperatingHandChanged(callback)

订阅操作手状态变化（API 15+）。

| 参数 | 类型 | 说明 | |------|------|------| | callback | (status: OperatingHandStatus) => void | 状态变化回调 | | 返回 | () => void | 取消订阅函数 |

HoldingHand.getHoldingHandStatus()

获取当前握持手状态（API 20+）。

| 返回 | 类型 | |------|------| | Promise<HoldingHandStatus> | 状态码枚举 |

HoldingHand.getOperatingHandStatus()

获取当前操作手状态（API 15+）。

| 返回 | 类型 | |------|------| | Promise<OperatingHandStatus> | 状态码枚举 |

HoldingHand.subscribeHoldingHand() / unsubscribeHoldingHand()

手动管理握持手原生订阅（底层 API，推荐使用 onHoldingHandChanged）。

HoldingHand.subscribeOperatingHand() / unsubscribeOperatingHand()

手动管理操作手原生订阅（底层 API，推荐使用 onOperatingHandChanged）。

🏗 架构

react-native-holding-hand/
├── src/                          # JS/TS 层
│   ├── NativeHoldingHand.ts      # TurboModule Spec 定义
│   ├── HoldingHand.ts            # 高层 API 封装
│   └── index.ts                  # 入口
├── harmony/
│   └── rn_holding_hand/          # 鸿蒙原生层
│       ├── src/main/ets/
│       │   ├── Logger.ts         # 日志工具
│       │   ├── HoldingHandManager.ts  # motion API 封装
│       │   ├── RNHoldingHandTurboModule.ts  # TurboModule 实现
│       │   └── RNHoldingHandPackage.ts      # RN Package 注册
│       ├── index.ets
│       ├── ts.ts
│       └── oh-package.json5
├── index.d.ts                    # 类型声明
└── package.json

🔗 相关链接

• HarmonyOS 智感握姿开发指导
• HarmonyOS Motion API 参考
• holding-harmony (Flutter 版)

📄 License

MIT