Intl.DateTimeFormat

Intl.DateTimeFormat은 언어에 맞는 날짜 및 시간 서식을 지원하는 객체의 생성자입니다. dateStyletimeStyle 옵션을 통해 날짜와 시간 형식을 빠르게 맞출 수 있고, 더 자세한 조정을 위한 다른 옵션도 존재합니다.

구문

new Intl.DateTimeFormat([locales[, options]])
Intl.DateTimeFormat.call(this[, locales[, options]])

매개변수

locales Optional

BCP 47 언어 태그를 포함하는 문자열이나 문자열의 배열. 로케일 매개변수의 일반적인 형식 및 해석은 Intl 문서를 참고하세요. 다음의 유니코드 확장 키를 사용할 수 있습니다.

nu
사용할 기수법. "arab", "arabext", "bali", "beng", "deva", "fullwide", "gujr", "guru", "hanidec", "khmr", "knda", "laoo", "latn", "limb", "mlym", "mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt" 등을 사용할 수 있습니다.
ca
역법. "buddhist", "chinese", "coptic", "ethioaa", "ethiopic", "gregory", "hebrew", "indian", "islamic", "islamicc", "iso8601", "japanese", "persian", "roc" 등을 사용할 수 있습니다.
hc
시간 사이클. "h11", "h12", "h23", "h24" 등을 사용할 수 있습니다.
options Optional

다음 속성을 포함하는 객체.

dateStyle
format()을 호출했을 때 사용할 날짜 서식. 가능한 값은 다음을 포함합니다.
  • "full"
  • "long"
  • "medium"
  • "short"
timeStyle
format()을 호출했을 때 사용할 시간 서식. 가능한 값은 다음을 포함합니다.
  • "full"
  • "long"
  • "medium"
  • "short"
localeMatcher
사용할 로케일 매칭 알고리즘. 가능한 값은 "lookup""best fit"이고, 기본값은 "best fit"입니다. 자세한 정보는 Intl 문서를 참고하세요.
timeZone
사용할 시간대. 구현체가 반드시 인식해야 하는 유일한 값은 "UTC"입니다. 기본값은 런타임의 기본 시간대입니다. 구현체에 따라 "Asia/Shanghai", "Asia/Kolkata", "America/New_York" 등 IANA 시간대 데이터베이스의 시간대 이름을 인식할 수도 있습니다.
hour12
24시간제 대신 12시간제를 사용할지 여부. 가능한 값은 truefalse이고, 기본값은 로케일에 따라 다릅니다. 이 옵션을 지정하면 hc 언어 태그와 hourCycle 옵션을 모두 무시합니다.
hourCycle
사용할 시간제. 가능한 값은 "h11", "h12", "h23", "h24"입니다. 이 옵션을 지정하면 hc 언어 태그를 무시합니다. hour12 옵션을 지정한 경우 그 값이 우선순위를 가집니다.
formatMatcher
사용할 서식 매칭 알고리즘. 가능한 값은 "basic""best fit"이고, 기본값은 "best fit"입니다. 아래의 단락에서 이 속성의 자세한 정보를 확인하세요.

이후의 속성은 서식을 적용한 출력 결과가 사용할 날짜 및 시간 구성요소를 나타냅니다. 구현체는 적어도 아래의 부분집합을 지원해야 합니다.

  • weekday, year, month, day, hour, minute, second
  • weekday, year, month, day
  • year, month, day
  • year, month
  • month, day
  • hour, minute, second
  • hour, minute

구현체에 따라 다른 집합을 지원할 수도 있습니다. 서식 요청은 가능한 모든 부분집합 조합 중 최적으로 일치하는 집합으로 조정됩니다. 조정 알고리즘에는 명세에 완벽히 정의된 basic 알고리즘과, 구현체에 따라 다른 best-fit 알고리즘 두 종류가 있으며 formatMatcher 속성의 값이 어느 쪽을 사용할지 결정합니다.

weekday
요일. 가능한 값은 다음과 같습니다.
  • "long" (금요일, Thursday 등)
  • "short" ((금), Thu 등)
  • "narrow" ((금), T 등). 일부 로케일에서는 두 개의 요일이 같은 값을 스타일을 가질 수 있습니다. (예: ThursdayTuesday 둘 다 T)
era
시대. 가능한 값은 다음과 같습니다.
  • "long" (서기, Anno Domini 등)
  • "short" (AD 등)
  • "narrow" (A, AD 등)
year
연도. 가능한 값은 다음과 같습니다.
  • "numeric" (2019년, 2019 등)
  • "2-digit" (19년, 19 등)
