TimeExtent | References | ArcGIS Maps SDK for JavaScript

import TimeExtent from "@arcgis/core/time/TimeExtent.js";

Inheritance:: TimeExtent→Accessor

Since: ArcGIS Maps SDK for JavaScript 4.31

A period of time with a definitive start and end date. Time extent is used to FeatureLayerView.filter or query features that fall within the specified time period. To represent an instant of time, set the start and end times to the same date.

When creating a JavaScript Date, be mindful that most constructors will create a date with respect to your local timezone rather than UTC (i.e. universal time). To create a date with respect to UTC, use the UTC method on the Date object.

Example

// Represents the data for the month of Jan, 1970
const timeExtent = new TimeExtent({
  start: new Date(Date.UTC(1970, 0, 1, 6, 30)),
  end: new Date(Date.UTC(1970, 0, 31, 6, 30))
});

Constructors

Constructor

Parameters

Parameter	Type	Description	Required
properties	`TimeExtentProperties`

See the properties table for a list of all the properties that may be passed into the constructor.

Example

// Typical usage
// Represents the data for the month of Jan, 1970
const timeExtent = new TimeExtent({
  start: new Date(Date.UTC(1970, 0, 1, 6, 30)),
  end: new Date(Date.UTC(1970, 0, 31, 6, 30))
});

Properties

Any properties can be set, retrieved or listened to. See the Watch for changes topic.

Property	Type	Class
`declaredClass` readonly inherited	`string`	Accessor
`end`	`Date \| null \| undefined`
`start`	`Date \| null \| undefined`

declaredClass

readonlyinherited Property

Type: string

Inherited from: Accessor

The name of the class. The declared class name is formatted as esri.folder.className.

end

autocast Property

Type: Date | null | undefined

The end time of the time extent.

start

autocast Property

Type: Date | null | undefined

The start time of the time extent.

Methods

Method	Signature	Class
`fromJSON` inherited static	`fromJSON(json: any): any`	JSONSupportMixin
`clone`	`clone(): TimeExtent`
`expandTo`	`expandTo(unit: TimeUnit, timeZone?: TimeZone): TimeExtent`
`intersection`	`intersection(timeExtent: TimeExtent \| null \| undefined): TimeExtent`
`toJSON` inherited	`toJSON(): any`	JSONSupportMixin
`union`	`union(timeExtent: TimeExtent \| null \| undefined): TimeExtent`

fromJSON

inheritedstatic Method

Signature: fromJSON (json: any): any

Inherited from: JSONSupportMixin

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	`any`	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

Method

Signature: clone (): TimeExtent

Creates a deep clone of TimeExtent object.

Returns: TimeExtent
A new instance of a TimeExtent object equal to the object used to call .clone().

expandTo

Method

Signature: expandTo (unit: TimeUnit, timeZone?: TimeZone): TimeExtent

Expands the TimeExtent so that the start and end dates are rounded down and up, respectively, to the parsed time unit.

See also

Sample - Time Slider component

Parameters

Parameter	Type	Description	Required
unit	`TimeUnit`	The time unit to align the start and end dates.
timeZone	`TimeZone`	The time zone in which progressing will occur. The default is "system".

Returns: TimeExtent
A new expanded TimeExtent.

Examples

// Expand a time extent to a decade.
const extent = new TimeExtent({
  start: new Date(2012, 3, 5),
  end: new Date(2019, 0, 4)
});
const decade = extent.expandTo("decades");
// decade is: 1/1/2010 to 1/1/2020

// Expand a time extent to the nearest month.
const extent = new TimeExtent({
  start: new Date(2012, 3, 5),
  end: new Date(2019, 0, 4)
});
const expandToMonth = extent.expandTo("months");
// expandToMonth is: 4/1/2012 to 2/1/2019

intersection

Method

Signature: intersection (timeExtent: TimeExtent | null | undefined): TimeExtent

Returns the time extent resulting from the intersection of a given time extent and parsed time extent. Returns a timeExtent with undefined values for start and end properties if the two time extents do not intersect.

Parameters

Parameter	Type	Description	Required
timeExtent	`TimeExtent \| null \| undefined`	The time extent to be intersected with the time extent on which `intersection()` is being called on.

Returns: TimeExtent
The intersecting time extent between two time extents.

Example

// get the intersecting timeExtent between view.timeExtent and
// layer view filter's timeExtent
const timeExtent = view.timeExtent.intersection(layerView.effect.filter.timeExtent);
if (timeExtent){
  console.log("time intersection", timeExtent);
  const query = layerView.createQuery();
  query.timeExtent = timeExtent;
  layerView.queryFeatures(query).then(function(results){
    console.log(results.features.length, " are returned for intersecting timeExtent");
  });
}

toJSON

inherited Method

Signature: toJSON (): any

Inherited from: JSONSupportMixin

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.

union

Method

Signature: union (timeExtent: TimeExtent | null | undefined): TimeExtent

Returns the time extent resulting from the union of the current time extent and a given time extent.

Parameters

Parameter	Type	Description	Required
timeExtent	`TimeExtent \| null \| undefined`	The time extent to be unioned with.

Returns: TimeExtent
The resulting union of the current time extent and the given time extent.

Example

// Return the union of two time extents. One from 1990 to 2000 and the second from 2010 to 2020.
const decade1 = new TimeExtent({
  start: new Date(1990, 0, 1),
  end: new Date(2000, 0, 1)
});
const decade2 = new TimeExtent({
  start: new Date(2010, 0, 1),
  end: new Date(2020, 0, 1)
});
const union = decade1.union(decade2);
console.log(`The unioned extent starts from year ${union.start.getFullYear()} to ${union.end.getFullYear()}`);
// output: "The unioned extent starts from year 1990 to 2020"