日付と数値の形式

このドキュメントでは、API リクエストに含めることができる新しい日付と数値の形式パターンを定義する方法について説明します。

日時と数値の形式を設定すると、シートでのデータの表示方法を制御できます。Google スプレッドシートには、選択可能な一般的な形式がいくつか用意されていますが、独自の形式を定義することもできます。

スプレッドシートの UI では、[表示形式] > [数字] メニューを使用して、セルに数値と日付の形式を適用します。Google Sheets API では、spreadsheets.batchUpdate メソッド呼び出しを使用して UpdateCellsRequest または RepeatCellRequest を送信することで、これらの形式を設定します。リクエストでは、NumberFormatType（NUMBER、CURRENCY、PERCENT、DATE、TIME など）とオプションの pattern 文字列を指定して、NumberFormat オブジェクトを構成します。pattern を省略すると、スプレッドシートの locale に基づいて、指定された type のデフォルトの形式パターンが使用されます（例: en_US の CURRENCY の場合は $1,000.12）。

サンプル範囲にカスタムの日時または 10 進数形式を設定するでは、Sheets API を使用して形式パターンを設定する方法を示しています。形式の実際のレンダリングは、スプレッドシートの locale によって異なります。このドキュメントでは、locale が en_US であることを前提としています。スプレッドシートの locale を確認するには、spreadsheets リソースの spreadsheets.get メソッドを使用して SpreadsheetProperties オブジェクトを読み取ります。

その他のサンプルについては、基本的な書式設定と条件付き書式設定をご覧ください。

日付と時刻の値について

スプレッドシートは、他のほとんどのスプレッドシート アプリケーションと同様に、日付と時刻の値を 10 進数値として扱います。これにより、数式で算術演算を実行できるため、日や週の増分、2 つの日時の加算や減算、その他の同様の演算を実行できます。

スプレッドシートでは、スプレッドシートで一般的に使用されるエポック日付の形式が使用されます。値の整数部分（小数点の左側）は、1899 年 12 月 30 日からの日数をカウントします。小数部分（小数点の右側）は、1 日の端数として時間をカウントします。たとえば、1900 年 1 月 1 日の正午は 2.5、2 です。これは、1899 年 12 月 30 日から 2 日後であるためです。また、正午は半日であるため、0.5 です。1900 年 2 月 1 日午後 3 時は 33.625 です。

スプレッドシートでは、1900 年はうるう年ではなく平年として正しく扱われます。日付と時刻のシリアル番号には、タイムゾーン オフセットは保存されません。代わりに、スプレッドシートの timeZone に基づいています。これは、spreadsheets.get メソッドを使用して SpreadsheetProperties オブジェクトから読み取ることができます。

日付と時刻の形式パターン

日時形式パターンは、トークン部分文字列の文字列です。スプレッドシートは、解析時に対応する日時要素（月や時間など）に置き換えます。

日付と時刻の形式トークン

次の表に、日時形式パターンで使用できるトークン部分文字列を示します。+ 文字は、直前の文字が 1 回以上出現してもパターンに一致することを示します。この表に記載されていない文字はリテラルとして扱われ、変更されずに出力されます。

トークン 説明
h 時間帯。文字列に AM または PM のインジケーターが存在するかどうかに応じて、12 時間形式と 24 時間形式を切り替えます。
hh+ 前と同じですが、1 ～ 9 の場合は先頭に 0 が付きます。
m 前の非リテラル トークンが時間、または次の非リテラル トークンが秒の場合、1 時間の分を表します（先頭に 0 は付きません）。それ以外の場合は、月を数値（先頭に 0 を付けない）で表します。
M 先頭に 0 が付かない月。このトークンを使用すると、パターンで分ではなく月を明示的に指定できます。
mm m と同じですが、どちらの場合も先頭に 0 が付きます。
MM 先頭に 0 が付いた月。このトークンを使用すると、パターンで分ではなく月を明示的に指定できます。
mmm 3 文字の月の略語（例: 「Feb」）。
mmmm 完全な月の名前。mmmmmm+ もこれに一致します。
mmmmm 月の最初の文字（例: 6 月の場合は「J」）。
s 秒（先頭に 0 を付けない）。
ss 秒（先頭に 0 を付ける）。
[h+] 期間の経過時間数。文字数は、最小桁数を示します（先頭に 0 が追加されます）。
[m+] 期間の経過分数。文字数は、最小桁数を示します（先頭に 0 が追加されます）。
[s+] 期間の経過秒数。文字数は、最小桁数を示します（先頭に 0 が追加されます）。
d 月の日付。10 未満の数字の先頭に 0 は付きません。
dd 月の日付。10 未満の数値の場合は先頭に 0 が付きます。
ddd 曜日（3 文字の略語、例: 「Mon」）。
dddd+ 曜日（フルネーム）。
y 2 桁の年。
yy
yyy 4 桁の年。
yyyy+
a/p 午前は「a」、午後は「p」と表示されます。また、時刻を 12 時間形式に変更します。トークンの文字が大文字の場合、出力も大文字になります。
am/pm 上記と同じですが、「AM」または「PM」が表示され、常に大文字になります。
0 10 分の 1 秒。00 を使用して精度を 2 桁に、000 を使用して 3 桁（ミリ秒）に増やすことができます。
\ 次の文字をリテラル値として扱い、特別な意味を持たせません。
"text" 引用符内のテキストをリテラルとして表示します。

