Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Форматы даты и чисел

В этом документе описано, как задать новые шаблоны формата даты и чисел, которые можно включить в запрос к API.

С помощью форматов даты, времени и чисел можно настраивать, как показываются данные в таблице. В Google Таблицах предлагается выбор из ряда распространенных форматов, но вы также можете задавать собственные.

В интерфейсе Таблиц форматы чисел и дат применяются к ячейкам с помощью меню Формат > Числа. В Google Sheets API эти форматы задаются с помощью вызова метода spreadsheets.batchUpdate для отправки UpdateCellsRequest или RepeatCellRequest. В запросе вы настраиваете объект NumberFormat, указывая NumberFormatType (например, NUMBER, CURRENCY, PERCENT, DATE или TIME) и необязательную строку pattern. Если параметр pattern не указан, Таблицы используют формат по умолчанию для указанного значения type на основе locale таблицы (например, $1,000.12 для CURRENCY в en_US).

Пример Задание собственного формата даты и времени или десятичного формата для диапазона показывает, как задать шаблон формата с помощью Sheets API. Обратите внимание, что фактическое отображение формата зависит от locale таблицы. В этом документе предполагается, что locale – это en_US. Вы можете определить locale таблицы, прочитав объект SpreadsheetProperties с помощью метода spreadsheets.get для ресурса spreadsheets.

Дополнительные примеры можно найти в статьях Базовое форматирование и Условное форматирование.

Значения даты и времени

Таблицы, как и большинство других приложений для работы с электронными таблицами, обрабатывают значения даты и времени как десятичные значения. Это позволяет выполнять с ними арифметические действия в формулах, например увеличивать количество дней или недель, складывать или вычитать две даты и время и выполнять другие подобные операции.

В Таблицах используется дата начала отсчета, которая часто применяется в электронных таблицах. Целая часть значения (слева от десятичной запятой) – это количество дней, прошедших с 30 декабря 1899 года. Дробная часть (справа от запятой) считает время как долю одного дня. Например, 1 января 1900 года в полдень – это 2.5, 2, потому что прошло два дня с 30 декабря 1899 года, и 0.5, потому что полдень – это половина дня. 1 февраля 1900 года в 15:00 – это 33.625.

Таблицы правильно считают 1900 год обычным, а не високосным. Порядковые номера даты и времени не хранят смещение часового пояса. Вместо этого они основаны на timeZone таблицы, который можно получить из объекта SpreadsheetProperties с помощью метода spreadsheets.get.

Шаблоны формата даты и времени

Шаблон формата даты и времени – это строка подстрок токенов, которые Таблицы заменяют соответствующими элементами даты и времени (например, месяцем или часом) при синтаксическом анализе.

Токены формата даты и времени

В таблице ниже приведены подстроки токенов, которые можно использовать в шаблоне формата даты и времени. Символ + указывает на то, что предыдущий символ может повторяться один или несколько раз. Символы, не указанные в этой таблице, Таблицы обрабатывают как литералы и выводят без изменений.

Токен	Описание
`h`	Время суток. Переключается между 12- и 24-часовым форматом в зависимости от того, есть ли в строке индикатор AM или PM.
`hh+`	То же, что и в предыдущем случае, но с нулем впереди для чисел от 1 до 9.
`m`	Если предыдущим небуквенным токеном были часы или последующим – секунды, то он представляет минуты в часе (без начального нуля). В противном случае оно представляет собой номер месяца в году (без нуля в начале).
`M`	Месяц года без нуля в начале. Используйте этот токен, чтобы явно указать в шаблоне месяц, а не минуту.
`mm`	То же, что и `m`, но с ведущим нулем в обоих случаях.
`MM`	Месяц года с нулем в начале. Используйте этот токен, чтобы явно указать в шаблоне месяц, а не минуту.
`mmm`	Трехбуквенное сокращение месяца (например, "Feb").
`mmmm`	Полное название месяца. `mmmmmm+` также соответствует этому.
`mmmmm`	Первая буква названия месяца (например, "И" для июня).
`s`	Секунды без нуля в начале.
`ss`	Секунды в минуте с начальным нулем.
`[h+]`	Количество часов в периоде времени. Количество букв указывает на минимальное количество цифр (добавляет нули в начале).
`[m+]`	Количество минут в периоде времени. Количество букв указывает на минимальное количество цифр (добавляются нули в начале).
`[s+]`	Количество секунд, прошедших за определенный период времени. Количество букв указывает на минимальное количество цифр (добавляет нули в начале).
`d`	День месяца без нуля впереди для чисел меньше 10.
`dd`	День месяца с нулем впереди для чисел меньше 10.
`ddd`	День недели, трехбуквенное сокращение (например, "Пнд").
`dddd+`	День недели, полное название.
`y`	Год в виде двузначного числа.
`yy`	Год в виде двузначного числа.
`yyy`	Год в виде четырехзначного числа.
`yyyy+`	Год в виде четырехзначного числа.
`a/p`	Отображает "a" для времени до полудня и "p" для времени после полудня. Также меняет формат времени на 12-часовой. Если буква в токене заглавная, то и в выходных данных она будет заглавной.
`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."`	16:08
`yyyy-mm-dd`	2016-04-05
`mmmm d \[dddd\]`	5 апреля, вторник
`h PM, ddd mmm dd`	16:00, вторник, 5 апреля
`dddd, m/d/yy at h:mm`	Вторник, 5 апреля 2016 г., 16:08
Шаблоны истекшего времени	`3 hours, 13 minutes, 41.255 seconds`
`[hh]`	03
`[mmmm]`	0193
`[ss]`	11621

