La méthodejoin() des instances deArray crée et retourne une nouvelle chaîne de caractères en concaténant tous les éléments de ce tableau, séparés par des virgules ou par une chaîne de séparation définie. Si le tableau ne contient qu'un seul élément, cet élément est retourné sans utiliser le séparateur.

Exemple interactif

const elements = ["Feu", "Air", "Eau"];console.log(elements.join());// Résultat attendu : « Feu,Air,Eau »console.log(elements.join(""));// Résultat attendu : « FeuAirEau »console.log(elements.join("-"));// Résultat attendu : « Feu-Air-Eau »

Syntaxe

join()join(separator)

Paramètres

separatorFacultatif

Une chaîne de caractères utilisée pour séparer chaque paire d'éléments adjacents du tableau. Si ce paramètre est omis, les éléments du tableau sont séparés par une virgule (",").

Valeur de retour

Une chaîne de caractères contenant tous les éléments du tableau fusionnés. Siarray.length vaut 0, une chaîne de caractères vide est retournée.

Description

Les conversions en chaîne de caractères de tous les éléments du tableau sont jointes en une seule chaîne de caractères. Si un élément vautundefined ounull, il est converti en chaîne de caractères vide au lieu de la chaîne de caractères"null" ou"undefined".

La méthodejoin est utilisée en interne parArray.prototype.toString() sans argument. Redéfinirjoin sur une instance de tableau redéfinit aussi son comportementtoString.

Array.prototype.join convertit récursivement chaque élément, y compris les tableaux imbriqués, en chaînes de caractères. Comme la chaîne retournée parArray.prototype.toString (équivalent àjoin()) ne contient pas de séparateurs, les tableaux imbriqués semblent aplatis. Vous ne pouvez contrôler que le séparateur du premier niveau, les niveaux plus profonds utilisent toujours la virgule par défaut.

const matrice = [  [1, 2, 3],  [4, 5, 6],  [7, 8, 9],];console.log(matrice.join()); // 1,2,3,4,5,6,7,8,9console.log(matrice.join(";")); // 1,2,3;4,5,6;7,8,9

Si un tableau est cyclique (il contient un élément qui fait référence à lui-même), les navigateurs évitent la récursion infinie en ignorant la référence cyclique.

const arr = [];arr.push(1, [3, arr, 4], 2);console.log(arr.join(";")); // 1;3,,4;2

Lorsqu'elle est utilisée sur untableau creux, la méthodejoin() itère sur les emplacements vides comme s'ils avaient la valeurundefined.

La méthodejoin() estgénérique. Elle attend uniquement que la valeur dethis possède une propriétélength et des propriétés à clés entières.

Exemples

Fusionner un tableau de quatre façons différentes

L'exemple suivant crée un tableau,a, avec trois éléments, puis joint le tableau à trois reprises : en utilisant le séparateur par défaut, une virgule et un espace, puis un plus, puis avec la chaîne vide.

const a = new Array("Vent", "Pluie", "Feu");a.join(); // "Vent,Pluie,Feu"a.join(", "); // "Vent, Pluie, Feu"a.join(" + "); // "Vent + Pluie + Feu"a.join(""); // "VentPluieFeu"

Utiliserjoin() sur un tableau creux

join() traite les emplacements vides comme des valeursundefined et produit un séparateur supplémentaire :

console.log([1, , 3].join()); // '1,,3'console.log([1, undefined, 3].join()); // '1,,3'

Appelerjoin() sur des objets qui ne sont pas des tableaux

La méthodejoin() lit la propriétélength dethis puis accède à chaque propriété dont la clé est un entier non négatif inférieur àlength.

const objetSimilaireTableau = {  length: 3,  0: 2,  1: 3,  2: 4,  3: 5, // ignoré par join() car length vaut 3};console.log(Array.prototype.join.call(objetSimilaireTableau));// 2,3,4console.log(Array.prototype.join.call(objetSimilaireTableau, "."));// 2.3.4

Spécifications

Compatibilité des navigateurs

Voir aussi

• Guide des collections indexées
• L'objet globalArray
• La méthodeString.prototype.split()
• La méthodeArray.prototype.toString()
• La méthodeTypedArray.prototype.join()
• Prothèse d'émulation deArray.prototype.join dans core-js^(angl.)
• Prothèse d'émulation es-shims deArray.prototype.join^(angl.)