D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
home
/
etb1lp46s9ed
/
wcloud.whatzi.online
/
node_modules
/
event-target-shim
/
Filename :
README.md
back
Copy
# 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.