実行環境 Node.js 15.2.1

公開日 February 27, 2021, GMT+9

コード例の出力としてconsole.logを使用しています。

使用方法がわからない場合は以下のページを参照してからコード例を確認してください。

console.logの使用方法

unshift(Array、配列)

このページでは豊富な例を用いてJavaScript(js)のArrayオブジェクトのunshiftメソッドの使い方を学ぶことができます。

JavaScript(js)のunshiftメソッドはArrayオブジェクト(配列)のメソッドの1つです。

unshiftメソッドは「呼び出し元の配列の先頭」に「引数で指定した値」を追加し、呼び出した配列自体を変更します。
返り値として要素を追加された後の配列の長さ(length)が返されます。

// 記述例

先頭に要素を追加したい配列.unshift(追加する値)

TL;DR

基本

// 引数で与えた値を配列の先頭に追加する、返り値は変更後の配列の長さ(length)
const array1 = ['js', 'javascript', 'typescript'];
console.log(array1);
==> [ 'js', 'javascript', 'typescript' ]
console.log(array1.length);
==> 3

// 先頭に文字列を追加
const returnValue1 = array1.unshift('FooBarNinja');
console.log(array1);
==> [ 'FooBarNinja', 'js', 'javascript', 'typescript' ]
console.log(array1.length);
==> 4
console.log(returnValue1);
==> 4







// 引数を複数与えることもできる
const array2 = ['js', 'javascript'];
const returnValue2 = array2.unshift('Foo', 'Bar', 'Ninja');
console.log(array2);
==> [ 'Foo', 'Bar', 'Ninja', 'js', 'javascript' ]
console.log(returnValue2);
==> 5
console.log(array2.length);
==> 5






// 配列の追加
const array3 = ['apple', 'pen'];
const array3_1 = ['pen', 'pineapple'];
const returnValue3 = array3.unshift(array3_1);
console.log(array3);
==> [ [ 'pen', 'pineapple' ], 'apple', 'pen' ]
console.log(returnValue3);
==> 3






// 配列をスプレッド構文で展開
const array4 = ['apple', 'pen'];
const array4_1 = ['pen', 'pineapple'];
const returnValue4 = array4.unshift(...array4_1);
console.log(array4);
==> [ 'pen', 'pineapple', 'apple', 'pen' ]
console.log(returnValue4);
==> 4






// オブジェクトの追加
const array5 = [true, 100];
array5.unshift({ id: 1, name: 'node' });
console.log(array5);
==> [ { id: 1, name: 'node' }, true, 100 ]

配列に似たオブジェクトに対する使用

const arrayLikeObject1 = { 0: 'Foo', 1: 'Bar', 2: 'Ninja', length: 3 };
const returnValue1 = Array.prototype.unshift.call(arrayLikeObject1, 'js', 'JavaScript');
console.log(arrayLikeObject1);
------------------------------
{
  '0': 'js',
  '1': 'JavaScript',
  '2': 'Foo',
  '3': 'Bar',
  '4': 'Ninja',
  length: 5
}
------------------------------
console.log(returnValue1);
==> 5

解説

// 記述例

先頭に要素を追加したい配列.unshift(追加する値)

基本

unshiftメソッドは「呼び出した配列の先頭」に「引数で指定した値」を追加し、呼び出し元の配列自体を変更します。
「要素が追加された後の呼び出し元の配列の長さ(length)」を返り値として返します。

引数には全ての型の値を指定することができます。
また、不定数の引数(残余引数、可変長引数、rest parameters)、つまり複数の引数を取ることができ、先頭に追加される順番は引数で与えた順番と同一です。

const array1 = ['A', 'B', 'C'];
console.log(array1);
==> [ 'A', 'B', 'C' ]
console.log(array1.length);
==> 3

const returnValue1 = array1.unshift('D');
console.log(array1);
==> [ 'D', 'A', 'B', 'C' ]
console.log(returnValue1);
==> 4
console.log(array1.length);
==> 4







// 複数の引数の指定
const array2 = ['A', 'B', 'C'];
const returnValue2 = array2.unshift('a', 'b', 'c');
console.log(array2);
==> [ 'a', 'b', 'c', 'A', 'B', 'C' ]
console.log(returnValue2);
==> 6






// 配列の追加
const array3 = ['A', 'B', 'C'];
const array3_1 = ['Foo', 'Bar', 'Ninja'];
const returnValue3 = array3.unshift(array3_1);
console.log(array3);
==> [ [ 'Foo', 'Bar', 'Ninja' ], 'A', 'B', 'C' ]
console.log(returnValue3);
==> 4






// スプレッド構文で引数を展開する
const array4 = ['A', 'B', 'C'];
const array4_1 = ['Foo', 'Bar', 'Ninja'];
const returnValue4 = array4.unshift(...array4_1);
console.log(array4);
==> [ 'Foo', 'Bar', 'Ninja', 'A', 'B', 'C' ]
console.log(returnValue4);
==> 6






// オブジェクトの追加
const array5 = [1, false];
const object5 = { page: 'unshift', language: 'javascript' };
array5.unshift(object5);
console.log(array5);
==> [ { page: 'unshift', language: 'javascript' }, 1, false ]

配列に似たオブジェクトに対する使用

callメソッドやapplyメソッドを使用することで「配列に似たオブジェクト」に対してもunshiftメソッドを使用することができます。

対象のオブジェクトは数値のプロパティやlengthプロパティなどを持っているなど、配列に似た特徴を備えている必要があります。

コード例としてcallメソッドを使用した呼び出し例を記載しますので参考にしてください。

const arrayLikeObject1 = { 0: 'A', 1: 'B', length: 2 };
const returnValue1 = Array.prototype.unshift.call(arrayLikeObject1, true, 100);
console.log(arrayLikeObject1);
==> { '0': true, '1': 100, '2': 'A', '3': 'B', length: 4 }
console.log(returnValue1);
==> 4

1次情報

Array.prototype.unshift() - MDN web docs

スプレッド構文 - MDN web docs

Function.prototype.call() - MDN web docs

残余引数 - MDN web docs