Titanium Mobile

# Global.Intl.DateTimeFormat

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

Availability
9.1.0
6.0.0
9.2.0
Extends
Object

# Overview

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 (opens new window).

# 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

# constructor READONLY

Availability
9.1.0
6.0.0
9.2.0
constructor :Global.Intl.DateTimeFormat

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

# Syntax

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

# Parameters

  • locales: Global.String/Global.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 currentLocale.

  • options: DateTimeFormatOptions (optional)

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

# Methods

# format

Availability
9.1.0
6.0.0
9.2.0
format(date) → String

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

Parameters

Name Type Description
date Date

The date to be formatted.

Returns

The localized date and/or time string.

Type
String

# formatToParts

Availability
9.1.0
6.0.0
9.2.0
formatToParts(date) → Array<DateTimeFormattedPart>

Formats given date to an array of components describing what the formmated 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

Name Type Description
date Date

The date to be formatted into parts.

Returns

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

Type
Array<DateTimeFormattedPart>

# resolvedOptions

Availability
9.1.0
6.0.0
9.2.0
resolvedOptions() → DateTimeFormatOptions

Gets the object's formatting options.

Returns the formatting options the format object uses.

For more detail, see the MDN website about resolvedOptions.

Returns

Returns the formatting options used.

Type
DateTimeFormatOptions

# supportedLocalesOf

Availability
9.1.0
6.0.0
9.2.0
supportedLocalesOf(locales) → Array<String>

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

For more detail, see the MDN website about supportedLocalesOf.

Parameters

Name Type Description
locales String | Array<String>

A string or array of strings providing BCP 47 locale identifiers to query.

Returns

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

Type
Array<String>

Contents