日付と時刻の形式の例

次の表に、日時 Tuesday, April 5, 2016, 4:08:53.528 PM を指定した場合のパターンと、それに対応する日時のレンダリングの例を示します。表の 2 番目のセクションには、経過時間 3 hours, 13 minutes, 41.255 seconds の経過時間形式の例が示されています。

日時パターン Tuesday, April 5, 2016, 4:08:53.528 PM
h:mm:ss.00 a/p 4:08:53.53 p
hh:mm A/P".M." 16:08
yyyy-mm-dd 2016-04-05
mmmm d \[dddd\] 4 月 5 日（火）
h PM, ddd mmm dd 4 月 5 日（火）16:00
dddd, m/d/yy at h:mm 2016 年 4 月 5 日（火）16:08
経過時間パターン 3 hours, 13 minutes, 41.255 seconds
[hh] 03
[mmmm] 0193
[ss] 11621

数値形式パターン

数値形式パターンは、トークンの部分文字列の文字列です。スプレッドシートは、解析時に対応する数値表現に置き換えます。数値形式パターンは、セミコロンで区切られた最大 4 つのセクションで構成できます。これらのセクションでは、正の数、負の数、ゼロ、テキスト（この順序）に使用される個別の形式を定義します。

[POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT];[TEXT FORMAT]

4 つのセクションすべてをフォーマットに含める必要はありません。セクションを 1 つだけ含めると、スプレッドシートはその形式をすべての値に使用します。2 つのセクションを使用すると、最初の形式がゼロと正の数に適用され、2 番目の形式が負の数に適用されます。3 つのセクションを使用すると、正の数、負の数、ゼロの数に個別の形式を定義できます。次に例を示します。

[NUMBER FORMAT]
[POSITIVE/ZERO FORMAT];[NEGATIVE FORMAT]
[POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT]

ただし、セクションが 2 つ以上あり、最後のセクションがテキスト形式の場合、スプレッドシートはそのセクションをテキスト形式として扱い、他のセクションはセクションが 1 つ少ないかのように動作します。したがって、最終的なテキスト形式を含めることで、次のような形式を定義できます。

[POSITIVE/ZERO FORMAT];[NEGATIVE FORMAT];[TEXT FORMAT]
[NUMBER FORMAT];[TEXT FORMAT]

形式のセクションへの解析は他の解析の前に行われるため、日付または時刻の形式をセクションの 1 つとして含めることができます（ただし、これは限定的なユーティリティです）。

数値形式のトークン

次の表に、フォーマット セクションで使用できるトークン部分文字列を示します。これを使用して、そのセクションの値を表す方法を定義できます。

