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
|
---
title: Array.prototype.includes()
slug: Web/JavaScript/Reference/Global_Objects/Array/includes
tags:
- Array
- ECMAScript 2016
- JavaScript
- 数组
- 方法
translation_of: Web/JavaScript/Reference/Global_Objects/Array/includes
---
<div>{{JSRef}} </div>
<p><code><strong>includes()</strong></code> 方法用来判断一个数组是否包含一个指定的值，根据情况，如果包含则返回 <code>true</code>，否则返回 <code>false</code>。</p>
<div>{{EmbedInteractiveExample("pages/js/array-includes.html")}}</div>
<h2 id="语法">语法</h2>
<pre><var>arr</var>.includes(<var>valueToFind[</var>, <var>fromIndex]</var>)</pre>
<h3 id="参数">参数</h3>
<dl>
<dt><code>valueToFind</code></dt>
<dd>
<p>需要查找的元素值。</p>
<div class="note">
<p><strong>备注：</strong>使用<strong> </strong><code>includes()</code>比较字符串和字符时是区分大小写的。</p>
</div>
</dd>
<dt><code>fromIndex</code> {{optional_inline}}</dt>
<dd>从<code>fromIndex</code> 索引处开始查找 <code>valueToFind</code>。如果为负值，则按升序从 <code>array.length + fromIndex</code> 的索引开始搜 （即使从末尾开始往前跳 <code>fromIndex</code> 的绝对值个索引，然后往后搜寻）。默认为 0。</dd>
</dl>
<h3 id="返回值">返回值</h3>
<p>返回一个布尔值 {{jsxref("Boolean")}} 。<br>]如果在数组中（或 <code>fromIndex</code> 指定的范围中）找到了 <code>valueToFind</code>，则返回 <code>true</code>，否则返回 <code>false</code>。</p>
<p>0 的值将全部视为相等，与符号无关（即 -0 与 0 和 +0 相等），但 <code>false</code> 不被认为与 0 相等。</p>
<div class="note">
<p><strong>备注：</strong> 技术上来讲，<code>includes()</code> 使用 <code><a href="https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Equality_comparisons_and_sameness#%E9%9B%B6%E5%80%BC%E7%9B%B8%E7%AD%89">零值相等</a></code> 算法来确定是否找到给定的元素。</p>
</div>
<h2 id="示例">示例</h2>
<pre class="brush: js">[1, 2, 3].includes(2); // true
[1, 2, 3].includes(4); // false
[1, 2, 3].includes(3, 3); // false
[1, 2, 3].includes(3, -1); // true
[1, 2, NaN].includes(NaN); // true
</pre>
<h3 id="fromIndex_大于等于数组长度">fromIndex 大于等于数组长度</h3>
<p>如果 <code>fromIndex</code> 大于等于数组的长度，则将直接返回 <code>false</code>，且不搜索该数组。</p>
<pre class="brush: js">var arr = ['a', 'b', 'c'];
arr.includes('c', 3); // false
arr.includes('c', 100); // false</pre>
<h3 id="计算出的索引小于_0">计算出的索引小于 0</h3>
<p>如果 <code>fromIndex</code> 为负值，计算出的索引将作为开始搜索<code>searchElement</code>的位置。如果计算出的索引小于 0，则整个数组都会被搜索。</p>
<pre class="brush: js">// array length is 3
// fromIndex is -100
// computed index is 3 + (-100) = -97
var arr = ['a', 'b', 'c'];
arr.includes('a', -100); // true
arr.includes('b', -100); // true
arr.includes('c', -100); // true
arr.includes('a', -2); // false</pre>
<h3 id="作为通用方法的_includes">作为通用方法的 includes()</h3>
<p><code>includes()</code> 方法有意设计为通用方法。它不要求<code>this</code>值是数组对象，所以它可以被用于其他类型的对象 (比如类数组对象)。下面的例子展示了 在函数的 <a href="/zh-CN/docs/Web/JavaScript/Reference/Functions/arguments">arguments</a> 对象上调用的 <code>includes()</code> 方法。</p>
<pre class="brush: js">(function() {
console.log([].includes.call(arguments, 'a')); // true
console.log([].includes.call(arguments, 'd')); // false
})('a','b','c');</pre>
<h2 id="Polyfill">Polyfill</h2>
<pre class="brush: js">// https://tc39.github.io/ecma262/#sec-array.prototype.includes
if (!Array.prototype.includes) {
Object.defineProperty(Array.prototype, 'includes', {
value: function(valueToFind, fromIndex) {
if (this == null) {
throw new TypeError('"this" is null or not defined');
}
// 1. Let O be ? ToObject(this value).
var o = Object(this);
// 2. Let len be ? ToLength(? Get(O, "length")).
var len = o.length >>> 0;
// 3. If len is 0, return false.
if (len === 0) {
return false;
}
// 4. Let n be ? ToInteger(fromIndex).
// (If fromIndex is undefined, this step produces the value 0.)
var n = fromIndex | 0;
// 5. If n ≥ 0, then
// a. Let k be n.
// 6. Else n < 0,
// a. Let k be len + n.
// b. If k < 0, let k be 0.
var k = Math.max(n >= 0 ? n : len - Math.abs(n), 0);
function sameValueZero(x, y) {
return x === y || (typeof x === 'number' && typeof y === 'number' && isNaN(x) && isNaN(y));
}
// 7. Repeat, while k < len
while (k < len) {
// a. Let elementK be the result of ? Get(O, ! ToString(k)).
// b. If SameValueZero(valueToFind, elementK) is true, return true.
if (sameValueZero(o[k], valueToFind)) {
return true;
}
// c. Increase k by 1.
k++;
}
// 8. Return false
return false;
}
});
}
</pre>
<p>如果你需要支持那些不支持<code><a href="https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty">Object.defineProperty</a></code>的废弃JavaScript 引擎，你最好不要 polyfill <code>Array.prototype</code> 方法，因为你不能使它们不可枚举。</p>
<h2 id="规范">规范</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">规范</th>
<th scope="col">状态</th>
<th scope="col">备注</th>
</tr>
<tr>
<td>{{SpecName('ES7', '#sec-array.prototype.includes', 'Array.prototype.includes')}}</td>
<td>{{Spec2('ES7')}}</td>
<td>Initial definition.</td>
</tr>
<tr>
<td>{{SpecName('ESDraft', '#sec-array.prototype.includes', 'Array.prototype.includes')}}</td>
<td>{{Spec2('ESDraft')}}</td>
<td></td>
</tr>
</tbody>
</table>
<h2 id="浏览器兼容性">浏览器兼容性</h2>
<p>{{Compat("javascript.builtins.Array.includes")}}</p>
<h2 id="参见">参见</h2>
<ul>
<li>{{jsxref("TypedArray.prototype.includes()")}}</li>
<li>{{jsxref("String.prototype.includes()")}}</li>
<li>{{jsxref("Array.prototype.indexOf()")}}</li>
<li>{{jsxref("Array.prototype.find()")}}</li>
<li>{{jsxref("Array.prototype.findIndex()")}}</li>
</ul>
|
