Date and Time Formatting

Use Cases

The date and time formats vary according to countries and cultures. The difference lies in such aspects as the sequence of year, month, and day in a date and the separator of hour, minute, and second in the time. If your application needs to display the date and time, ensure that the information is displayed in line with local user habits for easy understanding.

Time and date formatting includes date and time formatting, relative time formatting, and time segment formatting. Date and time formatting means to convert the date and time into a string in the specified format. Relative time formatting means to convert the time difference between a time point and another time point to the specified format, for example, 30 seconds ago or 1 day later. Time segment formatting means to convert a time segment to the specified format, for example, Wednesday or 8:00-11:30.

Constraints

1. The date format and time format must be set at the same time. If the date format, but not the time format, is set, only the date format is displayed. If the time format, but not the date format, is set, only the time format is displayed.

2. If the date or time format is specified, setting of the year, month, day, hour, minute, second, and weekday formats is not supported. If the date or time format is not set, the year, month, day, hour, minute, second, and weekday formats can be set independently.

How to Develop

Date and Time Formatting

Date and time formatting is implemented by the format API of DateTimeFormat. The development procedure is as follows:

1. Import the intl module.

   import Intl from '@ohos.intl';
   

2. Create a DateTimeFormat object. Pass in a locale or locale list. If a locale list is passed, the first valid locale is used. If you do not pass in any locale, the current system locale will be used. You can use DateTimeOptions to set different date and time formats. For details, see Table 1 to Table 6.

   let dateFormat: Intl.DateTimeFormat = new Intl.DateTimeFormat(locale: string | Array<string>, options?: DateTimeOptions);
   let dateFormat: Intl.DateTimeFormat = new Intl.DateTimeFormat(); // Do not pass in the locale parameter.
   

3. Format the date and time.

   // Format the date and time.
   let formattedDate: string = dateFormat.format(date: Date);
   
   // Format the time segment.
   let formattedDateRange: string = dateFormat.formatRange(startDate: Date, endDate: Date);
   

4. Obtain DateTimeOptions and view the configuration of formatting options.

   let options: Intl.DateTimeOptions = dateFormat.resolvedOptions();
   

Date and Time Formatting Options

The following uses the time 2021-09-17 13:04:00 and locale zh-CN as an example to show the values of DateTimeOptions and corresponding display effects.

Table 1 Date display format (dateStyle)

Table 2 Time display format (timeStyle)

Table 3 Year display format (year)

Table 4 Weekday display format (weekday)

Table 5 Hour cycle (hourCycle)

Development Example

// Import the intl module.
import Intl from '@ohos.intl';

// Set the date to be formatted.
let date = new Date(2021, 8, 17, 13, 4, 0);
let startDate = new Date(2021, 8, 17, 13, 4, 0);
let endDate = new Date(2021, 8, 18, 13, 4, 0);

// Display complete time information.
let dateFormat1 = new Intl.DateTimeFormat('zh-CN', {dateStyle: 'full', timeStyle: 'full'});
let formattedDate1 = dateFormat1.format(date); // formattedDate1: Friday, September 17, 2021 at 13:04:00 China Standard Time

// Display short time information in limited space.
let dateFormat2 = new Intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short'});
let formattedDate2 = dateFormat2.format(date); // formattedDate2: 2021/9/17 13:04 

