{"_id":"@coffic/key-listener","_rev":"2-99768668748eb697131a26fd17e2e43d","name":"@coffic/key-listener","dist-tags":{"latest":"1.0.4"},"versions":{"1.0.3":{"name":"@coffic/key-listener","version":"1.0.3","keywords":["macos","command-key","hotkeys","keyboard","listener","native"],"author":{"name":"CofficLab"},"license":"MIT","_id":"@coffic/key-listener@1.0.3","maintainers":[{"name":"nookery","email":"nooks@qq.com"}],"os":["darwin"],"dist":{"shasum":"11c5587cb5e712cf6f55c541856b2bdfe3dd9259","tarball":"https://registry.npmjs.org/@coffic/key-listener/-/key-listener-1.0.3.tgz","fileCount":6,"integrity":"sha512-RCXm0MI0S2GWyYJNdq+2/QcktrvunOqr1ZgZse1bix1iKSsxuXiYZT7pz4CvLblPgm5esDaq2aV46DJr6r0Mcg==","signatures":[{"sig":"MEUCIFzYfRunogHiv8d/r/5wG+eFui4CLz7UuyTxuaZvad2JAiEAnNZevsy5AIxt6hQN4W2rLs3w4UUW6GhD+xLqx8XkJWE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":75305},"main":"dist/index.js","type":"commonjs","_from":"file:coffic-key-listener-1.0.3.tgz","types":"dist/index.d.ts","engines":{"node":">=14.0.0"},"scripts":{"test":"echo \"Error: no test specified\" && exit 1","build":"npm run build:ts && npm run build:native","build:ts":"tsc","build:native":"node native/build.js"},"_npmUser":{"name":"nookery","email":"nooks@qq.com"},"_resolved":"/private/var/folders/qn/7t0vq3ts721cmgt0tgrtgzl80000gn/T/a120c15f8775a3396732b840ff739732/coffic-key-listener-1.0.3.tgz","_integrity":"sha512-RCXm0MI0S2GWyYJNdq+2/QcktrvunOqr1ZgZse1bix1iKSsxuXiYZT7pz4CvLblPgm5esDaq2aV46DJr6r0Mcg==","_npmVersion":"10.8.2","description":"macOS系统按键事件监听器","directories":{},"_nodeVersion":"18.20.8","dependencies":{"node-addon-api":"^7.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.0","@types/node":"^22.13.0"},"peerDependencies":{"electron":">=22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/key-listener_1.0.3_1743674260863_0.2929032718320974","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@coffic/key-listener","version":"1.0.4","description":"macOS系统按键事件监听器","main":"dist/index.js","types":"dist/index.d.ts","type":"commonjs","homepage":"https://github.com/CofficLab/key-listener","publishConfig":{"access":"public"},"os":["darwin"],"engines":{"node":">=14.0.0"},"keywords":["macos","command-key","hotkeys","keyboard","listener","native"],"author":{"name":"CofficLab"},"license":"MIT","dependencies":{"node-addon-api":"^7.0.0"},"devDependencies":{"@types/node":"^22.13.0","typescript":"^5.8.0"},"peerDependencies":{"electron":">=22.0.0"},"scripts":{"build":"npm run build:ts && npm run build:native","build:ts":"tsc","build:native":"node native/build.js","test":"echo \"Error: no test specified\" && exit 1"},"_id":"@coffic/key-listener@1.0.4","_integrity":"sha512-w43SSjMcudhJxaFt8mel8gdRLRMuSs+1JU9eBnlOvsaNQunCyxRb8ILeNiD0Q7xko1nbOWu0SLqnBTLAceZloA==","_resolved":"/private/var/folders/7g/cnfrzbd555q9lmpsr1byngs80000gn/T/757d7ac9526ddc6efa2c8a8053d5b457/coffic-key-listener-1.0.4.tgz","_from":"file:coffic-key-listener-1.0.4.tgz","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-w43SSjMcudhJxaFt8mel8gdRLRMuSs+1JU9eBnlOvsaNQunCyxRb8ILeNiD0Q7xko1nbOWu0SLqnBTLAceZloA==","shasum":"c59e4b65f6e1900809be42a5f84e5ddd45fe4dfe","tarball":"https://registry.npmjs.org/@coffic/key-listener/-/key-listener-1.0.4.tgz","fileCount":6,"unpackedSize":75901,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD5/41RSWe2Uk7ryvbocMzPJtgPQ7ZzlqEKxeFfK3Am5AIhALEZgIXJyI6UVPHi5rprqIWHU9OC7PzTNKe1Wm3O8CWp"}]},"_npmUser":{"name":"nookery","email":"nooks@qq.com"},"directories":{},"maintainers":[{"name":"nookery","email":"nooks@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/key-listener_1.0.4_1745895831989_0.45549739416258106"},"_hasShrinkwrap":false}},"time":{"created":"2025-04-03T09:57:40.791Z","modified":"2025-04-29T03:03:52.407Z","1.0.3":"2025-04-03T09:57:41.042Z","1.0.4":"2025-04-29T03:03:52.202Z"},"author":{"name":"CofficLab"},"license":"MIT","keywords":["macos","command-key","hotkeys","keyboard","listener","native"],"description":"macOS系统按键事件监听器","maintainers":[{"name":"nookery","email":"nooks@qq.com"}],"readme":"# @coffic/key-listener\n\n[![English](https://img.shields.io/badge/English-Click-yellow)](README.md)\n[![简体中文](https://img.shields.io/badge/中文文档-点击查看-orange)](README-zh.md)\n\nA global keyboard event listener for macOS.\n\n## Features\n\n- Listen to all keyboard events on macOS (both in-app and system-wide)\n- Support all types of keys (regular keys and modifier keys)\n- Implemented with native modules for high performance and stability\n- Simple event interface for easy integration\n- Smart handling of repeated events, triggering only once per keypress\n\n## Event Triggering Mechanism\n\nThis listener implements an intelligent event triggering mechanism:\n\n1. **Single Trigger**: Each key triggers an event only once when pressed, regardless of whether it's a regular key or a modifier key (like Command, Shift, etc.)\n2. **Hold Handling**: Holding down a key does not trigger repeated events\n3. **Reset Mechanism**: A new event is only triggered after releasing and pressing the key again\n4. **Unified Processing**: All types of keys are handled with the same logic, ensuring consistent and predictable behavior\n\nThis mechanism is particularly suitable for:\n- Hotkey listening\n- Global key triggers\n- Keyboard statistics and analysis\n- Keyboard event recording\n\n## Installation\n\n```bash\nnpm install @coffic/key-listener\n```\n\n## System Requirements\n\n- **Operating System**: macOS only\n- **Node.js**: >= 14.0.0\n- **Build Tools**: Xcode Command Line Tools (for native module compilation)\n\n## Basic Usage\n\n```typescript\nimport { KeyListener } from '@coffic/key-listener';\n\n// Create listener instance\nconst listener = new KeyListener();\n\n// Listen for keyboard events\nlistener.on('keypress', (event) => {\n  console.log('Key event:', {\n    keyCode: event.keyCode  // Key code\n  });\n});\n\n// Start the listener (returns Promise)\nlistener.start().then(success => {\n  if (success) {\n    console.log('Listener started');\n  } else {\n    console.error('Failed to start listener');\n  }\n});\n\n// ... Other application logic ...\n\n// Stop listening (when no longer needed)\nlistener.stop();\n```\n\n## API Reference\n\n### `KeyListener` Class\n\n#### Constructor\n\n```typescript\nnew KeyListener()\n```\n\nCreates a new keyboard event listener instance.\n\n#### Methods\n\n##### `start(): Promise<boolean>`\n\nStarts the listener. Returns a Promise that resolves to a boolean indicating success.\n\n##### `stop(): boolean`\n\nStops the listener. Returns a boolean indicating success.\n\n##### `isListening(): boolean`\n\nGets the current state of the listener. Returns a boolean indicating if it's listening.\n\n#### Events\n\n##### `keypress`\n\nTriggered when a key event is detected. The event object contains:\n\n- `keyCode: number` - The key code of the pressed key\n\n```typescript\nlistener.on('keypress', (event) => {\n  // Handle key event\n});\n```\n\n## Common Key Code Reference\n\n- 54: Right Command key\n- 55: Left Command key\n- 56: Left Shift key\n- 57: Caps Lock key\n- 58: Left Option key\n- 59: Left Control key\n- 60: Right Shift key\n- 61: Right Option key\n- 62: Right Control key\n- 63: Function key\n\nFor more key codes, please refer to example code or documentation.\n\n## Important Notes\n\n1. **Platform Limitation**: This package only works on macOS and will not function on other platforms (though it won't cause errors).\n\n2. **Permission Requirements**: Your application needs Accessibility permission to use this listener. macOS will prompt users to grant permission on first use.\n\n3. **Application Packaging**: When packaging your application with Electron or other tools, ensure proper inclusion of native module files.\n\n4. **Event Handling**: \n   - Each key triggers an event only once when pressed\n   - Holding a key won't trigger repeated events\n   - New events require releasing and pressing the key again\n   - This behavior applies to all key types, including modifier keys\n\n## Troubleshooting\n\n### Listener Won't Start\n\n- Check if you're running on macOS\n- Ensure Accessibility permission is granted\n- Check console for error messages\n\n### Compilation Errors\n\nIf you encounter compilation errors during installation:\n\n- Ensure Xcode Command Line Tools are installed: `xcode-select --install`\n- Verify Node.js version compatibility\n- Try rebuilding native modules with `npm rebuild`\n\n## License\n\nMIT\n\n## Contributing\n\nIssues and Pull Requests are welcome.\n","readmeFilename":"README.md","homepage":"https://github.com/CofficLab/key-listener"}