【Googleスプレッドシート】Apps Scriptでセルに値を書き込む!setValueとsetValuesの違い

Google Apps Scriptを使ってスプレッドシートを操作していると、セルへの値の書き込みには「setValue」と「setValues」の2つのメソッドがあることに気づきます。どちらもよく似ていますが、使い方やパフォーマンスに大きな違いがあります。この記事では、setValueとsetValuesの違いを詳しく解説し、状況に応じた使い分けができるようになります。

setValueとsetValuesの基本的な違い

setValueとsetValuesは、どちらもRangeオブジェクトのメソッドです。setValueは1つのセルに1つの値を設定するのに対し、setValuesは複数のセルに2次元配列(配列の配列)を一度に設定します。ここでは、構文と動作の違いを説明します。

setValueの構文と動作

setValueは引数に任意の値を1つだけ取ります。指定したRangeが単一セルの場合、そのセルに値が書き込まれます。Rangeが複数セルを指している場合は、先頭セル(左上)だけに値が書き込まれ、他のセルは空白になるか、元の値が消える可能性があるため注意が必要です。

setValuesの構文と動作

setValuesは引数に2次元配列を取ります。配列の行数と列数は、対象のRangeの行数と列数に一致しなければなりません。一致しない場合はエラーになります。setValuesはスプレッドシートAPIへの呼び出し回数が1回で済むため、大量データの書き込みに適しています。

具体的な使用例とパフォーマンス比較

実際のコード例を使って、setValueとsetValuesの使い方とパフォーマンスの違いを確認します。シートにデータを書き込む典型的なシナリオで比較します。

setValueを使ったループ書き込み

1. 単一セルへの書き込み
   次のコードは、A1セルに「Hello」と書き込みます。
   SpreadsheetApp.getActiveSheet().getRange('A1').setValue('Hello');
2. ループによる複数セルへの書き込み
   下の例では、A1からA10まで1から10の数値をループで書き込んでいます。1セルずつsetValueを呼び出すため、10回のAPI呼び出しが発生します。
   for (let i = 1; i <= 10; i++) { sheet.getRange(i, 1).setValue(i); }

setValuesによる一括書き込み

1. 2次元配列の作成
   まず、書き込むデータを2次元配列で用意します。行と列の構造を持ちます。
   const data = [];
for (let i = 1; i <= 10; i++) { data.push([i]); // 1列の場合 }
2. setValuesで一括書き込み
   対象範囲を指定し、setValuesに配列を渡します。
   sheet.getRange(1, 1, data.length, data[0].length).setValues(data);
   これで1回のAPI呼び出しで10セルに書き込めます。

パフォーマンスの違い

スプレッドシートAPIへの呼び出し回数は、setValueをループで使うとセル数分だけ増えます。一方、setValuesは1回で済むため、特に100セル以上の大量データでは処理時間に顕著な差が出ます。計測例では、1000セルへの書き込みでsetValueループが約2秒かかるのに対し、setValuesは0.1秒未満という結果がよく報告されています。

注意点とよくあるエラー

setValueとsetValuesを使う際に陥りやすいミスと、その対処法を説明します。特に配列のサイズ不一致や型の扱いに注意してください。

setValuesの配列サイズがRangeと合わない

setValuesに渡す配列の行数と列数が、指定したRangeの行数・列数と一致しないとエラーになります。例えば、Rangeが5行3列なのに4行2列の配列を渡すと「The number of rows or columns in the data does not match the number of rows or columns in the range.」というエラーが発生します。事前に配列の長さとRangeのサイズを確認するコードを入れましょう。

setValueで複数セル指定したときの挙動

setValueを複数セルのRangeに対して使うと、先頭セル(左上)だけに値が設定され、他のセルはクリアされます。誤って広い範囲を指定すると、意図しないデータ消失を招く恐れがあります。必ず単一セルを指定するか、getRangeの引数に行と列を1つずつ渡すようにします。

日付や通貨の書式設定

setValueやsetValuesで値を書き込むと、セルの書式は自動判定されます。日付の文字列を入れてもシリアル値として認識されない場合があります。日付として正しく表示したい場合は、setNumberFormatなどで明示的に書式を設定するか、Dateオブジェクトを直接書き込みます。setValuesでも同様です。

setValueとsetValuesの比較表

まとめ

セルへの値書き込みには、単一セルにはsetValue、複数セルにはsetValuesを使い分けるのが基本です。setValueのループで多数のセルを更新するよりも、setValuesで一括処理する方がスクリプトの実行時間を大幅に短縮できます。また、setValuesを使う際は配列のサイズとRangeのサイズを必ず一致させる必要があります。この使い分けをマスターすることで、効率的なスプレッドシート操作が可能になります。