Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/shentao/vue-global-events
⌨️ Register global events as a component
https://github.com/shentao/vue-global-events
events javascript vue
Last synced: 14 days ago
JSON representation
⌨️ Register global events as a component
- Host: GitHub
- URL: https://github.com/shentao/vue-global-events
- Owner: shentao
- License: mit
- Created: 2017-11-29T22:15:22.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2024-01-04T09:17:55.000Z (10 months ago)
- Last Synced: 2024-05-29T03:13:29.434Z (6 months ago)
- Topics: events, javascript, vue
- Language: TypeScript
- Homepage:
- Size: 1.62 MB
- Stars: 689
- Watchers: 11
- Forks: 32
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/funding.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# vue-global-events [](https://circleci.com/gh/shentao/vue-global-events) [](https://www.npmjs.com/package/vue-global-events)
> Add shortcuts by listening to events on the document, anywhere
This is the version for Vue 3, if you are looking for the Vue 2 version, [take a look at the `v1` branch](https://github.com/shentao/vue-global-events/tree/v1)
## Sponsors
### Bronze
## Installation
```bash
yarn add vue-global-events
npm install vue-global-events
```
## [Demo](https://jsfiddle.net/posva/o4hj375r/)
## Idea
Thanks to Vue’s event modifiers, handling events is extremely easy however, you’re limited to DOM element events.
We decided to change that, so now you can register global events (for example application shortcuts) just like you would listen to events on a component. No need to worry about removing them either. You can toggle the events with a single `v-if`. Works with SSR too.
## Usage
```js
import { GlobalEvents } from 'vue-global-events'
// register globally
app.component('GlobalEvents', GlobalEvents)
// or locally
export default {
components: { GlobalEvents },
// rest of your component
}
```
After that you can register global events like this:
```html
```
### Props
#### `target`
Target element where `addEventListener` is called on. It's a String that refers to a global variable like `document` or `window`. This allows you to add events to the `window` instead of `document`.
- type: `String`
- default: `'document'`
_Warning_: This prop is not reactive. It should be provided as a static value. If you need it to be reactive, add a `key` attribute with the same value:
```html
```
#### `filter`
Function to prevent any event from being executed based on anything related to the event like the element that triggered it, the name, or the handler.
- type: `Function`
- default: `() => true`
##### arguments
- `event`: Native Event Object
- `handler`: method passed to `GlobalEvents` component
- `eventName`: event name that was attached to the _target_ (See above)
`filter` should return `false` to prevent the execution of a handler. For example, you can avoid the calls if the event is triggered by an ``:
```html
```
In the example above `event` would be the native `keyup` [Event Object](https://developer.mozilla.org/en-US/docs/Web/API/Event), `handler` would be the method `nextTab` and `eventName` would be the string `keyup`.
## Advice / Caveats
- Always `.prevent` events with `.ctrl` and other modifiers as browsers may be using them as shortcuts.
- Do not use shortcuts that are used by the system or that the browser **does not allow you to `.preventDefault()`**. The list includes `Ctrl+Tab`/`Cmd+Tab`, `Ctrl+W`/`Cmd+W`. You can find more information [in this StackOverflow answer](https://stackoverflow.com/a/40434403/3384501).
- Prefer using actual characters to keyCodes whenever possible: `@keydown.+` for detecting the plus sign. This is important because symbols and numbers on the digit row will provide different keyCodes depending on the layout used.
- About using `keyup` with modifiers like `.ctrl` or `.shift`: the keyup event is triggered when a key is released and that's also when the `event.ctrlKey` is checked, which if you just released, will be false. This is because `ctrl`, `shift` and `alt` are checked differently. If you want to trigger on the `keyup` event of a modifier, you need to use its keycode ([check it here](http://keycode.info). For example, for the `ctrl` key, that would be: `@keyup.17`. You can also use the advice above this one to provide it a name like _ctrlkey_.
## Development
Run tests in watch mode:
```bash
yarn jest --watch
```
## Authors
Damian Dulisz [@shentao](https://github.com/shentao)
Eduardo San Martin Morote [@posva](https://github.com/posva)
## License
[MIT](http://opensource.org/licenses/MIT)