-
Notifications
You must be signed in to change notification settings - Fork 22.4k
/
index.md
468 lines (350 loc) · 15.4 KB
/
index.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
---
title: setTimeout() global function
short-title: setTimeout()
slug: Web/API/setTimeout
page-type: web-api-global-function
browser-compat: api.setTimeout
---
{{APIRef("HTML DOM")}}{{AvailableInWorkers}}
The global **`setTimeout()`** method sets a timer which executes a function or specified
piece of code once the timer expires.
## Syntax
```js-nolint
setTimeout(code)
setTimeout(code, delay)
setTimeout(functionRef)
setTimeout(functionRef, delay)
setTimeout(functionRef, delay, param1)
setTimeout(functionRef, delay, param1, param2)
setTimeout(functionRef, delay, param1, param2, /* …, */ paramN)
```
### Parameters
- `functionRef`
- : A {{jsxref("function")}} to be executed after the timer expires.
- `code`
- : An alternative syntax that allows you to include a string instead of a function,
which is compiled and executed when the timer expires. This syntax is **not
recommended** for the same reasons that make using
{{jsxref("Global_Objects/eval", "eval()")}} a security risk.
- `delay` {{optional_inline}}
- : The time, in milliseconds that the timer should wait before
the specified function or code is executed. If this parameter is omitted, a value of 0
is used, meaning execute "immediately", or more accurately, the next event cycle.
Note that in either case, the actual delay may be longer than intended; see [Reasons for delays longer than specified](#reasons_for_delays_longer_than_specified) below.
Also note that if the value isn't a number, implicit [type coercion](/en-US/docs/Glossary/Type_coercion) is silently done on the value to convert it to a number — which can lead to unexpected and surprising results; see [Non-number delay values are silently coerced into numbers](#non-number_delay_values_are_silently_coerced_into_numbers) for an example.
- `param1`, …, `paramN` {{optional_inline}}
- : Additional arguments which are passed through to the function specified by
`functionRef`.
### Return value
The returned `timeoutID` is a positive integer value which
identifies the timer created by the call to `setTimeout()`. This value can be
passed to {{domxref("clearTimeout","clearTimeout()")}} to
cancel the timeout.
It is guaranteed that a `timeoutID` value will never be reused by a subsequent call to
`setTimeout()` or `setInterval()` on the same object (a window or
a worker) while the timer is still active. However, different objects use separate pools of IDs.
## Description
Timeouts are cancelled using
{{domxref("clearTimeout()")}}.
To call a function repeatedly (e.g., every _N_ milliseconds), consider using
{{domxref("setInterval()")}}.
### Non-number delay values are silently coerced into numbers
If `setTimeout()` is called with [_delay_](#delay) value that's not a number, implicit [type coercion](/en-US/docs/Glossary/Type_coercion) is silently done on the value to convert it to a number. For example, the following code incorrectly uses the string `"1000"` for the _delay_ value, rather than the number `1000` – but it nevertheless works, because when the code runs, the string is coerced into the number `1000`, and so the code executes 1 second later.
```js example-bad
setTimeout(() => {
console.log("Delayed for 1 second.");
}, "1000");
```
But in many cases, the implicit type coercion can lead to unexpected and surprising results. For example, when the following code runs, the string `"1 second"` ultimately gets coerced into the number `0` — and so, the code executes immediately, with zero delay.
```js example-bad
setTimeout(() => {
console.log("Delayed for 1 second.");
}, "1 second");
```
Therefore, don't use strings for the _delay_ value but instead always use numbers:
```js example-good
setTimeout(() => {
console.log("Delayed for 1 second.");
}, 1000);
```
### Working with asynchronous functions
`setTimeout()` is an asynchronous function, meaning that the timer function will not pause execution of other functions in the functions stack.
In other words, you cannot use `setTimeout()` to create a "pause" before the next function in the function stack fires.
See the following example:
```js
setTimeout(() => {
console.log("this is the first message");
}, 5000);
setTimeout(() => {
console.log("this is the second message");
}, 3000);
setTimeout(() => {
console.log("this is the third message");
}, 1000);
// Output:
// this is the third message
// this is the second message
// this is the first message
```
Notice that the first function does not create a 5-second "pause" before calling the second function. Instead, the first function is called, but waits 5 seconds to
execute. While the first function is waiting to execute, the second function is called, and a 3-second wait is applied to the second function before it executes. Since neither
the first nor the second function's timers have completed, the third function is called and completes its execution first. Then the second follows. Then finally the first function
is executed after its timer finally completes.
To create a progression in which one function only fires after the completion of another function, see the documentation on [Promises](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
### The "this" problem
When you pass a method to `setTimeout()`, it will be invoked with a `this` value that may differ from your
expectation. The general issue is explained in detail in the [JavaScript reference](/en-US/docs/Web/JavaScript/Reference/Operators/this#callbacks).
Code executed by `setTimeout()` is called from an execution context separate
from the function from which `setTimeout` was called. The usual rules for
setting the `this` keyword for the called function apply, and if you have not
set `this` in the call or with `bind`, it will default to
the `window` (or `global`) object, even in [strict mode](/en-US/docs/Web/JavaScript/Reference/Strict_mode). It will not be the same as the
`this` value for the function that called `setTimeout`.
See the following example:
```js
const myArray = ["zero", "one", "two"];
myArray.myMethod = function (sProperty) {
console.log(arguments.length > 0 ? this[sProperty] : this);
};
myArray.myMethod(); // prints "zero,one,two"
myArray.myMethod(1); // prints "one"
```
The above works because when `myMethod` is called, its `this` is
set to `myArray` by the call, so within the function,
`this[sProperty]` is equivalent to `myArray[sProperty]`. However,
in the following:
```js
setTimeout(myArray.myMethod, 1.0 * 1000); // prints "[object Window]" after 1 second
setTimeout(myArray.myMethod, 1.5 * 1000, "1"); // prints "undefined" after 1.5 seconds
```
The `myArray.myMethod` function is passed to `setTimeout`, then
when it's called, its `this` is not set, so it defaults to the
`window` object.
There's also no option to pass a `thisArg` to
`setTimeout` as there is in Array methods such as {{jsxref("Array.forEach()", "forEach()")}} and {{jsxref("Array.reduce()", "reduce()")}}. As shown below,
using `call` to set `this` doesn't work either.
```js
setTimeout.call(myArray, myArray.myMethod, 2.0 * 1000); // error
setTimeout.call(myArray, myArray.myMethod, 2.5 * 1000, 2); // same error
```
#### Solutions
##### Use a wrapper function
A common way to solve the problem is to use a wrapper function that sets
`this` to the required value:
```js
setTimeout(function () {
myArray.myMethod();
}, 2.0 * 1000); // prints "zero,one,two" after 2 seconds
setTimeout(function () {
myArray.myMethod("1");
}, 2.5 * 1000); // prints "one" after 2.5 seconds
```
The wrapper function can be an arrow function:
```js
setTimeout(() => {
myArray.myMethod();
}, 2.0 * 1000); // prints "zero,one,two" after 2 seconds
setTimeout(() => {
myArray.myMethod("1");
}, 2.5 * 1000); // prints "one" after 2.5 seconds
```
##### Use bind()
Alternatively, you can use {{jsxref("Function.bind()", "bind()")}} to set the value of `this` for all calls to a given function:
```js
const myArray = ["zero", "one", "two"];
const myBoundMethod = function (sProperty) {
console.log(arguments.length > 0 ? this[sProperty] : this);
}.bind(myArray);
myBoundMethod(); // prints "zero,one,two" because 'this' is bound to myArray in the function
myBoundMethod(1); // prints "one"
setTimeout(myBoundMethod, 1.0 * 1000); // still prints "zero,one,two" after 1 second because of the binding
setTimeout(myBoundMethod, 1.5 * 1000, "1"); // prints "one" after 1.5 seconds
```
### Passing string literals
Passing a string instead of a function to `setTimeout()` has the same problems as using
[`eval()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval).
```js example-bad
// Don't do this
setTimeout("console.log('Hello World!');", 500);
```
```js example-good
// Do this instead
setTimeout(() => {
console.log("Hello World!");
}, 500);
```
A string passed to `setTimeout()` is evaluated in the global context, so local symbols in the context where `setTimeout()` was called will not be available when the string is evaluated as code.
### Reasons for delays longer than specified
There are a number of reasons why a timeout may take longer to fire than anticipated.
This section describes the most common reasons.
#### Nested timeouts
As specified in the [HTML standard](https://html.spec.whatwg.org/multipage/timers-and-user-prompts.html#timers),
browsers will enforce a minimum timeout of 4 milliseconds once a nested call to `setTimeout` has been scheduled 5 times.
This can be seen in the following example, in which we nest a call to `setTimeout` with a delay of `0` milliseconds,
and log the delay each time the handler is called. The first four times, the delay is approximately 0 milliseconds, and after that it is
approximately 4 milliseconds:
```html
<button id="run">Run</button>
<table>
<thead>
<tr>
<th>Previous</th>
<th>This</th>
<th>Actual delay</th>
</tr>
</thead>
<tbody id="log"></tbody>
</table>
```
```js
let last = 0;
let iterations = 10;
function timeout() {
// log the time of this call
logline(new Date().getMilliseconds());
// if we are not finished, schedule the next call
if (iterations-- > 0) {
setTimeout(timeout, 0);
}
}
function run() {
// clear the log
const log = document.querySelector("#log");
while (log.lastElementChild) {
log.removeChild(log.lastElementChild);
}
// initialize iteration count and the starting timestamp
iterations = 10;
last = new Date().getMilliseconds();
// start timer
setTimeout(timeout, 0);
}
function logline(now) {
// log the last timestamp, the new timestamp, and the difference
const tableBody = document.getElementById("log");
const logRow = tableBody.insertRow();
logRow.insertCell().textContent = last;
logRow.insertCell().textContent = now;
logRow.insertCell().textContent = now - last;
last = now;
}
document.querySelector("#run").addEventListener("click", run);
```
```css hidden
* {
font-family: monospace;
}
th,
td {
padding: 0 10px 0 10px;
text-align: center;
border: 1px solid;
}
table {
border-collapse: collapse;
margin-top: 10px;
}
```
{{EmbedLiveSample("Nested_timeouts", 100, 420)}}
#### Timeouts in inactive tabs
To reduce the load (and associated battery usage) from background tabs, browsers will enforce
a minimum timeout delay in inactive tabs. It may also be waived if a page is playing sound
using a Web Audio API {{domxref("AudioContext")}}.
The specifics of this are browser-dependent:
- Firefox Desktop and Chrome both have a minimum timeout of 1 second for inactive tabs.
- Firefox for Android has a minimum timeout of 15 minutes for inactive tabs and may unload them entirely.
- Firefox does not throttle inactive tabs if the tab contains an {{domxref("AudioContext")}}.
#### Throttling of tracking scripts
Firefox enforces additional throttling for scripts that it recognizes as tracking scripts.
When running in the foreground, the throttling minimum delay is still 4ms. In background tabs, however,
the throttling minimum delay is 10,000 ms, or 10 seconds, which comes into effect 30 seconds after a
document has first loaded.
See [Tracking Protection](https://wiki.mozilla.org/Security/Tracking_protection) for
more details.
#### Late timeouts
The timeout can also fire later than expected if the page (or the OS/browser) is busy with other tasks.
One important case to note is that the function or code snippet cannot be executed until
the thread that called `setTimeout()` has terminated. For example:
```js
function foo() {
console.log("foo has been called");
}
setTimeout(foo, 0);
console.log("After setTimeout");
```
Will write to the console:
```plain
After setTimeout
foo has been called
```
This is because even though `setTimeout` was called with a delay of zero,
it's placed on a queue and scheduled to run at the next opportunity; not immediately.
Currently-executing code must complete before functions on the queue are executed, thus
the resulting execution order may not be as expected.
#### Deferral of timeouts during pageload
Firefox will defer firing `setTimeout()` timers
while the current tab is loading. Firing is deferred until the main thread is deemed
idle (similar to [window.requestIdleCallback()](/en-US/docs/Web/API/Window/requestIdleCallback)),
or until the load event is fired.
### WebExtension background pages and timers
In [WebExtensions](/en-US/docs/Mozilla/Add-ons/WebExtensions), `setTimeout()`
does not work reliably. Extension authors should use the [`alarms`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/alarms)
API instead.
### Maximum delay value
Browsers store the delay as a 32-bit signed integer internally. This causes an integer
overflow when using delays larger than 2,147,483,647 ms (about 24.8 days). So for example, this code:
```js
setTimeout(() => console.log("hi!"), 2 ** 32 - 5000);
```
…results in the timeout being executed immediately (since `2**32 - 5000` overflows to a negative number), while the following code:
```js
setTimeout(() => console.log("hi!"), 2 ** 32 + 5000);
```
…results in the timeout being executed after approximately 5 seconds.
**Note**: That doesn't match `setTimeout` behavior in Node.js, where any timeout larger than 2,147,483,647 ms
results in an immediate execution.
## Examples
### Setting and clearing timeouts
The following example sets up two simple buttons in a web page and hooks them to the
`setTimeout()` and `clearTimeout()` routines. Pressing the first
button will set a timeout which shows a message after two seconds and stores the
timeout id for use by `clearTimeout()`. You may optionally cancel this
timeout by pressing on the second button.
#### HTML
```html
<button onclick="delayedMessage();">Show a message after two seconds</button>
<button onclick="clearMessage();">Cancel message before it happens</button>
<div id="output"></div>
```
#### JavaScript
```js
let timeoutID;
function setOutput(outputContent) {
document.querySelector("#output").textContent = outputContent;
}
function delayedMessage() {
setOutput("");
timeoutID = setTimeout(setOutput, 2 * 1000, "That was really slow!");
}
function clearMessage() {
clearTimeout(timeoutID);
}
```
```css hidden
#output {
padding: 0.5rem 0;
}
```
#### Result
{{EmbedLiveSample('Setting_and_clearing_timeouts')}}
See also the [`clearTimeout()` example](/en-US/docs/Web/API/clearTimeout#examples).
## Specifications
{{Specifications}}
## Browser compatibility
{{Compat}}
## See also
- [Polyfill of `setTimeout` which allows passing arguments to the callback in `core-js`](https://github.com/zloirock/core-js#settimeout-and-setinterval)
- {{domxref("clearTimeout")}}
- {{domxref("setInterval()")}}
- {{domxref("window.requestAnimationFrame")}}
- {{domxref("queueMicrotask()")}}