devextreme
Version:
HTML5 JavaScript Component Suite for Responsive Web Development
729 lines (687 loc) • 23.6 kB
TypeScript
/**
* DevExtreme (viz/vector_map.d.ts)
* Version: 25.1.3
* Build date: Wed Jun 25 2025
*
* Copyright (c) 2012 - 2025 Developer Express Inc. ALL RIGHTS RESERVED
* Read about DevExtreme licensing here: https://js.devexpress.com/Licensing/
*/
import DataSource, { DataSourceLike } from '../data/data_source';
import {
UserDefinedElement,
DxElement,
} from '../core/element';
import {
template,
HorizontalAlignment,
SingleMultipleOrNone,
VerticalEdge,
} from '../common';
import {
EventInfo,
NativeEventInfo,
InitializedEventInfo,
ChangedOptionInfo,
} from '../common/core/events';
import {
Format,
} from '../localization';
import {
BaseLegend,
BaseLegendItem,
} from './common';
import BaseWidget, {
BaseWidgetMargin,
BaseWidgetOptions,
BaseWidgetTooltip,
BaseWidgetAnnotationConfig,
FileSavingEventInfo,
ExportInfo,
IncidentInfo,
} from './core/base_widget';
import {
VectorMapProjection,
VectorMapProjectionConfig,
} from './vector_map/projection';
import {
Palette,
Font,
} from '../common/charts';
export {
SingleMultipleOrNone,
Palette,
VectorMapProjection,
VerticalEdge,
};
export type VectorMapLayerType = 'area' | 'line' | 'marker';
export type VectorMapMarkerShape = 'circle' | 'square';
export type VectorMapMarkerType = 'bubble' | 'dot' | 'image' | 'pie';
/**
*
* @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
*/
export interface TooltipInfo {
/**
*
*/
target?: MapLayerElement | dxVectorMapAnnotationConfig;
}
/**
* The type of the centerChanged event handler's argument.
*/
export type CenterChangedEvent = EventInfo<dxVectorMap> & {
/**
*
*/
readonly center: Array<number>;
};
/**
* The type of the click event handler's argument.
*/
export type ClickEvent = NativeEventInfo<dxVectorMap, MouseEvent | PointerEvent> & {
/**
*
*/
readonly target: MapLayerElement;
};
/**
* The type of the disposing event handler's argument.
*/
export type DisposingEvent = EventInfo<dxVectorMap>;
/**
* The type of the drawn event handler's argument.
*/
export type DrawnEvent = EventInfo<dxVectorMap>;
/**
* The type of the exported event handler's argument.
*/
export type ExportedEvent = EventInfo<dxVectorMap>;
/**
* The type of the exporting event handler's argument.
*/
export type ExportingEvent = EventInfo<dxVectorMap> & ExportInfo;
/**
* The type of the fileSaving event handler's argument.
*/
export type FileSavingEvent = FileSavingEventInfo<dxVectorMap>;
/**
* The type of the incidentOccurred event handler's argument.
*/
export type IncidentOccurredEvent = EventInfo<dxVectorMap> & IncidentInfo;
/**
* The type of the initialized event handler's argument.
*/
export type InitializedEvent = InitializedEventInfo<dxVectorMap>;
/**
* The type of the optionChanged event handler's argument.
*/
export type OptionChangedEvent = EventInfo<dxVectorMap> & ChangedOptionInfo;
/**
* The type of the selectionChanged event handler's argument.
*/
export type SelectionChangedEvent = EventInfo<dxVectorMap> & {
/**
*
*/
readonly target: MapLayerElement;
};
/**
* The type of the tooltipHidden event handler's argument.
*/
export type TooltipHiddenEvent = EventInfo<dxVectorMap> & TooltipInfo;
/**
* The type of the tooltipShown event handler's argument.
*/
export type TooltipShownEvent = EventInfo<dxVectorMap> & TooltipInfo;
/**
* The type of the zoomFactorChanged event handler's argument.
*/
export type ZoomFactorChangedEvent = EventInfo<dxVectorMap> & {
/**
*
*/
readonly zoomFactor: number;
};
/**
* This section describes the Layer object, which represents a vector map layer.
* @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
*/
export interface MapLayer {
/**
* Deselects all layer elements.
*/
clearSelection(): void;
/**
* The type of the layer elements.
*/
elementType?: string;
/**
* Returns the DataSource instance.
*/
getDataSource(): DataSource;
/**
* Gets all layer elements.
*/
getElements(): Array<MapLayerElement>;
/**
* The layer index in the layers array.
*/
index?: number;
/**
* The name of the layer.
*/
name?: string;
/**
* The layer type. Can be 'area', 'line' or 'marker'.
*/
type?: string;
}
/**
* This section describes the Layer Element object, which represents a vector map layer element.
* @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
*/
export interface MapLayerElement {
/**
* Applies the layer element settings and updates element appearance.
*/
applySettings(settings: any): void;
/**
* Gets the value of an attribute.
*/
attribute(name: string): any;
/**
* Sets the value of an attribute.
*/
attribute(name: string, value: any): void;
/**
* Gets the layer element coordinates.
*/
coordinates(): any;
/**
* The parent layer of the layer element.
*/
layer?: any;
/**
* Gets the selection state of the layer element.
*/
selected(): boolean;
/**
* Sets the selection state of the layer element.
*/
selected(state: boolean): void;
}
/**
* An object that provides information about a legend item in the VectorMap UI component.
*/
export type LegendItem = VectorMapLegendItem;
/**
* @deprecated Use LegendItem instead
* @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
*/
export interface VectorMapLegendItem extends BaseLegendItem {
/**
* The color of the legend item's marker.
*/
color?: string;
/**
* The end value of the group that the legend item indicates.
*/
end?: number;
/**
* The diameter of the legend item's marker in pixels.
*/
size?: number;
/**
* The start value of the group that the legend item indicates.
*/
start?: number;
}
/**
*
* @deprecated
* @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
*/
export interface dxVectorMapOptions extends BaseWidgetOptions<dxVectorMap> {
/**
* Specifies the properties for the map background.
*/
background?: {
/**
* Specifies a color for the background border.
*/
borderColor?: string;
/**
* Specifies a color for the background.
*/
color?: string;
};
/**
* Specifies the positioning of a map in geographical coordinates.
*/
bounds?: Array<number>;
/**
* Specifies the geographical coordinates of the center for a map.
*/
center?: Array<number>;
/**
* Configures the control bar.
*/
controlBar?: {
/**
* Specifies a color for the outline of the control bar elements.
*/
borderColor?: string;
/**
* Specifies a color for the inner area of the control bar elements.
*/
color?: string;
/**
* Specifies whether or not to display the control bar.
*/
enabled?: boolean;
/**
* Specifies whether the pan control is visible.
*/
panVisible?: boolean;
/**
* Specifies whether the zoom bar is visible.
*/
zoomVisible?: boolean;
/**
* Specifies the position of the control bar.
*/
horizontalAlignment?: HorizontalAlignment;
/**
* Specifies the margin of the control bar in pixels.
*/
margin?: number;
/**
* Specifies the opacity of the control bar.
*/
opacity?: number;
/**
* Specifies the position of the control bar.
*/
verticalAlignment?: VerticalEdge;
};
/**
* Specifies properties for VectorMap UI component layers.
*/
layers?: Array<{
/**
* Specifies a color for the border of the layer elements.
*/
borderColor?: string;
/**
* Specifies the line width (for layers of a line type) or width of the layer elements border in pixels.
*/
borderWidth?: number;
/**
* Specifies a color for layer elements.
*/
color?: string;
/**
* Specifies the field that provides data to be used for coloring of layer elements.
*/
colorGroupingField?: string | undefined;
/**
* Allows you to paint layer elements with similar attributes in the same color.
*/
colorGroups?: Array<number>;
/**
* A function that customizes each layer element individually.
*/
customize?: ((elements: Array<MapLayerElement>) => void);
/**
* Specifies the name of the attribute containing marker data. Setting this property makes sense only if the layer type is 'marker' and the elementType is 'bubble', 'pie' or 'image'.
*/
dataField?: string | undefined;
/**
* Specifies a data source for the layer.
*/
dataSource?: object | DataSourceLike<any> | null;
/**
* Specifies the type of a marker element. Setting this property makes sense only if the layer type is 'marker'.
*/
elementType?: VectorMapMarkerType;
/**
* Specifies whether or not to change the appearance of a layer element when it is hovered over.
*/
hoverEnabled?: boolean;
/**
* Specifies a color for the border of the layer element when it is hovered over.
*/
hoveredBorderColor?: string;
/**
* Specifies the pixel-measured line width (for layers of a line type) or width for the border of the layer element when it is hovered over.
*/
hoveredBorderWidth?: number;
/**
* Specifies a color for a layer element when it is hovered over.
*/
hoveredColor?: string;
/**
* Specifies marker label properties.
*/
label?: {
/**
* The name of the data source attribute containing marker texts.
*/
dataField?: string;
/**
* Enables marker labels.
*/
enabled?: boolean;
/**
* Specifies font properties for marker labels.
*/
font?: Font;
};
/**
* Specifies the pixel-measured diameter of the marker that represents the biggest value. Setting this property makes sense only if the layer type is 'marker'.
*/
maxSize?: number;
/**
* Specifies the pixel-measured diameter of the marker that represents the smallest value. Setting this property makes sense only if the layer type is 'marker'.
*/
minSize?: number;
/**
* Specifies the layer name.
*/
name?: string;
/**
* Specifies the layer opacity (from 0 to 1).
*/
opacity?: number;
/**
* The name of a predefined palette or a custom range of colors to be used as a palette.
*/
palette?: Array<string> | Palette;
/**
* Specifies the number of colors in a palette.
*/
paletteSize?: number;
/**
* The position of a color in the palette[] array. Should not exceed the value of the paletteSize property.
*/
paletteIndex?: number;
/**
* Specifies a color for the border of the layer element when it is selected.
*/
selectedBorderColor?: string;
/**
* Specifies a pixel-measured line width (for layers of a line type) or width for the border of the layer element when it is selected.
*/
selectedBorderWidth?: number;
/**
* Specifies a color for the layer element when it is selected.
*/
selectedColor?: string;
/**
* Specifies whether single or multiple map elements can be selected on a vector map.
*/
selectionMode?: SingleMultipleOrNone;
/**
* Specifies the size of markers. Setting this property makes sense only if the layer type is 'marker' and the elementType is 'dot', 'pie' or 'image'.
*/
size?: number;
/**
* Specifies the field that provides data to be used for sizing bubble markers. Setting this property makes sense only if the layer type is 'marker' and the elementType is 'bubble'.
*/
sizeGroupingField?: string | undefined;
/**
* Allows you to display bubbles with similar attributes in the same size. Setting this property makes sense only if the layer type is 'marker' and the elementType is 'bubble'.
*/
sizeGroups?: Array<number>;
/**
* Specifies layer type.
*/
type?: VectorMapLayerType;
}> | { borderColor?: string; borderWidth?: number; color?: string; colorGroupingField?: string; colorGroups?: Array<number>; customize?: ((elements: Array<MapLayerElement>) => any); dataField?: string; dataSource?: object | DataSourceLike<any> | null; elementType?: 'bubble' | 'dot' | 'image' | 'pie'; hoverEnabled?: boolean; hoveredBorderColor?: string; hoveredBorderWidth?: number; hoveredColor?: string; label?: { dataField?: string; enabled?: boolean; font?: Font }; maxSize?: number; minSize?: number; name?: string; opacity?: number; palette?: Array<string> | Palette; paletteSize?: number; selectedBorderColor?: string; selectedBorderWidth?: number; selectedColor?: string; selectionMode?: SingleMultipleOrNone; size?: number; sizeGroupingField?: string; sizeGroups?: Array<number>; type?: 'area' | 'line' | 'marker' };
/**
* Configures map legends.
*/
legends?: Array<Legend> | undefined;
/**
* Generates space around the UI component.
*/
margin?: BaseWidgetMargin;
/**
* Specifies a map's maximum zoom factor.
*/
maxZoomFactor?: number;
/**
* A function that is executed each time the center coordinates are changed.
*/
onCenterChanged?: ((e: CenterChangedEvent) => void);
/**
* A function that is executed when any location on the map is clicked or tapped.
*/
onClick?: ((e: ClickEvent) => void) | string;
/**
* A function that is executed when a layer element is selected or selection is canceled.
*/
onSelectionChanged?: ((e: SelectionChangedEvent) => void);
/**
* A function that is executed when a tooltip becomes hidden.
*/
onTooltipHidden?: ((e: TooltipHiddenEvent) => void);
/**
* A function that is executed when a tooltip appears.
*/
onTooltipShown?: ((e: TooltipShownEvent) => void);
/**
* A function that is executed each time the zoom factor is changed.
*/
onZoomFactorChanged?: ((e: ZoomFactorChangedEvent) => void);
/**
* Disables the panning capability.
*/
panningEnabled?: boolean;
/**
* Specifies the map projection.
*/
projection?: VectorMapProjection | VectorMapProjectionConfig | string | any;
/**
* Configures tooltips.
*/
tooltip?: Tooltip;
/**
* Specifies whether the map should respond to touch gestures.
*/
touchEnabled?: boolean;
/**
* Specifies whether or not the map should respond when a user rolls the mouse wheel.
*/
wheelEnabled?: boolean;
/**
* Specifies a number that is used to zoom a map initially.
*/
zoomFactor?: number;
/**
* Disables the zooming capability.
*/
zoomingEnabled?: boolean;
/**
* Specifies settings common for all annotations in the VectorMap.
*/
commonAnnotationSettings?: dxVectorMapCommonAnnotationConfig;
/**
* Specifies the annotation collection.
*/
annotations?: Array<dxVectorMapAnnotationConfig | any>;
/**
* Customizes an individual annotation.
*/
customizeAnnotation?: ((annotation: dxVectorMapAnnotationConfig | any) => dxVectorMapAnnotationConfig) | undefined;
}
/**
*
* @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
*/
export interface dxVectorMapAnnotationConfig extends dxVectorMapCommonAnnotationConfig {
/**
* Specifies the annotation's name.
*/
name?: string | undefined;
}
/**
*
* @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
*/
export interface dxVectorMapCommonAnnotationConfig extends BaseWidgetAnnotationConfig {
/**
* Positions the annotation's center at specified geographic coordinates: [longitude, latitude].
*/
coordinates?: Array<number>;
/**
* Customizes the text and appearance of the annotation's tooltip.
*/
customizeTooltip?: ((annotation: dxVectorMapAnnotationConfig | any) => any) | undefined;
/**
* Specifies a custom template for the annotation. Applies only if the type is 'custom'.
*/
template?: template | ((annotation: dxVectorMapAnnotationConfig | any, element: SVGGElement) => string | UserDefinedElement<SVGElement>) | undefined;
/**
* Specifies a custom template for an annotation's tooltip.
*/
tooltipTemplate?: template | ((annotation: dxVectorMapAnnotationConfig | any, element: DxElement) => string | UserDefinedElement) | undefined;
}
/**
* Configures map legends.
*/
export type Legend = BaseLegend & {
/**
* Specifies text for a hint that appears when a user hovers the mouse pointer over the text of a legend item.
*/
customizeHint?: ((itemInfo: { start?: number; end?: number; index?: number; color?: string; size?: number }) => string);
/**
* Allows you to change the order and visibility of legend items.
*/
customizeItems?: ((items: Array<LegendItem>) => Array<LegendItem>);
/**
* Specifies text for legend items.
*/
customizeText?: ((itemInfo: { start?: number; end?: number; index?: number; color?: string; size?: number }) => string);
/**
* Specifies the legend items' font properties.
*/
font?: Font;
/**
* Specifies the color of item markers in the legend. The specified color applied only when the legend uses 'size' source.
*/
markerColor?: string | undefined;
/**
* Specifies the shape of item markers.
*/
markerShape?: VectorMapMarkerShape;
/**
* Specifies the marker's size in a legend item in pixels.
*/
markerSize?: number;
/**
* Specifies an SVG element that serves as a custom legend item marker.
*/
markerTemplate?: template | ((legendItem: LegendItem, element: SVGGElement) => string | UserDefinedElement<SVGElement>) | undefined;
/**
* Specifies the source of data for the legend.
*/
source?: {
/**
* Specifies the type of the legend grouping.
*/
grouping?: string;
/**
* Specifies a layer to which the legend belongs.
*/
layer?: string;
};
};
/**
* Configures tooltips.
*/
export type Tooltip = BaseWidgetTooltip & {
/**
* Specifies a custom template for a tooltip.
*/
contentTemplate?: template | ((info: MapLayerElement, element: DxElement) => string | UserDefinedElement) | undefined;
/**
* Specifies text and appearance of a set of tooltips.
*/
customizeTooltip?: ((info: MapLayerElement) => any) | undefined;
/**
*
*/
format?: Format;
};
/**
* The VectorMap is a UI component that visualizes geographical locations. This UI component represents a geographical map that contains areas and markers. Areas embody continents and countries. Markers flag specific points on the map, for example, towns, cities or capitals.
*/
export default class dxVectorMap extends BaseWidget<dxVectorMapOptions> {
/**
* Gets the current map center coordinates.
*/
center(): Array<number>;
/**
* Sets the map center coordinates.
*/
center(centerCoordinates: Array<number>): void;
/**
* Deselects all the selected area and markers on a map at once. The areas and markers are displayed in their initial style after.
*/
clearSelection(): void;
/**
* Converts coordinates from pixels to the dataSource coordinate system.
*/
convertToGeo(x: number, y: number): Array<number>;
/**
* Converts coordinates from the dataSource coordinate system to pixels.
*/
convertToXY(longitude: number, latitude: number): Array<number>;
/**
* Gets a layer with a specific index.
*/
getLayerByIndex(index: number): MapLayer;
/**
* Gets a layer with a specific name.
*/
getLayerByName(name: string): MapLayer;
/**
* Gets all layers.
*/
getLayers(): Array<MapLayer>;
/**
* Gets the current map viewport coordinates.
*/
viewport(): Array<number>;
/**
* Sets the map viewport coordinates.
*/
viewport(viewportCoordinates: Array<number>): void;
/**
* Gets the current zoom factor value.
*/
zoomFactor(): number;
/**
* Sets the zoom factor value.
*/
zoomFactor(zoomFactor: number): void;
}
export type Properties = dxVectorMapOptions;
/**
* @deprecated use Properties instead
* @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
*/
export type Options = dxVectorMapOptions;
// #region deprecated in v23.1
/**
* @deprecated Use Legend instead
* @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
*/
export type dxVectorMapLegends = Legend;
/**
* @deprecated Use Tooltip instead
* @deprecated Attention! This type is for internal purposes only. If you used it previously, please submit a ticket to our {@link https://supportcenter.devexpress.com/ticket/create Support Center}. We will check if there is an alternative solution.
*/
export type dxVectorMapTooltip = Tooltip;
// #endregion