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
|
---
title: Array.prototype.push()
slug: Web/JavaScript/Reference/Global_Objects/Array/push
tags:
- Array
- JavaScript
- Méthode
- Prototype
- Reference
translation_of: Web/JavaScript/Reference/Global_Objects/Array/push
original_slug: Web/JavaScript/Reference/Objets_globaux/Array/push
---
<div>{{JSRef}}</div>
<p>La méthode <code><strong>push()</strong></code> ajoute un ou plusieurs éléments à la fin d'un tableau et retourne la nouvelle taille du tableau.</p>
<div>{{EmbedInteractiveExample("pages/js/array-push.html")}}</div>
<p class="hidden">Le code source de cet exemple interactif est disponible dans un dépôt GitHub. Si vous souhaitez contribuez à ces exemples, n'hésitez pas à cloner <a href="https://github.com/mdn/interactive-examples">https://github.com/mdn/interactive-examples</a> et à envoyer une <em>pull request</em> !</p>
<h2 id="Syntaxe">Syntaxe</h2>
<pre class="syntaxbox"><var>arr</var>.push(<var>élément1</var>, ..., <var>élémentN</var>)</pre>
<h3 id="Paramètres">Paramètres</h3>
<dl>
<dt><code>élément1, ...,élémentN</code></dt>
<dd>Les éléments à ajouter à la fin du tableau.</dd>
</dl>
<h3 id="Valeur_de_retour">Valeur de retour</h3>
<p>La nouvelle valeur de la propriété {{jsxref("Array.length", "length")}} de l'objet sur lequel la méthode a été appelée.</p>
<h2 id="Description">Description</h2>
<p>La méthode <code>push</code> permet d'ajouter des valeurs à un tableau.</p>
<p><code>push</code> est une méthode générique. Cette méthode peut ainsi être utilisée avec les méthodes {{jsxref("Function.call()")}} ou {{jsxref("Function.apply()")}} sur des objets similaires aux tableaux.</p>
<p>La méthode <code>push</code> se base sur la propriété <code>length</code> pour déterminer à partir de quel index les valeurs données doivent être insérées. Si la propriété <code>length</code> ne peut pas être convertie en nombre, l'index utilisé est 0. Si la propriété <code>length</code> n'est pas définie, elle est alors créée.</p>
<p>Bien que <code>push</code> soit une méthode générique, elle ne peut pas être utilisée sur les chaînes de caractères ou sur l'objet <code>arguments</code> car ils sont immuables.</p>
<h2 id="Exemples">Exemples</h2>
<h3 id="Ajouter_des_éléments_à_un_tableau">Ajouter des éléments à un tableau</h3>
<p>Le code suivant crée un tableau <code>sports</code> contenant à sa création deux éléments, auxquels sont ajoutés deux nouveaux éléments. La variable <code>total</code> contient la nouvelle taille du tableau.</p>
<pre class="brush: js">var sports = ["plongée", "baseball"];
var total = sports.push("football", "tennis");
console.log(sports); // ["plongée", "baseball", "football", "tennis"]
console.log(total); // 4
</pre>
<h3 id="Fusionner_deux_tableaux">Fusionner deux tableaux</h3>
<p>Dans l'exemple qui suit, on utilise la méthode {{jsxref("Function.apply()")}} pour ajouter les différents éléments d'un second tableau</p>
<pre class="brush: js">var legumes = ['navet', 'pomme de terre'];
var autresLegumes = ['céleri', 'radis'];
// On fusionne les deux tableaux
// Équivalent à legumes.push('céleri', 'radis');
Array.prototype.push.apply(legumes, autresLegumes);
console.log(legumes); // ['navet', 'pomme de terre', 'céleri', 'radis']</pre>
<div class="note">
<p><strong>Note :</strong> Attention à ne pas utiliser cette méthode lorsque les tableaux sont très grands car une fonction n'accepte qu'un nombre limité d'arguments. Voir {{jsxref("Function.apply","apply()")}} pour plus d'informations sur ces limites.</p>
</div>
<h3 id="Utiliser_un_objet_comme_on_utiliserait_un_tableau">Utiliser un objet comme on utiliserait un tableau</h3>
<p>Comme nous l'avons vu auparavant, <code>push</code> est une méthode générique et nous pouvons donc utiliser <code>Array.prototype.push</code> sur les objets. On notera qu'il n'est pas nécessaire de stocker un ensemble d'objets. En fait, on enregistre l'ensemble dans l'objet et on utilise <code>call</code> sur <code>Array.prototype.push</code> :</p>
<pre class="brush: js">var obj = {
length: 0,
ajoutElem: function ajoutElem (elem) {
// obj.length est automatiquement incrémenté
// quand on ajoute un élément
[].push.call(this, elem);
}
};
// Ajoutons quelques objets vides pour illustrer
// l'exemple.
obj.ajoutElem({});
obj.ajoutElem({});
console.log(obj.length);
// → 2
</pre>
<h2 id="Spécifications">Spécifications</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Spécification</th>
<th scope="col">État</th>
<th scope="col">Commentaires</th>
</tr>
<tr>
<td>{{SpecName('ES3')}}</td>
<td>{{Spec2('ES3')}}</td>
<td>Définition initiale. Implémentée avec JavaScript 1.2.</td>
</tr>
<tr>
<td>{{SpecName('ES5.1', '#sec-15.4.4.7', 'Array.prototype.push')}}</td>
<td>{{Spec2('ES5.1')}}</td>
<td></td>
</tr>
<tr>
<td>{{SpecName('ES6', '#sec-array.prototype.push', 'Array.prototype.push')}}</td>
<td>{{Spec2('ES6')}}</td>
<td></td>
</tr>
<tr>
<td>{{SpecName('ESDraft', '#sec-array.prototype.push', 'Array.prototype.push')}}</td>
<td>{{Spec2('ESDraft')}}</td>
<td></td>
</tr>
</tbody>
</table>
<h2 id="Compatibilité_des_navigateurs">Compatibilité des navigateurs</h2>
<div>
<div class="hidden">Le tableau de compatibilité de cette page a été généré à partir de données structurées. Si vous souhaitez contribuer à ces données, n'hésitez pas à consulter <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> et à nous envoyer une<em>pull request</em>.</div>
<p>{{Compat("javascript.builtins.Array.push")}}</p>
</div>
<h2 id="Voir_aussi">Voir aussi</h2>
<ul>
<li>{{jsxref("Array.prototype.pop()")}}</li>
<li>{{jsxref("Array.prototype.shift()")}}</li>
<li>{{jsxref("Array.prototype.unshift()")}}</li>
<li>{{jsxref("Array.prototype.concat()")}}</li>
</ul>
|
