@amcharts/amcharts5
Version:
amCharts 5
520 lines • 19.9 kB
TypeScript
import type { MapSeries } from "./MapSeries";
import type { GeoProjection, GeoPath, GeoRawProjection } from "d3-geo";
import type { IPoint } from "../../core/util/IPoint";
import type { IGeoPoint } from "../../core/util/IGeoPoint";
import type { Time } from "../../core/util/Animation";
import type { ZoomControl } from "./ZoomControl";
import type { Animation } from "../../core/util/Entity";
import type { DataItem } from "../../core/render/Component";
import type { IMapPolygonSeriesDataItem } from "./MapPolygonSeries";
import { SerialChart, ISerialChartPrivate, ISerialChartSettings, ISerialChartEvents } from "../../core/render/SerialChart";
import { Rectangle } from "../../core/render/Rectangle";
import type { IDisposer } from "../../core/util/Disposer";
import type { ISpritePointerEvent } from "../../core/render/Sprite";
/**
* Registry of projections that can be looked up by name via the `projectionName`
* setting on `MapChart`. The `am5map` entry point populates this with all
* bundled d3-geo projections. Custom projections can be added via
* `registerProjection()`.
*/
export declare const projectionRegistry: {
[name: string]: () => GeoProjection;
};
/**
* Wraps a projection factory so the projections it produces carry their
* registered `name`. The tag lets `ChartSerializer` emit a matching
* `projectionName` even for charts that set `projection` directly in code.
*/
export declare function tagProjection(name: string, factory: () => GeoProjection): () => GeoProjection;
/**
* Registers a projection factory under the given name so it can be referenced
* by `MapChart`'s `projectionName` setting.
*
* Returns a name-tagged factory: use its return value (e.g. `const cc =
* registerProjection("geoConicConformal", geoConicConformal)`) as
* `projection: cc()` and the chart will round-trip through serialization the
* same way the bundled projections do.
*/
export declare function registerProjection(name: string, factory: () => GeoProjection): () => GeoProjection;
export interface IMapChartSettings extends ISerialChartSettings {
/**
* A projection to use when plotting the map.
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/#Projections} for more info
*/
projection?: GeoProjection;
/**
* Name of a projection to use, e.g. `"geoMercator"`, `"geoOrthographic"`.
*
* A string-friendly alternative to `projection`: when set, the chart looks the
* name up in `projectionRegistry` and assigns the resulting projection to the
* `projection` setting. Handy for JSON config, where a function can't be used.
*
* The bundled projections — `"geoMercator"`, `"geoOrthographic"`,
* `"geoEquirectangular"`, `"geoAlbersUsa"`, `"geoEqualEarth"`,
* `"geoNaturalEarth1"` — are registered automatically when `am5map` is loaded,
* so these names resolve out of the box.
*
* In code you can also just set `projection` directly, e.g.
* `projection: am5map.geoOrthographic()`. The `am5map` projection factories tag
* their output with the projection name, so `ChartSerializer` emits the matching
* `projectionName` either way — the chart round-trips through serialization.
*
* To use a projection that isn't bundled, register it once before creating
* the chart:
*
* ```TypeScript
* import { geoConicConformal } from "d3-geo";
* am5map.registerProjection("geoConicConformal", geoConicConformal);
* ```
* ```JavaScript
* am5map.registerProjection("geoConicConformal", d3.geoConicConformal);
* ```
*
* @since 5.19.0
*/
projectionName?: string;
/**
* Current zoom level.
*/
zoomLevel?: number;
/**
* current x position of a map
*/
translateX?: number;
/**
* current y position of a map
*/
translateY?: number;
/**
* Vertical centering of the map.
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/#Centering_the_map} for more info
*/
rotationY?: number;
/**
* Horizontal centering of the map.
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/#Centering_the_map} for more info
*/
rotationX?: number;
/**
* Depth centering of the map.
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/#Centering_the_map} for more info
*/
rotationZ?: number;
/**
* Highest zoom level map is allowed to zoom in to.
*
* @default 32
*/
maxZoomLevel?: number;
/**
* Lowest zoom level map is allowed to zoom in to.
*
* @default 1
*/
minZoomLevel?: number;
/**
* Increment zoom level by `zoomStep` when user zooms in via [[ZoomControl]] or
* API.
*
* @default 2
*/
zoomStep?: number;
/**
* Defines what happens when map is being dragged horizontally.
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/map-pan-zoom/#Panning} for more info
* @default "translateX"
*/
panX?: "none" | "rotateX" | "translateX";
/**
* Defines what happens when map is being dragged vertically.
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/map-pan-zoom/#Panning} for more info
* @default "translateY"
*/
panY?: "none" | "rotateY" | "translateY";
/**
* Enables pinch-zooming of the map on multi-touch devices.
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/map-pan-zoom/#Pinch_zoom} for more info
* @default true
*/
pinchZoom?: boolean;
/**
* Defines what happens when horizontal mouse wheel (only some mouses do have such a wheel)
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/map-pan-zoom/#Mouse_wheel_behavior} for more info
* @default "none"
*/
wheelX?: "none" | "zoom" | "rotateX" | "rotateY";
/**
* Defines what happens when mouse wheel is turned.
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/map-pan-zoom/#Mouse_wheel_behavior} for more info
* @default "zoom"
*/
wheelY?: "none" | "zoom" | "rotateX" | "rotateY";
/**
* Sensitivity of a mouse wheel.
*
* NOTE: this setting is ignored when `wheelX` or `wheelY` is set to `"zoom"`.
*
* @default 1
*/
wheelSensitivity?: number;
/**
* Duration of mouse-wheel action animation, in milliseconds.
*
* NOTE: this setting is ignored when `wheelX` or `wheelY` is set to `"zoom"`.
*/
wheelDuration?: number;
/**
* An easing function to use for mouse wheel action animations.
*
* NOTE: this setting is ignored when `wheelX` or `wheelY` is set to `"zoom"`.
*
* @see {@link https://www.amcharts.com/docs/v5/concepts/animations/#Easing_functions} for more info
* @default am5.ease.out($ease.cubic)
*/
wheelEasing?: (t: Time) => Time;
/**
* Duration of zoom/pan animations, in milliseconds.
*/
animationDuration?: number;
/**
* An easing function to use for zoom/pan animations.
*
* @see {@link https://www.amcharts.com/docs/v5/concepts/animations/#Easing_functions} for more info
* @default am5.ease.out($ease.cubic)
*/
animationEasing?: (t: Time) => Time;
/**
* A [[ZoomControl]] instance.
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/#Zoom_control} for more info
*/
zoomControl?: ZoomControl;
/**
* Initial/home zoom level.
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/map-pan-zoom/#Initial_position_and_zoom} for more info
*/
homeZoomLevel?: number;
/**
* Initial/home rotationX.
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/map-pan-zoom/#Initial_position_and_zoom} for more info
*/
homeRotationX?: number;
/**
* Initial/home rotationY.
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/map-pan-zoom/#Initial_position_and_zoom} for more info
*/
homeRotationY?: number;
/**
* Initial coordinates to center map on load or `goHome()` call.
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/map-pan-zoom/#Initial_position_and_zoom} for more info
*/
homeGeoPoint?: IGeoPoint;
/**
* How much of a map can go outside the viewport.
*
* @default 0.4
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/map-pan-zoom/#Panning_outside_viewport} for more info
*/
maxPanOut?: number;
/**
* Setting `true` means that the map will automatically center itself (or go
* to `homeGeoPoint` if set) when fully zoomed out.
*
* `false` would mean that zoom out will be centered around the mouse
* cursor (when zooming using wheel), or current map position.
*
* @default true
* @since 5.2.1
*/
centerMapOnZoomOut?: boolean;
/**
* Setting to `true` will make map zoom in on a double click (or double tap),
* and zoom out on a shift + double click.
*
* On maps that are panned by rotating (`panX: "rotateX"` and/or
* `panY: "rotateY"`) the clicked location is rotated to the center of the
* map. Otherwise it stays under the pointer.
*
* @default true
* @since 5.20.2
*/
doubleClickZoom?: boolean;
/**
* Allows zooming the map to an area drawn with a pointer.
*
* The value defines a key that needs to be held down while dragging, with
* `"drag"` meaning that no key is needed. Since a plain drag pans the map,
* `"drag"` should be used with `panX`/`panY` set to `"none"`.
*
* The drawn area is represented by the `boxZoomSelection` element.
*
* @default "none"
* @since 5.20.2
*/
boxZoom?: "none" | "drag" | "shift" | "ctrl" | "alt";
}
export interface IMapChartPrivate extends ISerialChartPrivate {
/**
* @ignore
*/
geoPath: GeoPath;
/**
* @ignore
*/
mapScale: number;
/**
* @ignore
*/
projectionBlend?: number;
}
export interface IMapChartEvents extends ISerialChartEvents {
/**
* Invoked when geo bounds of the map change, usually after map is
* initialized.
*/
geoboundschanged: {};
}
export declare class MapChart extends SerialChart {
static className: string;
static classNames: Array<string>;
_settings: IMapChartSettings;
_privateSettings: IMapChartPrivate;
_seriesType: MapSeries;
_events: IMapChartEvents;
protected _downTranslateX: number | undefined;
protected _downTranslateY: number | undefined;
protected _downRotationX: number | undefined;
protected _downRotationY: number | undefined;
protected _downRotationZ: number | undefined;
protected _pLat: number;
protected _pLon: number;
protected _movePoints: {
[index: number]: IPoint;
};
protected _downZoomLevel: number;
protected _doubleDownDistance: number;
/**
* A [[Rectangle]] element that shows the area being drawn when `boxZoom` is
* enabled.
*
* @since 5.20.2
*/
readonly boxZoomSelection: Rectangle;
protected _boxDownPoint: IPoint | undefined;
protected _panSuspended: boolean;
protected _suspendedPanX: "none" | "rotateX" | "translateX" | undefined;
protected _suspendedPanY: "none" | "rotateY" | "translateY" | undefined;
protected _dirtyGeometries: boolean;
protected _geometryColection: GeoJSON.GeometryCollection;
_centerLocation: [number, number] | null;
protected _za?: Animation<this["_settings"]["zoomLevel"]>;
protected _rxa?: Animation<this["_settings"]["rotationX"]>;
protected _rya?: Animation<this["_settings"]["rotationY"]>;
protected _txa?: Animation<this["_settings"]["translateX"]>;
protected _tya?: Animation<this["_settings"]["translateY"]>;
protected _mapBounds: number[][];
protected _geoCentroid: IGeoPoint;
protected _geoBounds: {
left: number;
right: number;
top: number;
bottom: number;
};
protected _prevGeoBounds: {
left: number;
right: number;
top: number;
bottom: number;
};
protected _dispatchBounds: boolean;
protected _wheelDp: IDisposer | undefined;
protected _pw?: number;
protected _ph?: number;
protected _mapFitted: boolean;
protected _centerX: number;
protected _centerY: number;
protected _projectionRaw?: GeoRawProjection;
protected _appliedProjectionName?: string;
protected _projectionBlendAnim?: Animation<this["_privateSettings"]["projectionBlend"]>;
protected _projectionBlendData?: {
blended: GeoProjection;
mutate: Function;
sourceScale: number;
targetScale: number;
sourceTranslateX: number;
sourceTranslateY: number;
targetTranslateX: number;
targetTranslateY: number;
target: GeoProjection;
targetRaw: GeoRawProjection;
};
protected _makeGeoPath(): void;
/**
* Returns a geoPoint of the current zoom position.
*
* You can later use it to restore zoom position, e.g.: `chart.zoomToGeoPoint(geoPoint, zoomLevel, true)`.
*
* @since 5.2.19
*/
geoPoint(): IGeoPoint;
/**
* Returns coordinates to geographical center of the map.
*/
geoCentroid(): IGeoPoint;
/**
* Returns geographical bounds of the map.
*/
geoBounds(): {
left: number;
right: number;
top: number;
bottom: number;
};
protected _handleSetWheel(): void;
protected _handleDoubleClick(event: ISpritePointerEvent): void;
/**
* Zooms to a point on the screen, rotating the map so that the point ends up
* in the center of it, if the map is panned by rotating.
*/
protected _zoomToScreenPoint(point: IPoint, level: number): void;
protected _isBoxZoomEvent(event: ISpritePointerEvent): boolean;
protected _handleBoxDown(event: ISpritePointerEvent): void;
protected _handleBoxMove(event: ISpritePointerEvent): void;
protected _handleBoxUp(event: ISpritePointerEvent): void;
protected _endBoxZoom(): void;
protected _drawBoxSelection(point: IPoint): void;
_prepareChildren(): void;
protected _fitMap(): void;
/**
* Returns geographical coordinates for calculated or manual center of the
* map.
*/
homeGeoPoint(): IGeoPoint;
/**
* Repositions the map to the "home" zoom level and center coordinates.
*
* @see {@link https://www.amcharts.com/docs/v5/charts/map-chart/map-pan-zoom/#Resetting_position_level} for more info
* @param duration Animation duration in milliseconds
*/
goHome(duration?: number): void;
_updateChildren(): void;
_afterChanged(): void;
protected _setUpTouch(): void;
/**
* @ignore
*/
markDirtyGeometries(): void;
/**
* @ignore
*/
markDirtyProjection(): void;
protected _afterNew(): void;
protected _handleChartDown(event: ISpritePointerEvent): void;
/**
* Converts screen coordinates (X and Y) within chart to latitude and
* longitude.
*
* @param point Screen coordinates
* @return Geographical coordinates
*/
invert(point: IPoint): IGeoPoint;
/**
* Converts latitude/longitude to screen coordinates (X and Y).
*
* @param point Geographical coordinates
* @param rotationX X rotation of a map if different from current
* @param rotationY Y rotation of a map if different from current
*
* @return Screen coordinates
*/
convert(point: IGeoPoint, rotationX?: number, rotationY?: number): IPoint;
protected _handleChartUp(_event: ISpritePointerEvent): void;
protected _handlePinch(): void;
protected _handleChartMove(event: ISpritePointerEvent): void;
protected _handleWheelRotateY(delta: number, duration: number, easing: (t: Time) => Time): void;
protected _handleWheelRotateX(delta: number, duration: number, easing: (t: Time) => Time): void;
protected _handleWheelZoom(delta: number, point: IPoint): void;
/**
* Zoom the map to geographical bounds.
*
* @param geoBounds Bounds
* @param duration Animation duration in milliseconds
* @param rotationX X rotation of a map at the end of zoom
* @param rotationY Y rotation of a map at the end of zoom
*/
zoomToGeoBounds(geoBounds: {
left: number;
right: number;
top: number;
bottom: number;
}, duration?: number, rotationX?: number, rotationY?: number): Animation<this["_settings"]["zoomLevel"]> | undefined;
/**
* Zooms the map to specific screen point.
*
* @param point Point
* @param level Zoom level
* @param center Center the map
* @param duration Duration of the animation in milliseconds
*/
zoomToPoint(point: IPoint, level: number, center?: boolean, duration?: number): Animation<this["_settings"]["zoomLevel"]> | undefined;
/**
* Zooms the map to specific geographical point.
*
* @param geoPoint Point
* @param level Zoom level
* @param center Center the map
* @param duration Duration of the animation in milliseconds
* @param rotationX X rotation of a map at the end of zoom
* @param rotationY Y rotation of a map at the end of zoom
*
*/
zoomToGeoPoint(geoPoint: IGeoPoint, level: number, center?: boolean, duration?: number, rotationX?: number, rotationY?: number): Animation<this["_settings"]["zoomLevel"]> | undefined;
rotate(rotationX?: number, rotationY?: number, duration?: number): void;
/**
* Animates the map projection transition from the current projection to
* the target projection over the specified duration.
*
* Since d3-geo does not expose raw projection functions on projection
* instances, you must pass both the target `GeoProjection` and its
* corresponding `GeoRawProjection`. On the first call you must also
* pass `sourceRaw` so the method knows the current projection's raw
* function. Subsequent calls reuse the previous target's raw
* automatically.
*
* @param target Target projection (e.g. `geoOrthographic()`)
* @param targetRaw Raw projection function (e.g. `geoOrthographicRaw`)
* @param duration Duration in milliseconds (default: `animationDuration`)
* @param easing Easing function (default: `animationEasing`)
* @param sourceRaw Raw function of the current projection (needed on first call)
*
* @since 5.16.0
*/
animateProjection(target: GeoProjection, targetRaw: GeoRawProjection, duration?: number, easing?: (t: Time) => Time, sourceRaw?: GeoRawProjection): void;
/**
* Zooms the map in.
*/
zoomIn(): Animation<this["_settings"]["zoomLevel"]> | undefined;
/**
* Zooms the map out.
*/
zoomOut(): Animation<this["_settings"]["zoomLevel"]> | undefined;
_clearDirty(): void;
/**
* Returns area of a mapPolygon in square pixels.
*/
getArea(dataItem: DataItem<IMapPolygonSeriesDataItem>): number;
}
//# sourceMappingURL=MapChart.d.ts.map