// Customize the display effect of year, month, day, hour, minute, and second.
let dateFormat3 = new Intl.DateTimeFormat('zh-CN', {year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit'});
let formattedDate3 = dateFormat3.format(date); // formattedDate3: 2021/09/17 13:04:00

// Display only part of the time.
let dateFormat4 = new Intl.DateTimeFormat('zh-CN', {month: 'long', day: 'numeric', weekday: 'long' });
let formattedDate4 = dateFormat4.format(date); // formattedDate4: Friday, September 17

// Customize the date and time format.
let dateFormat5 = new Intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short', hourCycle: 'h11'});
let formattedDate5 = dateFormat5.format(date); // formattedDate5: 2021/9/17 1:04 PM

// Customize the date and time format for users accustomed to other numeral systems.
let dateFormat6 = new Intl.DateTimeFormat('zh-CN', {dateStyle: 'short', timeStyle: 'short', numberingSystem: 'arab'});
let formattedDate6 = dateFormat6.format(date); // formattedDate6: ٢٠٢١/٩/١٧ ١٣:٠٤

// Format a time segment.
let dataFormat7 = new Intl.DateTimeFormat('en-GB');
let formattedDateRange = dataFormat7.formatRange(startDate, endDate); // formattedDateRange: 17/9/2021 - 18/9/2021

// Obtain formatting options.
let dataFormat8 = new Intl.DateTimeFormat('en-GB', {dateStyle: 'full'});
let options = dataFormat8.resolvedOptions();
let dateStyle = options.dateStyle; // dateStyle: full

Relative Time Formatting

Relative time formatting is implemented by the format API of RelativeTimeFormat. The development procedure is as follows:

1. Import the intl module.

   import Intl from '@ohos.intl';
   

2. Create a RelativeTimeFormat object. You can use RelativeTimeFormatInputOptions to set different output message formats and message lengths. For details, see Table 7 and Table 8.

   let relativeTimeFormat: Intl.RelativeTimeFormat = new Intl.RelativeTimeFormat(locale: string | Array<string>, options?: RelativeTimeFormatInputOptions);
   

3. Format the relative time. value indicates the formatted value, and unit indicates the formatted unit.

   let formattedRelativeTime: string = relativeTimeFormat.format(value: number, unit: string);
   

4. Format the custom relative time.

   let parts: Array<object> = relativeTimeFormat.formatToParts(value: number, unit: string);
   

5. Obtain RelativeTimeFormatInputOptions and view the configuration of formatting options.

   let options: IntlRelativeTimeFormatInputOptions = relativeTimeFormat.resolvedOptions();
   

Relative Time Formatting Options

The following uses the relative time one day ago and locales fr-FR and en-GB as an example to show different values of RelativeTimeFormatInputOptions and corresponding display effects.

Table 6 Output message format (numeric)

Table 7 Internationalization message length (style)

Development Example

// Import the intl module.
import Intl from '@ohos.intl';

// Display the relative time.
let relativeTimeFormat1 = new Intl.RelativeTimeFormat('en-GB');
let formattedRelativeTime1 = relativeTimeFormat1.format(-1, 'day'); // formattedRelativeTime1: 1 day ago

// Display the relative time in a conversational style.
let relativeTimeFormat2 = new Intl.RelativeTimeFormat('en-GB', {numeric: "auto"});
let formattedRelativeTime2 = relativeTimeFormat2.format(-1, 'day'); // formattedRelativeTime2: yesterday

// Use the narrow style for certain languages.
let relativeTimeFormat3 = new Intl.RelativeTimeFormat('fr-FR'); // The default style is long.
let formattedRelativeTime3 = relativeTimeFormat3.format(-1, 'day'); // formattedRelativeTime3: il y a 1 jour
let relativeTimeFormat4 = new Intl.RelativeTimeFormat('fr-FR', {style: 'narrow'});
let formattedRelativeTime4 = relativeTimeFormat4.format(-1, 'day'); // formattedRelativeTime4: -1 j

// Display the custom relative time for the specified locale.
let relativeTimeFormat5 = new Intl.RelativeTimeFormat('en-GB', {style: 'long'});
// parts: [{type: 'literal', value: 'in'}, {type: 'integer', value: 1, unit: 'day'}, {type: 'literal', value: 'day'}]
let parts = relativeTimeFormat5.formatToParts(1, 'day');

// Obtain the formatting options of RelativeTimeFormat.
let relativeTimeFormat6 = new Intl.RelativeTimeFormat('en-GB', {numeric: 'auto'});
let options = relativeTimeFormat6.resolvedOptions();
let numeric = options.numeric; // numeric: auto