From f35fdc52c4c02bd0ea48880fea96be1dad9a9c8d Mon Sep 17 00:00:00 2001 From: jaywcjlove <398188662@qq.com> Date: Tue, 20 Mar 2018 20:54:42 +0800 Subject: [PATCH] Update documents. --- README-zh.md | 278 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 290 ++++++++++++++++++++++++++------------------------- 2 files changed, 425 insertions(+), 143 deletions(-) create mode 100644 README-zh.md diff --git a/README-zh.md b/README-zh.md new file mode 100644 index 0000000..efac159 --- /dev/null +++ b/README-zh.md @@ -0,0 +1,278 @@ +# Hotkeys + +[![](https://img.shields.io/github/issues/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/issues) [![](https://img.shields.io/github/forks/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/network) [![](https://img.shields.io/github/stars/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/stargazers) [![](https://img.shields.io/github/release/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/releases) ![](http://jaywcjlove.github.io/sb/status/no-dependencies.svg) [![jaywcjlove/sb](https://jaywcjlove.github.io/sb/lang/english.svg)](./README.md) + +这是一个强健的 Javascript 库用于捕获键盘输入和输入的组合键，它没有依赖，压缩只有只有(~3kb)，gzip:1.9k。[官方文档DEMO预览](http://jaywcjlove.github.io/hotkeys/?lang=cn) + + +```text + __ __ __ + | |--..-----.| |_ | |--..-----..--.--..-----. + | || _ || _|| < | -__|| | ||__ --| + |__|__||_____||____||__|__||_____||___ ||_____| + |_____| +``` + +## 创建 + +您将需要在您的系统上安装的 Node.js。 + +```sh +# bower 安装 +$ bower install hotkeysjs + +# npm 安装 +$ npm install hotkeys-js + +$ npm run build # 编译 +$ npm run watch # 开发模式 +``` + +## React中使用 + +[react-hotkeys](https://github.com/jaywcjlove/react-hotkeys)，安装如下： + +```sh +npm i -S react-hot-keys +``` + +例子 + +```js +import React, { Component } from 'react'; +import Hotkeys from 'react-hot-keys'; + +export default class HotkeysDemo extends Component { + constructor(props) { + super(props); + this.state = { + output: 'Hello, I am a component that listens to keydown and keyup of a', + } + } + onKeyUp(keyName, e, handle) { + console.log("test:onKeyUp", e, handle) + this.setState({ output: `onKeyUp ${keyName}` }); + } + onKeyDown(keyName, e, handle) { + console.log("test:onKeyDown", keyName, e, handle) + this.setState({ output: `onKeyDown ${keyName}` }); + } + render() { + return ( + +
{this.state.output}
+ + ) + } +} +``` + +## 使用 + +传统调用 + +```html + +``` + +包加载 + +```js +import hotkeys from 'hotkeys-js'; + +hotkeys('shift+a,alt+d, w', function(e){ + console.log('干点活儿',e); + if(hotkeys.shift) console.log('大哥你摁下了 shift 键！'); + if(hotkeys.ctrl) console.log('大哥你摁下了 ctrl 键！'); + if(hotkeys.alt) console.log('大哥你摁下了 alt 键！'); +}); +``` + + +## 定义快捷键 + +```js +// 定义 F5 快捷键 +hotkeys('f5', function(event,handler){ + //event.srcElement: input + //event.target: input + // 阻止Widnows系统下的默认刷新事件 + event.preventDefault() + alert('你按下了 F5 键!') +}); +// 定义a快捷键 +hotkeys('a', function(event,handler){ + //event.srcElement: input + //event.target: input + if(event.target === "input"){ + alert('你在输入框中按下了 a!') + } + alert('你按下了 a!') +}); + +// 定义a快捷键 +hotkeys('ctrl+a,ctrl+b,r,f', function(event,handler){ + switch(handler.key){ + case "ctrl+a":alert('你按下了ctrl+a!');break; + case "ctrl+b":alert('你按下了ctrl+b!');break; + case "r":alert('你按下了r!');break; + case "f":alert('你按下了f!');break; + } + //handler.scope 范围 +}); + +// 返回false将停止活动，并阻止默认浏览器事件 +hotkeys('ctrl+r', function(){ alert('停止刷新!'); return false }); + +// 多个快捷方式做同样的事情 +hotkeys('⌘+r, ctrl+r', function(){ }); + +// 对所有摁键执行任务 +hotkeys('*','wcj', function(e){ + console.log('干点活儿',e); + console.log("key.getScope()::",hotkeys.getScope()); + if(hotkeys.shift) console.log('大哥你摁下了 shift 键！'); + if(hotkeys.ctrl) console.log('大哥你摁下了 ctrl 键！'); + if(hotkeys.alt) console.log('大哥你摁下了 alt 键！'); +}); +``` + +## 支持的键 + +`⇧`, `shift`, `option`, `⌥`, `alt`, `ctrl`, `control`, `command`, `⌘` + +`⌘` Command() +`⌃` Control +`⌥` Option(alt) +`⇧` Shift +`⇪` Caps Lock(大写) +~~`fn` 功能键就是fn(不支持)~~ +`↩︎` return/enter +`space` 空格键 + +## 修饰键判断 +可以对下面的修饰键判断 `shift` `alt` `option` `ctrl` `control` `command`，特别注意`+`和`=`键值相同，组合键设置`⌘+=` + +```js +hotkeys('shift+a,alt+d, w', function(e){ + console.log('干点活儿',e); + if(hotkeys.shift) console.log('大哥你摁下了 shift 键！'); + if(hotkeys.ctrl) console.log('大哥你摁下了 ctrl 键！'); + if(hotkeys.alt) console.log('大哥你摁下了 alt 键！'); +}); +``` + +## 切换快捷键 + +如果在单页面在不同的区域，相同的快捷键，干不同的事儿，之间来回切换。O(∩_∩)O ！ + +```js +// 一个快捷键，有可能干的活儿不一样哦 +hotkeys('ctrl+o, ctrl+alt+enter', 'scope1', function(){ + console.log('你好看'); +}); + +hotkeys('ctrl+o, enter', 'scope2', function(){ + console.log('你好丑陋啊！'); +}); + +// 你摁 “ctrl+o”组合键 +// 当scope等于 scope1 ，执行 回调事件打印出 “你好看”， +// 当scope等于 scope2 ，执行 回调事件打印出 “你好丑陋啊！”， + +// 通过setScope设定范围scope +hotkeys.setScope('scope1'); // 默认所有事儿都干哦 +``` + +## 标记快捷键范围 + +**删除** 区域范围标记 + +```js +hotkeys.deleteScope('scope1'); +``` + +**获取** 区域范围标记 + +```js +hotkeys.getScope(); +``` + +**设置** 区域范围标记 + +```js +hotkeys.setScope('scope1'); +``` + +## 解除绑定 + +`hotkeys.unbind("ctrl+o, ctrl+alt+enter")` 解除绑定两组快捷键 +`hotkeys.unbind("ctrl+o","files")` 解除绑定名字叫files钟的一组快捷键 + +## 键判断 + +判断摁下的键是否为某个键 + +```js +hotkeys('a', function(){ + console.log(hotkeys.isPressed("a")); //=> true + console.log(hotkeys.isPressed("A")); //=> true + console.log(hotkeys.isPressed(65)); //=> true +}); +``` + +## 获取摁下键值 + +获取摁下绑定键的键值 `hotkeys.getPressedKeyCodes()` + +```js +hotkeys('command+ctrl+shift+a,f', function(){ + console.log(hotkeys.getPressedKeyCodes()); //=> [17, 65] 或者 [70] +}) +``` + +## 过滤 + +`INPUT` `SELECT` `TEXTAREA` 默认不处理。 +`hotkeys.filter` 返回 `true` 快捷键设置才会起作用，`false` 快捷键设置失效。 + +```javascript +hotkeys.filter = function(event){ + return true; +} +// 如何增加过滤可编辑标签
+// contentEditable老浏览器不支持滴 +hotkeys.filter = function(event) { + var tagName = (event.target || event.srcElement).tagName; + return !(tagName.isContentEditable || + tagName == 'INPUT' || + tagName == 'SELECT' || + tagName == 'TEXTAREA'); +} + +// +hotkeys.filter = function(event){ + var tagName = (event.target || event.srcElement).tagName; + hotkeys.setScope(/^(INPUT|TEXTAREA|SELECT)$/.test(tagName) ? 'input' : 'other'); + return true; +} +``` + +## 兼容模式 + +```js +var k = hotkeys.noConflict(); +k('a', function() { + console.log("这里可以干一些事儿") +}); + +hotkeys() +// -->Uncaught TypeError: hotkeys is not a function(anonymous function) +// @ VM2170:2InjectedScript._evaluateOn +// @ VM2165:883InjectedScript._evaluateAndWrap +// @ VM2165:816InjectedScript.evaluate @ VM2165:682 +``` diff --git a/README.md b/README.md index e99870f..81358c1 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,11 @@ -# 设置快捷键 +# Hotkeys -[![](https://img.shields.io/github/issues/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/issues) [![](https://img.shields.io/github/forks/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/network) [![](https://img.shields.io/github/stars/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/stargazers) [![](https://img.shields.io/github/release/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/releases) +[![](https://img.shields.io/github/issues/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/issues) [![](https://img.shields.io/github/forks/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/network) [![](https://img.shields.io/github/stars/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/stargazers) [![](https://img.shields.io/github/release/jaywcjlove/hotkeys.svg)](https://github.com/jaywcjlove/hotkeys/releases) ![](http://jaywcjlove.github.io/sb/status/no-dependencies.svg) [![jaywcjlove/sb](https://jaywcjlove.github.io/sb/lang/chinese.svg)](./README-zh.md) -这是一个强健的 Javascript 库用于捕获键盘输入和输入的组合键，它没有依赖，压缩只有只有(~3kb)，gzip:1.9k。`hotkey` 可以算是临摹参考[madrobby/keymaster](https://github.com/madrobby/keymaster)的作品，重写了一遍，修复多个兼容问题，键支持，添加UMD支持和 **测试用例**，[官方文档DEMO预览](http://jaywcjlove.github.io/hotkeys/?lang=cn) [En](http://jaywcjlove.github.io/hotkeys/?lang=en) +HotKeys.js is an input capture library with some very special features, it is easy to pick up and use, has a reasonable footprint (~3kb) (gzipped: 1.73kb), and has no dependencies. It should not interfere with any JavaScript libraries or frameworks. Official document [demo preview](http://jaywcjlove.github.io/hotkeys). -[![jaywcjlove/sb](https://jaywcjlove.github.io/sb/lang/chinese.svg)](http://jaywcjlove.github.io/hotkeys/?lang=cn) [![jaywcjlove/sb](https://jaywcjlove.github.io/sb/lang/english.svg)](http://jaywcjlove.github.io/hotkeys/?lang=en) -```text +```bash __ __ __ | |--..-----.| |_ | |--..-----..--.--..-----. | || _ || _|| < | -__|| | ||__ --| @@ -14,32 +13,35 @@ |_____| ``` -## 创建 +## Usage -您将需要在您的系统上安装的 Node.js。 +You will need `Node.js` installed on your system. -```sh -# bower 安装 -$ bower install hotkeysjs +```shell +$ npm install hotkeys-js --save +``` + +```js +import hotkeys from 'hotkeys-js'; +``` -# npm 安装 -$ npm install hotkeys-js +Or manually download and link **hotkeys.js** in your HTML: -$ npm run build # 编译 -$ npm run watch # 开发模式 +```html + ``` -## React中使用 +### Used in React -[react-hotkeys](https://github.com/jaywcjlove/react-hotkeys)，安装如下： +[react-hotkeys](https://github.com/jaywcjlove/react-hotkeys) is the React component that listen to keydown and keyup keyboard events, defining and dispatching keyboard shortcuts. -```sh -npm i -S react-hot-keys +```shell +$ npm install react-hot-keys --save ``` -例子 +Detailed use method please see its documentation [react-hotkeys](https://github.com/jaywcjlove/react-hotkeys). -```js +```jsx import React, { Component } from 'react'; import Hotkeys from 'react-hot-keys'; @@ -50,179 +52,135 @@ export default class HotkeysDemo extends Component { output: 'Hello, I am a component that listens to keydown and keyup of a', } } - onKeyUp(keyName, e, handle) { - console.log("test:onKeyUp", e, handle) - this.setState({ - output: `onKeyUp ${keyName}`, - }); + onKeyUp(keyNm, e, handle) { + this.setState({output: keyNm}) } onKeyDown(keyName, e, handle) { - console.log("test:onKeyDown", keyName, e, handle) - this.setState({ - output: `onKeyDown ${keyName}`, - }); + this.setState({output: keyNm}) } render() { return ( -
- {this.state.output} -
+
{this.state.output}
) } } ``` -## 使用 +## Browser Support -传统调用 +Mousetrap has been tested and should work in. -```html - -``` - -包加载 - -```js -import hotkeys from 'hotkeys-js'; - -hotkeys('shift+a,alt+d, w', function(e){ - console.log('干点活儿',e); - if(hotkeys.shift) console.log('大哥你摁下了 shift 键！'); - if(hotkeys.ctrl) console.log('大哥你摁下了 ctrl 键！'); - if(hotkeys.alt) console.log('大哥你摁下了 alt 键！'); -}); +```shell +Internet Explorer 6+ +Safari +Firefox +Chrome ``` +## Defining Shortcuts -## 定义快捷键 +One global method is exposed, key which defines shortcuts when called directly. ```js -// 定义 F5 快捷键 -hotkeys('f5', function(event,handler){ - //event.srcElement: input - //event.target: input - // 阻止Widnows系统下的默认刷新事件 +hotkeys('f5', function(event, handler){ + // Prevent the default refresh event under WIDNOWS system event.preventDefault() - alert('你按下了 F5 键!') + alert('you pressed F5!') }); -// 定义a快捷键 + hotkeys('a', function(event,handler){ //event.srcElement: input //event.target: input if(event.target === "input"){ - alert('你在输入框中按下了 a!') + alert('you pressed a!') } - alert('你按下了 a!') + alert('you pressed a!') }); -// 定义a快捷键 hotkeys('ctrl+a,ctrl+b,r,f', function(event,handler){ switch(handler.key){ - case "ctrl+a":alert('你按下了ctrl+a!');break; - case "ctrl+b":alert('你按下了ctrl+b!');break; - case "r":alert('你按下了r!');break; - case "f":alert('你按下了f!');break; + case "ctrl+a":alert('you pressed ctrl+a!');break; + case "ctrl+b":alert('you pressed ctrl+b!');break; + case "r":alert('you pressed r!');break; + case "f":alert('you pressed f!');break; } - //handler.scope 范围 }); -// 返回false将停止活动，并阻止默认浏览器事件 -hotkeys('ctrl+r', function(){ alert('停止刷新!'); return false }); - -// 多个快捷方式做同样的事情 -hotkeys('⌘+r, ctrl+r', function(){ }); - -// 对所有摁键执行任务 hotkeys('*','wcj', function(e){ - console.log('干点活儿',e); - console.log("key.getScope()::",hotkeys.getScope()); - if(hotkeys.shift) console.log('大哥你摁下了 shift 键！'); - if(hotkeys.ctrl) console.log('大哥你摁下了 ctrl 键！'); - if(hotkeys.alt) console.log('大哥你摁下了 alt 键！'); + console.log('do something',e); }); ``` -## 支持的键 - -`⇧`, `shift`, `option`, `⌥`, `alt`, `ctrl`, `control`, `command`, `⌘` +## API REFERENCE -`⌘` Command() -`⌃` Control -`⌥` Option(alt) -`⇧` Shift -`⇪` Caps Lock(大写) -~~`fn` 功能键就是fn(不支持)~~ -`↩︎` return/enter -`space` 空格键 +Asterisk "*" -## 修饰键判断 -可以对下面的修饰键判断 `shift` `alt` `option` `ctrl` `control` `command`，特别注意`+`和`=`键值相同，组合键设置`⌘+=` +Modifier key judgments ```js -hotkeys('shift+a,alt+d, w', function(e){ - console.log('干点活儿',e); - if(hotkeys.shift) console.log('大哥你摁下了 shift 键！'); - if(hotkeys.ctrl) console.log('大哥你摁下了 ctrl 键！'); - if(hotkeys.alt) console.log('大哥你摁下了 alt 键！'); +hotkeys('*','wcj', function(e){ + if(hotkeys.shift) console.log('shift is pressed！'); + if(hotkeys.ctrl) console.log('shift is pressed! '); + if(hotkeys.alt) console.log('shift is pressed! '); }); ``` -## 切换快捷键 +### setScope -如果在单页面在不同的区域，相同的快捷键，干不同的事儿，之间来回切换。O(∩_∩)O ！ +Use the `hotkeys.setScope` method to set scope. ```js -// 一个快捷键，有可能干的活儿不一样哦 -hotkeys('ctrl+o, ctrl+alt+enter', 'scope1', function(){ - console.log('你好看'); +// define shortcuts with a scope +hotkeys('ctrl+o, ctrl+alt+enter', 'issues', function(){ + console.log('do something'); }); - -hotkeys('ctrl+o, enter', 'scope2', function(){ - console.log('你好丑陋啊！'); +hotkeys('o, enter', 'files', function(){ + console.log('do something else'); }); -// 你摁 “ctrl+o”组合键 -// 当scope等于 scope1 ，执行 回调事件打印出 “你好看”， -// 当scope等于 scope2 ，执行 回调事件打印出 “你好丑陋啊！”， - -// 通过setScope设定范围scope -hotkeys.setScope('scope1'); // 默认所有事儿都干哦 +// set the scope (only 'all' and 'issues' shortcuts will be honored) +hotkeys.setScope('issues'); // default scope is 'all' ``` -## 标记快捷键范围 +### getScope -**删除** 区域范围标记 +Use the `hotkeys.getScope` method to get scope. ```js -hotkeys.deleteScope('scope1'); +hotkeys.getScope(); ``` -**获取** 区域范围标记 +### deleteScope + +Use the `hotkeys.deleteScope` method to delete set scope. ```js -hotkeys.getScope(); +hotkeys.deleteScope('issues'); ``` -**设置** 区域范围标记 +### unbind -```js -hotkeys.setScope('scope1'); -``` +Similar to defining shortcuts, they can be unbound using `hotkeys.unbind`. -## 解除绑定 +```js +// unbind 'a' handler +hotkeys.unbind('a'); -`hotkeys.unbind("ctrl+o, ctrl+alt+enter")` 解除绑定两组快捷键 -`hotkeys.unbind("ctrl+o","files")` 解除绑定名字叫files钟的一组快捷键 +// unbind a hotkeys only for a single scope +// when no scope is specified it defaults to the current scope (hotkeys.getScope()) +hotkeys.unbind('o, enter', 'issues'); +hotkeys.unbind('o, enter', 'files'); +``` -## 键判断 +### isPressed -判断摁下的键是否为某个键 +Other key queries. For example, `hotkeys.isPressed(77)` is true if the `M` key is currently pressed. ```js hotkeys('a', function(){ @@ -232,36 +190,32 @@ hotkeys('a', function(){ }); ``` -## 获取摁下键值 +### getPressedKeyCodes -获取摁下绑定键的键值 `hotkeys.getPressedKeyCodes()` +returns an array of key codes currently pressed. ```js hotkeys('command+ctrl+shift+a,f', function(){ - console.log(hotkeys.getPressedKeyCodes()); //=> [17, 65] 或者 [70] + console.log(hotkeys.getPressedKeyCodes()); //=> [17, 65] or [70] }) ``` -## 过滤 +### filter -`INPUT` `SELECT` `TEXTAREA` 默认不处理。 -`hotkeys.filter` 返回 `true` 快捷键设置才会起作用，`false` 快捷键设置失效。 +`INPUT` `SELECT` `TEXTAREA` default does not handle. +`Hotkeys.filter` to return to the `true` shortcut keys set to play a role, `flase` shortcut keys set up failure. -```javascript +```js hotkeys.filter = function(event){ return true; } -// 如何增加过滤可编辑标签
-// contentEditable老浏览器不支持滴 +//How to add the filter to edit labels.
+//"contentEditable" Older browsers that do not support drops hotkeys.filter = function(event) { var tagName = (event.target || event.srcElement).tagName; - return !(tagName.isContentEditable || - tagName == 'INPUT' || - tagName == 'SELECT' || - tagName == 'TEXTAREA'); + return !(tagName.isContentEditable || tagName == 'INPUT' || tagName == 'SELECT' || tagName == 'TEXTAREA'); } -// hotkeys.filter = function(event){ var tagName = (event.target || event.srcElement).tagName; hotkeys.setScope(/^(INPUT|TEXTAREA|SELECT)$/.test(tagName) ? 'input' : 'other'); @@ -269,17 +223,67 @@ hotkeys.filter = function(event){ } ``` -## 兼容模式 +### noConflict + +Relinquish HotKeys’s control of the `hotkeys` variable. ```js var k = hotkeys.noConflict(); k('a', function() { - console.log("这里可以干一些事儿") + console.log("do something") }); hotkeys() -// -->Uncaught TypeError: hotkeys is not a function(anonymous function) -// @ VM2170:2InjectedScript._evaluateOn -// @ VM2165:883InjectedScript._evaluateAndWrap +// -->Uncaught TypeError: hotkeys is not a function(anonymous function) +// @ VM2170:2InjectedScript._evaluateOn +// @ VM2165:883InjectedScript._evaluateAndWrap // @ VM2165:816InjectedScript.evaluate @ VM2165:682 ``` + +## Supported Keys + +HotKeys understands the following modifiers: `⇧`, `shift`, `option`, `⌥`, `alt`, `ctrl`, `control`, `command`, and `⌘`. + +The following special keys can be used for shortcuts: backspace, tab, clear, enter, return, esc, escape, space, up, down, left, right, home, end, pageup, pagedown, del, delete and f1 through f19. + +`⌘` Command() +`⌃` Control +`⌥` Option(alt) +`⇧` Shift +`⇪` Caps Lock(Capital) +~~`fn` Does not support fn~~ +`↩︎` return/Enter space + +## Development + +To develop, run the self-reloading build, Get the code: + +```shell +$ git https://github.com/jaywcjlove/hotkeys.git +$ cd hotkeys # Into the directory +$ npm install # or yarn install +``` + +To develop, run the self-reloading build: + +```shell +$ npm run watch +``` + +Run Document Website Environment. + +```shell +$ npm run doc:dev +``` + +To contribute, please fork Hotkeys.js, add your patch and tests for it (in the `test/` folder) and submit a pull request. + +```shell +$ npm run test +$ npm run test:watch # Development model +``` + + +## License + +[MIT © Kenny Wong](./LICENSE)