HTML
Living Standard — Last Updated 13 November 2024
Living Standard — Last Updated 13 November 2024
setTimeout()とsetInterval()メソッドは、著者がタイマーベースのコールバックをスケジュールできるようにする。
id = self.setTimeout(handler [, timeout [, ...arguments ] ])Support in all current engines.
timeoutミリ秒後にhandlerを実行するためにタイムアウトをスケジュールする。すべてのargumentsは直接handlerに渡される。
id = self.setTimeout(code [, timeout ])timeoutミリ秒後にcodeを実行するためにタイムアウトをスケジュールする。
self.clearTimeout(id)Support in all current engines.
idで識別されるsetTimeout()またはsetInterval()で設定されたタイムアウトをキャンセルする。
id = self.setInterval(handler [, timeout [, ...arguments ] ])Support in all current engines.
timeoutミリ秒ごとにhandlerを実行するためにタイムアウトをスケジュールする。すべてのargumentsは直接handlerに渡される。
id = self.setInterval(code [, timeout ])timeoutミリ秒ごとにcodeを実行するためにタイムアウトをスケジュールする。
self.clearInterval(id)Support in all current engines.
idで識別されるsetInterval()またはsetTimeout()で設定されたタイムアウトをキャンセルする。
タイマーは入れ子にすることができる。しかし、5つのそのようなネストされたタイマー後に、間隔は少なくとも4ミリ秒であることが強制される。
このAPIは、タイマーがスケジュールどおり正確に動作することを保証しない。CPU負荷やその他のタスクなどによる遅延が予想される。
Objects that implement the WindowOrWorkerGlobalScope mixin have a map of setTimeout and setInterval IDs, which is an ordered map, initially empty. Each key in this map is a positive integer, corresponding to the return value of a setTimeout() or setInterval() call. Each value is a unique internal value, corresponding to a key in the object's map of active timers.
The setTimeout(handler, timeout, ...arguments) method steps are to return the result of running the timer initialization steps given this, handler, timeout, arguments, and false.
The setInterval(handler, timeout, ...arguments) method steps are to return the result of running the timer initialization steps given this, handler, timeout, arguments, and true.
The clearTimeout(id) and clearInterval(id) method steps are to remove this's map of setTimeout and setInterval IDs[id].
Because clearTimeout() and clearInterval() clear entries from the same map, either method can be used to clear timers created by setTimeout() or setInterval().
To perform the timer initialization steps, given a WindowOrWorkerGlobalScope global, a string or Function or TrustedScript handler, a number timeout, a list arguments, a boolean repeat, and optionally (and only if repeat is true) a number previousId, perform the following steps. They return a number.
Let thisArg be global if that is a WorkerGlobalScope object; otherwise let thisArg be the WindowProxy that corresponds to global.
If previousId was given, let id be previousId; otherwise, let id be an implementation-defined integer that is greater than zero and does not already exist in global's map of setTimeout and setInterval IDs.
If the surrounding agent's event loop's currently running task is a task that was created by this algorithm, then let nesting level be the task's timer nesting level. Otherwise, let nesting level be zero.
The task's timer nesting level is used both for nested calls to setTimeout(), and for the repeating timers created by setInterval(). (Or, indeed, for any combination of the two.) In other words, it represents nested invocations of this algorithm, not of a particular method.
If timeout is less than 0, then set timeout to 0.
If nesting level is greater than 5, and timeout is less than 4, then set timeout to 4.
Let realm be global's relevant realm.
Let initiating script be the active script.
Let uniqueHandle be null.
Let task be a task that runs the following substeps:
Assert: uniqueHandle is a unique internal value, not null.
If id does not exist in global's map of setTimeout and setInterval IDs, then abort these steps.
If global's map of setTimeout and setInterval IDs[id] does not equal uniqueHandle, then abort these steps.
This accommodates for the ID having been cleared by a clearTimeout() or clearInterval() call, and being reused by a subsequent setTimeout() or setInterval() call.
Record timing info for timer handler given handler, global's relevant settings object, and repeat.
If handler is a Function, then invoke handler given arguments and "report", and with callback this value set to thisArg.
Otherwise:
If previousId was not given:
Let globalName be "Window" if global is a Window object; "Worker" otherwise.
Let methodName be "setInterval" if repeat is true; "setTimeout" otherwise.
Let sink be a concatenation of globalName, U+0020 SPACE, and methodName.
Set handler to the result of invoking the Get Trusted Type compliant string algorithm with TrustedScript, global, handler, sink, and "script".
Assert: handler is a string.
Perform EnsureCSPDoesNotBlockStringCompilation(realm, « », handler, handler, timer, « », handler). If this throws an exception, catch it, report it for global, and abort these steps.
Let settings object be global's relevant settings object.
Let fetch options be the default script fetch options.
Let base URL be settings object's API base URL.
If initiating script is not null, then:
Set fetch options to a script fetch options whose cryptographic nonce is initiating script's fetch options's cryptographic nonce, integrity metadata is the empty string, parser metadata is "not-parser-inserted", credentials mode is initiating script's fetch options's credentials mode, referrer policy is initiating script's fetch options's referrer policy, and fetch priority is "auto".
Set base URL to initiating script's base URL.
The effect of these steps ensures that the string compilation done by setTimeout() and setInterval() behaves equivalently to that done by eval(). That is, module script fetches via import() will behave the same in both contexts.
Let script be the result of creating a classic script given handler, settings object, base URL, and fetch options.
Run the classic script script.
If id does not exist in global's map of setTimeout and setInterval IDs, then abort these steps.
If global's map of setTimeout and setInterval IDs[id] does not equal uniqueHandle, then abort these steps.
The ID might have been removed via the author code in handler calling clearTimeout() or clearInterval(). Checking that uniqueHandle isn't different accounts for the possibility of the ID, after having been cleared, being reused by a subsequent setTimeout() or setInterval() call.
If repeat is true, then perform the timer initialization steps again, given global, handler, timeout, arguments, true, and id.
Otherwise, remove global's map of setTimeout and setInterval IDs[id].
Increment nesting level by one.
Set task's timer nesting level to nesting level.
Let completionStep be an algorithm step which queues a global task on the timer task source given global to run task.
Set uniqueHandle to the result of running steps after a timeout given global, "setTimeout/setInterval", timeout, completionStep.
Set global's map of setTimeout and setInterval IDs[id] to uniqueHandle.
Return id.
Argument conversion as defined by Web IDL (for example, invoking toString() methods on objects passed as the first argument) happens in the algorithms defined in Web IDL, before this algorithm is invoked.
So for example, the following rather silly code will result in the log containing "ONE TWO ":
var log = '' ;
function logger( s) { log += s + ' ' ; }
setTimeout({ toString: function () {
setTimeout( "logger('ONE')" , 100 );
return "logger('TWO')" ;
} }, 100 ); 遅延なく背中合わせに数ミリ秒のタスクを実行するために、飢えたユーザーインターフェイスを避けるために（およびCPUを占有するためのスクリプトを殺すブラウザーを避けるために）ブラウザーに戻って従いつつ、作業を実行する前の簡単なキューの次のタイマー：
function doExpensiveWork() {
var done = false ;
// ...
// this part of the function takes up to five milliseconds
// set done to true if we're done
// ...
return done;
}
function rescheduleWork() {
var id = setTimeout( rescheduleWork, 0 ); // preschedule next iteration
if ( doExpensiveWork())
clearTimeout( id); // clear the timeout if we don't need it
}
function scheduleWork() {
setTimeout( rescheduleWork, 0 );
}
scheduleWork(); // queues a task to do lots of work Objects that implement the WindowOrWorkerGlobalScope mixin have a map of active timers, which is an ordered map, initially empty. Each key in this map is a unique internal value that represents a timer, and each value is a DOMHighResTimeStamp, representing the expiry time for that timer.
To run steps after a timeout, given a WindowOrWorkerGlobalScope global, a string orderingIdentifier, a number milliseconds, and a set of steps completionSteps, perform the following steps. They return a unique internal value.
Let timerKey be a new unique internal value.
Let startTime be the current high resolution time given global.
Set global's map of active timers[timerKey] to startTime plus milliseconds.
Run the following steps in parallel:
If global is a Window object, wait until global's associated Document has been fully active for a further milliseconds milliseconds (not necessarily consecutively).
Otherwise, global is a WorkerGlobalScope object; wait until milliseconds milliseconds have passed with the worker not suspended (not necessarily consecutively).
Wait until any invocations of this algorithm that had the same global and orderingIdentifier, that started before this one, and whose milliseconds is less than or equal to this one's, have completed.
Optionally, wait a further implementation-defined length of time.
This is intended to allow user agents to pad timeouts as needed to optimize the power usage of the device. For example, some processors have a low-power mode where the granularity of timers is reduced; on such platforms, user agents can slow timers down to fit this schedule instead of requiring the processor to use the more accurate mode with its associated higher power usage.
Perform completionSteps.
Remove global's map of active timers[timerKey].
Return timerKey.
Run steps after a timeout is meant to be used by other specifications that want to execute developer-supplied code after a developer-supplied timeout, in a similar manner to setTimeout(). (Note, however, it does not have the nesting and clamping behavior of setTimeout().) Such specifications can choose an orderingIdentifier to ensure ordering within their specification's timeouts, while not constraining ordering with respect to other specification's timeouts.
Support in all current engines.
The queueMicrotask(callback) method must queue a microtask to invoke callback with « » and "report".
queueMicrotask()メソッドは、著者がマイクロタスクキューでコールバックをスケジュールすることを可能にする。これは、JavaScript実行コンテキストスタックが次に空になるとコードを実行でき、これは、現在実行中のすべての同期JavaScriptが完了するまで実行されたときに発生する。これは、たとえばsetTimeout(f, 0)を使用する場合のように、イベントループに制御を戻すことはない。
著者は、大量のマイクロタスクをスケジュールすることが、大量の同期コードを実行するのと同じパフォーマンスの低下があることに注意する必要がある。 どちらも、ブラウザーがレンダリングなどの独自の作業を実行を妨げることになる。多くの場合、requestAnimationFrame()またはrequestIdleCallback()の方がよい選択である。 特に、次のレンダリングサイクルの前にコードを実行することが目標である場合、それはrequestAnimationFrame()の目的である。
次の例からわかるように、queueMicrotask()について考える最良の方法は、同期コードを再配置するためのメカニズムとして、現在実行中の同期JavaScriptが完了した直後にキューに入れられたコードを効果的に配置することである。
queueMicrotask() 使用する最も一般的な理由は、情報が同期的に利用できる場合でも、過度の遅延を発生させることなく、一貫した順序を作成することである。
たとえば、以前にロードされたデータの内部キャッシュも維持する、loadイベントを発生させるカスタム要素について考えてみる。ナイーブな実装は次のようになるだろう：
MyElement. prototype. loadData = function ( url) {
if ( this . _cache[ url]) {
this . _setData( this . _cache[ url]);
this . dispatchEvent( new Event( "load" ));
} else {
fetch( url). then( res => res. arrayBuffer()). then( data => {
this . _cache[ url] = data;
this . _setData( data);
this . dispatchEvent( new Event( "load" ));
});
}
}; しかし、このナイーブな実装には、ユーザーに一貫性のない動作が発生するという問題がある。たとえば、次のようなコードは
element. addEventListener( "load" , () => console. log( "loaded" ));
console. log( "1" );
element. loadData();
console. log( "2" ); "1, 2, loaded"（データをフェッチする必要がある場合）を記録することもあれば、"1, loaded, 2"（データがすでにキャッシュされている場合）を記録することもある。同様に、loadData()の呼び出し後、データが要素に設定されているかどうかは一貫性がない。
一貫した順序を取得するためには、queueMicrotask()を使用できる：
MyElement. prototype. loadData = function ( url) {
if ( this . _cache[ url]) {
queueMicrotask(() => {
this . _setData( this . _cache[ url]);
this . dispatchEvent( new Event( "load" ));
});
} else {
fetch( url). then( res => res. arrayBuffer()). then( data => {
this . _cache[ url] = data;
this . _setData( data);
this . dispatchEvent( new Event( "load" ));
});
}
}; キューに入れられたコードをJavaScript実行コンテキストスタックが空になった後になるように基本的に再配置することで、要素の状態の一貫した順序付けおよび更新が保証される。
queueMicrotask()のもう1つの興味深い使用法は、 複数の呼び出し元による作業の調整されていない"バッチ処理"を可能にすることである。たとえば、できるだけ早くどこかにデータを送信したいが、簡単に回避できる場合は、 複数のネットワークリクエストを行いたくないライブラリ関数について考えてみる。このバランスをとる1つの方法は次のようになる：
const queuedToSend = [];
function sendData( data) {
queuedToSend. push( data);
if ( queuedToSend. length === 1 ) {
queueMicrotask(() => {
const stringToSend = JSON. stringify( queuedToSend);
queuedToSend. length = 0 ;
fetch( "/endpoint" , stringToSend);
});
}
} このアーキテクチャでは、現在実行中の同期JavaScript内でsendData()を呼び出す複数の後続の呼び出しは、1つのfetch()呼び出しにまとめられるが、イベントループのタスクがフェッチを先取りすることはない（代わりに同様のコードで発生した場合のようにsetTimeout()を使用する）。
window.alert(message)Support in all current engines.
指定されたメッセージを持つモーダルアラートを表示し、それを命令するユーザーに対して待機する。
result = window.confirm(message)Support in all current engines.
与えられたメッセージとともにモーダルOK/Cancelプロンプトを表示し、それを命令するユーザーに対して待機し、ユーザーがOKをクリックした場合はtrueを返し、ユーザーがCancelをクリックする場合はfalseを返す。
result = window.prompt(message [, default])Support in all current engines.
与えられたメッセージとともにモーダルテキストコントロールプロンプトを表示し、ユーザーがそれを閉じるのを待ち、ユーザーが入力した値を返す。ユーザーがプロンプトをキャンセルした場合、代わりにnullを返す。2番目の引数が存在する場合、指定された値がデフォルトとして使用される。
メディアデータを読み込むメディア要素のような、タスクまたはマイクロタスクに依存するロジックは、このメソッドが発動されるときに延期される。
The alert() and alert(message) method steps are:
If we cannot show simple dialogs for this, then return.
If the method was invoked with no arguments, then let message be the empty string; otherwise, let message be the method's first argument.
Set message to the result of normalizing newlines given message.
Set message to the result of optionally truncating message.
Show message to the user, treating U+000A LF as a line break.
Invoke WebDriver BiDi user prompt opened with this, "alert", and message.
Optionally, pause while waiting for the user to acknowledge the message.
Invoke WebDriver BiDi user prompt closed with this and true.
This method is defined using two overloads, instead of using an optional argument, for historical reasons. The practical impact of this is that alert(undefined) is treated as alert("undefined"), but alert() is treated as alert("").
The confirm(message) method steps are:
If we cannot show simple dialogs for this, then return false.
Set message to the result of normalizing newlines given message.
Set message to the result of optionally truncating message.
Show message to the user, treating U+000A LF as a line break, and ask the user to respond with a positive or negative response.
Invoke WebDriver BiDi user prompt opened with this, "confirm", and message.
Pause until the user responds either positively or negatively.
Invoke WebDriver BiDi user prompt closed with this, and true if the user responded positively or false otherwise.
If the user responded positively, return true; otherwise, the user responded negatively: return false.
The prompt(message, default) method steps are:
If we cannot show simple dialogs for this, then return null.
Set message to the result of normalizing newlines given message.
Set message to the result of optionally truncating message.
Set default to the result of optionally truncating default.
Show message to the user, treating U+000A LF as a line break, and ask the user to either respond with a string value or abort. The response must be defaulted to the value given by default.
Invoke WebDriver BiDi user prompt opened with this, "prompt", message, and default.
Pause while waiting for the user's response.
Let result be null if the user aborts, or otherwise the string that the user responded with.
Invoke WebDriver BiDi user prompt closed with this, false if result is null or true otherwise, and result.
Return result.
To optionally truncate a simple dialog string s, return either s itself or some string derived from s that is shorter. User agents should not provide UI for displaying the elided portion of s, as this makes it too easy for abusers to create dialogs of the form "Important security alert! Click 'Show More' for full details!".
For example, a user agent might want to only display the first 100 characters of a message. Or, a user agent might replace the middle of the string with "…". These types of modifications can be useful in limiting the abuse potential of unnaturally large, trustworthy-looking system dialogs.
We cannot show simple dialogs for a Window window when the following algorithm returns true:
If the active sandboxing flag set of window's associated Document has the sandboxed modals flag set, then return true.
If window's relevant settings object's origin and window's relevant settings object's top-level origin are not same origin-domain, then return true.
Optionally, return true. (For example, the user agent might give the user the option to ignore all modal dialogs, and would thus abort at this step whenever the method was invoked.)
falseを返す。
Support in all current engines.
window.print()ページを印刷するようユーザーに指示する。
The print() method steps are:
Let document be this's associated Document.
If document is not fully active, then return.
If document's unload counter is greater than 0, then return.
If document is ready for post-load tasks, then run the printing steps for document.
Otherwise, set document's print when loaded flag.
User agents should also run the printing steps whenever the user asks for the opportunity to obtain a physical form (e.g. printed copy), or the representation of a physical form (e.g. PDF copy), of a document.
The printing steps for a Document document are:
The user agent may display a message to the user or return (or both).
For instance, a kiosk browser could silently ignore any invocations of the print() method.
For instance, a browser on a mobile device could detect that there are no printers in the vicinity and display a message saying so before continuing to offer a "save to PDF" option.
If the active sandboxing flag set of document has the sandboxed modals flag set, then return.
If the printing dialog is blocked by a Document's sandbox, then neither the beforeprint nor afterprint events will be fired.
The user agent must fire an event named beforeprint at the relevant global object of document, as well as any child navigable in it.
Firing in children only doesn't seem right here, and some tasks likely need to be queued. See issue #5096.
The beforeprint event can be used to annotate the printed copy, for instance adding the time at which the document was printed.
The user agent should offer the user the opportunity to obtain a physical form (or the representation of a physical form) of document. The user agent may wait for the user to either accept or decline before returning; if so, the user agent must pause while the method is waiting. Even if the user agent doesn't wait at this point, the user agent must use the state of the relevant documents as they are at this point in the algorithm if and when it eventually creates the alternate form.
The user agent must fire an event named afterprint at the relevant global object of document, as well as any child navigables in it.
Firing in children only doesn't seem right here, and some tasks likely need to be queued. See issue #5096.
The afterprint event can be used to revert annotations added in the earlier event, as well as showing post-printing UI. For instance, if a page is walking the user through the steps of applying for a home loan, the script could automatically advance to the next step after having printed a form or other.