Global.Intl.DateTimeFormat

moduleAndroidiPhoneiPadmacOSsince iPhone 6.0.0, iPad 6.0.0, Android 9.1.0, macOS 9.2.0

Immutable object used to generate localized date and time formatted strings.

A DateTimeFormat object is used to format a Date object to a localized date and/or time string. This will respect the system's current language setting when outputting a full month or weekday name. It will also respect the current locale's date component ordering such as Month/Day/Year, Day/Month/Year, and Year/Month/Day.

For more detail, see the MDN website about Intl.DateTimeFormat.

Examples

Output Numeric Date

// 2020-March-1st
const date = new Date(Date.UTC(2020, 2, 1));

// Logs "3/1/2020" for US English locale.
// Logs "1.3.2020" for German locale.
// Logs "2020/3/1" for Japanese locale.
const formatter = new Intl.DateTimeFormat(Ti.Locale.currentLocale, {
    year: 'numeric',
    month: 'numeric',
    day: 'numeric',
    timeZone: 'UTC'
});
console.log(`Time: ${formatter.format(date)}`);

Output 12-Hour Time

// 2020-January-1st 08:02:05 PM
const date = new Date(Date.UTC(2020, 0, 1, 20, 2, 5));

// Logs "8:02:05 PM" for English locales.
// Logs "8:02:05 nachm." for German locales.
const formatter = new Intl.DateTimeFormat(Ti.Locale.currentLocale, {
    hour: 'numeric',
    minute: '2-digit',
    second: '2-digit',
    hour12: true,
    dayPeriod: 'narrow',
    timeZone: 'UTC'
});
console.log(`Time: ${formatter.format(date)}`);

Output 24-Hour Time

// 2020-January-1st 08:02:05 PM
const date = new Date(Date.UTC(2020, 0, 1, 20, 2, 5));

// Logs "20:02:05".
const formatter = new Intl.DateTimeFormat(Ti.Locale.currentLocale, {
    hour: '2-digit',
    minute: '2-digit',
    second: '2-digit',
    hour12: false,
    timeZone: 'UTC'
});
console.log(`Time: ${formatter.format(date)}`);

Output Localized Weekday Name

// Log current weekday name (such as "Monday") using system's selected language.
const formatter = new Intl.DateTimeFormat(Ti.Locale.currentLocale, { weekday: 'long' });
console.log(formatter.format(new Date()));

Properties 1

constructor

Global.Intl.DateTimeFormatread-only

Creates a new Intl.DateTimeFormat object with the given locale and formatting options.

Syntax

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

Parameters

locales: String/String[] (optional)

The BCP 47 language and country code(s) to use for localized formatting. Can provide multiple locales where the best-supported locale will be favored in the order provided by the array. If parameter is not assigned, then the system may use the 'en-US' locale by default instead of the system's current locale. It's recommended to set this parameter using Titanium.Locale.currentLocale.
options: DateTimeFormatOptions (optional)

Provides settings indicating how a Date object should be formatted to a String.

Methods 4

format

Formats the given date object to a localized date and/or time string.

Parameters
Parameters	Type	Description
date	Date	The date to be formatted.

Returns String

The localized date and/or time string.

formatToParts

iOS 11.2+

Formats given date to an array of components describing what the formatted string would produce.

Returns an array of objects providing the "type" and "value" of each component the formatted string would produce. Can be used to detect month/day/year ordering for the current locale, to fetch the localized separators between date and time components, etc.

For more detail, see the MDN website about formatToParts.

Parameters
Parameters	Type	Description
date	Date	The date to be formatted into parts.

Returns Array<DateTimeFormattedPart>

Array of objects providing the "type" and "value" of each component in formatted string.

resolvedOptions

Gets the object's formatting options.

Returns the formatting options the format object uses.

For more detail, see the MDN website about resolvedOptions.

Returns DateTimeFormatOptions

Returns the formatting options used.

supportedLocalesOf

Static method indicating what locales are supported by DateTimeFormat from the given locale(s).

For more detail, see the MDN website about supportedLocalesOf.

Parameters
Parameters	Type	Description
locales	String \| Array<String>	A string or array of strings providing BCP 47 locale identifiers to query.

Returns Array<String>

Array containing a subset of the given locale strings supported by DateTimeFormat objects.