{"id":27915171,"url":"https://github.com/cofficlab/key-listener","last_synced_at":"2025-07-22T01:03:53.573Z","repository":{"id":285916796,"uuid":"959757581","full_name":"CofficLab/key-listener","owner":"CofficLab","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-18T12:11:33.000Z","size":64,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-19T05:04:55.437Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Objective-C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CofficLab.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-03T09:57:00.000Z","updated_at":"2025-05-18T12:11:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"238a8eea-809e-4be1-91f2-d4e6df4a0ad9","html_url":"https://github.com/CofficLab/key-listener","commit_stats":null,"previous_names":["cofficlab/key-listener"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/CofficLab/key-listener","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CofficLab%2Fkey-listener","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CofficLab%2Fkey-listener/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CofficLab%2Fkey-listener/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CofficLab%2Fkey-listener/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CofficLab","download_url":"https://codeload.github.com/CofficLab/key-listener/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CofficLab%2Fkey-listener/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266405405,"owners_count":23923536,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-21T11:47:31.412Z","response_time":64,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-06T15:35:33.806Z","updated_at":"2025-07-22T01:03:53.562Z","avatar_url":"https://github.com/CofficLab.png","language":"Objective-C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @coffic/key-listener\n\n[![English](https://img.shields.io/badge/English-violet)](README.md)\n[![简体中文](https://img.shields.io/badge/中文文档-gray)](README-zh.md)\n[![DEV](https://img.shields.io/badge/DEV-gray)](README-dev.md)\n[![NPM](https://img.shields.io/badge/NPM-orange)](https://www.npmjs.com/package/@coffic/key-listener)\n![NPM Downloads](https://img.shields.io/npm/dm/%40coffic%2Fkey-listener)\n![NPM Version](https://img.shields.io/npm/v/%40coffic%2Fkey-listener)\n[![Coffic](https://img.shields.io/badge/Coffic-green)](https://coffic.cn)\n[![Maintainer](https://img.shields.io/badge/Maintainer-blue)](https://github.com/nookery)\n![GitHub License](https://img.shields.io/github/license/cofficlab/key-listner)\n\n\nmacOS系统全局键盘事件监听器。\n\n## 功能介绍\n\n- 监听 macOS 系统上的所有键盘事件（包括应用内和应用外）\n- 支持所有类型的按键（普通键和修饰键）\n- 使用原生模块实现，性能高效稳定\n- 提供简单的事件接口，易于集成\n- 智能处理重复事件，每个按键在按下时只触发一次\n\n## 事件触发机制\n\n本监听器采用了智能的事件触发机制：\n\n1. **单次触发**: 每个按键在按下后只会触发一次事件，无论是普通键还是修饰键（如Command、Shift等）\n2. **按住处理**: 按住按键不放不会触发重复事件\n3. **重置机制**: 只有在松开按键后再次按下，才会触发新的事件\n4. **统一处理**: 对所有类型的按键采用相同的处理逻辑，行为一致且可预测\n\n这种机制特别适合用于：\n- 快捷键监听\n- 全局按键触发器\n- 按键统计和分析\n- 键盘事件录制\n\n## 安装\n\n```bash\nnpm install @coffic/key-listener\n```\n\n## 系统要求\n\n- **操作系统**: 仅支持 macOS 系统\n- **Node.js**: \u003e= 14.0.0\n- **构建工具**: Xcode命令行工具（用于编译原生模块）\n\n## 基本用法\n\n```typescript\nimport { KeyListener } from '@coffic/key-listener';\n\n// 创建监听器实例\nconst listener = new KeyListener();\n\n// 监听键盘事件\nlistener.on('keypress', (event) =\u003e {\n  console.log('按键事件:', {\n    keyCode: event.keyCode  // 键码\n  });\n});\n\n// 启动监听器（返回Promise）\nlistener.start().then(success =\u003e {\n  if (success) {\n    console.log('监听器已启动');\n  } else {\n    console.error('监听器启动失败');\n  }\n});\n\n// ... 应用其他逻辑 ...\n\n// 停止监听（不再需要时）\nlistener.stop();\n```\n\n## API参考\n\n### `KeyListener` 类\n\n#### 构造函数\n\n```typescript\nnew KeyListener()\n```\n\n创建一个新的键盘事件监听器实例。\n\n#### 方法\n\n##### `start(): Promise\u003cboolean\u003e`\n\n启动监听器。返回一个Promise，解析为布尔值表示是否成功启动。\n\n##### `stop(): boolean`\n\n停止监听器。返回布尔值表示是否成功停止。\n\n##### `isListening(): boolean`\n\n获取监听器的当前状态。返回布尔值表示是否正在监听。\n\n#### 事件\n\n##### `keypress`\n\n当检测到按键事件时触发。事件对象包含以下属性：\n\n- `keyCode: number` - 按键的键码\n\n```typescript\nlistener.on('keypress', (event) =\u003e {\n  // 处理按键事件\n});\n```\n\n## 常见键码参考\n\n- 54: 右Command键\n- 55: 左Command键\n- 56: 左Shift键\n- 57: Caps Lock键\n- 58: 左Option键\n- 59: 左Control键\n- 60: 右Shift键\n- 61: 右Option键\n- 62: 右Control键\n- 63: Function键\n\n更多键码请参考示例代码或文档。\n\n## 注意事项\n\n1. **平台限制**: 此包仅在macOS系统上可用，在其他平台上将不起作用但不会导致错误。\n\n2. **权限要求**: 使用此监听器时，您的应用需要辅助功能（Accessibility）权限。首次使用时，macOS会提示用户授予权限。\n\n3. **应用打包**: 在使用Electron或其他工具打包应用时，请确保正确包含原生模块文件。\n\n4. **事件处理**: \n   - 每个按键在按下时只会触发一次事件\n   - 按住按键不会触发重复事件\n   - 需要松开按键后再次按下才会触发新事件\n   - 这个行为适用于所有类型的按键，包括修饰键\n\n## 故障排除\n\n### 监听器无法启动\n\n- 检查您是否在macOS系统上运行\n- 确保已授予应用辅助功能权限\n- 检查控制台是否有错误信息\n\n### 编译错误\n\n如果在安装过程中遇到编译错误：\n\n- 确保已安装Xcode命令行工具：`xcode-select --install`\n- 确保Node.js版本兼容\n- 尝试使用`npm rebuild`重建原生模块\n\n## 许可证\n\nMIT\n\n## 贡献\n\n欢迎提交Issue和Pull Request。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcofficlab%2Fkey-listener","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcofficlab%2Fkey-listener","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcofficlab%2Fkey-listener/lists"}