@arcgis/map-components
Version:
ArcGIS Map Components
251 lines (250 loc) • 11.3 kB
TypeScript
/// <reference path="../../index.d.ts" />
import type MapView from "@arcgis/core/views/MapView.js";
import type SceneView from "@arcgis/core/views/SceneView.js";
import type Graphic from "@arcgis/core/Graphic.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { ArcgisReferenceElement, IconName } from "../types.js";
import type { T9nMeta } from "@arcgis/lumina/controllers";
import type { GoToOverride } from "@arcgis/core/widgets/support/types.js";
import type { PositionFilterFunction, TrackViewModelState } from "./types.js";
import type { Button as Button } from "@esri/calcite-components/components/calcite-button";
/**
* The Track component is a button that when activated continuously animates the Map or Scene
* to the user's location as the user moves.
* The view rotates based on device heading, and the default heading symbol will display
* when speed is greater than zero and the browser provides heading information.
*
* This component uses the browser's [Geolocation API](https://developer.mozilla.org/docs/Web/API/Geolocation_API) which is only available in [secure contexts](https://developer.mozilla.org/docs/Web/Security/Defenses/Secure_Contexts), such as HTTPS.
* `localhost` is considered "potentially secure" and can be used for testing.
*
* > [!WARNING]
* >
* > **Note**
* >
* > To avoid unexpected navigation, especially when using custom spatial references, configure the view [constraints](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/#constraints)
* > such as `extent`, `minZoom`, and `maxZoom`.
* > This helps when the geolocated position is inaccurate or causes the map to navigate to a location that is no longer visible because it is outside of
* > a layer's `fullExtent`.
*
* **Known limitations**
*
* - The heading symbol is not currently supported within an [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/).
*
* @since 4.28
*/
export abstract class ArcgisTrack 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-track/#destroy) method when you are done to
* prevent memory leaks.
*
* @default false
*/
accessor autoDestroyDisabled: boolean;
/**
* Indicates the current position of the geolocation result returned by the browser's Geolocation API.
* This property is updated when a new position is returned by the API, and is used to update the graphic and navigate to that location.
*
* @since 5.1
*/
accessor currentPosition: GeolocationPosition | undefined;
/**
* Error that caused the last [track-error](https://developers.arcgis.com/javascript/latest/references/core/widgets/Track/TrackViewModel/#event:track-error) event to fire.
*
* @since 4.29
* @example
* if(track.viewModel.state === 'error')
* console.error(track.viewModel.error);
*/
accessor error: Error | GeolocationPositionError | undefined;
/**
* An object used for setting optional position parameters. Refer to the
* [Geolocation API Specification](https://www.w3.org/TR/geolocation/#position_options_interface)
* for details on using these parameters.
*
* @example
* const track = new Track({
* view: view,
* // Set optional position parameters
* geolocationOptions: {
* maximumAge: 0,
* timeout: 15000,
* enableHighAccuracy: true
* }
* });
*/
accessor geolocationOptions: PositionOptions | undefined;
/**
* Indicates whether to navigate the view to the position and scale of the geolocated result.
*
* @default false
*/
accessor goToLocationDisabled: boolean;
/**
* This function provides the ability to override either the [arcgis-map.goTo()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-map/#goTo) or [arcgis-scene.goTo()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#goTo) methods.
*
* @since 4.33
* @example
* ```js
* component.goToOverride = function(view, goToParams) {
* goToParams.options = {
* duration: updatedDuration
* };
* return view.goTo(goToParams.target, goToParams.options);
* };
* ```
*/
accessor goToOverride: GoToOverride | undefined;
/**
* The graphic used to show the user's location on the map.
*
* @example
* const trackComponent = document.createElement("arcgis-track");
* // Overwrite the default symbol used for the
* // graphic placed at the location of the user
* trackComponent.graphic = new Graphic ({
* symbol: {
* // autocasts as new SimpleMarkerSymbol()
* type: "simple-marker",
* size: "12px",
* color: "blue",
* // autocasts as new SimpleLineSymbol()
* outline: {
* color: "#efefef",
* width: "1.5px"
* }
* }
* });
*/
accessor graphic: Graphic;
/**
* Icon displayed in the component's button.
*
* @default "compass-north-circle"
* @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
*/
accessor icon: IconName | undefined;
/** The component's default label. */
accessor label: string | undefined;
/**
* Replace localized message strings with your own strings.
*
* _**Note**: Individual message keys may change between releases._
*/
accessor messageOverrides: {
componentLabel?: string | undefined;
startTracking?: string | undefined;
stopTracking?: string | undefined;
permissionError?: string | undefined;
timeoutError?: string | undefined;
positionUnavailable?: string | undefined;
};
/** @internal */
protected messages: Partial<{
componentLabel: string;
startTracking: string;
stopTracking: string;
permissionError: string;
timeoutError: string;
positionUnavailable: string;
}> & T9nMeta<{
componentLabel: string;
startTracking: string;
stopTracking: string;
permissionError: string;
timeoutError: string;
positionUnavailable: string;
}>;
/**
* A function that is used as an expression to evaluate geolocation points, and returns a boolean
* value. If the function returns `true`, the component will draw a graphic and navigate to the position.
* The component will ignore `false` values and not draw a graphic and not navigate to the position.
*
* Example use cases include smoothing out geolocation anomalies and geofencing.
*
* @since 4.27
* @example
* // Exclude locations that full outside an extent.
* trackComponent.positionFilterFunction = (value) => {
* const { longitude, latitude } = value.position.coords;
* const myLocation = new Point({ longitude, latitude });
* const geofenceExtent = new Extent({
* // whatever
* });
* return geometryEngine.within(myLocation, geofenceExtent);
* };
*/
accessor positionFilterFunction: PositionFilterFunction | undefined;
/**
* 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;
/**
* Indicates whether the component will automatically rotate to the device heading based on
* the Geolocation APIs [`GeolocationCoordinates.heading`](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/heading)
* property. The map will not rotate if the speed is `0`,
* or if the device is unable to provide heading information.
*
* @default false
* @since 4.33
*/
accessor rotationDisabled: boolean;
/**
* Indicates the scale to set on the view when navigating to the position of the geolocated
* result, after a location is returned.
*
* By default, the view will navigate to a scale of `2500` for 3D and `4514` for 2D.
* To override the default in 2D, set the `scale` property and also set [snapToZoom](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#constraints) to `false`.
* For 2D views the value should be within the [effectiveMinScale](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#constraints)
* and [effectiveMaxScale](https://developers.arcgis.com/javascript/latest/references/core/views/MapView/#constraints).
*
* @since 4.7
*/
accessor scale: number | undefined;
/**
* The current state of the component.
*
* @default "disabled"
*/
get state(): TrackViewModelState;
/**
* Indicates whether new positions are being watched.
*
* @default false
*/
get tracking(): boolean;
/**
* 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-track component will be associated with a map or scene component rather than using the `view` property.
*/
accessor view: MapView | SceneView | undefined;
/**
* Specifies the size of the component.
*
* @default "m"
* @since 5.0
*/
accessor visualScale: Button["scale"];
/** Permanently destroy the component. */
destroy(): Promise<void>;
/** Start tracking the user's location. Only start the component on a user gesture such as a click event. */
start(): Promise<void>;
/** Stop tracking the user's location. */
stop(): Promise<void>;
readonly arcgisComplete: import("@arcgis/lumina").TargetedEvent<this, { position: GeolocationPosition; }>;
readonly arcgisError: import("@arcgis/lumina").TargetedEvent<this, { error: GeolocationPositionError; }>;
/** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
readonly arcgisPropertyChange: import("@arcgis/lumina").TargetedEvent<this, { name: "state"; }>;
/** 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>;
readonly "@eventTypes": {
arcgisComplete: ArcgisTrack["arcgisComplete"]["detail"];
arcgisError: ArcgisTrack["arcgisError"]["detail"];
arcgisPropertyChange: ArcgisTrack["arcgisPropertyChange"]["detail"];
arcgisReady: ArcgisTrack["arcgisReady"]["detail"];
};
}