# finger-mouse

**Repository Path**: mirrors_theajack/finger-mouse

## Basic Information

- **Project Name**: finger-mouse
- **Description**: Mouse control with hand gestures
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-03
- **Last Updated**: 2026-03-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<!--
 * @Author: theajack
 * @Date: 2023-05-09 22:31:06
 * @Description: Coding something
-->
# [指尖鼠标](https://github.com/theajack/finger-mouse)

指尖鼠标是一个基于手势识别的鼠标，通过手指的行为来控制鼠标的移动和点击。同时提供底层识别的手指关节事件，可以自定义交互行为。

[在线Demo](https://theajack.github.io/finger-mouse?cn) | [English](https://github.com/theajack/finger-mouse/blob/master/README.md)

## 快速使用

### npm 使用

```plain
npm i finger-mouse
```

```js
import { initFingerMouse } from 'finger-mouse';
initFingerMouse();
```

### CDN 使用

```html
<script src="https://cdn.jsdelivr.net/npm/finger-mouse"></script>
<script>
  FingerMouse.initFingerMouse();
</script>
```


## init 参数

```js
export declare function initFingerMouse(options?: {
    showOriginPointer?: boolean; // 是否显示鼠标真实指针，默认为false
    showPanel?: boolean; // 是否显示性能面板，默认为false
    cdnMirror?: string; // CDN镜像地址
    showCamera?: boolean; // 是否显示摄像头画面，默认为false
    showHandSkeleton?: boolean; // 是否显示手的骨架绘制画面，默认为true
    fingerColor?: string; // 手指颜色，默认为 Red
    lineColor?: string; // 节点之间的连接线颜色，默认为 White
    touchedFingerColor?: string; // 手指触摸时的颜色，默认为 Green
    whichHand?: "left" | "right" | "auto"; // 使用哪个手操作，auto表示使用先识别到的手
    touchThreshold?: number; // 判断手指触摸到距离的阈值，默认为25px
    showPointer?: boolean; // 是否显示模拟的鼠标指针，默认为true
    disableDefaultAction?: boolean; // 是否禁用默认模拟的鼠标操作行为，默认为false
    onRenderReady?: () => void; // 渲染准备完成的回调函数
    onHandMove?: (x: number, y: number) => void; // 大拇指移动的回调函数
    onFingerTouch?: (finger: IFinger, touched: boolean) => void; // 大拇指与四个手指触摸到的回到函数
    onOriginData?: (data: any) => void; // 手掌原始数据回调函数
    onMouseDown?: (e: IMouseEvent) => void; // 默认鼠标行为下的模拟鼠标点击事件
    onMouseUp?: (e: IMouseEvent) => void; // 默认鼠标行为下的模拟鼠标松开事件
    onMouseMove?: (e: IMouseMoveEvent) => void; // 默认鼠标行为下的模拟鼠标移动事件
}): Promise<Camera>;
```

### CDN 镜像

FingerMouse中使用的模型相关资源是使用的第三方CDN，默认使用的是 jsDelivr 中国镜像，你可以通过 CDM_MIRROR 来使用内置的其他镜像或自定义镜像。

```js
import { CDM_MIRROR } from 'finger-mouse';
```

## API

### FingerClient

```js
const client = await initFingerMouse();

await client.ready; // 等待渲染准备完成，等价于 onRenderReady

client.isRenderReady; // 是否渲染准备完成, boolean
client.pointer; // 获取模拟的鼠标指针Dom元素

client.isFingerTouched('index'); // 获取某根手指是否与大拇指触碰到 // 'index' | 'middle' | 'ring' | 'pinky';
client.destroy(); // 销毁实例，销毁后无法再次使用
```

### Mouse

```js
const client = await initFingerMouse();
await client.ready; // 等待渲染准备完成，等价于 onRenderReady
const mouse = client.mouse;
client.clientX; // 模拟的鼠标指针的X坐标
client.clientY; // 模拟的鼠标指针的Y坐标
```