@arcgis/map-components
Version:
ArcGIS Map Components
427 lines (426 loc) • 18.6 kB
TypeScript
/// <reference path="../../index.d.ts" />
import type Collection from "@arcgis/core/core/Collection.js";
import type Point from "@arcgis/core/geometry/Point.js";
import type Conversion from "@arcgis/core/widgets/CoordinateConversion/support/Conversion.js";
import type Format from "@arcgis/core/widgets/CoordinateConversion/support/Format.js";
import type PictureMarkerSymbol from "@arcgis/core/symbols/PictureMarkerSymbol.js";
import type SimpleMarkerSymbol from "@arcgis/core/symbols/SimpleMarkerSymbol.js";
import type CIMSymbol from "@arcgis/core/symbols/CIMSymbol.js";
import type PointSymbol3D from "@arcgis/core/symbols/PointSymbol3D.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { ArcgisReferenceElement, IconName, HeadingLevel } from "../types.js";
import type { LengthUnit } from "@arcgis/core/core/units.js";
import type { StorageType } from "./types.js";
import type { T9nMeta } from "@arcgis/lumina/controllers";
import type { MapViewOrSceneView } from "@arcgis/core/views/MapViewOrSceneView.js";
import type { GoToOverride } from "@arcgis/core/widgets/support/types.js";
import type { Mode } from "@arcgis/core/widgets/types.js";
import type { Panel as Panel } from "@esri/calcite-components/components/calcite-panel";
import type { CoordinateConversionViewModelState } from "@arcgis/core/widgets/CoordinateConversion/CoordinateConversionViewModel.js";
/**
* > [!WARNING]
* > The Coordinate Conversion (next) component is the successor to the [arcgis-coordinate-conversion](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-coordinate-conversion/) component, provided to you for early testing and feedback.
* > It provides a more consistent design and improved user experience.
* > In version 6.0, the implementation of [arcgis-coordinate-conversion](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-coordinate-conversion/) will be updated under the hood to that of [arcgis-coordinate-conversion-next](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-coordinate-conversion-next/) and this component will be removed.
* > To update at version 6.0, simply remove `-next` from the component name.
*
* The Coordinate Conversion component provides a way to display user cursor position either as map coordinates or
* as any of several popular coordinate notations. Additionally, the component provides a way to convert
* user input coordinates into a [point](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/).
*
*
* Several common formats are included by default:
* * XY - Longitude, Latitude (WGS84)
* * MGRS - [Military Grid Reference System](https://earth-info.nga.mil/index.php?dir=coordsys&action=coordsys#mgrs)
* * UTM - [Universal Transverse Mercator](https://earth-info.nga.mil/index.php?dir=coordsys&action=coordsys#utm)
* * DD - Decimal Degrees
* * DDM - Degrees Decimal Minutes
* * DMS - Degrees Minutes Seconds
* * Basemap - X, Y in the coordinate system used by the current basemap in the units used by the basemap.
* Web Mercator is the standard for Esri-provided basemaps.
*
* Additional formats can be created by a developer and made available
* through the component
*
* @beta
* @since 5.1
* @example
* ```html
* <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
* <arcgis-coordinate-conversion slot="bottom-left"></arcgis-coordinate-conversion>
* </arcgis-map>
* ```
*/
export abstract class ArcgisCoordinateConversionNext 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-coordinate-conversion-next/#destroy) method when you are done to
* prevent memory leaks.
*
* @default false
*/
accessor autoDestroyDisabled: boolean;
/**
* A [collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/) of conversions
* that the component is currently displaying. Each row in the component displaying a coordinate is a conversion.
*
* @example
* Conversions can be set with an array of strings where each string is a format's name.
* ```js
* coordinateConversionComponent.conversions = ["mgrs"];
* ```
* @since 4.7
*/
accessor conversions: Collection<Conversion>;
/**
* Describes the location of the coordinates currently displayed by the component as a [Point](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/).
* Setting this property will update all conversions.
*
* @example
* Set the current location.
* ```js
* coordinateConversionComponent.currentLocation = { x: 77.0369, y: 38.9072, spatialReference: { wkid: 4326 } };
* ```
* @since 4.7
*/
accessor currentLocation: Point | null | undefined;
/**
* A [collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/) containing every coordinate format
* that the component is capable of displaying.
*
* The default formats are `basemap`, `dd`, `ddm`, `dms`, `mgrs`, `usng`, `utm`, and `xy`.
*
* @example
* Only show the "xy" format.
* ```js
* const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];
* const toRemove = coordinateConversionComponent.formats.filter(format => format.name !== "xy");
* coordinateConversionComponent.formats.removeMany(toRemove);
* ```
* @example
* Show every format except "xy".
* ```js
* const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];
* const toRemove = coordinateConversionComponent.formats.filter(format => format.name === "xy");
* coordinateConversionComponent.formats.removeMany(toRemove);
* ```
*/
accessor formats: Collection<Format>;
/**
* 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 | null | undefined;
/**
* Indicates the heading level to use for the coordinate input and coordinate settings headings. By default,
* these headings are rendered as level 4 headings (e.g. `<h4>Input coordinate</h4>`). Depending on the coordinate conversion component's
* placement in your app, you may need to adjust this heading for proper semantics. This is important for meeting
* accessibility standards.
*
* @default 4
*/
accessor headingLevel: HeadingLevel;
/**
* Determines whether the capture section will be shown in the component. If `true`, the capture section will be hidden.
*
* @default false
* @since 5.1
* @example
* Hide the capture section.
* ```html
* <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
* <arcgis-coordinate-conversion hide-capture-section slot="bottom-left"></arcgis-coordinate-conversion>
* </arcgis-map>
* ```
*/
accessor hideCaptureSection: boolean;
/**
* Determines whether the input section will be shown in the component. If `true`, the input section will be hidden.
*
* @default false
* @since 5.1
* @example
* Hide the input section.
* ```html
* <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
* <arcgis-coordinate-conversion hide-input-section slot="bottom-left"></arcgis-coordinate-conversion>
* </arcgis-map>
* ```
*/
accessor hideInputSection: boolean;
/**
* Determines whether the settings button will be shown in the component. If `true`, the settings button will be hidden.
*
* @default false
* @example
* Hide the settings button.
* ```html
* <arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
* <arcgis-coordinate-conversion hide-settings-button slot="bottom-left"></arcgis-coordinate-conversion>
* </arcgis-map>
* ```
*/
accessor hideSettingsButton: boolean;
/**
* Icon which represents the component.
* Typically used when the component is controlled by another component (e.g. by the Expand component).
* Search [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/) for possible values.
*
* @default "coordinate-system"
*/
accessor icon: IconName;
/**
* If false, the component will estimate coordinate precision based on the current state of the
* view. As the view is zoomed farther out, fewer decimal places will be shown. Only affects `DD`,
* `DDM`, `DMS`, and `XY` formats.
*
* @default false
* @since 5.1
*/
accessor ignoreCoordinatePrecision: boolean;
/**
* The component's default label.
*
* @default "Coordinate conversion"
*/
accessor label: string;
/**
* This symbol is used to visualize the location currently described by the component when `capture` mode
* is active.
*
* This property should be set to a point symbol, typically a [Simple Marker Symbol](https://developers.arcgis.com/javascript/latest/references/core/symbols/SimpleMarkerSymbol/).
*
* @example
* Set the location symbol to be an 'x'.
* ```js
* const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];
* coordinateConversionComponent.locationSymbol = { type: "simple-marker", style: "x" };
* ```
*/
accessor locationSymbol: PictureMarkerSymbol | SimpleMarkerSymbol | CIMSymbol | PointSymbol3D;
/** @internal */
protected messages: {
componentLabel: string;
abbreviatedDirections: {
north: string;
south: string;
east: string;
west: string;
};
addConversion: string;
alertLabel: string;
captureMode: string;
display: string;
convert: string;
convertAndGoTo: string;
coordinates: string;
copyLabel: string;
copyElevationLabel: string;
copySuccessMessage: string;
defaultPattern: string;
done: string;
elevation: string;
selectElevationUnit: string;
format: string;
formatDescriptions: {
dd: string;
dms: string;
ddm: string;
mgrs: string;
usng: string;
utm: string;
xy: string;
basemap: string;
custom: string;
};
input: string;
inputCoordTitle: string;
inputFormat: string;
invalidCoordinate: string;
liveMode: string;
locationOffBasemap: string;
noBasemap: string;
noDisplayProperties: string;
noElevation: string;
noLocation: string;
preview: string;
selectFormat: string;
selectFormats: string;
settingsTitleWithFormat: string;
} & T9nMeta<{
componentLabel: string;
abbreviatedDirections: {
north: string;
south: string;
east: string;
west: string;
};
addConversion: string;
alertLabel: string;
captureMode: string;
display: string;
convert: string;
convertAndGoTo: string;
coordinates: string;
copyLabel: string;
copyElevationLabel: string;
copySuccessMessage: string;
defaultPattern: string;
done: string;
elevation: string;
selectElevationUnit: string;
format: string;
formatDescriptions: {
dd: string;
dms: string;
ddm: string;
mgrs: string;
usng: string;
utm: string;
xy: string;
basemap: string;
custom: string;
};
input: string;
inputCoordTitle: string;
inputFormat: string;
invalidCoordinate: string;
liveMode: string;
locationOffBasemap: string;
noBasemap: string;
noDisplayProperties: string;
noElevation: string;
noLocation: string;
preview: string;
selectFormat: string;
selectFormats: string;
settingsTitleWithFormat: string;
}>;
/**
* Describes the current mode of the component.
*
* * While in `live` mode, the component will update as the cursor moves.
* * While in `capture` mode, the component will update on mouse click and display a graphic
* marking the current location.
* * While in `idle` mode, the component will not update based on cursor movement or mouse clicks.
* This mode can be used to "pause" the component without losing the current location.
*
* @default "live"
* @example
* Programmatically set the component to idle mode.
* ```js
* const coordinateConversionComponent = document.getElementsByTagName("arcgis-coordinate-conversion")[0];
* coordinateConversionComponent.mode = "idle";
* ```
*/
accessor mode: Mode;
/**
* If this property is set to `true`, multiple conversions will be disabled, and only a single conversion will be displayed. Otherwise, multiple conversions will be shown.
*
* @default false
*/
accessor multipleConversionsDisabled: boolean;
/**
* 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;
/**
* Determines whether leading zeros will be shown in `DD`, `DDM`, and `DMS` formats.
* When false: 01.37°N, 008.71°E
* When true: 1.37°N, 8.71°E
*
* @default false
* @since 5.1
*/
accessor removeLeadingZeros: boolean;
/**
* Determines whether the elevation of the current location will be shown. Only applicable when the view is a SceneView.
*
* @default false
* @since 5.1
*/
accessor showElevation: boolean;
/**
* The current state of the component.
*
* @default "disabled"
*/
get state(): CoordinateConversionViewModelState;
/**
* If this property is set to `true`, sessionStorage or localStorage (depending on [storageType](https://developers.arcgis.com/javascript/latest/references/core/widgets/CoordinateConversion/#storageType))
* will not be used to hydrate and persist the component's state.
*
* @default false
*/
accessor storageDisabled: boolean;
/**
* This property determines whether sessionStorage or localStorage will be used to store component's state.
*
* @default "session"
* @see [Window.sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)
* @see [Window.localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
* @since 4.23
*/
accessor storageType: StorageType;
/**
* Indicates the vertical unit to use when displaying elevation.
*
* @default "meters"
* @since 5.1
* @see [LengthUnit](https://developers.arcgis.com/javascript/latest/references/core/core/units/#LengthUnit)
*/
accessor verticalUnit: LengthUnit;
/**
* 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-coordinate-conversion-next component will be associated with a map or scene component rather than using the `view` property.
*/
accessor view: MapViewOrSceneView | null | undefined;
/**
* Determines the component's scale. Options are small ("s"), medium ("m"), and large ("l").
*
* @default "s"
* @since 5.1
*/
accessor visualScale: Panel["scale"];
/** Permanently destroy the component. */
destroy(): Promise<void>;
/**
* Attempt to convert a string into a [point](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/). The format of the
* string must be specified. A [collection](https://developers.arcgis.com/javascript/latest/references/core/core/Collection/) of available formats can be
* obtained from the [arcgis-coordinate-conversion.formats](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-coordinate-conversion/#formats) property.
*
* @param coordinate - The coordinate string.
* @param format - Specifies the format of the input coordinate.
* @returns When resolved, returns a [point](https://developers.arcgis.com/javascript/latest/references/core/geometry/Point/).
*/
reverseConvert(coordinate: string, format: Format): Promise<Point | null | undefined>;
/**
* Emitted when a conversion is added or removed, or when the order of conversions changes.
*
* @since 4.34
*/
readonly arcgisConversionChange: import("@arcgis/lumina").TargetedEvent<this, void>;
/** 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: "currentLocation" | "state" | "mode" | "verticalUnit"; }>;
/** 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": {
arcgisConversionChange: ArcgisCoordinateConversionNext["arcgisConversionChange"]["detail"];
arcgisPropertyChange: ArcgisCoordinateConversionNext["arcgisPropertyChange"]["detail"];
arcgisReady: ArcgisCoordinateConversionNext["arcgisReady"]["detail"];
};
}