subscribe-ui-event
Version:
A single, throttle built-in solution to subscribe to browser UI Events.
139 lines (97 loc) • 5.34 kB
Markdown
# subscribe-ui-event
[](http://badge.fury.io/js/subscribe-ui-event)
With `subscribe-ui-event`, instead of calling multiple `window.addEventListener('scroll', eventHandler);` by different components, call `subscribe('scroll', eventHandler)`. It will only add a single event listener and dispatch event to those who subscribe to the event via [eventemitter3](https://github.com/primus/EventEmitter3).
## Install
```bash
npm install subscribe-ui-event
```
## Single Event Listener v.s. Multiple Event Listeners
Why a single event? More performant and less memory consumption.
The [jsperf ](http://jsperf.com/subscribe-v-s-addeventlistener/2) runs 10 `addEventListener` and 10 non-throttling `subscribe`, and the outcome is that the ops/sec of `subscribe` is slightly less. But in regular case, you will use throttling `subscribe`, and it will be more performant.
For 10 `addEventListener`, the difference of memory consumption between peak and trough is about 4.1K.
For 10 `subscribe`, the difference of memory consumption between peak and trough is about 1.0K.
## Other Benefits
1. Throttling by default.
2. Access `document.body.scrollTop`, `window.innerWidth` once.
3. Provide `requestAnimationFrame` throttle for high performance.
4. Be able to use events like `scrollStart` (see below) those edge events.
## API
### subscribe
```ts
subscribe(eventType: String, callback: Function, options: Object?): Subscription
```
Provide throttled version of `window` or `document` events, such like `scroll`, `resize`, `touch` and `visibilitychange` to subscribe, see below.
**Note on IE8 or the below, the throttle will be turned off because the event object is global and will be deleted for setTimeout or rAF.**
Example:
```ts
import { subscribe } from 'subscribe-ui-event';
function eventHandler (e, payload) {
// e is the native event object and
// payload is the additional information
...
}
// 50ms throttle by default
const subscription = subscribe('scroll', eventHandler);
// remove later
subscription.unsubscribe();
```
#### Optional Payload
The format of the payload is:
```js
{
type: <String>, // could be 'scroll', 'resize' ...
// you need to pass options.enableScrollInfo = true to subscribe to get the following data
scroll: {
top: <Number>, // The scroll position, i.g., document.body.scrollTop
delta: <Number> // The delta of scroll position, it is helpful for scroll direction
},
// you need to pass options.enableResizeInfo = true to subscribe to get the following data
resize: {
width: <Number>, // The client width
height: <Number> // The client height
},
// you need to pass options.enableTouchInfo = true to subscribe to get the following data
touch: {
axisIntention: <String>, // 'x', 'y', or ''.
startX: <Number>,
startY: <Number>,
deltaX: <Number>,
deltaY: <Number>
}
}
```
#### Options
`options.throttleRate` allows of changing the throttle rate, and the default value is 50 (ms). Set 0 for no throttle. **On IE8, there will be no throttle, because throttling will use setTimeout or rAF to achieve, and the event object passed into event handler will be overwritten.**
`options.context` allows of setting the caller of callback function.
`options.useRAF = true` allows of using `requestAnimationFrame` instead of `setTimeout`.
`options.enableScrollInfo = true` allows of getting `scrollTop`.
`options.enableResizeInfo = true` allows of getting `width` and `height` of client.
`options.enableTouchInfo = true` allows of getting touch information (see above).
`eventType` could be one of the following:
1. scroll - window.scoll
2. scrollStart - The start of window.scoll
3. scrollEnd - The end of window.scoll
4. resize - window.resize
5. resizeStart - The start window.resize
6. resizeEnd - The end window.resize
7. visibilitychange - document.visibilitychange (IE8 doesn't support)
8. touchmoveStart - The start of window.touchmove
9. touchmoveEnd - The end of window.touchmove
10. touchmove - window.touchmove
11. touchstart - window.touchstart
12. touchend - window.touchend
`options.eventOptions`: An options object that specifies characteristics about the event listener (if passive event is supported by the browser)
### unsubscribe
```js
unsubscribe(eventType: String, callback: Function): Void
```
Unsubscribe to an event listener, we suggest you use `subscription.unsubscribe()`, because it may accidentally unsubscribe those events having the same `eventType` and `callback`, but different `throttleRate`.
## Credits
- This library runs full browser test suite using Sauce Labs.
## License
This software is free to use under the BSD license.
See the [LICENSE file](./LICENSE.md) for license text and copyright information.