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
|
---
title: Promise.race()
slug: Web/JavaScript/Reference/Global_Objects/Promise/race
translation_of: Web/JavaScript/Reference/Global_Objects/Promise/race
---
<div>{{JSRef}}</div>
<p><code><strong>Promise.race(iterable)</strong></code> 方法回傳一個 promise 物件，此 promise 物件會於 iterable 引數中任一個 promise 轉為 resolve 或 rejected 時立即轉變成 resolve 或 rejected，並且接收其成功值或失敗訊息。</p>
<h2 id="語法">語法</h2>
<pre class="syntaxbox"><var>Promise.race(iterable)</var>;</pre>
<h3 id="參數">參數</h3>
<dl>
<dt>iterable</dt>
<dd>一個 iterable 物件，像是 {{jsxref("Array")}}. 請參考<a href="/zh-TW/docs/Web/JavaScript/Reference/Iteration_protocols#可迭代協議">可迭代協議</a>。</dd>
</dl>
<h3 id="回傳值">回傳值</h3>
<p>當傳入的 iterable 中有 promise 被實現或拒絕時，立刻回傳被實現或拒絕的 {{jsxref("Promise")}}。</p>
<h2 id="描述">描述</h2>
<p><code>race</code> 函式回傳一個與傳入的 iterable 之中第一個被解決（settled）的 promise 相同方式被解決（且以相同值）的 <code>Promise</code>。</p>
<h2 id="範例">範例</h2>
<h3 id="Promise.race_的非同步性質"><code>Promise.race</code> 的非同步性質</h3>
<p>以下例子演示了 <code>Promise.race</code> <code>的非同步性質：</code></p>
<pre class="brush: js">// we are passing as argument an array of promises that are already resolved,
// to trigger Promise.race as soon as possible
var resolvedPromisesArray = [Promise.resolve(33), Promise.resolve(44)];
var p = Promise.race(resolvedPromisesArray);
// immediately logging the value of p
console.log(p);
// using setTimeout we can execute code after the stack is empty
setTimeout(function(){
console.log('the stack is now empty');
console.log(p);
});
// logs, in order:
// Promise { <state>: "pending" }
// the stack is now empty
// Promise { <state>: "fulfilled", <value>: 33 }</pre>
<p>一個空的 iterable 造成回傳的 promise 永久擱置：</p>
<pre class="brush: js">var foreverPendingPromise = Promise.race([]);
console.log(foreverPendingPromise);
setTimeout(function(){
console.log('the stack is now empty');
console.log(foreverPendingPromise);
});
// logs, in order:
// Promise { <state>: "pending" }
// the stack is now empty
// Promise { <state>: "pending" }
</pre>
<p>若 iterable 中有一個或多個非 promise 值且／或一個已經被實現／解決的 promise，<code>Promise.race</code> 將以陣列中第一個這樣的值解決：</p>
<pre class="brush: js">var foreverPendingPromise = Promise.race([]);
var alreadyResolvedProm = Promise.resolve(666);
var arr = [foreverPendingPromise, alreadyResolvedProm, "non-Promise value"];
var arr2 = [foreverPendingPromise, "non-Promise value", Promise.resolve(666)];
var p = Promise.race(arr);
var p2 = Promise.race(arr2);
console.log(p);
console.log(p2);
setTimeout(function(){
console.log('the stack is now empty');
console.log(p);
console.log(p2);
});
// logs, in order:
// Promise { <state>: "pending" }
// Promise { <state>: "pending" }
// the stack is now empty
// Promise { <state>: "fulfilled", <value>: 666 }
// Promise { <state>: "fulfilled", <value>: "non-Promise value" }
</pre>
<h3 id="使用_Promise.race_–_及_setTimeout_的範例">使用 <code>Promise.race</code> – 及 <code><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout">setTimeout</a></code> 的範例</h3>
<pre class="brush: js">var p1 = new Promise(function(resolve, reject) {
setTimeout(resolve, 500, 'one');
});
var p2 = new Promise(function(resolve, reject) {
setTimeout(resolve, 100, 'two');
});
Promise.race([p1, p2]).then(function(value) {
console.log(value); // "two"
// Both resolve, but p2 is faster
});
var p3 = new Promise(function(resolve, reject) {
setTimeout(resolve, 100, 'three');
});
var p4 = new Promise(function(resolve, reject) {
setTimeout(reject, 500, 'four');
});
Promise.race([p3, p4]).then(function(value) {
console.log(value); // "three"
// p3 is faster, so it resolves
}, function(reason) {
// Not called
});
var p5 = new Promise(function(resolve, reject) {
setTimeout(resolve, 500, 'five');
});
var p6 = new Promise(function(resolve, reject) {
setTimeout(reject, 100, 'six');
});
Promise.race([p5, p6]).then(function(value) {
// Not called
}, function(reason) {
console.log(reason); // "six"
// p6 is faster, so it rejects
});
</pre>
<h2 id="規範">規範</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
<tr>
<td>{{SpecName('ES2015', '#sec-promise.race', 'Promise.race')}}</td>
<td>{{Spec2('ES2015')}}</td>
<td>Initial definition in an ECMA standard.</td>
</tr>
<tr>
<td>{{SpecName('ESDraft', '#sec-promise.race', 'Promise.race')}}</td>
<td>{{Spec2('ESDraft')}}</td>
<td> </td>
</tr>
</tbody>
</table>
<h2 id="瀏覽器相容性">瀏覽器相容性</h2>
<p>{{Compat("javascript.builtins.Promise.race")}}</p>
<h2 id="參見">參見</h2>
<ul>
<li>{{jsxref("Promise")}}</li>
<li>{{jsxref("Promise.all()")}}</li>
</ul>
|
