Array : méthode copyWithin() - JavaScript | MDN

Basculer la barre latérale

Thème

Automatique
Clair
Sombre

Français

Se souvenir de la langue En savoir plus

Array : méthode copyWithin()

Baseline Large disponibilité

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éthode copyWithin() des instances de Array copie superficiellement une partie de ce tableau à un autre emplacement dans le même tableau et retourne ce tableau sans en modifier la longueur.

Dans cet article

Exemple interactif

const array = ["a", "b", "c", "d", "e"];

// Copie à l'indice 0 l'élément à l'indice 3
console.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 fin
console.log(array.copyWithin(1, 3));
// Résultat attendu : Array ["d", "d", "e", "d", "e"]

L'indice (à partir de zéro) auquel copier la séquence, converti en entier. Cela correspond à l'emplacement où l'élément à l'indice start sera copié, et tous les éléments compris entre start et end seront copiés aux indices suivants.

Un indice négatif compte à rebours depuis la fin du tableau — si -array.length <= target < 0, on utilise target + array.length.
Si target < -array.length, on utilise 0.
Si target >= array.length, rien n'est copié.
Si target est positionné après start après normalisation, la copie ne se fait que jusqu'à la fin de array.length (autrement dit, copyWithin() n'étend jamais le tableau).

start

L'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 utilise start + array.length.
Si start < -array.length, on utilise 0.
Si start >= array.length, rien n'est copié.

end Facultatif

L'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 utilise end + array.length.
Si end < -array.length, on utilise 0.
Si end >= array.length ou si end est omis ou undefined, on utilise array.length, ce qui fait que tous les éléments jusqu'à la fin sont copiés.
Si end implique une position avant ou à la même position que celle impliquée par start, rien n'est copié.

Valeur de retour

Le tableau modifié.

Description

La méthode copyWithin() fonctionne comme memmove 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éthode TypedArray 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.

Comme undefined devient 0 lorsqu'il est converti en entier, omettre le paramètre start a le même effet que de passer 0, 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 explicitement 0 comme valeur de start.

js
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 droite

La méthode copyWithin() est une méthode de mutation. Elle ne modifie pas la longueur de this, mais elle modifie le contenu de this et peut créer de nouvelles propriétés ou supprimer des propriétés existantes si nécessaire.

La méthode copyWithin() préserve les cases vides. Si la région à copier est creuxe, les nouveaux indices correspondants des cases vides sont supprimés et deviennent aussi des cases vides.

La méthode copyWithin() est générique. Elle attend seulement que la valeur de this 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 de copyWithin()

js
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 de copyWithin() sur des tableaux creux

copyWithin() propage les cases vides.

console.log([1, , 3].copyWithin(2, 1, 2)); // [1, vide, vide]

Appel de copyWithin() sur des objets qui ne sont pas des tableaux

La méthode copyWithin() lit la propriété length de this puis manipule les indices entiers concernés.

js
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 vide

Aider à améliorer MDN

Cette page vous a-t-elle été utile ?

Oui Non

Apprendre à contribuer

Cette page a été modifiée le 6 nov. 2025 par les contributeur·ice·s du MDN.

Voir cette page sur GitHub • Signaler un problème avec ce contenu

Objets natifs standards
Array
Constructeur
1. Array()
Méthodes statiques
Propriétés statiques
1. [Symbol.species]
Méthodes d'instance
Propriétés d'instance
1. length
2. [Symbol.unscopables]
Héritage
Object/Function
Méthodes statiques
Propriétés statiques
Méthodes d'instance
Propriétés d'instance
1. Object.prototype.__proto__
2. Object.prototype.constructor

Array : méthode copyWithin()

Dans cet article

Exemple interactif

Syntaxe

Paramètres