AppsScriptでスプレッドシートのセルにフォーマットを設定する

こんにちは、村上です。

スプレッドシートを使っているとセルには様々な種類の値を入力すると思います。
また、入力した値のフォーマットを指定したりもすると思います。
AppsScriptからも同様にスプレッドシートに色々な値の入力やフォーマットの指定ができます。
今回は、スプレッドシートのセルにフォーマットを設定する方法を紹介します。

フォーマットの指定

AppsScriptでは Range.setNumberFormat(String) 関数でセルにフォーマットを指定できます。フォーマットは文字列で指定します。
この関数はsetNumberFormatという名前の関数ですが、数値だけでなく日付の値のフォーマットも指定できます。

例えば、次のコードは常に小数点3桁を表示するフォーマットを現在選択しているセルに指定しています。
コードを実行するとセルには1.200と表示されます。

1
2
3
var range = SpreadsheetApp.getActiveRange();
range.setNumberFormat('0.000');
range.setValue(1.2);

日付の場合は、次のように設定します。
この例では、現在日時を年月日、曜日、時分秒のフォーマット(例えば、2015年8月31日 月曜日 21時58分16秒)で表示するように指定しています。

1
2
3
var range = SpreadsheetApp.getActiveRange();
range.setNumberFormat('yyyy年mm月dd日 dddd h時mm分ss秒');
range.setValue(new Date());

このようにセルにフォーマットを指定すれば、利用者に対してより適切な形式で値を表示できるようになります。

フォーマットを指定しない場合の振る舞い

フォーマットを明示的に指定しない場合、自動でセルの値から推測されるフォーマットが適用されます。
例えば、文字列として8-30と入力すると2015/8/30と日付として値が設定されます。AppsScriptからこのセル値を取得するとStringではなくDateのオブジェクトが返ってきます。この振る舞いは次のコードで確認できます。

1
2
3
4
var range = SpreadsheetApp.getActiveRange();
range.setValue('8-31');
var value = range.getValue();
Logger.log(value); // "Mon Aug 31 00:00:00 GMT+09:00 2015"が出力される

この振る舞いは、セルの値として Date を期待している場合は問題ありませんが、String を期待している場合には厄介です。
String を期待して値を設定したにもかかわらず値を取得すると Date になっているので、セルから取得できる値が String であることを前提にコーディングしていると期待したように動作しなくなってしまいます。

このような場合、セルにフォーマットを指定することで期待した内容で値が設定されるようにします。
先ほどのコードの 8-31 をそのまま String として扱いたい場合は @[1]という文字列をフォーマットとして指定します。
8-31 が String として設定、取得できることは次のコードで確認できます。

1
2
3
4
5
var range = SpreadsheetApp.getActiveRange();
range.setNumberFormat('@'); // 文字列をそのまま表示するフォーマット
range.setValue('8-31');
var value = range.getValue();
Logger.log(value); // "8-31"が出力される

まとめ

AppsScriptでスプレッドシートのセルにフォーマットを指定する方法を紹介しました。
Range.setNumberFormat(String) 関数でセルにフォーマットを指定できます。
フォーマットを指定しない場合には自動でフォーマットが適用されるので、必要に応じて明示的にフォーマットを指定するようにしましょう。

  1. @ は入力された値を文字列のまま扱うフォーマットです。これ以外にも指定できるフォーマット文字列はドキュメントエディタヘルプの 数値、日付、通貨の表示形式を設定する で確認できます。