Cette page a été traduite à partir de l'anglais par la communauté.Vous pouvez contribuer en rejoignant la communauté francophone sur MDN Web Docs.
Array : méthode copyWithin()
Baseline Widely available
Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis septembre 2015.
La méthodecopyWithin() des instances deArray copie superficiellement une partie de ce tableau à un autre emplacement dans le même tableau et retourne ce tableau sans en modifier la longueur.
Exemple interactif
const array = ["a", "b", "c", "d", "e"];// Copie à l'indice 0 l'élément à l'indice 3console.log(array.copyWithin(0, 3, 4));// Résultat attendu : Array ["d", "b", "c", "d", "e"]// Copie à l'indice 1 tous les éléments de l'indice 3 à la finconsole.log(array.copyWithin(1, 3));// Résultat attendu : Array ["d", "d", "e", "d", "e"]Syntaxe
copyWithin(target, start)copyWithin(target, start, end)Paramètres
targetL'indice (à partir de zéro) auquel copier la séquence,converti en entier. Cela correspond à l'emplacement où l'élément à l'indice
startsera copié, et tous les éléments compris entrestartetendseront copiés aux indices suivants.- Un indice négatif compte à rebours depuis la fin du tableau — si
-array.length <= target < 0, on utilisetarget + array.length. - Si
target < -array.length, on utilise0. - Si
target >= array.length, rien n'est copié. - Si
targetest positionné aprèsstartaprès normalisation, la copie ne se fait que jusqu'à la fin dearray.length(autrement dit,copyWithin()n'étend jamais le tableau).
- Un indice négatif compte à rebours depuis la fin du tableau — si
startL'indice (à partir de zéro) à partir duquel commencer à copier les éléments,converti en entier.
- Un indice négatif compte à rebours depuis la fin du tableau — si
-array.length <= start < 0, on utilisestart + array.length. - Si
start < -array.length, on utilise0. - Si
start >= array.length, rien n'est copié.
- Un indice négatif compte à rebours depuis la fin du tableau — si
endFacultatifL'indice (à partir de zéro) auquel arrêter de copier les éléments,converti en entier.
copyWithin()copie jusqu'à (mais sans inclure)end.- Un indice négatif compte à rebours depuis la fin du tableau — si
-array.length <= end < 0, on utiliseend + array.length. - Si
end < -array.length, on utilise0. - Si
end >= array.lengthou siendest omis ouundefined, on utilisearray.length, ce qui fait que tous les éléments jusqu'à la fin sont copiés. - Si
endimplique une position avant ou à la même position que celle impliquée parstart, rien n'est copié.
- Un indice négatif compte à rebours depuis la fin du tableau — si
Valeur de retour
Le tableau modifié.
Description
La méthodecopyWithin() fonctionne commememmove en C et C++ ; c'est une méthode très performante pour décaler les données d'un tableau (Array). Cela s'applique en particulier à la méthodeTypedArray du même nom. La séquence est copiée et collée en une seule opération ; la séquence collée aura les valeurs copiées même si les zones de copie et de collage se chevauchent.
Commeundefined devient0 lorsqu'il est converti en entier, omettre le paramètrestart a le même effet que de passer0, ce qui copie tout le tableau à la position cible, équivalent à un décalage vers la droite où la borne droite est tronquée et la borne gauche est dupliquée. Ce comportement peut prêter à confusion pour les lecteurs·rices de votre code ; il est donc préférable de passer explicitement0 comme valeur destart.
console.log([1, 2, 3, 4, 5].copyWithin(2));// [1, 2, 1, 2, 3] ; décale tous les éléments de 2 positions vers la droiteLa méthodecopyWithin() est uneméthode de mutation. Elle ne modifie pas la longueur dethis, mais elle modifie le contenu dethis et peut créer de nouvelles propriétés ou supprimer des propriétés existantes si nécessaire.
La méthodecopyWithin() préserve les cases vides. Si la région à copier estcreuxe, les nouveaux indices correspondants des cases vides sontsupprimés et deviennent aussi des cases vides.
La méthodecopyWithin() estgénérique. Elle attend seulement que la valeur dethis possède une propriétélength et des propriétés à clés entières. Bien que les chaînes de caractères soient aussi similaires à des tableaux, cette méthode n'est pas adaptée pour être appliquée sur elles, car les chaînes sont immuables.
Exemples
Utilisation decopyWithin()
console.log([1, 2, 3, 4, 5].copyWithin(0, 3));// [4, 5, 3, 4, 5]console.log([1, 2, 3, 4, 5].copyWithin(0, 3, 4));// [4, 2, 3, 4, 5]console.log([1, 2, 3, 4, 5].copyWithin(-2, -3, -1));// [1, 2, 3, 3, 4]Utilisation decopyWithin() sur des tableaux creux
copyWithin() propage les cases vides.
console.log([1, , 3].copyWithin(2, 1, 2)); // [1, vide, vide]Appel decopyWithin() sur des objets qui ne sont pas des tableaux
La méthodecopyWithin() lit la propriétélength dethis puis manipule les indices entiers concernés.
const objetSimilaireTableau = { length: 5, 3: 1,};console.log(Array.prototype.copyWithin.call(objetSimilaireTableau, 0, 3));// { '0': 1, '3': 1, length: 5 }console.log(Array.prototype.copyWithin.call(objetSimilaireTableau, 3, 1));// { '0': 1, length: 5 }// La propriété '3' est supprimée car la source copiée est une case videSpécifications
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-array.prototype.copywithin |