@arcgis/core

import type FieldFormat from "./FieldFormat.js"; export interface DateTimeFieldFormatProperties extends Partial<Pick<DateTimeFieldFormat, "dateStyle" | "hour12" | "month" | "timeStyle" | "year">> {} export type Hour12 = "always" | "auto" | "never"; /** * The `DateTimeFieldFormat` class defines the formatting options for date and time. It is used in the [FieldConfiguration](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FieldConfiguration/) class to define the display format of fields in a [FeatureLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/). It applies to both the map's popup and any components/widgets that display the field. It is applicable to field [types](https://developers.arcgis.com/javascript/latest/references/core/layers/support/Field/#type) of `date`, `date-only`, `time-only`, and `timestamp-offset`. * * > [!WARNING] * > * > **Breaking change** * > Some date formats may now appear slightly different. For example, if working with the `en-US` locale, the legacy [FieldInfoFormat.dateFormat](https://developers.arcgis.com/javascript/latest/references/core/popup/support/FieldInfoFormat/#dateFormat) property would display `short-date` with a four-digit year, e.g. `3/4/2025`. Using `DateTimeFieldFormat` follows [CLDR](https://cldr.unicode.org/#what-is-cldr) standards based on the specified locale. For `en-US`, this means dates now display with a two-digit year, e.g. `3/4/25`. * > Set the [timeStyle](https://developers.arcgis.com/javascript/latest/references/core/layers/support/DateTimeFieldFormat/#timeStyle) property to either `long` or `full` if the view’s [MapView.timeZone](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#timeZone) is set to `unknown` and the field includes time information. * * ### Date/Time Format Mappings * * The following tables show equivalencies between the legacy [FieldInfoFormat.dateFormat](https://developers.arcgis.com/javascript/latest/references/core/popup/support/FieldInfoFormat/#dateFormat) values and `DateTimeFieldFormat` properties. The examples shown are for the `en-US` locale. Note that the actual display will vary based on the locale of the user. * * > [!WARNING] * > * > **Breaking change** * > When using `dateStyle = "short"`, the display of the year varies by locale. For example, in the `en-US locale`, the year `1969` may be shown as `69`. This formatting follows the * > [CLDR](https://cldr.unicode.org/) standards. * --- * * #### Date & Time Formats * * | **Legacy FieldInfoFormat** | **Equivalent DateTimeFieldFormat** | **Example (en-US)** | * |---|---|---| * | `short-date` | `dateStyle = "short"` | 12/31/1969. | * | `short-date-short-time` | `dateStyle = "short"`, `timeStyle = "short"`, `hour12 = "always"` | 12/31/1969, 7:00 PM | * | `short-date-short-time-24` | `dateStyle = "short"`, `timeStyle = "short"`, `hour12 = never` | 12/31/1969, 19:00 | * | `short-date-long-time` | `dateStyle = "short"`, `timeStyle = "medium"`, `hour12 = "always"` | 12/31/1969, 7:00:00 PM | * | `short-date-long-time-24` | `dateStyle = "short"`, `timeStyle = "medium"`, `hour12 = never` | 12/31/1969, 19:00:00 | * | `long-month-day-year` | `dateStyle = "long"` | December 31, 1969 | * | `long-month-day-year-short-time` | `dateStyle = "long"`, `timeStyle = "short"`, `hour12 = "always"` | December 31, 1969, 7:00 PM | * | `long-month-day-year-short-time-24` | `dateStyle = "long"`, `timeStyle = "short"`, `hour12 = never` | December 31, 1969, 19:00 | * | `long-month-day-year-long-time` | `dateStyle = "long"`, `timeStyle = "medium"`, `hour12 = "always"` | December 31, 1969, 7:00:00 PM | * | `long-month-day-year-long-time-24` | `dateStyle = "long", timeStyle = "medium"`, `hour12 = never` | December 31, 1969, 19:00:00 | * | `day-short-month-year` | `dateStyle = "medium"` | Dec 31, 1969 | * | `day-short-month-year-short-time` | `dateStyle = "medium"`, `timeStyle = "short"`, `hour12 = "always"` | Dec 31, 1969, 7:00 PM | * | `day-short-month-year-short-time-24` | `dateStyle = "medium"`, `timeStyle = "short"`, `hour12 = never` | Dec 31, 1969, 19:00 | * | `day-short-month-year-long-time` | `dateStyle = "medium"`, `timeStyle = "medium"`, `hour12 = "always"` | Dec 31, 1969, 7:00:00 PM | * | `day-short-month-year-long-time-24` | `dateStyle = "medium"`, `timeStyle = "medium"`, `hour12 = never` | Dec 31, 1969, 19:00:00 | * | `long-date` | `dateStyle = "full"` | Wednesday, December 31, 1969 | * | `long-date-short-time` | `dateStyle = "full"`, `timeStyle = "short"`, `hour12 = "always"` | Wednesday, December 31, 1969, 7:00 PM | * | `long-date-short-time-24` | `dateStyle = "full"`, `timeStyle = "short"`, `hour12 = never` | Wednesday, December 31, 1969, 19:00 | * | `long-date-long-time` | `dateStyle = "full"`, `timeStyle = "medium"`, `hour12 = "always"` | Wednesday, December 31, 1969, 7:00:00 PM | * | `long-date-long-time-24` | `dateStyle = "full"`, `timeStyle = "medium"`, `hour12 = never` | Wednesday, December 31, 1969, 19:00:00 | * * --- * * #### Month/Year Only Formats * * | **Legacy (`Format.dateFormat`)** | **DateTimeFieldFormat equivalency** | **Example (en-US)** | * |---|---|---| * | `longMonthYear` | `month: "long"`, `year: "numeric"` | December 1969 | * | `shortMonthYear` | `month: "short"`, `year: "numeric"` | Dec 1969 | * | `year` | `year: "numeric"` | 1969 | * * --- * * #### Legacy (`LE`) Formats * | **Legacy (`Format.dateFormat`)** | **DateTimeFieldFormat equivalency** | * |---|---| * | `short-date-le`, `short-date-le-short-time`, `short-date-le-short-time-24`, `short-date-le-long-time`, `short-date-le-long-time-24` | Treated as equivalent to non-LE versions. `LE` is no longer needed since locale is implied from the browser. | * * @since 4.34 * @see [MDN documentation - DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) * @see [CLDR](https://cldr.unicode.org/) * @see [FieldConfiguration](https://developers.arcgis.com/javascript/latest/references/core/layers/support/FieldConfiguration/) * @example * // Create a date-time field format * const dateTimeFormat = new DateTimeFieldFormat ({ * dateStyle: "medium", * timeStyle: "short", * hour12: "never" * }); * * // Create a field configuration object containing the date-time format * const dateFieldConfiguration = new FieldConfiguration ({ * name: "pollsclose", // name of the field in the service * fieldFormat: dateTimeFormat, * alias: "Polls close" * }); * * // Create a feature layer and pass in the field configurations * const featureLayer = new FeatureLayer ({ * url: "URL to feature service", * outFields: ["*"], * fieldConfigurations: [dateFieldConfiguration] // add as many field configurations as needed * }); */ export default class DateTimeFieldFormat extends FieldFormat { constructor(properties?: DateTimeFieldFormatProperties); /** * Defines the date format. For more options, refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat#parameters). * * @since 4.34 * @see [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) */ accessor dateStyle: "full" | "long" | "medium" | "short" | null | undefined; /** * Determines whether to use 12-hour time (as opposed to 24-hour time). Possible values include: * * Value | Description * ------|------------ * always | Always use 12-hour time (e.g., 1 PM). * auto | (_default_) Use either 12-hour or 24-hour time as based on the locale. * never | Never use 12-hour time (e.g., 13:00). * * @default "auto" * @since 4.34 * @see [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat#parameters) */ accessor hour12: Hour12; /** * Specifies how the month is displayed. For more options, refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat). * * @since 4.34 * @see [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) */ accessor month: "long" | "short" | null | undefined; /** * Defines the time format. For more options, refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat#parameters). * * @since 4.34 * @see [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) */ accessor timeStyle: "full" | "long" | "medium" | "short" | null | undefined; /** * The type of field format. * * @since 4.34 */ get type(): "date-time"; /** * Specifies how the year is displayed. Currently, only supports `numeric`. For more options, refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat). * * @since 4.34 * @see [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) */ accessor year: "numeric" | null | undefined; }