# ldesign-hotkey

**Repository Path**: ldesign-v1/ldesign-hotkey

## Basic Information

- **Project Name**: ldesign-hotkey
- **Description**: LDesign ????? - Hotkey/shortcut management
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-04-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @ldesign/hotkey

> 快捷键管理系统 — 注册、管理和分发键盘快捷键，支持作用域、组合键和冲突检测。

## ✨ 特性

- **作用域管理** — 支持多作用域快捷键，自动过滤非当前作用域的绑定
- **组合键** — 支持 `ctrl+s`、`shift+alt+d` 等组合键格式
- **冲突检测** — 注册时自动检测同一作用域内的快捷键冲突
- **Vue 集成** — 提供 `useHotkey` / `useHotkeyScope` 组合式函数
- **指令支持** — Vue 指令 `v-hotkey` 快速绑定
- **帮助面板** — 内置快捷键帮助面板生成

## 📦 安装

```bash
# 核心
pnpm add @ldesign/hotkey

# Vue 适配器
pnpm add @ldesign/hotkey @ldesign/hotkey-vue
```

## 🚀 快速开始

### 原生 JavaScript

```ts
import { HotkeyManager } from '@ldesign/hotkey'

const hotkey = new HotkeyManager({ scope: 'global' })

// 注册快捷键
const unregister = hotkey.register({
  key: 'ctrl+s',
  handler: (e) => {
    e.preventDefault()
    console.log('保存')
  },
  description: '保存文档',
})

// 切换作用域
hotkey.setScope('editor')

// 查看冲突
const conflicts = hotkey.detectConflicts(binding)

// 销毁
hotkey.destroy()
```

### Vue 3

```vue
<script setup>
import { useHotkey, useHotkeyScope } from '@ldesign/hotkey-vue'

// 全局快捷键
useHotkey('ctrl+s', (e) => {
  e.preventDefault()
  save()
}, { description: '保存' })

// 作用域快捷键
const { scope, setScope } = useHotkeyScope('editor')
useHotkey('ctrl+z', undo, { scope: 'editor' })
</script>
```

### Vue 指令

```vue
<template>
  <button v-hotkey="'ctrl+s'">保存</button>
  <div v-hotkey="{ key: 'escape', handler: close }">按 ESC 关闭</div>
</template>
```

## 📖 API 文档

### HotkeyManager

| 方法 | 说明 |
|------|------|
| `register(binding)` | 注册快捷键，返回取消注册函数 |
| `unregister(key, scope?)` | 取消注册 |
| `setScope(scope)` | 切换当前作用域 |
| `getScope()` | 获取当前作用域 |
| `getBindings()` | 获取所有已注册快捷键 |
| `getBindingsByScope(scope?)` | 获取指定作用域的快捷键 |
| `detectConflicts(binding)` | 检测冲突 |
| `destroy()` | 销毁管理器 |

### 快捷键格式

支持的修饰键：`ctrl` / `control`、`alt`、`shift` / `meta` / `cmd` / `command` / `win`

示例：`ctrl+s`、`shift+alt+d`、`meta+enter`

## 📄 License

MIT © LDesign Team