month
월. 가능한 값은 다음과 같습니다.
  • "numeric" (3 등)
  • "2-digit" (03 등)
  • "long" (3월, March 등)
  • "short" (Mar 등)
  • "narrow" (M 등). 일부 로케일에서는 두 개의 요일이 같은 값을 스타일을 가질 수 있습니다. (예: MarchMay 둘 다 M)
day
일. 가능한 값은 다음과 같습니다.
  • "numeric" (1 등)
  • "2-digit" (01 등)
hour
시. 가능한 값은 "numeric", "2-digit"입니다.
minute
분. 가능한 값은 "numeric", "2-digit"입니다.
second
초. 가능한 값은 "numeric", "2-digit"입니다.
timeZoneName
시간대 이름. 가능한 값은 다음과 같습니다.
  • "long" (한국 표준시, British Summer Time등)
  • "short" (GMT+9 등)

각 구성요소 속성의 기본값은 undefined입니다. 그러나 모든 속성이 undefined일 경우, year, month, day"numeric"으로 취급합니다.

설명

속성

Intl.DateTimeFormat.prototype
모든 인스턴스에 속성을 추가할 수 있습니다.

메서드

Intl.DateTimeFormat.supportedLocalesOf()
주어진 로케일 목록 중, 런타임이 지원하는 항목을 배열로 반환합니다.

DateTimeFormat 인스턴스

속성

DateTimeFormat 인스턴스는 프로토타입의 다음 속성을 상속합니다.

Intl.DateTimeFormat.prototype.constructor
Intl.DateTimeFormat에 대한 참조입니다.

메서드

DateTimeFormat 인스턴스는 프로토타입의 다음 메서드를 상속합니다.

Intl.DateTimeFormat.prototype.format()
주어진 날짜에 DateTimeFormat 객체의 로케일과 서식 설정을 적용해 반환합니다.
Intl.DateTimeFormat.prototype.formatToParts()
서식을 적용한 날짜 문자열의 각 부분을 객체로 표현해서 Array로 반환합니다. 반환 값은 로케일별 커스텀 서식에 사용할 수 있습니다.
Intl.DateTimeFormat.prototype.resolvedOptions()
객체 인스턴스 생성 때 주어진 로케일과 서식 설정이 어떻게 반영되었나 나타내는 새로운 객체를 반환합니다.

예제

DateTimeFormat 사용하기

로케일을 지정하지 않고 사용하면 기본 로케일 및 기본 옵션 서식을 적용한 문자열을 반환합니다.

var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 매개변수 없이 toLocaleString() 호출한 결과는
// 구현체, 기본 로케일, 기본 시간대에 다라 달라짐
console.log(new Intl.DateTimeFormat().format(date));
// → ko-KR 로케일(언어)와 Asia/Seoul 시간대(UTC+0900)에서 "2012. 12. 20."

locales 사용하기

다음 예제는 지역화된 숫자 서식의 예시를 보입니다. 어플리케이션의 사용자 인터페이스 언어에 맞는 서식을 적용하려면 locales 매개변수로 적절한 언어(와, 필요한 경우 대체 언어)를 제공하는걸 잊지 마세요.

var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 아래 결과는 모두 Asia/Seoul 시간대를 사용한 결과 (UTC+0900, 한국 표준시)

// 한국어에서 날짜 표기는 연월일 순서
console.log(new Intl.DateTimeFormat('ko-KR').format(date));
// → "2012. 12. 20."

// 미국 영어에서 날짜 표기는 월일년 순서
console.log(new Intl.DateTimeFormat('en-US').format(date));
// → "12/20/2012"

// 영국 영어에서 날짜 표기는 일월년 순서
console.log(new Intl.DateTimeFormat('en-GB').format(date));
// → "20/12/2012"

// 대부분의 아랍어 국가에서는 진짜 아라비아 숫자 사용
console.log(new Intl.DateTimeFormat('ar-EG').format(date));
// → "٢٠‏/١٢‏/٢٠١٢"

// 일본어의 경우 어플리케이션에 연호를 사용해야 할 수도 있음
// 2012년은 헤이세이 24년
console.log(new Intl.DateTimeFormat('ja-JP-u-ca-japanese').format(date));
// → "24/12/20"

// 발리어와 같이 지원되지 않을 수도 있는 언어를 지정할 때는
// 다음과 같이 대체 언어를 지정할 수 있음. 아래의 경우 대체 언어는 인도어
console.log(new Intl.DateTimeFormat(['ban', 'id']).format(date));
// → "20/12/2012"

