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. dateStyle and timeStyle must be set simultaneously. If only timeStyle is set, only the time is displayed. If only dateStyle is set, only the date is displayed.

2. If dateStyle or timeStyle is present, you are not allowed to specify the year, month, day, hour, minute, second, and workday formats. If dateStyle and timeStyle are not present, you can set the year, month, day, hour, minute, second, and workday formats 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 '@kit.LocalizationKit';
   

2. Create a DateTimeFormat object. Pass a single locale ID or a list of locale IDs. If a list of locale IDs is passed, the first valid locale is used. If no locale is passed, the current system locale ID is used. You can use DateTimeOptions to set different date and time formats. For details, see Table 1 to Table 10.

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

1. Format the date and time. “`ts // 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.
   ```ts
   let options: intl.DateTimeOptions = dateFormat.resolvedOptions();

Date and Time Formatting Options

The following uses 13:04:00 and 00:25:00 on September 17, 2021 and locale IDs zh-CN and en as examples to illustrate the values and display results of DateTimeOptions.

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 format (hourCycle)

NOTE

The preceding table shows the display effect for different values of hourCycle when dateStyle or timeStyle is not set.

Table 6 Hour cycle format (hourCycle)

NOTE

The preceding table shows the display effect for different values of hourCycle when dateStyle or timeStyle is set.

Table 7 Month format (month)

Table 8 Localized representation of time zone names (timeZoneName)

Table 9 Era display format (era)

Table 10 Time period format (dayPeriod)

Development Example

// Import the intl module.
import { intl } from '@kit.LocalizationKit';

let date: Date = new Date(2021, 8, 17, 13, 4, 0); // The date and time is 2021.09.17 13:04:00.
let startDate: Date = new Date(2021, 8, 17, 13, 4, 0);
let endDate: Date = new Date(2021, 8, 18, 13, 4, 0);

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

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

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

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

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

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

// Format a time segment.
let dateRangeFormat: intl.DateTimeFormat = new intl.DateTimeFormat('en-GB');
let formattedDateRange: string =
  dateRangeFormat.formatRange(startDate, endDate); // formattedDateRange = '17/09/2021 - 18/09/2021'

// Obtain formatting options.
let dateFormat: intl.DateTimeFormat = new intl.DateTimeFormat('en-GB', { dateStyle: 'full' });
let options: intl.DateTimeOptions = dateFormat.resolvedOptions();
let dateStyle: string|undefined = 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 '@kit.LocalizationKit';
   

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: intl.RelativeTimeFormatInputOptions = relativeTimeFormat.resolvedOptions();
   

Relative Time Formatting Options

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

Table 11 Numeric representation (numeric)

Table 12 Relative time style (style)

Development Example

// Import the intl module.
import { intl } from '@kit.LocalizationKit';

// Display the relative time.
let relativeTimeFormat: intl.RelativeTimeFormat = new intl.RelativeTimeFormat('en-GB');
let formattedRelativeTime: string = relativeTimeFormat.format(-1, 'day'); // formattedRelativeTime = '1 day ago'

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

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

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

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

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Localization Kit

harmony 鸿蒙Calendar Setting

harmony 鸿蒙Character Processing

harmony 鸿蒙Overview

harmony 鸿蒙DST Transition

harmony 鸿蒙Overview of Internationalization and Localization

harmony 鸿蒙Language and Locale Name Localization

harmony 鸿蒙Locale ID and Cultural Habit Division

harmony 鸿蒙Number and Unit of Measurement Formatting

harmony 鸿蒙Phone Number Formatting