import DateTimeFieldFormat from "@arcgis/core/layers/support/DateTimeFieldFormat.js";const DateTimeFieldFormat = await $arcgis.import("@arcgis/core/layers/support/DateTimeFieldFormat.js");- Inheritance:
- DateTimeFieldFormat→
FieldFormat→ Accessor
- Since
- ArcGIS Maps SDK for JavaScript 4.34
The DateTimeFieldFormat class defines the formatting options for date and time. It is used in the FieldConfiguration class to define the display format of fields in a FeatureLayer. It applies to both the map's popup and any components/widgets that display the field. It is applicable to field types of date, date-only, time-only, and timestamp-offset.
Breaking change
Some date formats may now appear slightly different. For example, if working with the en-US locale, the legacy FieldInfoFormat.dateFormat property would display short-date with a four-digit year, e.g. 3/4/2025. Using DateTimeFieldFormat follows 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 property to either long or full if the view’s 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 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.
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 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 PM |
short-date-short-time-24 | dateStyle = "short", timeStyle = "short", hour12 = never | 12/31/1969, 19 |
short-date-long-time | dateStyle = "short", timeStyle = "medium", hour12 = "always" | 12/31/1969, 7:00 PM |
short-date-long-time-24 | dateStyle = "short", timeStyle = "medium", hour12 = never | 12/31/1969, 19: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 PM |
long-month-day-year-short-time-24 | dateStyle = "long", timeStyle = "short", hour12 = never | December 31, 1969, 19 |
long-month-day-year-long-time | dateStyle = "long", timeStyle = "medium", hour12 = "always" | December 31, 1969, 7:00 PM |
long-month-day-year-long-time-24 | dateStyle = "long", timeStyle = "medium", hour12 = never | December 31, 1969, 19: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 PM |
day-short-month-year-short-time-24 | dateStyle = "medium", timeStyle = "short", hour12 = never | Dec 31, 1969, 19 |
day-short-month-year-long-time | dateStyle = "medium", timeStyle = "medium", hour12 = "always" | Dec 31, 1969, 7:00 PM |
day-short-month-year-long-time-24 | dateStyle = "medium", timeStyle = "medium", hour12 = never | Dec 31, 1969, 19:00 |
long-date | dateStyle = "full" | Wednesday, December 31, 1969 |
long-date-short-time | dateStyle = "full", timeStyle = "short", hour12 = "always" | Wednesday, December 31, 1969, 7 PM |
long-date-short-time-24 | dateStyle = "full", timeStyle = "short", hour12 = never | Wednesday, December 31, 1969, 19 |
long-date-long-time | dateStyle = "full", timeStyle = "medium", hour12 = "always" | Wednesday, December 31, 1969, 7:00 PM |
long-date-long-time-24 | dateStyle = "full", timeStyle = "medium", hour12 = never | Wednesday, December 31, 1969, 19: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. |
Example
// Create a date-time field formatconst dateTimeFormat = new DateTimeFieldFormat ({ dateStyle: "medium", timeStyle: "short", hour12: "never"});
// Create a field configuration object containing the date-time formatconst 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 configurationsconst featureLayer = new FeatureLayer ({ url: "URL to feature service", outFields: ["*"], fieldConfigurations: [dateFieldConfiguration] // add as many field configurations as needed});Constructors
Constructor
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| properties | | |
Properties
| Property | Type | Class |
|---|---|---|
| | ||
declaredClass readonly inherited | ||
| | ||
| | ||
| | ||
type readonly | "date-time" | |
| |
dateStyle
Defines the date format. For more options, refer to the MDN documentation.
- See also
hour12
- Type
- Hour12
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). |
- See also
- Default value
- "auto"
month
Specifies how the month is displayed. For more options, refer to the MDN documentation.
- See also
timeStyle
Defines the time format. For more options, refer to the MDN documentation.
- See also
year
Specifies how the year is displayed. Currently, only supports numeric. For more options, refer to the MDN documentation.
- See also
Methods
fromJSON
- Signature
-
fromJSON (json: any): any
Creates a new instance of this class and initializes it with values from a JSON object
generated from an ArcGIS product. The object passed into the input json
parameter often comes from a response to a query operation in the REST API or a
toJSON()
method from another ArcGIS product. See the Using fromJSON()
topic in the Guide for details and examples of when and how to use this function.
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| json | A JSON representation of the instance in the ArcGIS format. See the ArcGIS REST API documentation for examples of the structure of various input JSON objects. | |
- Returns
- any
Returns a new instance of this class.
clone
- Signature
-
clone (): this
Creates a deep clone of this object. Any properties that store values by reference will be assigned copies of the referenced values on the cloned instance.
- Returns
- this
A deep clone of the class instance that invoked this method.
toJSON
- Signature
-
toJSON (): any
Converts an instance of this class to its ArcGIS portal JSON representation. See the Using fromJSON() guide topic for more information.
- Returns
- any
The ArcGIS portal JSON representation of an instance of this class.