【Googleスプレッドシート】Apps Scriptでセル値を更新!setValue・setValuesの使い方

Googleスプレッドシートの自動化に欠かせないApps Scriptですが、セルに値を書き込む方法として「setValue」と「setValues」の2つがあり、どちらを使えばよいか迷うことはありませんか。どちらもセルの値を更新するメソッドですが、動作や使い方が異なります。この記事では、setValueとsetValuesの正しい使い方と、具体的なコード例を交えて解説します。これを読めば、単一セルから複数セルまで、状況に応じた最適な書き込み方法を身につけられます。

setValueとsetValuesの基本的な仕組み

Apps Scriptでセル値を操作するには、まずシート上の範囲をRangeオブジェクトとして取得します。そのRangeに対してsetValueまたはsetValuesメソッドを呼び出すことで、値を書き込みます。setValueは引数に数値、文字列、真偽値、日付などの単一の値を受け取ります。一方setValuesは、2次元配列(配列の配列)を受け取り、その配列の行と列が、指定したRangeの行と列に対応します。例えば、3行2列の範囲にsetValues([[1,2],[3,4],[5,6]])とすると、各セルに順番に値が入ります。

setValueの使い方とサンプルコード

setValueは最もシンプルな書き込み方法です。単一セルに固定値を入れたい場合や、ループ内で1つずつ値を設定するような場面で使います。ただし、パフォーマンスを重視する場合は、後述するsetValuesで一括更新するのがおすすめです。

基本的なsetValueの書き方

1. スクリプトエディタを開く
   スプレッドシートのメニューから「拡張機能」→「Apps Script」をクリックしてスクリプトエディタを開きます。
2. サンプルコードを記述する
   以下のコードを.gsファイルに貼り付けます。

   function setValueExample() {
     var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
     var cell = sheet.getRange('A1');
     cell.setValue('Hello, World!');
   }

3. 実行して確認する
   スクリプトエディタの実行ボタンを押すと、アクティブなシートのA1セルに「Hello, World!」と表示されます。

setValueで数式を書き込む

setValueは文字列だけでなく数式もそのままセルに設定できます。数式を文字列として渡すと、セルに数式として認識されます。

function setFormulaExample() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var cell = sheet.getRange('B1');
  cell.setValue('=SUM(A1:A10)');
}

このコードを実行すると、B1セルにSUM関数が入力され、A1からA10までの合計が計算されます。

setValuesの使い方とサンプルコード

setValuesは複数セルを一度に更新する強力なメソッドです。2次元配列を使い、一度のAPI呼び出しで大量のデータを書き込めるため、処理速度が大幅に向上します。特に数百行以上のデータを扱う場合は必須です。

基本的なsetValuesの書き方

1. 範囲を指定する
   書き込みたい範囲をgetRangeで指定します。例えばB2:D4なら3行3列です。
2. 2次元配列を用意する
   範囲の行数×列数のサイズの配列を作成します。例:3行3列なら [[1,2,3],[4,5,6],[7,8,9]]
3. setValuesを呼び出す
   用意した配列を引数にしてsetValuesを実行します。

   function setValuesExample() {
     var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
     var range = sheet.getRange('B2:D4');
     var data = [
       [1, 2, 3],
       [4, 5, 6],
       [7, 8, 9]
     ];
     range.setValues(data);
   }

動的にデータを作成して書き込む

実際の業務では、ループや別の関数の結果を配列に格納してからsetValuesで書き込むことが多いです。以下の例では、1から10までの数値とその2乗値をA1:B10に書き込みます。

function writeSquareData() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  var rows = 10;
  var cols = 2;
  var data = [];
  for (var i = 0; i < rows; i++) {
    var row = [];
    row.push(i + 1);
    row.push(Math.pow(i + 1, 2));
    data.push(row);
  }
  var range = sheet.getRange(1, 1, rows, cols);
  range.setValues(data);
}

setValueとsetValues使用時の注意点と制限

setValueとsetValuesにはいくつかの注意点があります。特にsetValuesの配列サイズと範囲サイズの不一致によるエラーは初心者がよく遭遇します。

setValuesの配列サイズと範囲サイズは完全一致が必要

setValuesに渡す2次元配列の行数と列数は、指定したRangeの行数・列数と完全に一致しなければなりません。一致しないと「配列のサイズが範囲のサイズと一致しません」というエラーが発生します。例えば3行2列の範囲に2行3列の配列を渡すとエラーになります。配列の行数はRangeの行数、配列の各要素の列数はRangeの列数と一致させる必要があります。

setValueの複数セル指定時の挙動

setValueは複数のセルを含むRangeに対して呼び出すこともできますが、その場合Rangeの先頭セル(左上)だけに値が書き込まれ、残りのセルは更新されません。これはよくある誤解なので注意しましょう。複数セルに同じ値を一括で書き込みたい場合は、setValuesで全セル分の配列を用意するか、ループでsetValueを繰り返す必要があります。ただし、ループはパフォーマンスが低下するため、同じ値でよければsetValuesで全セル同じ値を入れた配列を作るほうが効率的です。

大量データ書き込み時のパフォーマンス

100行を超えるようなデータを書き込む場合、setValueをループで使うと非常に遅くなります。setValuesは一度のAPI呼び出しで済むため、数十倍速くなることもあります。可能な限りsetValuesを使って一括更新しましょう。また、getValuesで一括取得し、加工後にsetValuesで一括書き戻す「バッチ処理」が推奨されます。

日付や通貨などの特別な値の扱い

setValuesでは、日付オブジェクトや数値、真偽値、文字列など、JavaScriptで扱える値をそのまま渡せます。ただし、日付を書き込むとスプレッドシートのシリアル値として認識されます。表示形式はシート側で設定する必要があります。また、通貨やパーセントなどの表示形式はsetValuesでは設定できません。表示形式を設定するには、setNumberFormatメソッドを別途呼び出してください。

setValueとsetValuesの比較表

項目	setValue	setValues
対象セル	単一セル(Rangeが複数セルの場合は先頭のみ)	複数セル(範囲全体)
引数	単一の値(文字列、数値、真偽値、日付など)	2次元配列
パフォーマンス	1回の呼び出しで1セル更新。ループで多数呼ぶと遅い	1回の呼び出しで全セル更新。大量データに最適
エラーが起きやすい点	複数セルを指定して全セルに書き込めない誤解	配列サイズと範囲サイズの不一致
代表的な使用シーン	特定の1セルだけ更新したい、動的に1つずつ値が決まる場合	データベースから抽出した表を一括貼り付け、計算結果の一括出力

まとめ

この記事では、Apps ScriptのsetValueとsetValuesの使い方と違いを解説しました。単一セルを更新するだけならsetValue、複数セルを効率的に更新するならsetValuesを使うのが基本です。特に大量データを扱う際は、必ずsetValuesを利用してパフォーマンスを改善しましょう。また、getValuesでデータを取得し、加工後にsetValuesで書き戻す一連の流れをマスターすれば、シート操作の自動化が飛躍的に進みます。次は、getValue/getValuesの使い方や、setValuesと組み合わせたデータ加工の応用例にも挑戦してみてください。