Intl.DateTimeFormat() 생성자

Intl.DateTimeFormat 생성자는 언어에 맞는 날짜 및 시간 서식을 적용하기 위한 Intl.DateTimeFormat 객체를 생성합니다.

시도해보기

구문

js
new Intl.DateTimeFormat();
new Intl.DateTimeFormat(locales);
new Intl.DateTimeFormat(locales, options);

매개변수

locales Optional

BCP 47 언어 태그를 포함하는 문자열이나 문자열의 배열입니다. 브라우저 기본 로케일을 사용하려면 빈 배열을 지정하세요. ko-u-ca-buddhist처럼 유니코드 확장 형태도 지원합니다. 로케일 매개변수의 일반적인 형식 및 해석은 Intl (en-US) 문서를 참고하세요. 다음의 유니코드 확장 키를 사용할 수 있습니다.

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", "ethiopia", "ethiopic", "gregory", "hebrew", "indian", "islamic", "iso8601", "japanese", "persian", "roc" 등을 사용할 수 있습니다.

hc

시간제. "h11", "h12", "h23", "h24" 등을 사용할 수 있습니다.

options Optional

다음 속성 일부 또는 전부를 포함하는 객체입니다.

  • dateStyle
    • : format()을 호출했을 때 사용할 날짜 서식입니다. 가능한 값은 다음을 포함합니다.
      • "full"
      • "long"
      • "medium"
      • "short"

      참고: dateStyletimeStyle과 함께 사용할 수 있지만, 다른 옵션인 weekday, hour, month 등과는 함께 사용할 수 없습니다.

  • timeStyle
    • : format()을 호출했을 때 사용할 시간 서식입니다. 가능한 값은 다음을 포함합니다.
      • "full"
      • "long"
      • "medium"
      • "short"

      참고: timeStyledateStyle과 함께 사용할 수 있지만, 다른 옵션인 weekday, hour, month 등과는 함께 사용할 수 없습니다.

  • calendar
    • : 역법입니다. "buddhist", "chinese", " coptic", "ethiopia", "ethiopic", "gregory", " hebrew", "indian", "islamic", "iso8601", " japanese", "persian", "roc" 등을 사용할 수 있습니다.
  • dayPeriod
    • : (영어의 경우) "in the morning", "am", "noon", "n"처럼 시간의 위치를 나타낼 때 사용할 시간 서식입니다. "narrow", "short", " long" 등을 사용할 수 있습니다.

    참고:

    • 12시간제 형식을 사용할 때만 결과의 차이가 있습니다.
    • 한국어를 포함해, 많은 로케일에서는 지정한 너비에 상관하지 않고 같은 문자열을 반환합니다. ("새벽", "밤" 등)
  • numberingSystem
    • : 기수법입니다. "arab", "arabext", " bali", "beng", "deva", "fullwide", " gujr", "guru", "hanidec", "khmr", " knda", "laoo", "latn", "limb", "mlym", " mong", "mymr", "orya", "tamldec", " telu", "thai", "tibt" 등을 사용할 수 있습니다.
  • localeMatcher
    • : 로케일 매칭 알고리즘입니다. 가능한 값은 "lookup", "best fit"이며 기본 값은 "best fit"입니다. 자세한 정보는 Intl (en-US) 문서를 참고하세요.
  • timeZone
    • : 시간대입니다. 구현체가 반드시 인식해야 하는 유일한 값은 "UTC"입니다. 기본 값은 런타임의 기본 시간대입니다. 구현체에 따라 "Asia/Seoul", "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

구현체에 따라 다른 구성요소 조합을 지원할 수도 있습니다. 시간 서식을 요청하면, 현재 구현체가 지원하는 모든 구성요소 조합 중 최적 조합을 탐색해 사용합니다. 탐색 알고리즘은 formatMatcher 옵션 속성을 사용해 지정할 수 있고, 명세에 완벽히 정의된 "basic" 알고리즘과 구현체에 따라 다른 "best-fit" 알고리즘의 두 종류가 있습니다.

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"입니다.

fractionalSecondDigits

밀리초를 나타낼 소숫점 이하 자릿수. 가능한 값은 다음과 같습니다.

  • 0 (밀리초를 표시하지 않음.)
  • 1 (밀리초를 한 자리까지 표시함. 예를 들어, 0.736초는 7까지 보입니다.)
  • 2 (밀리초를 두 자리까지 표시함. 예를 들어, 0.736초는 73로 보입니다.)
  • 3 (밀리초를 세 자리까지 표시함. 예를 들어, 0.736초는 736으로 보입니다.)
timeZoneName

시간대 이름. 가능한 값은 다음과 같습니다.

  • "long" 지역화된 긴 시간대 이름 (한국 표준시, British Summer Time)
  • "short" 지역화된 짧은 시간대 이름 (PST, GMT+9)
  • "shortOffset" 지역화된 GMT 형식 (GMT-8, GMT+9)
  • "longOffset" 지역화된 긴 GMT 형식 (GMT+0900)
  • "shortGeneric" 지역을 특정하지 않는 일반적인 형식 (PT)
  • "longGeneric" 지역을 특정하지 않는 긴 일반적인 형식 (Pacific Time)

참고: 요구한 형식을 사용할 수 없을 경우 시간대 서식이 다른 형태로 대체될 수 있습니다. 예를 들어 지역을 특정하지 않는 서식의 경우 특정 국가나 도시 이름을 포함하지 않아야 하지만, "Los Angeles Time"처럼 필요할 경우 이름을 포함할 수 있습니다.

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

예제

DateTimeFormat 사용하기

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

js
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."

timeStyle과 dateStyle 사용하기

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

js
let o = new Intl.DateTimeFormat("en", {
  timeStyle: "short",
});
console.log(o.format(Date.now())); // "13:31 AM"

let o = new Intl.DateTimeFormat("en", {
  dateStyle: "short",
});
console.log(o.format(Date.now())); // "07/07/20"

let o = new Intl.DateTimeFormat("en", {
  timeStyle: "medium",
  dateStyle: "short",
});
console.log(o.format(Date.now())); // "07/07/20, 13:31:55 AM"

timeZoneName 사용하기

timeZoneName을 사용하면 시간대도 결과에 포함할 수 있습니다.

js
var date = Date.UTC(2021, 11, 17, 3, 0, 42);
const timezoneNames = [
  "short",
  "long",
  "shortOffset",
  "longOffset",
  "shortGeneric",
  "longGeneric",
];

for (const zoneName of timezoneNames) {
  var formatter = new Intl.DateTimeFormat("en-US", {
    timeZone: "America/Los_Angeles",
    timeZoneName: zoneName,
  });
  console.log(zoneName + ": " + formatter.format(date));
}

// 예상 출력 결과:
// > "short: 12/16/2021, PST"
// > "long: 12/16/2021, Pacific Standard Time"
// > "shortOffset: 12/16/2021, GMT-8"
// > "longOffset: 12/16/2021, GMT-08:00"
// > "shortGeneric: 12/16/2021, PT"
// > "longGeneric: 12/16/2021, Pacific Time"

명세

Specification
ECMAScript Internationalization API Specification
# sec-intl-datetimeformat-constructor

브라우저 호환성

BCD tables only load in the browser

같이 보기