EventTarget: when() method
MDN Web Docs · نسخهٔ df622a2a1c1e · CC BY-SA 2.5 و مجوز جداگانهٔ ناشر برای نمونهکد
{{APIRef("DOM")}}{{SeeCompatTable}}
The **when()** method of the {{domxref("EventTarget")}} interface returns an {{domxref("Observable")}} object representing a stream of events fired on the event target it is called on.
You can call {{domxref("Observable.subscribe", "subscribe()")}} on the resulting observable to subscribe to the event stream.
The returned observable uses an event listener in the background, the same as listeners created by {{domxref("EventTarget.addEventListener()")}}. This listener's creation, sharing among observers, and removal follow the same lifecycle as the {{domxref("Subscriber")}} object for a custom observable.
توجه: This shared-subscription behavior may change. A [proposal to give each observer its own Subscriber](https://github.com/WICG/observable/issues/217) would make each subscription start a separate execution instead of reusing an active subscription.
Syntax
when(type)
when(type, options)Parameters
type- : A case-sensitive string representing the event type to listen for.
options{{optional_inline}}- : An object that specifies characteristics about the event listener. The available options are:
capture{{optional_inline}}- : A boolean value indicating that events of the specified type will be dispatched to the listener registered in the background before being dispatched to any
EventTargetbeneath it in the DOM tree. If not specified, defaults tofalse. passive{{optional_inline}}- : A boolean value that, if
true, indicates that callbacks processing the events will never call {{domxref("Event.preventDefault", "preventDefault()")}}. If a passive listener callspreventDefault(), nothing will happen and a console warning may be generated.
If this option is not specified, it defaults to the same value as for addEventListener(). See Using passive listeners to learn more.
Return value
An {{domxref("Observable")}}.
Examples
Using when()
This example is a simple click counter app.
HTML
The markup contains a {{htmlelement("button")}} element to click, and a {{htmlelement("p")}} element to display the number of clicks.
<button>Click me</button>
<p>Click count: 0</p>JavaScript
We call when("click") on the btn, which obtains an observable for the click event stream. We then chain a subscribe() call onto the observable to subscribe the increment() function to the observable, so it is called each time the button is clicked.
const btn = document.querySelector("button");
const para = document.querySelector("p");
let countValue = 0;
function increment() {
countValue++;
para.textContent = `Click count: ${countValue}`;
}
btn.when("click").subscribe(increment);توجه: For this particular example, .when("click").subscribe(increment) and .addEventListener("click", increment) are almost exactly equivalent. However, using when() allows you to compose event streams using observables. The Using observables guide has more examples.
Result
The rendered result is as follows:
{{EmbedLiveSample("basic-when", "", 80)}}
Try clicking the button to see the click count increment.
Specifications
{{Specifications}}
Browser compatibility
{{Compat}}
See also
- Using observables
- {{domxref("EventTarget.addEventListener()")}}
- Observable explainer