window.setTimeout

Resumen

Establece un temporizador que llama a una función o ejecuta un fragmento de código después del retraso especificado.

Sintaxis

var timeoutID = window.setTimeout(func, retraso, [param1, param2, ...]);
var timeoutID = window.setTimeout(código, retraso);

Parámetros

• timeoutID es el ID numérico del timeout, que puede usarse después con window.clearTimeout().
• func es la función que usted quiere ejecutar después de los milisegundos de retraso.
• código en la sintaxis alternativa es una cadena de código que usted quiere ejecutar después de los milisegundos de retraso (el uso de esta sintaxis no está recomendado por las mismas razones de su uso en eval())
• retraso es el número de milisegundos (milésimas de segundo) que la función debe esperar para ser ejecutada. El retraso actual puede ser más largo; ver Notes abajo.

Tenga en cuenta que pasando parámetros adicionales a la función en la primera sintaxis no funciona en Internet Explorer < 9. Si usted quiere habilitar esta funcionalidad en ese navegador, usted debe usar un código de compatibilidad (vea el párrafo Callback arguments).

Ejemplo

El siguiente ejemplo establece dos botenes simples en una página web y los engancha a las rutinas setTimeout y clearTimeout. Presionando el primer botón verá un timeout que llama un diálogo de alerta después de dos segundos y guarda el id del timeout para usarlo en el clearTimeout. Opcionalmente puede cancelar este timeout presionando el segundo botón.

Contenido HTML

<p>Ejemplo funcional</p>
<button onclick="delayedAlert();">Muestra una caja de alerta después de dos segundos</button>
<p></p>
<button onclick="clearAlert();">Cancela la alerta antes de que ocurra</button>

Contenido JavaScript

var timeoutID;

function delayedAlert() {
  timeoutID = window.setTimeout(slowAlert, 2000);
}

function slowAlert() {
  alert("That was really slow!");
}

function clearAlert() {
  window.clearTimeout(timeoutID);
}

Vea también clearTimeout() example.

Callback arguments

Si necesita pasar un argumento a su función callback, pero necesita que funcione en Internet Explorer, que no soporta el envío de parámetros adicionales (ni con setTimeout() o setInterval()) usted puede incluir este código de compatibilidad IE-specific que habilitará la funcionalidad estándar de HTML5 para pasar los parámetros adicionales en ese navegador para ambos temporizadores solamente insertandolo al inicio de sus scripts.

/*\
|*|
|*|  IE-specific polyfill which enables the passage of arbitrary arguments to the
|*|  callback functions of JavaScript timers (HTML5 standard syntax).
|*|
|*|  https://developer.mozilla.org/en-US/docs/DOM/window.setInterval
|*|
|*|  Syntax:
|*|  var timeoutID = window.setTimeout(func, delay, [param1, param2, ...]);
|*|  var timeoutID = window.setTimeout(code, delay);
|*|  var intervalID = window.setInterval(func, delay[, param1, param2, ...]);
|*|  var intervalID = window.setInterval(code, delay);
|*|
\*/

if (document.all && !window.setTimeout.isPolyfill) {
  var __nativeST__ = window.setTimeout;
  window.setTimeout = function (vCallback, nDelay /*, argumentToPass1, argumentToPass2, etc. */) {
    var aArgs = Array.prototype.slice.call(arguments, 2);
    return __nativeST__(vCallback instanceof Function ? function () {
      vCallback.apply(null, aArgs);
    } : vCallback, nDelay);
  };
  window.setTimeout.isPolyfill = true;
}

if (document.all && !window.setInterval.isPolyfill) {
  var __nativeSI__ = window.setInterval;
  window.setInterval = function (vCallback, nDelay /*, argumentToPass1, argumentToPass2, etc. */) {
    var aArgs = Array.prototype.slice.call(arguments, 2);
    return __nativeSI__(vCallback instanceof Function ? function () {
      vCallback.apply(null, aArgs);
    } : vCallback, nDelay);
  };
  window.setInterval.isPolyfill = true;
}

Arreglo solo para IE

Si quiere una solución completamente no intrusiva con otros navegadores móviles o de escritorio, incluyendo IE 9 y superior, puede usar los comentarios condicionales de JavaScript:

/*@cc_on
  // conditional IE < 9 only fix
  @if (@_jscript_version <= 6)
  (function(f){
     window.setTimeout =f(window.setTimeout);
     window.setInterval =f(window.setInterval);
  })(function(f){return function(c,t){var a=[].slice.call(arguments,2);return f(function(){c.apply(this,a)},t)}});
  @end
@*/

O usar un enfoque más limpio basado en el condicional para IE de HTML:

<!--[if lt IE 9]><script>
(function(f){
window.setTimeout =f(window.setTimeout);
window.setInterval =f(window.setInterval);
})(function(f){return function(c,t){
var a=[].slice.call(arguments,2);return f(function(){c.apply(this,a)},t)}
});
</script><![endif]-->

Otra posibilidad es usar una función anónima para llamar el callback, pero esta solución es un poco más costosa. Ejemplo:

var intervalID = setTimeout(function() { myFunc("uno", "dos", "tres"); }, 1000);

Sin embargo, otra posibilidad es usar function's bind. Ejemplo:

setTimeout(function(arg1){}.bind(undefined, 10));

El problema "this"

