@arcgis/core

import type { ClonableMixin } from "../../core/Clonable.js"; import type { JSONSupport } from "../../core/JSONSupport.js"; import type { DateFormat } from "../../intl/date.js"; export interface FieldInfoFormatProperties extends Partial<Pick<FieldInfoFormat, "dateFormat" | "digitSeparator" | "places">> {} /** * The `FieldInfoFormat` class is used with numerical or date fields to provide more detail * about how the value should be displayed in a popup. Use this class in place of the legacy * formatting functions: `DateString`, `DateFormat`, and/or `NumberFormat`. * * > [!WARNING] * > * > When formatting `Number` fields, you must set both the `digitSeparator` and `places` * > properties for the formatting to take effect. * * @since 4.11 * @see [PopupTemplate](https://developers.arcgis.com/javascript/latest/references/core/PopupTemplate/) * @see [FieldInfo](https://developers.arcgis.com/javascript/latest/references/core/popup/FieldInfo/) * @see [intl](https://developers.arcgis.com/javascript/latest/references/core/intl/) * @see [Sample - Intro to PopupTemplate](https://developers.arcgis.com/javascript/latest/sample-code/intro-popuptemplate/) * @see [Sample - Custom popup actions per feature](https://developers.arcgis.com/javascript/latest/sample-code/popup-custom-action/) * @see [Sample - Multiple popup elements](https://developers.arcgis.com/javascript/latest/sample-code/popup-multipleelements/) * @see [Sample - PopupTemplate function](https://developers.arcgis.com/javascript/latest/sample-code/popuptemplate-function/) * @see [Sample - PopupTemplate with promise](https://developers.arcgis.com/javascript/latest/sample-code/popuptemplate-promise/) * @example * let fieldInfo = new FieldInfo({ * fieldName: "PROMINENCE_ft", * label: "Prominence (feet)", * //autocasts to FieldInfo.Format * format: { * places: 0, * digitSeparator: true * } * }; */ export default class FieldInfoFormat extends FieldInfoFormatSuperclass { constructor(properties?: FieldInfoFormatProperties); /** * Used only with `Date` fields. Specifies how the date should appear in a popup. * * **Possible Values** * * | **Format** | **Date Formatting** | * |---|---| * | **short-date** | 12/31/1969 | * | **short-date-short-time** | 12/31/1969, 7:00 PM | * | **short-date-short-time-24** | 12/31/1969, 19:00 | * | **short-date-long-time** | 12/31/1969, 7:00:00 PM | * | **short-date-long-time-24** | 12/31/1969, 19:00:00 | * | **long-month-day-year** | December 31, 1969 | * | **long-month-day-year-short-time** | December 31, 1969, 7:00 PM | * | **long-month-day-year-short-time-24** | December 31, 1969, 19:00 | * | **long-month-day-year-long-time** | December 31, 1969, 7:00:00 PM | * | **long-month-day-year-long-time-24** | December 31, 1969, 19:00:00 | * | **day-short-month-year** | Dec 31, 1969 | * | **day-short-month-year-short-time** | Dec 31, 1969, 7:00 PM | * | **day-short-month-year-short-time-24** | Dec 31, 1969, 19:00 | * | **day-short-month-year-long-time** | Dec 31, 1969, 7:00:00 PM | * | **day-short-month-year-long-time-24** | Dec 31, 1969, 19:00:00 | * | **long-date** | Wednesday, December 31, 1969 | * | **long-date-short-time** | Wednesday, December 31, 1969, 7:00 PM | * | **long-date-short-time-24** | Wednesday, December 31, 1969, 19:00 | * | **long-date-long-time** | Wednesday, December 31, 1969, 7:00:00 PM | * | **long-date-long-time-24** | Wednesday, December 31, 1969, 19:00:00 | * | **long-month-year** | December 1969 | * | **short-month-year** | Dec 1969 | * | **year** | 1969 | * * > [!WARNING] * > * > The `time-only` date fields will only honor the _time_ component (i.e. _ShortTime_, _ShortTime24_, * > _LongTime_ or _LongTime24_) in a dateFormat. Date formats without a time component are not supported by time-only fields. * > Starting with version 4.28, `date` fields are formatted using the `short-date-short-time` format rather than * > `long-month-day-year` in [popup templates](https://developers.arcgis.com/javascript/latest/references/core/PopupTemplate/) created with the [createPopupTemplate()](https://developers.arcgis.com/javascript/latest/references/core/support/popupUtils/#createPopupTemplate) method. * > This is also the case for default [popup templates](https://developers.arcgis.com/javascript/latest/references/core/PopupTemplate/) created by setting the `defaultPopupTemplateEnabled` property to `true` on the * > [Popup.defaultPopupTemplateEnabled](https://developers.arcgis.com/javascript/latest/references/core/widgets/Popup/#defaultPopupTemplateEnabled), [Features](https://developers.arcgis.com/javascript/latest/references/core/widgets/Features/FeaturesViewModel/#defaultPopupTemplateEnabled), or [Feature.defaultPopupTemplateEnabled](https://developers.arcgis.com/javascript/latest/references/core/widgets/Feature/#defaultPopupTemplateEnabled) widgets. * > For example, previously a date that may have appeared as `"December 30, 1997"` will now appear as `"12/30/1997 6:00 PM"`. * > fields that need to have number formatting for chart/text elements. * > If displaying a `timestamp-offset` or `date` [Field.type](https://developers.arcgis.com/javascript/latest/references/core/layers/support/Field/#type) field in a [Popup](https://developers.arcgis.com/javascript/latest/references/core/widgets/Popup/), [Features](https://developers.arcgis.com/javascript/latest/references/core/widgets/Features/), or [Feature](https://developers.arcgis.com/javascript/latest/references/core/widgets/Feature/) widget and the [MapView](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/) has a [MapView.timeZone](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#timeZone) set other than `unknown`, * > the abbreviated time zone suffix will be omitted from the attribute value. For example, the attribute value will display as `9/28/2014, 7:58 PM`. To display an abbreviated time zone suffix, see the `Read more` section. * > <details> * > <summary>Read More</summary> * > * > * If the user wants `date` fields to show a time zone suffix (e.g. `9/28/2014, 7:58 PM PST`), then the [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) [Text](https://developers.arcgis.com/arcade/function-reference/text_functions/#text) function can be used to format the field value. This can be done either with [ExpressionContent](https://developers.arcgis.com/javascript/latest/references/core/popup/content/ExpressionContent/) or [attribute expressions](https://developers.arcgis.com/javascript/latest/references/core/popup/ExpressionInfo/). * > ```js * > // Attribute expression using expressionInfos to append the time zone suffix to a date field. * > // Date field types will show in the MapView's current time zone. * > layer.popupTemplate = { * > title: "Display time zones", * > fieldInfos: [{ * > fieldName: "expression/date-with-time-zone-suffix", * > }], * > expressionInfos: [{ * > expression: `Text($feature.date_Field, "M/D/Y, h:mm A ZZZZ")`, * > name: "date-with-time-zone-suffix", * > }], * > content: [{ * > type: "fields" * > }] * > }; * > ``` * > ```js * > // ExpressionContent to append the time zone suffix to a date field. * > // Date field types will show in the MapView's current time zone by default. * > layer.popupTemplate = { * > title: "Display time zones", * > content: [{ * > type: "expression", * > expressionInfo: { * > expression: `return { * > type : 'text', * > text : Text($feature.date_Field, "M/D/Y, h:mm A ZZZZ") * > }` * > } * > }] * > }; * > ``` * > * If the user wants `timestamp-offset` fields to display in the time zone from the server with an abbreviated time zone suffix, then the [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) [Text](https://developers.arcgis.com/arcade/function-reference/text_functions/#text) function can be used to format the field value. This can be done either with [ExpressionContent](https://developers.arcgis.com/javascript/latest/references/core/popup/content/ExpressionContent/) or [attribute expressions](https://developers.arcgis.com/javascript/latest/references/core/popup/ExpressionInfo/). * > ```js * > // Attribute expression using expressionInfos to append the time zone suffix to a timestamp-offset field. * > layer.popupTemplate = { * > title: "Display time zones", * > fieldInfos: [{ * > fieldName: "expression/TSO-from-server", * > }], * > expressionInfos: [{ * > expression: `Text($feature.TimestampOffset_Field, "M/D/Y, h:mm A ZZZZ")`, * > name: "TSO-from-server", * > }], * > content: [{ * > type: "fields" * > }] * > }; * > ``` * > ```js * > // ExpressionContent to append the time zone suffix to a timestamp-offset field. * > layer.popupTemplate = { * > title: "Display time zones", * > content: [{ * > type: "expression", * > expressionInfo: { * > expression: `return { * > type : 'text', * > text : Text($feature.TimestampOffset_Field, "M/D/Y, h:mm A ZZZZ") * > }` * > } * > }] * > }; * > ``` * > * If the user wants `timestamp-offset` fields to display in the MapView's time zone with an abbreviated time zone suffix, then the [`ChangeTimeZone`](https://developers.arcgis.com/javascript/latest/arcade/function-reference/date_functions/#changetimezone) [Arcade](https://developers.arcgis.com/javascript/latest/arcade/) function can be used to format the value. * > ```js * > // Attribute expression using expressionInfos to append the MapView's current time zone suffix to a timestamp-offset field * > layer.popupTemplate = { * > title: "Display time zones", * > fieldInfos: [{ * > fieldName: "expression/TSO-matching-view-tz", * > }], * > expressionInfos: [{ * > expression: `Text(ChangeTimeZone($feature.TimestampOffset_Field, GetEnvironment().timeZone), "M/D/Y, h:mm A ZZZZ")`, * > name: "TSO-matching-view-tz", * > }], * > content: [{ * > type: "fields" * > }] * > }; * > ``` * > ```js * > // ExpressionContent to append the MapView's current time zone suffix to a timestamp-offset field * > layer.popupTemplate = { * > title: "Display time zones", * > content: [{ * > type: "expression", * > expressionInfo: { * > expression: `return { * > type: "text", * > text: Text(ChangeTimeZone($feature.TimestampOffset_Field, GetEnvironment().timeZone), "M/D/Y, h:mm A ZZZZ") * > }` * > } * > }] * > }; * > ``` * > * > </details> * * @see [intl](https://developers.arcgis.com/javascript/latest/references/core/intl/) * @see [ElementExpressionInfo](https://developers.arcgis.com/javascript/latest/references/core/popup/ElementExpressionInfo/) */ dateFormat?: DateFormat | null; /** * Used only with `Number` fields. A value of `true` indicates the number * should have a digit (or thousands) separator when the value appears in popups. * A value of `false` means that no separator will be used. * * @default false */ accessor digitSeparator: boolean; /** * Used only with `Number` fields to specify the number of supported decimal places * that should appear in popups. Any places beyond this value are rounded. */ accessor places: number | null | undefined; } declare const FieldInfoFormatSuperclass: typeof JSONSupport & typeof ClonableMixin