Шаблоны числовых форматов

Шаблон формата чисел – это строка подстрок токенов, которые Таблицы заменяют соответствующими представлениями чисел при синтаксическом анализе. Шаблон формата чисел может состоять из четырех разделов, разделенных точкой с запятой. Они определяют отдельные форматы, используемые для положительных чисел, отрицательных чисел, нуля и текста (в указанном порядке):

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

Необязательно включать в формат все четыре раздела. Если вы укажете только один раздел, Таблицы будут использовать этот формат для всех значений. Если вы используете два раздела, первый формат будет применяться к нулю и положительным числам, а второй – к отрицательным. Если вы используете три раздела, то можете задать отдельные форматы для положительных, отрицательных и нулевых значений. Пример:

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

Однако если разделов два или больше и последний из них – текстовый, то Таблицы обрабатывают его как текстовый, а остальные – так, как если бы разделов было на один меньше. Таким образом, включив окончательный текстовый формат, можно определить такие форматы, как:

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

Разбивка формата на разделы происходит до других операций синтаксического анализа, поэтому в качестве одного из разделов можно включить формат даты или времени (хотя это не очень удобно).

Токены формата чисел

В таблице ниже приведены подстроки токенов, которые можно использовать в разделе формата, чтобы определить, как представлять значения для этого раздела.

Токен	Описание
`0`	Отображает лишние нули Если цифра – незначащий ноль, она отображается как 0. Например, числовой формат `00.0` преобразует число 3 в `03.0`.
`#`	Отображает лишние нули Если цифра – незначимый ноль, она не отображается. Например, числовой формат `##0` преобразует число 12 в `12`.
`?`	Отображает лишние нули Если цифра – незначащий ноль, она отображается как пробел. Часто используется для выравнивания десятичной запятой в столбце при использовании шрифтов фиксированной ширины. Например, формат `???.???` преобразует число 12,4 в `12.4`.
`.`	Первая точка – это десятичный разделитель. Последующие точки отображаются как литералы. Если в формате есть десятичный разделитель, он будет показываться всегда, даже для целых чисел. Например, `#0.#` преобразует число 3 в `3.`.
`%`	Отображается как литерал, но также приводит к тому, что существующие числа умножаются на 100 перед отображением, чтобы проценты были более читабельными. Например, числовой формат `#%` преобразует число 0,25 в `25%`.
`,`	Если он находится между двумя цифрами (`0`, `#` или `?`), то все число будет разделено на группы по три цифры. Если запятая стоит после цифр, то она делит число на тысячу (например, формат `#0.0,,` преобразует число 12 200 000 в `12.2`).
`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. Таблицы игнорируют этот токен.
`_`	Пропускает следующий символ и вставляет пробел. Используйте этот токен, чтобы выровнять форматы чисел, в которых отрицательное значение заключено в скобки.
`\`	Указывает, что следующий символ является литеральным значением и не имеет специального значения. Например, числовой формат `\#0` преобразует число 10 в `#10`.
`"text"`	Отображает текст в кавычках как литерал.
`@`	Если в ячейке есть текст, вставляется необработанный текст. Несовместим с другими специальными символами и не отображается для числовых значений (которые отображаются в общем формате).
`$ - + ( ) : space`	Таблицы обрабатывают эти символы и распространенные символы валют (например, `$`, `€`, `£` и `¥`) как литералы и отображают их без изменений.

Метаинструкции

Кроме того, в каждом разделе формата могут быть необязательные метаинструкции, заключенные в символы [], которые предшествуют формату и содержат дополнительные инструкции:

Инструкция	Описание
`[condition]`	Заменяет сравнение по умолчанию (положительное, отрицательное или нулевое) в разделе другим условным выражением. Например, `[<100]"Low";[>1000]"High";000` возвращает слово "Низкий" для значений ниже 100, "Высокий" – для значений выше 1000 и трехзначное число (с нулями в начале) для значений между ними. Условия можно применять только к первым двум подформатам. Если число соответствует нескольким условиям, Таблицы используют первое совпадение. Если задан третий формат, Таблицы используют его для всех остальных значений. Если число не соответствует ни одному из форматов, Таблицы заполняют ячейку символами "#". Если он есть, то для текста всегда используется четвертый формат.
`[Color] or [Color#]`	Задает цвет текста для любого значения, которое отображается в этом подформате. Допустимые значения для `Color`: Black (черный), Blue (синий), Cyan (голубой), Green (зеленый), Magenta (пурпурный), Red (красный), White (белый) или Yellow (желтый). Вместо символа # в атрибуте `Color#` можно указать число от 1 до 56. Цвета, заданные в формате чисел, переопределяют цвета, заданные пользователем, но не переопределяют цвета, заданные условным форматированием. Палитра содержит список цветов, соответствующих каждому числу. Они основаны на свойстве `ColorIndex` в Microsoft Excel.
`[$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)`	1234,56 $ (1234,56 $)
1230000	`0.0,,"M"`	1,2 млн
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]_(@_)`	1234 1234 0.0 MyText
1005 32 527	`[>1000]"HIGH";[Color43][<=200]"LOW";0000`	ВЫСОКИЙ НИЗКИЙ 0527

Форматы даты и чисел Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.