Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

날짜 및 숫자 형식

이 문서에서는 API 요청에 포함할 수 있는 새 날짜 및 숫자 형식 패턴을 정의하는 방법을 설명합니다.

날짜-시간 및 숫자 형식을 사용하면 시트에 데이터가 표시되는 방식을 관리할 수 있습니다. Google Sheets에서는 선택할 수 있는 몇 가지 일반적인 형식을 제공하지만 직접 형식을 정의할 수도 있습니다.

Sheets UI에서 서식 > 숫자 메뉴를 사용하여 셀에 숫자 및 날짜 형식을 적용합니다. Google Sheets API에서는 spreadsheets.batchUpdate 메서드 호출을 사용하여 UpdateCellsRequest 또는 RepeatCellRequest를 전송하여 이러한 형식을 설정합니다. 요청에서 NumberFormatType(예: NUMBER, CURRENCY, PERCENT, DATE, TIME) 및 선택적 pattern 문자열을 지정하여 NumberFormat 객체를 구성합니다. pattern를 생략하면 Sheets는 스프레드시트의 locale에 따라 지정된 type에 기본 형식 패턴을 사용합니다 (예: en_US의 CURRENCY에 대한 $1,000.12).

샘플 범위에 맞춤 날짜/시간 또는 십진수 형식 설정은 Sheets API를 사용하여 형식 패턴을 설정하는 방법을 보여줍니다. 형식의 실제 렌더링은 스프레드시트의 locale에 따라 달라집니다. 이 문서에서는 locale가 en_US라고 가정합니다. spreadsheets 리소스에서 spreadsheets.get 메서드를 사용하여 SpreadsheetProperties 객체를 읽어 스프레드시트의 locale를 확인할 수 있습니다.

더 많은 샘플은 기본 형식 지정 및 조건부 형식 지정을 참조하세요.

날짜 및 시간 값 정보

Sheets는 다른 대부분의 스프레드시트 애플리케이션과 마찬가지로 날짜 및 시간 값을 십진수 값으로 처리합니다. 이를 통해 수식에서 산술 연산을 수행할 수 있으므로 일 또는 주를 증가시키고, 두 날짜와 시간을 더하거나 빼고, 기타 유사한 작업을 수행할 수 있습니다.

Sheets는 스프레드시트에서 흔히 사용되는 에포크 날짜 형식을 사용합니다. 값의 정수 부분 (소수점 왼쪽)은 1899년 12월 30일 이후의 일수를 계산합니다. 소수 부분 (소수점 오른쪽)은 시간을 하루의 분수로 계산합니다. 예를 들어 1900년 1월 1일 정오는 1899년 12월 30일로부터 2일 후이므로 2.5, 2이고 정오는 반나절이므로 0.5입니다. 1900년 2월 1일 오후 3시는 33.625입니다.

스프레드시트는 1900년을 윤년이 아닌 평년으로 올바르게 처리합니다. 날짜 및 시간 일련번호에는 시간대 오프셋이 저장되지 않습니다. 대신 spreadsheets.get 메서드를 사용하여 SpreadsheetProperties 객체에서 읽을 수 있는 스프레드시트의 timeZone를 기반으로 합니다.

날짜 및 시간 형식 패턴

날짜-시간 형식 패턴은 파싱 시 Sheets에서 해당하는 날짜-시간 요소 (예: 월 또는 시간)로 대체하는 토큰 하위 문자열의 문자열입니다.

날짜 및 시간 형식 토큰

다음 표에서는 날짜-시간 형식 패턴에 사용할 수 있는 토큰 하위 문자열을 정의합니다. + 문자는 이전 문자가 한 번 이상 나타나고 패턴과 일치할 수 있음을 나타냅니다. Sheets는 이 표에 나열되지 않은 문자를 리터럴로 처리하고 변경 없이 출력합니다.

토큰	설명
`h`	시간대 문자열에 AM 또는 PM 표시가 있는지에 따라 12시간제와 24시간제 간에 전환됩니다.
`hh+`	이전과 동일하지만 1~9의 경우 앞에 0이 붙습니다.
`m`	이전의 리터럴이 아닌 토큰이 시간이었거나 후속 토큰이 초인 경우 시간의 분을 나타냅니다 (앞에 0이 없음). 그렇지 않으면 연도의 월을 숫자로 나타냅니다 (앞에 0이 없음).
`M`	앞에 0이 없는 월입니다. 이 토큰을 사용하여 패턴에서 분 대신 월을 명시적으로 지정합니다.
`mm`	`m`와 동일하지만 두 경우 모두 앞에 0이 붙습니다.
`MM`	앞에 0이 있는 연도의 월입니다. 이 토큰을 사용하여 패턴에서 분 대신 월을 명시적으로 지정합니다.
`mmm`	세 글자 월 약어 (예: 'Feb')
`mmmm`	월 이름입니다. `mmmmmm+`도 이와 일치합니다.
`mmmmm`	월의 첫 글자 (예: 6월의 경우 'J')
`s`	앞에 0이 없는 분의 초입니다.
`ss`	1분 기준의 초(앞에 0 표시)
`[h+]`	기간 중 경과된 시간 수입니다. 문자 수는 최소 자릿수를 나타냅니다 (앞에 0 추가).
`[m+]`	시간 동안 경과된 시간(분)입니다. 문자 수는 최소 자릿수를 나타냅니다 (앞에 0 추가).
`[s+]`	시간 경과(초)입니다. 문자 수는 최소 자릿수를 나타냅니다 (앞에 0 추가).
`d`	10 미만의 숫자에 앞에 0이 없는 날짜입니다.
`dd`	날짜(10 미만 숫자의 경우 앞에 0 표시)
`ddd`	요일, 세 글자 약어 (예: 'Mon')
`dddd+`	요일(전체 이름)
`y`	2자리 연도
`yy`	2자리 연도
`yyy`	4자리 연도
`yyyy+`	4자리 연도
`a/p`	오전은 'a', 오후는 'p'로 표시합니다. 또한 시간을 12시간 형식으로 변경합니다. 토큰 문자가 대문자이면 출력도 대문자입니다.
`am/pm`	위와 동일하지만 'AM' 또는 'PM'을 대신 표시하며 항상 대문자로 표시됩니다.
`0`	1/10초입니다. `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
`hh:mm A/P".M."`	오후 4시 8분
`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