トークン 説明
0 数値の桁を表します。数字が重要でない 0 の場合は、0 としてレンダリングされます。たとえば、数値形式 00.0 では、数値 3 は「03.0」としてレンダリングされます。
# 数値の桁を表します。桁が重要でない 0 の場合、レンダリングされません。たとえば、数値形式 ##0 を指定すると、数値 12 は「12」として表示されます。
? 数値の桁を表します。数字が重要でない 0 の場合は、スペースとしてレンダリングされます。これは、固定幅フォントを使用する場合に、列の小数点を揃えるためによく使用されます。たとえば、数値形式 ???.??? では、数値 12.4 は「12.4」としてレンダリングされます。
. 最初のピリオドは、数値の小数点を表します。後続のピリオドはリテラルとしてレンダリングされます。形式に小数点が含まれている場合、整数であっても常に小数点が表示されます。たとえば、#0.# は数値 3 を「3.」としてレンダリングします。
% リテラルとして表示されますが、既存の数値を 100 倍してからレンダリングすることで、パーセンテージを読みやすくします。たとえば、数値形式 #% では、数値 0.25 が「25%」としてレンダリングされます。
, 2 桁の数字（0、#、?）の間に表示される場合は、グループ区切り記号（1,000 単位のグループ化）を使用して数値全体をレンダリングします。数字の後に続く場合は、カンマごとに数字を 1,000 倍します（たとえば、#0.0,, 形式では、数値 12,200,000 は 12.2 としてレンダリングされます）。
E- 数値を科学的記数法でレンダリングします。E の左側の書式は指数以外の部分に使用され、E の右側の書式は指数部分に使用されます。E+ は、正の指数に + 記号を表示します。E- は、負の指数にのみ符号を表示します。小文字を使用すると、出力 e も小文字になります。たとえば、数値形式 ##0.00#E+## は、数値 0.0000001 を「100.00E-9」としてレンダリングします。
E+
e-
e+
/ 2 桁の文字（0、#、?）の間に表示される場合、これらの数字グループは分数形式として扱われます。たとえば、数値形式 0 #/# では、数値 23.25 が 23 1/4 としてレンダリングされます。分母をリテラル整数にすることもできます。その場合、その整数が分母として適用されます。数値形式 0 #/8 では、数値 23.25 が 23 2/8 として表示されます。分子が 0 になると、分数部分はレンダリングされません。数値 23.1 を数値形式 0 #/3 で表示すると、23 とだけ表示されます（0.1 が 0/3 に丸められるため）。/ は、科学形式または小数点を含む形式と互換性がありません。
* Microsoft Excel の数値形式との互換性を確保するために含まれています。 スプレッドシートでは、このトークンは無視されます。
_ 次の文字をスキップしてスペースをレンダリングします。このトークンは、負の値がかっこで囲まれている数値形式を揃えるために使用します。
\ 次の文字をリテラル値として扱い、特別な意味を持たせません。たとえば、数値形式 \#0 では、数値 10 は「#10」としてレンダリングされます。
"text" 引用符内のテキストをリテラルとして表示します。
@ セルにテキスト入力がある場合は、セルの未加工テキストが挿入されます。他の特殊文字との互換性はなく、数値（標準形式で表示される）には表示されません。
$ - + ( ) : space スプレッドシートでは、これらの文字と一般的な通貨記号（$、€、£、¥ など）はリテラルとして扱われ、変更されずに表示されます。

メタ指示

さらに、各フォーマット セクションには、フォーマットの前に [] 文字で囲まれたオプションのメタ指示を含めることができます。これにより、追加の指示を提供できます。

指示 説明
[condition] セクションのデフォルトの正、負、ゼロの比較を別の条件式に置き換えます。たとえば、[<100]"Low";[>1000]"High";000 は、100 未満の値には「Low」、1000 を超える値には「High」、その間の値には 3 桁の数字（先頭に 0 を付加）を表示します。条件を適用できるのは最初の 2 つのサブ形式のみです。数値が複数の条件に一致する場合は、最初に一致した条件が使用されます。3 つ目の形式がある場合、スプレッドシートはそれを「その他すべて」に使用します。それ以外の場合、数値がどちらの形式にも一致しないと、スプレッドシートはセルの幅全体に「#」文字をレンダリングします。存在する場合、4 番目の形式は常にテキストに使用されます。
[Color] or [Color#] このサブフォーマットでレンダリングされる値が、指定されたテキストの色で表示されます。Color の有効な値は、Black、Blue、Cyan、Green、Magenta、Red、White、Yellow です。Color# の「#」の有効な値は 1 ～ 56 です。数値形式の色は、セルにユーザーが入力した色をオーバーライドしますが、条件付き書式で設定された色はオーバーライドしません。このカラーパレットには、各数字に対応する色のリストが表示されます。これらは、Microsoft Excel の ColorIndex プロパティに基づいています。
[$currency] 指定した通貨記号または通貨コードをリテラルとして表示します（例: [$€]#,##0.00、[$CAD]#,##0.00）。ハイフンの後にオプションのロケール コード（[$CAD-1009] など）を指定した場合、スプレッドシートはそのロケール コードを無視します。

数値形式の例

次の表に、パターンの例と、対応する書式設定された数値のレンダリングを示します。

数値 パターン 書式設定された値
12345.125 ####.# 12345.1
12.34 000.0000 012.3400
12 #.0# 12.0
5.125 # ???/??? 5 1/8
12000 #,### 12,000
1234.56
-1234.56		 $#,##0.00;($#,##0.00) $1,234.56
（$1,234.56）
1230000 0.0,,"M" 120 万
1234500000 0.00e+00 1.23e+09
123114.15115
MyText		 ###0.000;"TEXT: "_(@_) 123114.151
TEXT: MyText
1234
-1234
0
MyText		 [Blue]#,##0;[Red]#,##0;[Green]0.0;[Magenta]_(@_) 1,234
1,234
0.0
MyText
1005
32
527		 [>1000]"HIGH";[Color43][<=200]"LOW";0000 高
低
0527