本文档介绍了如何定义新的日期和数字格式模式，您可以将其包含在 API 请求中。
日期时间格式和数字格式可用于控制数据在工作表中的显示方式。 Google 表格提供了一些常见格式供您选择，但您也可以自行定义格式。
在 Google 表格界面中，您可以使用格式 > 数字菜单将数字和日期格式应用于单元格。在 Google Sheets API 中，您可以使用 spreadsheets.batchUpdate 方法调用来发送 UpdateCellsRequest 或 RepeatCellRequest，从而设置这些格式。在请求中，您可以通过指定 NumberFormatType（例如 NUMBER、CURRENCY、PERCENT、DATE 或 TIME）和可选的 pattern 字符串来配置 NumberFormat 对象。如果您省略 pattern，Google 表格会根据电子表格的 locale，为指定的 type 使用默认格式模式（例如，en_US 中的 CURRENCY 对应 $1,000.12）。
为范围设置自定义日期时间或十进制格式示例展示了如何使用 Sheets API 设置格式模式。请注意，格式的实际呈现取决于电子表格的 locale。本文档假定 locale 为 en_US。您可以通过对 spreadsheets 资源使用 spreadsheets.get 方法读取 SpreadsheetProperties 对象，从而确定电子表格的 locale。
日期和时间值简介
与大多数其他电子表格应用一样，Google 表格会将日期和时间值视为十进制值。这样，您就可以在公式中对它们执行算术运算，从而增加天数或周数、对两个日期和时间进行加减运算，以及执行其他类似操作。
Google 表格使用电子表格中常用的纪元日期形式。该值的整数部分（小数点左侧）表示自 1899 年 12 月 30 日以来的天数。小数部分（小数点右侧）将时间计为一天的分数。例如，1900 年 1 月 1 日中午是 2.5，2 是因为该日期是 1899 年 12 月 30 日之后的第 2 天，0.5 是因为中午是一天的一半。1900 年 2 月 1 日下午 3 点为 33.625。
Google 表格会将 1900 年正确视为平年，而不是闰年。日期和时间序列号不存储时区偏移量。而是基于电子表格的 timeZone，您可以使用 spreadsheets.get 方法从 SpreadsheetProperties 对象中读取该值。
日期和时间格式模式
日期时间格式模式是一个由标记子字符串组成的字符串，在解析时，Google 表格会将其替换为相应的日期时间元素（例如月份或小时）。
日期和时间格式标记
下表定义了您可以在日期时间格式模式中使用的令牌子字符串。+ 字符表示前一个字符可以出现一次或多次，并且仍与模式匹配。Google 表格会将未在此表中列出的字符视为字面量，并原样输出。
| 令牌 | 说明 |
|---|---|
h |
一天中的时段。根据字符串中是否存在“凌晨/上午”或“下午/晚上”指示器，在 12 小时制和 24 小时制之间切换。 |
hh+ |
与上一个相同，但 1-9 带有前导 0。 |
m |
如果前一个非字面量令牌是小时，或者后一个非字面量令牌是秒，则表示小时中的分钟（不带前导 0）。否则，它会将一年中的月份表示为数字（不带前导 0）。 |
M |
一年中的月份，不含前导 0。使用此令牌可在模式中明确指定月份（而非分钟）。 |
mm |
与 m 相同，但两种情况下都带有前导 0。 |
MM |
一年中的月份，以 0 开头。使用此令牌可在模式中明确指定月份（而非分钟）。 |
mmm |
三个字母的月份缩写（例如“Feb”）。 |
mmmm |
月份的全名。mmmmmm+也与此匹配。 |
mmmmm |
月份的首字母（例如，用“J”表示 6 月）。 |
s |
一分钟中的秒，不含前导零。 |
ss |
一分钟中的秒，含前导零。 |
[h+] |
一段时间内经过的小时数。字母数量表示数字的最小位数（添加前导 0）。 |
[m+] |
一段时间内已经过的分钟数。字母数量表示数字的最小位数（添加前导 0）。 |
[s+] |
时间段内已经历的秒数。字母数量表示数字的最小位数（添加前导 0）。 |
d |
月份中的日期，对于小于 10 的数字，不带前导 0。 |
dd |
月份中的日期，对于小于 10 的数字，带有前导 0。 |
ddd |
星期几，三个字母的缩写（例如“Mon”）。 |
dddd+ |
星期几（全称）。 |
y |
年（2 位数）。 |
yy |
|
yyy |
年（4 位数）。 |
yyyy+ |
|
a/p |
“a”表示上午，“p”表示下午。还会将小时数更改为 12 小时制。如果令牌字母大写，则输出也大写。 |
am/pm |
与上述相同，但会显示“AM”或“PM”，并且始终大写。 |
0 |
十分之一秒。您可以使用 00 将精度提高到两位数，或使用 000 将精度提高到三位数（毫秒）。 |
\ |
将下一个字符视为字面量值，而不是其可能具有的任何特殊含义。 |
"text" |
将引号内的所有文本显示为字面量。 |
日期和时间格式示例
对于日期和时间 Tuesday, April 5, 2016, 4:08:53.528 PM，下表显示了一些示例模式及其对应的日期时间呈现。该表的第二部分显示了经过时间为 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." |
下午 4:08 |
yyyy-mm-dd |
2016-04-05 |
mmmm d \[dddd\] |
4 月 5 日 [星期二] |
h PM, ddd mmm dd |
4 月 5 日（周二）下午 4 点 |
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 |
数字格式模式
数字格式模式是由标记子字符串组成的字符串，Google 表格在解析时会将其替换为相应的数字表示法。数字格式模式最多可包含四个部分，各部分之间用分号分隔，分别定义用于正数、负数、零和文本的单独格式（按此顺序）：
[POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT];[TEXT FORMAT]
您无需在格式中包含所有四个部分。如果您只添加一个部分，Google 表格会将该格式应用于所有值。如果使用两个部分，则会将第一个格式应用于零和正数，将第二个格式应用于负数。使用三个部分可分别为正数、负数和零定义单独的格式。例如：
[NUMBER FORMAT] [POSITIVE/ZERO FORMAT];[NEGATIVE FORMAT] [POSITIVE FORMAT];[NEGATIVE FORMAT];[ZERO FORMAT]
不过，如果有两个或更多部分，并且最后一部分是文本格式，则 Google 表格会将该部分视为文本格式，而其他部分的行为就像少了一个部分一样。因此，通过添加最终文本格式，可以定义如下格式：
[POSITIVE/ZERO FORMAT];[NEGATIVE FORMAT];[TEXT FORMAT] [NUMBER FORMAT];[TEXT FORMAT]
将格式解析为多个部分的操作会在其他解析之前进行，因此可以将日期或时间格式作为其中一个部分包含在内（尽管这方面的实用性有限）。
数字格式令牌
下表定义了您可以在格式部分中使用的令牌子字符串，用于定义如何表示该部分的值。
| 令牌 | 说明 |
|---|---|
0 |
表示数字中的一个数位。如果该数字是无效的 0，则会呈现为 0。例如，数字格式 00.0 会将数字 3 呈现为“03.0”。 |
# |
表示数字中的一个数位。如果该数字是无效的 0，则不会呈现。例如，数字格式 ##0 会将数字 12 呈现为“12”。 |
? |
表示数字中的一个数位。如果数字是无效的 0，则会呈现为空格。在使用固定宽度字体时，这通常用于对齐列中的小数点。例如，数字格式 ???.??? 会将数字 12.4 呈现为：“ 12.4 ”。 |
. |
第一个英文句点表示数字中的小数点。后续句点会呈现为字面量。如果您在格式中包含小数点，则系统始终会呈现小数点，即使对于整数也是如此。例如，#0.# 会将数字 3 呈现为“3.”。 |
% |
显示为字面量，但也会导致现有数字在呈现之前乘以 100，以使百分比更易于阅读。例如，数字格式 #% 会将数字 0.25 呈现为“25%”。 |
, |
如果它出现在两位数字字符（0、# 或 ?）之间，则会使用分组分隔符（按千位分组）呈现整个数字。如果逗号位于数字字符后面，则每个逗号会将数字缩放一千倍（例如，格式 #0.0,, 会将数字 12,200,000 呈现为 12.2）。 |
E- |
以科学计数法格式呈现数字，E 左侧的格式用于非指数部分，E 右侧的格式用于指数部分。E+ 会为正指数显示 + 符号。E- 仅显示负指数的符号。如果使用小写，则输出 e 也是小写。例如，数字格式 ##0.00#E+## 会将数字 0.0000001 呈现为“100.00E-9”。 |
E+ |
|
e- |
|
e+ |
|
/ |
如果它出现在两个数字字符（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 数字格式兼容而添加。 Google 表格会忽略此令牌。 |
_ |
跳过下一个字符并呈现一个空格。使用此标记可对齐负值用括号括起来的数字格式。 |
\ |
将下一个字符视为字面量值，而不是其可能具有的任何特殊含义。例如，数字格式 \#0 会将数字 10 呈现为“#10”。 |
"text" |
将引号内的所有文本显示为字面量。 |
@ |
如果单元格包含文本输入，则会插入单元格的原始文本。不与其他任何特殊字符兼容，并且不显示数值（数值以常规格式显示）。 |
$ - + ( ) : space |
Google 表格会将这些字符和常见货币符号（例如 $、€、£ 和 ¥）视为字面量，并原样显示。 |
元指令
此外，每个格式部分都可以包含可选的元指令，这些指令用 [] 字符括起来，位于格式之前，用于提供额外说明：
| 指令 | 说明 |
|---|---|
[condition] |
将该部分的默认正数、负数或零比较替换为另一个条件表达式。例如，[<100]"Low";[>1000]"High";000 会将小于 100 的值呈现为“Low”，将大于 1000 的值呈现为“High”，并将介于两者之间的任何值呈现为三位数（前导 0）。您只能对前两个子格式应用条件，如果一个数字与多个子格式匹配，Google 表格会使用第一个匹配的子格式。如果存在第三种格式，Google 表格会将其用于“其他所有内容”；否则，如果数字与这两种格式都不匹配，Google 表格会在整个单元格宽度内呈现所有“#”字符。如果存在，第四种格式始终用于文本。 |
[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]），Google 表格会忽略该语言区域代码。 |
数字格式示例
下表列举了一些示例格式及其对应的格式化数字呈现方式：
| 数字 | 模式 | 已设置格式的值 |
|---|---|---|
| 12345.125 | ####.# |
12345.1 |
| 12.34 | 000.0000 |
012.3400 |
| 12 | #.0# |
12.0 |
| 5.125 | # ???/??? |
5 1/8 |
| 12000 | #,### |
12000 |
| 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 |