import FieldConfiguration from "@arcgis/core/layers/support/FieldConfiguration.js";const FieldConfiguration = await $arcgis.import("@arcgis/core/layers/support/FieldConfiguration.js");- Inheritance:
- FieldConfiguration→
Accessor
- Since
- ArcGIS Maps SDK for JavaScript 4.34
The FieldConfiguration class defines how fields in a layer are displayed and formatted within widgets and UI components. It provides a standardized way to customize field presentation, including display names, alias, and formatting rules for numbers and dates. Using field configurations ensures consistent formatting across components that consume the layer's data.
Previously, field information was defined using FieldInfo objects. Although compatibility with FieldInfo is maintained for existing applications, FieldConfiguration is the preferred pattern for new development and for updating existing code.
Field configurations are typically assigned to a layer's FeatureLayer.fieldConfigurations property before initializing components such as FeatureTable or Popup components. Configurations are created with the FieldConfiguration class, where the fieldFormat property can be set to either a DateTimeFieldFormat or NumberFieldFormat object, depending on the field type.
Note that field configurations affect only how field values are displayed in the UI. They do not modify the underlying data in the feature layer.
Known Limitations and Considerations:
- Field configuration support is currently limited to feature service-based FeatureLayer instances, including tables. Additional layer types and data sources, such as client-side graphics or feature collections, are not supported at this time. Support for additional layer types is planned for future releases.
- Field configurations are not supported in expression or relationship contexts in Arcade expressions. For example, fields referenced as
expression/abc123orrelationships/0/fielddo not currently support field configurations. - The FieldInfo.format property is used for date and number formatting when applied to unsupported layer types or contexts.
- When displaying date/time fields, set the DateTimeFieldFormat.timeStyle property to either
longorfullif the view’s MapView.timeZone is set tounknownand the field includes time information.
Examples
// Create a number field formatconst numberFormat = new NumberFieldFormat ({ minimumFractionDigits: 2, maximumFractionDigits: 4, useGrouping: "always"});
// Create a field configuration object containing the number formatconst numFieldConfiguration = new FieldConfiguration ({ name: "lat", // name of the field in the service fieldFormat: numberFormat, alias: "Latitude"});
// Create a date-time field formatconst dateTimeFormat = new DateTimeFieldFormat ({ dateStyle: "medium", timeStyle: "short", hour12: "never"});
// Create a field configuration object containing the date formatconst dateFieldConfiguration = new FieldConfiguration ({ name: "collectionDate", // name of the field in the service fieldFormat: dateTimeFormat, alias: "Date Collected"});
// Create a feature layer and pass in the field configurationsconst featureLayer = new FeatureLayer ({ url: "url to feature layer", outFields: ["*"], fieldConfigurations: [numFieldConfiguration, dateFieldConfiguration] // add as many field configurations as needed
});// Adding a new field configurationconst addNewConfig = (layer, fieldName, alias,fieldFormat) => { const existingConfig = layer.getFieldConfiguration(fieldName); if (!existingConfig) { const newConfig = new FieldConfiguration ({ name: fieldName, alias, fieldFormat }); const newConfigs = clone(layer.fieldConfigurations); newConfigs.push(newConfig); layer.fieldConfigurations = newConfigs; }};// Updating an existing field configurationconst updateConfig = (layer, fieldName, alias,fieldFormat) => { const existingConfig = layer.getFieldConfiguration(fieldName); if (existingConfig) { const newConfig = existingConfig.clone(); newConfig.alias = alias; newConfig.fieldFormat = fieldFormat;
const index = layer.fieldConfigurations.indexOf(existingConfig); const newConfigs = clone(layer.fieldConfigurations); newConfigs[index] = newConfig; layer.fieldConfigurations = newConfigs; }};// Deleting an existing field configurationconst deleteConfig = (layer, fieldName) => { const existingConfig = layer.getFieldConfiguration(fieldName); if(existingConfig) { const index = layer.fieldConfigurations.indexOf(existingConfig); var newConfigs = clone(layer.fieldConfigurations); newConfigs.splice(index, 1); layer.fieldConfigurations = newConfigs; }};Constructors
Constructor
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| properties | | |
Properties
| Property | Type | Class |
|---|---|---|
| | ||
declaredClass readonly inherited | ||
| | ||
| |
alias
The alias (or display name) for the field. This is used in place of the field name when displaying the field in a widget or UI component. If not specified, the field's Field.alias is used. If the layer does not define an alias for the field, the field name itself is used.
- See also
fieldFormat
- Type
- FieldFormatUnion | null | undefined
The format of the field. This can be either a DateTimeFieldFormat or NumberFieldFormat object. This is dependent upon the type of field.
Example
const fieldConfig = new FieldConfiguration({ "name": "install_date", "alias": "Date of Installation", "fieldFormat": { // Autocast to DateTimeFieldFormat "type": "date-time", "dateStyle": "short", "timeStyle": "medium" }});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.