@arcgis/map-components
Version:
ArcGIS Map Components
293 lines (292 loc) • 14.4 kB
TypeScript
/// <reference path="../../index.d.ts" />
import type SceneView from "@arcgis/core/views/SceneView.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { ArcgisReferenceElement, HeadingLevel } from "../types.js";
import type { Season } from "./types.js";
import type { T9nMeta } from "@arcgis/lumina/controllers";
import type { Icon as Icon } from "@esri/calcite-components/components/calcite-icon";
/**
* The Daylight component can be used to manipulate the lighting conditions of an
* [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/).
* To achieve this, the component modifies the `lighting` property of the
* [arcgis-scene.environment](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#environment) of the Scene component.
*
* To illuminate the scene, one can either use a configuration of date and time to position the
* [sun](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/SunLighting/) or switch to the
* [virtual](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/VirtualLighting/) mode,
* where the light source is relative to the camera.
*
* When illuminating the scene with **[sunlight](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/SunLighting/)**
* and adjusting the time and date, the positions of the sun and stars are updated accordingly. This also updates the
* [date](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/SunLighting/#date) property of
* [arcgis-scene.environment](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#environment).
*
* [](https://developers.arcgis.com/javascript/latest/sample-code/daylight/)
*
* The component has an option to select the timezone. When the user makes any adjustments here, a new time
* in the chosen timezone is calculated and displayed in the slider. The timezone selector can be disabled
* by using the [hideTimezone](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#hideTimezone) property.
*
* By default, a calendar is displayed to select the day, month, and year.
* With the [dateOrSeason](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#dateOrSeason) property, the calendar can be replaced with
* a dropdown menu where a season can be selected instead:
*
* 
*
* There are two play buttons: one corresponds to the time-of-day slider and animates the lighting
* over the course of a day, while the other corresponds to the date picker
* and animates the lighting over the course of a year (month by month). The speed of the time-of-day animation can
* be set using the [playSpeedMultiplier](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#playSpeedMultiplier) property.
*
* <video src="https://developers.arcgis.com/javascript/latest/assets/references/core/components/daylight/daylight-animation.webm" autoplay loop muted playsinline></video>
*
* Except for the daytime slider, all the elements in the Daylight component can be hidden:
*
* 
*
* Whenever the sun position option is unchecked, the scene applies the
* **[virtual light](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/VirtualLighting/)** source relative to the camera.
* With this, the component's time slider, timezone, and date picker get automatically disabled:
*
* 
*
* **Things to consider**
*
* * Daylight is only supported in a 3D [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/) component.
* * The Daylight component uses UTC time and does not account for the daylight savings times in different countries and regions of the world.
* * When using the [virtual light](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/VirtualLighting/),
* setting the time and date programmatically does not have an influence on the lighting conditions of the scene.
* * When using the [sunlight](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/SunLighting/),
* the time slider and time zone automatically react to the changes of the camera (e.g., position, rotation, pan, zoom) because the position of the simulated sun
* is updated to maintain a consistent solar time of day based on the camera's current longitude. This can be adjusted using the
* [cameraTrackingEnabled](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/SunLighting/#cameraTrackingEnabled)
* property on [arcgis-scene.environment](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#environment).
*
* @see [arcgis-scene.environment](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#environment)
* @see [SunLighting](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/SunLighting/)
* @see [VirtualLighting](https://developers.arcgis.com/javascript/latest/references/core/views/3d/environment/VirtualLighting/)
* @see [Sample - Daylight component](https://developers.arcgis.com/javascript/latest/sample-code/daylight/)
* @since 4.28
*/
export abstract class ArcgisDaylight extends LitElement {
/**
* If true, the component will not be destroyed automatically when it is
* disconnected from the document. This is useful when you want to move the
* component to a different place on the page, or temporarily hide it. If this
* is set, make sure to call the [destroy()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#destroy) method when you are done to
* prevent memory leaks.
*
* @default false
*/
accessor autoDestroyDisabled: boolean;
/**
* Sets the season that is used when the component displays the season picker.
* Each season uses a fixed date corresponding to the seasonal equinoxes and solstices.
*
* @see [dateOrSeason](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#dateOrSeason)
*/
accessor currentSeason: Season;
/**
* Controls whether the component displays a date or a season picker. When the date picker is set, the user selects the date from a calendar. The season picker allows the user to choose a season from a drop-down list. Each season uses a fixed month and day corresponding to the equinoxes and solstices in the current local date's year.
*
* @default "date"
*/
accessor dateOrSeason: "date" | "season";
/**
* Starts or pauses the daytime animation cycling through the minutes of the day.
* Set the property to `true` to start the animation and to `false` to pause it.
*
* @default false
*/
accessor dayPlaying: boolean;
/**
* Indicates the heading level to use for the component title.
*
* @default 2
*/
accessor headingLevel: HeadingLevel;
/** @default false */
accessor hideDatePicker: boolean;
/** @default false */
accessor hideHeader: boolean;
/** @default false */
accessor hidePlayButtons: boolean;
/** @default false */
accessor hideShadowsToggle: boolean;
/** @default false */
accessor hideSunLightingToggle: boolean;
/** @default false */
accessor hideTimezone: boolean;
/**
* Icon which represents the component. Typically used when the component is controlled by another component (e.g. by the Expand component).
*
* @default "brightness"
* @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
*/
accessor icon: Icon["icon"] | undefined;
/** The component's default label. */
accessor label: string | undefined;
/**
* The calendar date in the timezone given by [utcOffset](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#utcOffset).
*
* @example
* ```js
* daylight.localDate = new Date("2005-08-25");
* ```
* @example
* ```js
* // Alternatively, the date can be set by configuring the `date` property of `SunLighting`.
* viewElement.environment.lighting = new SunLighting({
* date: new Date("2005-08-25T16:00:00")
* });
* ```
* @since 4.34
*/
get localDate(): Date;
set localDate(value: Date | number | string);
get localDateAsString(): string | undefined;
/** @internal */
protected messages: {
componentLabel: string;
title: string;
shadowsToggle: {
label: string;
tooltip: string;
};
sunLightingToggle: {
label: string;
tooltip: string;
};
unsupported: string;
playDay: string;
playYear: string;
pause: string;
season: string;
spring: string;
summer: string;
winter: string;
fall: string;
date: string;
timezone: string;
timeSliderLabel: string;
} & T9nMeta<{
componentLabel: string;
title: string;
shadowsToggle: {
label: string;
tooltip: string;
};
sunLightingToggle: {
label: string;
tooltip: string;
};
unsupported: string;
playDay: string;
playYear: string;
pause: string;
season: string;
spring: string;
summer: string;
winter: string;
fall: string;
date: string;
timezone: string;
timeSliderLabel: string;
}>;
/**
* Controls the daytime animation speed.
*
* @default 1.0
* @example
* ```js
* // Plays the daylight animation at half of the default speed
* daylight.playSpeedMultiplier = 0.5;
* ```
*/
accessor playSpeedMultiplier: number;
/**
* By assigning the `id` attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.
*
* @see [Associate components with a Map or Scene component](https://developers.arcgis.com/javascript/latest/programming-patterns/#associate-components-with-a-map-or-scene-component)
*/
accessor referenceElement: ArcgisReferenceElement | string | undefined;
/**
* Slider position for the time of day in the timezone
* given by [utcOffset](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/#utcOffset). The position represents the time
* of the day in minutes. Possible values range between 0 and 1440.
*
* @example
* ```js
* // Set the time to 4:00 PM (16:00) in the given timezone.
* daylight.timeSliderPosition = 16 * 60;
* ```
* @example
* ```js
* // Alternatively, the time can be set by configuring the `date` property of `SunLighting`.
* // Then, the time slider gets updated automatically.
* viewElement.environment.lighting = new SunLighting({
* date: new Date("2005-08-25T16:00:00")
* });
* ```
* @since 4.34
*/
accessor timeSliderPosition: number | null | undefined;
/**
* Sets the interval, in minutes, with which the time slider increments or decrements as it is dragged or changed via the keyboard.
*
* @default 5
* @example
* ```js
* // Set steps at an interval of 60. Then, the slider thumb snaps at each hour of the day.
* daylight.timeSliderSteps = 60;
* ```
*/
accessor timeSliderSteps: number[] | number;
/**
* The difference in hours between UTC time and the time displayed in the component.
*
* @example
* ```js
* daylight.utcOffset = -8;
* ```
* @example
* ```js
* // Alternatively, the UTC offset can be set by configuring the `displayUTCOffset` property of `SunLighting`.
* viewElement.environment.lighting = new SunLighting({
* displayUTCOffset: -8
* });
* ```
* @since 4.34
*/
accessor utcOffset: number | null | undefined;
/**
* The view associated with the component.
* > **Note:** The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this `view` property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-daylight component will be associated with a map or scene component rather than using the `view` property.
*/
accessor view: SceneView | undefined;
/**
* Starts or pauses the date animation cycling through the months of the year.
* Set the property to `true` to start the animation and to `false` to pause it.
*
* @default false
*/
accessor yearPlaying: boolean;
/** Permanently destroy the component. */
destroy(): Promise<void>;
"@setterTypes": {
localDate?: Date | number | string;
};
/** Emitted when the component associated with a map or scene view is ready to be interacted with. */
readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
/**
* Fires when the user changes the date or time in the component by interacting with the slider, the date picker, the
* season selector or the play buttons.
*
* @since 4.33
*/
readonly arcgisUserDateTimeChange: import("@arcgis/lumina").TargetedEvent<this, void>;
readonly "@eventTypes": {
arcgisReady: ArcgisDaylight["arcgisReady"]["detail"];
arcgisUserDateTimeChange: ArcgisDaylight["arcgisUserDateTimeChange"]["detail"];
};
}