숫자 형식 패턴

숫자 형식 패턴은 파싱될 때 Sheets가 해당 숫자 표현으로 대체하는 토큰 하위 문자열의 문자열입니다. 숫자 형식 패턴은 세미콜론으로 구분된 최대 4개의 섹션으로 구성될 수 있으며, 양수, 음수, 0, 텍스트에 사용되는 별도의 형식을 순서대로 정의합니다.

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

형식에 네 가지 섹션을 모두 포함할 필요는 없습니다. 섹션을 하나만 포함하면 Sheets에서 모든 값에 해당 형식을 사용합니다. 두 섹션을 사용하면 첫 번째 형식은 0과 양수에 적용되고 두 번째 형식은 음수에 적용됩니다. 세 섹션을 사용하면 양수, 음수, 0에 대해 별도의 형식을 정의합니다. 예를 들면 다음과 같습니다.

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

하지만 섹션이 두 개 이상이고 마지막 섹션이 텍스트 형식인 경우 Sheets는 해당 섹션을 텍스트 형식으로 처리하고 다른 섹션은 섹션이 하나 적은 것처럼 작동합니다. 따라서 최종 텍스트 형식을 포함하면 다음과 같은 형식을 정의할 수 있습니다.

[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`, `#` 또는 `?`) 사이에 나타나면 그룹화 구분 기호 (천 단위로 그룹화)를 사용하여 전체 숫자를 렌더링합니다. 숫자 문자 뒤에 오는 경우 쉼표당 숫자를 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+`
`/`	두 자리 문자 (`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 숫자 형식과의 호환성을 위해 포함되었습니다. Sheets는 이 토큰을 무시합니다.
`_`	다음 문자를 건너뛰고 공백을 렌더링합니다. 이 토큰을 사용하여 음수 값을 괄호로 묶는 숫자 형식을 정렬합니다.
`\`	다음 문자를 특수 의미가 아닌 리터럴 값으로 처리합니다. 예를 들어 숫자 형식 `\#0`은 숫자 10을 '`#10`'로 렌더링합니다.
`"text"`	따옴표 안에 있는 모든 텍스트를 리터럴로 표시합니다.
`@`	셀에 텍스트 입력이 있는 경우 셀의 원시 텍스트를 삽입합니다. 다른 특수문자와 호환되지 않으며 숫자 값 (일반 형식으로 표시됨)에는 표시되지 않습니다.
`$ - + ( ) : space`	Sheets는 이러한 문자와 일반적인 통화 기호 (예: `$`, `€`, `£`, `¥`)를 리터럴로 처리하고 변경되지 않은 상태로 표시합니다.

메타 안내

또한 각 형식 섹션에는 형식 앞에 오고 추가 안내를 제공하는 선택적 메타 안내가 [] 문자로 묶여 있을 수 있습니다.

안내	설명
`[condition]`	섹션의 기본 양수, 음수 또는 0 비교를 다른 조건부 표현식으로 바꿉니다. 예를 들어 `[<100]"Low";[>1000]"High";000`은 100 미만의 값에 대해 'Low'라는 단어를, 1000을 초과하는 값에 대해 'High'라는 단어를, 그 사이의 값에 대해 세 자리 숫자 (앞에 0이 있음)를 렌더링합니다. 처음 두 하위 형식에만 조건을 적용할 수 있으며, 숫자가 두 개 이상 일치하는 경우 Sheets는 첫 번째 일치 항목을 사용합니다. 세 번째 형식이 있는 경우 Sheets는 이를 '기타 모든 항목'에 사용합니다. 그렇지 않고 숫자가 두 형식 중 하나와 일치하지 않으면 Sheets는 셀 너비에 걸쳐 모든 '#' 문자를 렌더링합니다. 존재하는 경우 네 번째 형식은 항상 텍스트에 사용됩니다.
`[Color] or [Color#]`	이 하위 형식에서 렌더링하는 모든 값이 지정된 텍스트 색상으로 표시됩니다. `Color`의 유효한 값은 검은색, 파란색, 청록색, 녹색, 자홍색, 빨간색, 흰색, 노란색입니다. `Color#`에서 '#'의 유효한 값은 1~56입니다. 숫자 형식 색상은 셀에 사용자가 입력한 색상을 재정의하지만 조건부 서식으로 설정된 색상은 재정의하지 않습니다. 이 색상 팔레트에는 각 숫자에 해당하는 색상 목록이 표시됩니다. Microsoft Excel의 `ColorIndex` 속성을 기반으로 합니다.
`[$currency]`	지정된 통화 기호 또는 코드를 리터럴로 표시합니다 (예: `[$€]#,##0.00` 또는 `[$CAD]#,##0.00`). 하이픈 뒤에 선택적 언어 코드 (예: `[$CAD-1009]`)를 포함하면 Sheets에서 언어 코드를 무시합니다.

숫자 형식 예시

다음 표에는 몇 가지 패턴 예시와 이에 해당하는 형식 지정된 숫자 렌더링이 나와 있습니다.

숫자	패턴	형식이 지정된 값
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