Intl.DateTimeFormat

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

The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.

구문

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시간제를 사용할지 여부. 가능한 값은 true 와 false이고, 기본값은 로케일에 따라 다릅니다. 이 옵션을 지정하면 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 등). 일부 로케일에서는 두 개의 요일이 같은 값을 스타일을 가질 수 있습니다. (예: Thursday와 Tuesday 둘 다 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 등). 일부 로케일에서는 두 개의 요일이 같은 값을 스타일을 가질 수 있습니다. (예: March와 May 둘 다 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 인스턴스는 프로토타입의 다음 속성을 상속합니다.

메서드

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

예제

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"

명세

브라우저 호환성

같이 보기