Cuando pasa un método a setTimeout() (o cualquier otra función , por el estilo), podría ser invocada con el valor de this equivocado. Este problema es explicado en detalle en la referencia de JavaScript.

Explicación

El código ejecutado por setTimeout() corre en un contexto de ejecución diferente al de la función por la que fue llamado. Como consecuencia, la palabra clave this para la función llamada será asignado al objeto window (o global); no tendrá el mismo valor del this de la función que llamó al setTimeout. Vea el siguiente ejemplo:

myArray = ["cero", "uno", "dos"];
myArray.myMethod = function (sProperty) {
    alert(arguments.length > 0 ? this[sProperty] : this);
};

myArray.myMethod(); // imprime "cero,uno,dos"
myArray.myMethod(1); // imprime "uno"
setTimeout(myArray.myMethod, 1000); // imprime "[object Window]" después de 1 segundo
setTimeout(myArray.myMethod, 1500, "1"); // imprime "undefined" después de 1.5 segundos
// intentemos pasar el objeto 'this'
setTimeout.call(myArray, myArray.myMethod, 2000); // error: "NS_ERROR_XPC_BAD_OP_ON_WN_PROTO: Illegal operation on WrappedNative prototype object"
setTimeout.call(myArray, myArray.myMethod, 2500, 2); // mismo error

Como puedes ver no hay forma de pasar el objeto this a la función callback.

Una posible solución

Una posible forma de resolver el problema del "this" es reemplazar las dos funciones globales nativas setTimeout() or setInterval()por dos no-nativas  que permitan su invocación a través del método Function.prototype.call. El siguiente ejemplo muestra un posible reemplazo:

// Enable the passage of the 'this' object through the JavaScript timers
 
var __nativeST__ = window.setTimeout, __nativeSI__ = window.setInterval;
 
window.setTimeout = function (vCallback, nDelay /*, argumentToPass1, argumentToPass2, etc. */) {
  var oThis = this, aArgs = Array.prototype.slice.call(arguments, 2);
  return __nativeST__(vCallback instanceof Function ? function () {
    vCallback.apply(oThis, aArgs);
  } : vCallback, nDelay);
};
 
window.setInterval = function (vCallback, nDelay /*, argumentToPass1, argumentToPass2, etc. */) {
  var oThis = this, aArgs = Array.prototype.slice.call(arguments, 2);
  return __nativeSI__(vCallback instanceof Function ? function () {
    vCallback.apply(oThis, aArgs);
  } : vCallback, nDelay);
};

Prueba de la nueva característica:

myArray = ["zero", "one", "two"];
myArray.myMethod = function (sProperty) {
    alert(arguments.length > 0 ? this[sProperty] : this);
};

setTimeout(alert, 1500, "Hello world!"); // the standard use of setTimeout and setInterval is preserved, but...
setTimeout.call(myArray, myArray.myMethod, 2000); // prints "zero,one,two" after 2 seconds
setTimeout.call(myArray, myArray.myMethod, 2500, 2); // prints "two" after 2.5 seconds

No hay soluciones nativas ad hoc a este problema.

Notas

Puede cancelar el temporizador usando window.clearTimeout(). Si desea tener una función llamada repetidamente (p.e., cada N milisegundos), considere usar window.setInterval().

Es importante notar que la función o fragmento de código no puede ser ejecutado hasta que el hilo que llamó setTimeout()haya terminado.

Pasando cadenas literales

Pasando una cadena en vez de una función a setTimeout()pasa lo mismo que al usar eval.

// Correcto
window.setTimeout(function() {
    alert("Hello World!");
}, 500);

// Incorrecto
window.setTimeout("alert(\"Hello World!\");", 500);

Las cadenas literales son evaluadas en el contexto global, así que los símbolos locales en el contexto donde setTimeout() fue llamado no estarán disponibles cuando la cadena es evaluada como código.

Minimum/ maximum delay and timeout nesting

Historically browsers implement setTimeout() "clamping": successive setTimeout() calls with delay smaller than the "minimum delay" limit are forced to use at least the minimum delay. The minimum delay, DOM_MIN_TIMEOUT_VALUE, is 4 ms (stored in a preference in Firefox: dom.min_timeout_value), with a DOM_CLAMP_TIMEOUT_NESTING_LEVEL of 5ms.

In fact, 4ms is specified by the HTML5 spec and is consistent across browsers released in 2010 and onward. Prior to (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2), the minimum timeout value for nested timeouts was 10 ms.

In addition to "clamping", the timeout can also fire later when the page (or the OS/browser itself) is busy with other tasks.

To implement a 0 ms timeout in a modern browser, you can use window.postMessage() as described here.

Browsers including Internet Explorer, Chrome, Safari, and Firefox store the delay as a 32-bit signed Integer internally. This causes an Integer overflow when using delays larger than 2147483647, resulting in the timeout being executed immediately.

Inactive tabs

In (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2) and Chrome 11, timeouts are clamped to firing no more often than once per second (1000ms) in inactive tabs; see bug 633421 for more information about this in Mozilla or crbug.com/66078 for details about this in Chrome.

Compatibilidad de navegadores

*1 Whether it supports the optional parameters when in its first form or not.

Especificación

Parte del DOM nivel 0, como se especifica en HTML5.

Vea también

• JavaScript timers
• Timer.jsm
• window.setInterval
• window.requestAnimationFrame
• Daemons management