options 사용하기

options 매개변수를 지정해 날짜와 시간 서식 결과를 원하는 형태로 바꿀 수 있습니다.

var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 긴 날짜 서식에 더해 요일 요청
var options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
console.log(new Intl.DateTimeFormat('de-DE', options).format(date));
// → "Donnerstag, 20. Dezember 2012"

// 어플리케이션이 GMT를 사용해야 하고, 그 점을 명시해야 할 때
options.timeZone = 'UTC';
options.timeZoneName = 'short';
console.log(new Intl.DateTimeFormat('en-US', options).format(date));
// → "Thursday, December 20, 2012, GMT"

// 좀 더 자세한 설정이 필요하면
options = {
  hour: 'numeric', minute: 'numeric', second: 'numeric', 
  timeZone: 'Australia/Sydney',
  timeZoneName: 'short'
};
console.log(new Intl.DateTimeFormat('en-AU', options).format(date));
// → "2:00:00 pm AEDT"

// 미국에서도 24시간제가 필요할 때
options = {
  year: 'numeric', month: 'numeric', day: 'numeric',
  hour: 'numeric', minute: 'numeric', second: 'numeric',
  hour12: false,
  timeZone: 'America/Los_Angeles' 
};
console.log(new Intl.DateTimeFormat('en-US', options).format(date));
// → "12/19/2012, 19:00:00"

명세

Specification Status Comment
ECMAScript Internationalization API 1.0 (ECMA-402)
The definition of 'Intl.DateTimeFormat' in that specification.
Standard Initial definition.
ECMAScript Internationalization API 2.0 (ECMA-402)
The definition of 'Intl.DateTimeFormat' in that specification.
Standard
ECMAScript Internationalization API 4.0 (ECMA-402)
The definition of 'Intl.DateTimeFormat' in that specification.
Draft

브라우저 호환성

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
DateTimeFormatChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android Full support 4.4Chrome Android Full support 26Firefox Android Full support 56Opera Android ? Safari iOS Full support 10Samsung Internet Android Full support Yesnodejs Full support Yes
formatChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android No support NoChrome Android Full support 26Firefox Android Full support 56Opera Android ? Safari iOS Full support 10Samsung Internet Android Full support Yesnodejs ?
formatToPartsChrome Full support 57
Notes
Full support 57
Notes
Notes Before version 71, formatToParts() returned an object with an incorrectly cased type key of dayperiod. Version 71 and later use the specification defined dayPeriod. See Chromium bug 865351.
Edge Full support 18Firefox Full support 51IE No support NoOpera Full support YesSafari Full support 11WebView Android Full support 57
Notes
Full support 57
Notes
Notes Before version 71, formatToParts() returned an object with an incorrectly cased type key of dayperiod. Version 71 and later use the specification defined dayPeriod. See Chromium bug 865351.
Chrome Android Full support 57
Notes
Full support 57
Notes
Notes Before version 71, formatToParts() returned an object with an incorrectly cased type key of dayperiod. Version 71 and later use the specification defined dayPeriod. See Chromium bug 865351.
Firefox Android Full support 56Opera Android No support NoSafari iOS Full support 11Samsung Internet Android Full support 7.0nodejs Full support Yes
hourCycleChrome ? Edge Full support YesFirefox Full support 58IE ? Opera ? Safari ? WebView Android ? Chrome Android ? Firefox Android Full support 58Opera Android ? Safari iOS ? Samsung Internet Android ? nodejs ?
IANA time zone names in timeZone optionChrome Full support 24Edge ? Firefox Full support 52IE ? Opera Full support 15Safari Full support 10WebView Android Full support 37Chrome Android Full support 26Firefox Android Full support 56Opera Android ? Safari iOS Full support 10Samsung Internet Android Full support Yesnodejs ?
prototypeChrome Full support 24Edge Full support YesFirefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android No support NoChrome Android Full support 26Firefox Android Full support 56Opera Android ? Safari iOS Full support 10Samsung Internet Android Full support Yesnodejs ?
resolvedOptionsChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android No support NoChrome Android Full support 26Firefox Android Full support 56Opera Android ? Safari iOS Full support 10Samsung Internet Android Full support Yesnodejs ?
supportedLocalesOfChrome Full support 24Edge Full support YesFirefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android No support NoChrome Android Full support 26Firefox Android Full support 56Opera Android ? Safari iOS Full support 10Samsung Internet Android Full support Yesnodejs ?

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
See implementation notes.
See implementation notes.

같이 보기