日付と数値の形式

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

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

スプレッドシートの UI では、[表示形式] > [数字] メニューを使用して、セルに数値と日付の形式を適用します。Google スプレッドシート API では、 a spreadsheets.batchUpdate メソッド呼び出しを使用して UpdateCellsRequest または RepeatCellRequestを送信することで、これらの形式を設定します。

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

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

日付と時刻の値について

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

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

スプレッドシートでは、1900 年はうるう年ではなく平年として正しく処理されます。

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

日付と時刻の形式パターンは、解析されると対応する日付と時刻の要素（月や時間など）に置き換えられるトークン サブストリングの文字列です。

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

次の表に、日付と時刻の形式パターンで使用できるトークン部分文字列の定義を示します。+ 文字は、前の文字が 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 1 分内の秒（先頭に 0 は付きません）。
ss 1 分内の秒（先頭に 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." 04:08 P.M.
yyyy-mm-dd 2016-04-05
mmmm d \[dddd\] April 5 [Tuesday]
h PM, ddd mmm dd 4 PM, Tue Apr 05
dddd, m/d/yy at h:mm Tuesday, 4/5/16 at 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 #、または ?）の間に表示される場合は、グループ区切り文字（3 桁区切り）を使用して数値全体 をレンダリングします。数字の後に続く場合は、カンマごとに数字を 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 になると、分数部分はレンダリングされません。数値形式 0 #/3 の数値 23.1 は、 23 としてレンダリングされます（0.1 は 0/3 に丸められるため）。/ は 科学形式または小数点を含む形式と互換性がありません 。
* これは、Microsoft Excel の数値形式との互換性のために含まれています。無視されます。
_ アンダースコア トークンは次の文字をスキップし、スペースをレンダリングします。これは、負の値がかっこで囲まれている数値形式を揃えるために使用されます。
\ 次の文字をリテラル値として扱い、特別な 意味は持ちません。たとえば、数値形式 \#0 は、数値 10 を「#10」としてレンダリングします。
"text" 引用符で囲まれたテキストをリテラルとして表示します。
@ セルにテキストが入力されている場合は、セルの未加工のテキストが挿入されます。他の特殊文字とは互換性がなく、数値（一般的な形式で表示される）には表示されません。
$ - + ( ) : space スプレッドシートでは、これらの文字はリテラルとして扱われ、変更されずに表示されます 。

メタ命令

また、各形式セクションには、形式の前に配置され、追加の指示を提供する [] 文字で囲まれたオプションのメタ命令を含めることができます。メタ命令には 2 種類あり、1 つのセクションで両方を使用できます。

手順 説明
[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 プロパティに基づいています。

数値の形式の例

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

数値 柄 書式設定された値
12345.125 ####.# 12345.1
12.34 000.0000 012.3400
12 #.0# 12.0
5.125 # ???/??? 5 1/8
12000 #,### 12,000
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 HIGH
LOW
0527