294 lines
8.7 KiB
Markdown
294 lines
8.7 KiB
Markdown
# event-target-shim
|
|
|
|
[](https://www.npmjs.com/package/event-target-shim)
|
|
[](http://www.npmtrends.com/event-target-shim)
|
|
[](https://travis-ci.org/mysticatea/event-target-shim)
|
|
[](https://codecov.io/gh/mysticatea/event-target-shim)
|
|
[](https://david-dm.org/mysticatea/event-target-shim)
|
|
|
|
An implementation of [WHATWG EventTarget interface](https://dom.spec.whatwg.org/#interface-eventtarget), plus few extensions.
|
|
|
|
- This provides `EventTarget` constructor that can inherit for your custom object.
|
|
- This provides an utility that defines properties of attribute listeners (e.g. `obj.onclick`).
|
|
|
|
```js
|
|
import {EventTarget, defineEventAttribute} from "event-target-shim"
|
|
|
|
class Foo extends EventTarget {
|
|
// ...
|
|
}
|
|
|
|
// Define `foo.onhello` property.
|
|
defineEventAttribute(Foo.prototype, "hello")
|
|
|
|
// Use
|
|
const foo = new Foo()
|
|
foo.addEventListener("hello", e => console.log("hello", e))
|
|
foo.onhello = e => console.log("onhello:", e)
|
|
foo.dispatchEvent(new CustomEvent("hello"))
|
|
```
|
|
|
|
## 💿 Installation
|
|
|
|
Use [npm](https://www.npmjs.com/) to install then use a bundler.
|
|
|
|
```
|
|
npm install event-target-shim
|
|
```
|
|
|
|
Or download from [`dist` directory](./dist).
|
|
|
|
- [dist/event-target-shim.mjs](dist/event-target-shim.mjs) ... ES modules version.
|
|
- [dist/event-target-shim.js](dist/event-target-shim.js) ... Common JS version.
|
|
- [dist/event-target-shim.umd.js](dist/event-target-shim.umd.js) ... UMD (Universal Module Definition) version. This is transpiled by [Babel](https://babeljs.io/) for IE 11.
|
|
|
|
## 📖 Usage
|
|
|
|
```js
|
|
import {EventTarget, defineEventAttribute} from "event-target-shim"
|
|
// or
|
|
const {EventTarget, defineEventAttribute} = require("event-target-shim")
|
|
|
|
// or UMD version defines a global variable:
|
|
const {EventTarget, defineEventAttribute} = window.EventTargetShim
|
|
```
|
|
|
|
### EventTarget
|
|
|
|
> https://dom.spec.whatwg.org/#interface-eventtarget
|
|
|
|
#### eventTarget.addEventListener(type, callback, options)
|
|
|
|
Register an event listener.
|
|
|
|
- `type` is a string. This is the event name to register.
|
|
- `callback` is a function. This is the event listener to register.
|
|
- `options` is a boolean or an object `{ capture?: boolean, passive?: boolean, once?: boolean }`. If this is a boolean, it's same meaning as `{ capture: options }`.
|
|
- `capture` is the flag to register the event listener for capture phase.
|
|
- `passive` is the flag to ignore `event.preventDefault()` method in the event listener.
|
|
- `once` is the flag to remove the event listener automatically after the first call.
|
|
|
|
#### eventTarget.removeEventListener(type, callback, options)
|
|
|
|
Unregister an event listener.
|
|
|
|
- `type` is a string. This is the event name to unregister.
|
|
- `callback` is a function. This is the event listener to unregister.
|
|
- `options` is a boolean or an object `{ capture?: boolean }`. If this is a boolean, it's same meaning as `{ capture: options }`.
|
|
- `capture` is the flag to register the event listener for capture phase.
|
|
|
|
#### eventTarget.dispatchEvent(event)
|
|
|
|
Dispatch an event.
|
|
|
|
- `event` is a [Event](https://dom.spec.whatwg.org/#event) object or an object `{ type: string, [key: string]: any }`. The latter is non-standard but useful. In both cases, listeners receive the event as implementing [Event](https://dom.spec.whatwg.org/#event) interface.
|
|
|
|
### defineEventAttribute(proto, type)
|
|
|
|
Define an event attribute (e.g. `onclick`) to `proto`. This is non-standard.
|
|
|
|
- `proto` is an object (assuming it's a prototype object). This function defines a getter/setter pair for the event attribute.
|
|
- `type` is a string. This is the event name to define.
|
|
|
|
For example:
|
|
|
|
```js
|
|
class AbortSignal extends EventTarget {
|
|
constructor() {
|
|
this.aborted = false
|
|
}
|
|
}
|
|
// Define `onabort` property.
|
|
defineEventAttribute(AbortSignal.prototype, "abort")
|
|
```
|
|
|
|
### EventTarget(types)
|
|
|
|
Define a custom `EventTarget` class with event attributes. This is non-standard.
|
|
|
|
- `types` is a string or an array of strings. This is the event name to define.
|
|
|
|
For example:
|
|
|
|
```js
|
|
// This has `onabort` property.
|
|
class AbortSignal extends EventTarget("abort") {
|
|
constructor() {
|
|
this.aborted = false
|
|
}
|
|
}
|
|
```
|
|
|
|
## 📚 Examples
|
|
|
|
### ES2015 and later
|
|
|
|
> https://jsfiddle.net/636vea92/
|
|
|
|
```js
|
|
const {EventTarget, defineEventAttribute} = EventTargetShim
|
|
|
|
// Define a derived class.
|
|
class Foo extends EventTarget {
|
|
// ...
|
|
}
|
|
|
|
// Define `foo.onhello` property.
|
|
defineEventAttribute(Foo.prototype, "hello")
|
|
|
|
// Register event listeners.
|
|
const foo = new Foo()
|
|
foo.addEventListener("hello", (e) => {
|
|
console.log("hello", e)
|
|
})
|
|
foo.onhello = (e) => {
|
|
console.log("onhello", e)
|
|
}
|
|
|
|
// Dispatching events
|
|
foo.dispatchEvent(new CustomEvent("hello", { detail: "detail" }))
|
|
```
|
|
|
|
### Typescript
|
|
|
|
```ts
|
|
import { EventTarget, defineEventAttribute } from "event-target-shim";
|
|
|
|
// Define events
|
|
type FooEvents = {
|
|
hello: CustomEvent
|
|
}
|
|
type FooEventAttributes = {
|
|
onhello: CustomEvent
|
|
}
|
|
|
|
// Define a derived class.
|
|
class Foo extends EventTarget<FooEvents, FooEventAttributes> {
|
|
// ...
|
|
}
|
|
// Define `foo.onhello` property's implementation.
|
|
defineEventAttribute(Foo.prototype, "hello")
|
|
|
|
// Register event listeners.
|
|
const foo = new Foo()
|
|
foo.addEventListener("hello", (e) => {
|
|
console.log("hello", e.detail)
|
|
})
|
|
foo.onhello = (e) => {
|
|
console.log("onhello", e.detail)
|
|
}
|
|
|
|
// Dispatching events
|
|
foo.dispatchEvent(new CustomEvent("hello", { detail: "detail" }))
|
|
```
|
|
|
|
Unfortunately, both `FooEvents` and `FooEventAttributes` are needed because TypeScript doesn't allow the mutation of string literal types. If TypeScript allowed us to compute `"onhello"` from `"hello"` in types, `FooEventAttributes` will be optional.
|
|
|
|
This `EventTarget` type is compatible with `EventTarget` interface of `lib.dom.d.ts`.
|
|
|
|
#### To disallow unknown events
|
|
|
|
By default, methods such as `addEventListener` accept unknown events. You can disallow unknown events by the third type parameter `"strict"`.
|
|
|
|
```ts
|
|
type FooEvents = {
|
|
hello: CustomEvent
|
|
}
|
|
class Foo extends EventTarget<FooEvents, {}, "strict"> {
|
|
// ...
|
|
}
|
|
|
|
// OK because `hello` is defined in FooEvents.
|
|
foo.addEventListener("hello", (e) => {
|
|
})
|
|
// Error because `unknown` is not defined in FooEvents.
|
|
foo.addEventListener("unknown", (e) => {
|
|
})
|
|
```
|
|
|
|
However, if you use `"strict"` parameter, it loses compatibility with `EventTarget` interface of `lib.dom.d.ts`.
|
|
|
|
#### To infer the type of `dispatchEvent()` method
|
|
|
|
TypeScript cannot infer the event type of `dispatchEvent()` method properly from the argument in most cases. You can improve this behavior with the following steps:
|
|
|
|
1. Use the third type parameter `"strict"`. This prevents inferring to `dispatchEvent<string>()`.
|
|
2. Make the `type` property of event definitions stricter.
|
|
|
|
```ts
|
|
type FooEvents = {
|
|
hello: CustomEvent & { type: "hello" }
|
|
hey: Event & { type: "hey" }
|
|
}
|
|
class Foo extends EventTarget<FooEvents, {}, "strict"> {
|
|
// ...
|
|
}
|
|
|
|
// Error because `detail` property is lacking.
|
|
foo.dispatchEvent({ type: "hello" })
|
|
```
|
|
|
|
### ES5
|
|
|
|
> https://jsfiddle.net/522zc9de/
|
|
|
|
```js
|
|
// Define a derived class.
|
|
function Foo() {
|
|
EventTarget.call(this)
|
|
}
|
|
Foo.prototype = Object.create(EventTarget.prototype, {
|
|
constructor: { value: Foo, configurable: true, writable: true }
|
|
// ...
|
|
})
|
|
|
|
// Define `foo.onhello` property.
|
|
defineEventAttribute(Foo.prototype, "hello")
|
|
|
|
// Register event listeners.
|
|
var foo = new Foo()
|
|
foo.addEventListener("hello", function(e) {
|
|
console.log("hello", e)
|
|
})
|
|
foo.onhello = function(e) {
|
|
console.log("onhello", e)
|
|
}
|
|
|
|
// Dispatching events
|
|
function isSupportEventConstrucor() { // IE does not support.
|
|
try {
|
|
new CusomEvent("hello")
|
|
return true
|
|
} catch (_err) {
|
|
return false
|
|
}
|
|
}
|
|
if (isSupportEventConstrucor()) {
|
|
foo.dispatchEvent(new CustomEvent("hello", { detail: "detail" }))
|
|
} else {
|
|
var e = document.createEvent("CustomEvent")
|
|
e.initCustomEvent("hello", false, false, "detail")
|
|
foo.dispatchEvent(e)
|
|
}
|
|
```
|
|
|
|
## 📰 Changelog
|
|
|
|
- See [GitHub releases](https://github.com/mysticatea/event-target-shim/releases).
|
|
|
|
## 🍻 Contributing
|
|
|
|
Contributing is welcome ❤️
|
|
|
|
Please use GitHub issues/PRs.
|
|
|
|
### Development tools
|
|
|
|
- `npm install` installs dependencies for development.
|
|
- `npm test` runs tests and measures code coverage.
|
|
- `npm run clean` removes temporary files of tests.
|
|
- `npm run coverage` opens code coverage of the previous test with your default browser.
|
|
- `npm run lint` runs ESLint.
|
|
- `npm run build` generates `dist` codes.
|
|
- `npm run watch` runs tests on each file change.
|