From 93901a2c0d6ae09d2a1db8d0900101edacd1cd2d Mon Sep 17 00:00:00 2001 From: Dmitry Demensky <10235949+demensky@users.noreply.github.com> Date: Mon, 23 Dec 2019 18:30:58 +0200 Subject: [PATCH] [googlemaps] improve map types & docs (#41044) * Add `MVCEventHandler` alias * Fix & specify type of `mapDiv` [`mapDiv`](https://developers.google.com/maps/documentation/javascript/reference/map#Map.constructor) is not nullable. * Add the missing [`getClickableIcons`](https://developers.google.com/maps/documentation/javascript/reference/map#Map.getClickableIcons) method * Fix [`setStreetView`](https://developers.google.com/maps/documentation/javascript/reference/map#Map.setStreetView) nullable argument * Specify types of events * Add blank line between fields * Add JSDoc * Update typescript * Fix googlemaps-tests * Fix load-google-maps-api-tests * Update load-google-maps-api typescript * Fix load-google-maps-api-tests --- types/googlemaps/googlemaps-tests.ts | 4 +- types/googlemaps/index.d.ts | 402 +++++++++++++++++- types/load-google-maps-api/index.d.ts | 2 +- .../load-google-maps-api-tests.ts | 4 +- 4 files changed, 401 insertions(+), 11 deletions(-) diff --git a/types/googlemaps/googlemaps-tests.ts b/types/googlemaps/googlemaps-tests.ts index 037b6cf98d..af271f0d46 100644 --- a/types/googlemaps/googlemaps-tests.ts +++ b/types/googlemaps/googlemaps-tests.ts @@ -42,7 +42,7 @@ let mapOptions: google.maps.MapOptions = { }; /***** Create map *****/ -let map: google.maps.Map = new google.maps.Map(document.getElementById('map'), mapOptions); +let map: google.maps.Map = new google.maps.Map(document.createElement('div'), mapOptions); /***** Fitting map to bounds *****/ map.fitBounds( @@ -320,7 +320,7 @@ marker.getIcon(); // $ExpectType string | ReadonlyIcon | ReadonlySymbol | null | marker.getLabel(); // $ExpectType ReadonlyMarkerLabel | null | undefined -marker.getMap(); // $ExpectType Map | StreetViewPanorama | null | undefined +marker.getMap(); // $ExpectType Map | StreetViewPanorama | null | undefined marker.getOpacity(); // $ExpectType number | null | undefined diff --git a/types/googlemaps/index.d.ts b/types/googlemaps/index.d.ts index 25b8578a85..11ba3a17f3 100644 --- a/types/googlemaps/index.d.ts +++ b/types/googlemaps/index.d.ts @@ -16,7 +16,7 @@ // Gavin Nitta // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped -// TypeScript Version: 2.7 +// TypeScript Version: 3.0 /* The MIT License @@ -51,32 +51,420 @@ declare namespace google.maps { const version: string; /***** Map *****/ - class Map extends MVCObject { - constructor(mapDiv: Element | null, opts?: MapOptions); + + interface MapHandlerMap { + /** + * This event is fired when the viewport bounds have changed. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.bounds_changed Maps JavaScript API} + * @see {@link Map#getBounds} + * @see {@link Map#fitBounds} + * @see {@link Map#panToBounds} + */ + bounds_changed: []; + + /** + * This event is fired when the map center property changes. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.center_changed Maps JavaScript API} + * @see {@link MapOptions#center} + * @see {@link Map#getCenter} + * @see {@link Map#setCenter} + */ + center_changed: []; + + /** + * This event is fired when the user clicks on the map. + * An ApiMouseEvent with properties for the clicked location is returned unless a place icon was clicked, in which case an IconMouseEvent with a placeid is returned. + * IconMouseEvent and ApiMouseEvent are identical, except that IconMouseEvent has the placeid field. + * The event can always be treated as an ApiMouseEvent when the placeid is not important. + * The click event is not fired if a marker or infowindow was clicked. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.click Maps JavaScript API} + */ + click: [MouseEvent | IconMouseEvent]; + + /** + * This event is fired when the user double-clicks on the map. Note that the click event will also fire, right before this one. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.dblclick Maps JavaScript API} + */ + dblclick: [MouseEvent]; + + /** + * This event is repeatedly fired while the user drags the map. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.drag Maps JavaScript API} + */ + drag: []; + + /** + * This event is fired when the user stops dragging the map. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.dragend Maps JavaScript API} + */ + dragend: []; + + /** + * This event is fired when the user starts dragging the map. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.dragstart Maps JavaScript API} + */ + dragstart: []; + + /** + * This event is fired when the map heading property changes. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.heading_changed Maps JavaScript API} + * @see {@link MapOptions#heading} + * @see {@link Map#getHeading} + * @see {@link Map#setHeading} + */ + heading_changed: []; + + /** + * This event is fired when the map becomes idle after panning or zooming. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.idle Maps JavaScript API} + */ + idle: []; + + /** + * This event is fired when the mapTypeId property changes. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.maptypeid_changed Maps JavaScript API} + * @see {@link MapOptions#mapTypeId} + * @see {@link Map#getMapTypeId} + * @see {@link Map#setMapTypeId} + */ + maptypeid_changed: []; + + /** + * This event is fired whenever the user's mouse moves over the map container. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.mousemove Maps JavaScript API} + */ + mousemove: [MouseEvent]; + + /** + * This event is fired when the user's mouse exits the map container. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.mouseout Maps JavaScript API} + */ + mouseout: [MouseEvent]; + + /** + * This event is fired when the user's mouse enters the map container. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.mouseover Maps JavaScript API} + */ + mouseover: [MouseEvent]; + + /** + * This event is fired when the projection has changed. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.projection_changed Maps JavaScript API} + * @see {@link Map#getProjection} + */ + projection_changed: []; + + /** + * This event is fired when the DOM contextmenu event is fired on the map container. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.rightclick Maps JavaScript API} + */ + rightclick: [MouseEvent]; + + /** + * This event is fired when the visible tiles have finished loading. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.tilesloaded Maps JavaScript API} + */ + tilesloaded: []; + + /** + * This event is fired when the map tilt property changes. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.tilt_changed Maps JavaScript API} + * @see {@link MapOptions#tilt} + * @see {@link Map#getTilt} + * @see {@link Map#setTilt} + */ + tilt_changed: []; + + /** + * This event is fired when the map zoom property changes. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.zoom_changed Maps JavaScript API} + * @see {@link MapOptions#zoom} + * @see {@link Map#getZoom} + * @see {@link Map#setZoom} + */ + zoom_changed: []; + } + + /** @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map Maps JavaScript API} */ + class Map extends MVCObject { + /** + * Creates a new map inside of the given HTML container, which is typically a DIV element. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.constructor Maps JavaScript API} + */ + constructor(mapDiv: E, opts?: MapOptions); + + /** + * @see {@link MapHandlerMap#bounds_changed bounds_changed} event + * @see {@link MapHandlerMap#center_changed center_changed} event + * @see {@link MapHandlerMap#click click} event + * @see {@link MapHandlerMap#dblclick dblclick} event + * @see {@link MapHandlerMap#drag drag} event + * @see {@link MapHandlerMap#dragend dragend} event + * @see {@link MapHandlerMap#dragstart dragstart} event + * @see {@link MapHandlerMap#heading_changed heading_changed} event + * @see {@link MapHandlerMap#idle idle} event + * @see {@link MapHandlerMap#maptypeid_changed maptypeid_changed} event + * @see {@link MapHandlerMap#mousemove mousemove} event + * @see {@link MapHandlerMap#mouseout mouseout} event + * @see {@link MapHandlerMap#mouseover mouseover} event + * @see {@link MapHandlerMap#projection_changed projection_changed} event + * @see {@link MapHandlerMap#rightclick rightclick} event + * @see {@link MapHandlerMap#tilesloaded tilesloaded} event + * @see {@link MapHandlerMap#tilt_changed tilt_changed} event + * @see {@link MapHandlerMap#zoom_changed zoom_changed} event + */ + addListener( + eventName: N, + handler: MVCEventHandler, + ): MapsEventListener; + + /** @deprecated */ + addListener(eventName: string, handler: MVCEventHandler): MapsEventListener; + + /** + * Sets the viewport to contain the given bounds. + * Note: When the map is set to `display: none`, the `fitBounds` function reads the map's size as 0x0, and therefore does not do anything. + * To change the viewport while the map is hidden, set the map to `visibility: hidden`, thereby ensuring the map div has an actual size. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.fitBounds Maps JavaScript API} + * @see {@link MapHandlerMap#bounds_changed event bounds_changed} + * @see {@link getBounds} + * @see {@link panBy} + * @see {@link panTo} + * @see {@link panToBounds} + * @see {@link setCenter} + */ fitBounds(bounds: LatLngBounds | LatLngBoundsLiteral, padding?: number | Padding): void; + + /** + * Returns the lat/lng bounds of the current viewport. + * If more than one copy of the world is visible, the bounds range in longitude from -180 to 180 degrees inclusive. + * If the map is not yet initialized (i.e. the mapType is still null), or center and zoom have not been set then the result is `null` or `undefined`. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.getBounds Maps JavaScript API} + * @see {@link MapHandlerMap#bounds_changed bounds_changed} event + * @see {@link fitBounds} + * @see {@link getCenter} + * @see {@link panToBounds} + */ getBounds(): LatLngBounds | null | undefined; + + /** + * Returns the position displayed at the center of the map. + * Note that this {@link LatLng} object is not wrapped. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.getCenter Maps JavaScript API} + * @see {@link MapOptions#center} + * @see {@link MapHandlerMap#center_changed center_changed} event + * @see {@link getBounds} + * @see {@link setCenter} + */ getCenter(): LatLng; - getDiv(): Element; + + /** + * Returns the clickability of the map icons. + * A map icon represents a point of interest, also known as a POI. + * If the returned value is true, then the icons are clickable on the map. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.getClickableIcons Maps JavaScript API} + * @see {@link MapOptions#clickableIcons} + * @see {@link setClickableIcons} + */ + getClickableIcons(): boolean; + + /** @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.getDiv Maps JavaScript API} */ + getDiv(): E; + + /** + * Returns the compass heading of aerial imagery. + * The heading value is measured in degrees (clockwise) from cardinal direction North. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.getHeading Maps JavaScript API} + * @see {@link MapOptions#heading} + * @see {@link MapHandlerMap#heading_changed heading_changed} event + * @see {@link setHeading} + */ getHeading(): number; + + /** + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.getMapTypeId Maps JavaScript API} + * @see {@link MapOptions#mapTypeId} + * @see {@link MapHandlerMap#maptypeid_changed maptypeid_changed} event + * @see {@link setMapTypeId} + * @see {@link mapTypes} + * @see {@link overlayMapTypes} + */ getMapTypeId(): MapTypeId; + + /** + * If the map is not yet initialized (i.e. the mapType is still `null`) then the result is `null`. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.getProjection Maps JavaScript API} + * @see {@link MapHandlerMap#projection_changed projection_changed} event + */ getProjection(): Projection | null; + + /** + * Returns the default {@link StreetViewPanorama} bound to the map, which may be a default panorama embedded within the map, or the panorama set using {@link setStreetView}(). + * Changes to the map's {@link MapOptions#streetViewControl streetViewControl} will be reflected in the display of such a bound panorama. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.getStreetView Maps JavaScript API} + * @see {@link MapOptions#streetView} + * @see {@link setStreetView} + */ getStreetView(): StreetViewPanorama; + + /** + * Returns the current angle of incidence of the map, in degrees from the viewport plane to the map plane. + * The result will be 0 for imagery taken directly overhead or 45 for 45° imagery. + * 45° imagery is only available for satellite and hybrid map types, within some locations, and at some zoom levels. + * Note: This method does not return the value set by setTilt. See setTilt for details. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.getTilt Maps JavaScript API} + * @see {@link MapOptions#tilt} + * @see {@link MapHandlerMap#tilt_changed tilt_changed} event + * @see {@link setTilt} + */ getTilt(): number; + + /** + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.getZoom Maps JavaScript API} + * @see {@link MapOptions#zoom} + * @see {@link MapHandlerMap#zoom_changed zoom_changed} event + * @see {@link getBounds} + * @see {@link setZoom} + */ getZoom(): number; + + /** + * Changes the center of the map by the given distance in pixels. + * If the distance is less than both the width and height of the map, the transition will be smoothly animated. + * Note that the map coordinate system increases from west to east (for x values) and north to south (for y values). + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.panBy Maps JavaScript API} + * @see {@link panTo} + * @see {@link panToBounds} + * @see {@link setCenter} + */ panBy(x: number, y: number): void; + + /** + * Changes the center of the map to the given {@link LatLng}. + * If the change is less than both the width and height of the map, the transition will be smoothly animated. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.panTo Maps JavaScript API} + * @see {@link panBy} + * @see {@link panToBounds} + * @see {@link setCenter} + */ panTo(latLng: LatLng | LatLngLiteral): void; + + /** + * Pans the map by the minimum amount necessary to contain the given {@link LatLngBounds}. + * It makes no guarantee where on the map the bounds will be, + * except that the map will be panned to show as much of the bounds as possible inside `{currentMapSizeInPx} - {padding}`. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.panToBounds Maps JavaScript API} + * @see {@link panBy} + * @see {@link panTo} + * @see {@link setCenter} + */ panToBounds(latLngBounds: LatLngBounds | LatLngBoundsLiteral, padding?: number | Padding): void; + + /** + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.setCenter Maps JavaScript API} + * @see {@link MapOptions#center} + * @see {@link MapHandlerMap#center_changed center_changed} event + * @see {@link fitBounds} + * @see {@link getCenter} + * @see {@link panBy} + * @see {@link panTo} + * @see {@link panToBounds} + */ setCenter(latlng: LatLng | LatLngLiteral): void; + + /** + * Sets the compass heading for aerial imagery measured in degrees from cardinal direction North. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.setHeading Maps JavaScript API} + * @see {@link MapOptions#heading} + * @see {@link MapHandlerMap#heading_changed} event + * @see {@link getHeading} + */ setHeading(heading: number): void; + + /** + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.setMapTypeId Maps JavaScript API} + * @see {@link MapOptions#mapTypeId} + * @see {@link MapHandlerMap#maptypeid_changed} event + * @see {@link getMapTypeId} + * @see {@link mapTypes} + * @see {@link overlayMapTypes} + */ setMapTypeId(mapTypeId: MapTypeId | string): void; + + /** @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.setOptions Maps JavaScript API} */ setOptions(options: MapOptions): void; - setStreetView(panorama: StreetViewPanorama): void; + + /** + * Binds a {@link StreetViewPanorama} to the map. + * This panorama overrides the default {@link StreetViewPanorama}, allowing the map to bind to an external panorama outside of the map. + * Setting the panorama to `null` binds the default embedded panorama back to the map. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.setStreetView Maps JavaScript API} + * @see {@link MapOptions#streetView} + * @see {@link getStreetView} + */ + setStreetView(panorama: StreetViewPanorama | null): void; + + /** + * Controls the automatic switching behavior for the angle of incidence of the map. + * The only allowed values are `0` and `45`. + * `setTilt(0)` causes the map to always use a 0° overhead view regardless of the zoom level and viewport. + * `setTilt(45)` causes the tilt angle to automatically switch to 45 whenever 45° imagery is available for the current zoom level and viewport, + * and switch back to 0 whenever 45° imagery is not available (this is the default behavior). + * 45° imagery is only available for {@link MapTypeId.SATELLITE satellite} and {@link MapTypeId.HYBRID hybrid} map types, within some locations, and at some zoom levels. + * Note: getTilt returns the current tilt angle, not the value set by `setTilt`. + * Because getTilt and setTilt refer to different things, do not `bind`() the `tilt` property; doing so may yield unpredictable effects. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.setTilt Maps JavaScript API} + * @see {@link MapOptions#tilt} + * @see {@link MapHandlerMap#tilt_changed} + * @see {@link getTilt} + */ setTilt(tilt: number): void; + + /** + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.setZoom Maps JavaScript API} + * @see {@link MapOptions#zoom} + * @see {@link MapHandlerMap#zoom_changed zoom_changed} event + * @see {@link fitBounds} + * @see {@link getZoom} + * @see {@link panToBounds} + */ setZoom(zoom: number): void; + + /** + * Additional controls to attach to the map. + * To add a control to the map, add the control's `
` to the {@link MVCArray} corresponding to the {@link ControlPosition} where it should be rendered. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.controls Maps JavaScript API} + */ controls: Array>; + + /** + * An instance of {@link Data}, bound to the map. + * Add features to this Data object to conveniently display them on this map. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.data Maps JavaScript API} + */ data: Data; + + /** + * A registry of {@link MapType} instances by string ID. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.mapTypes Maps JavaScript API} + */ mapTypes: MapTypeRegistry; + + /** + * Additional map types to overlay. + * Overlay map types will display on top of the base map they are attached to, in the order in which they appear in the + * `overlayMapTypes` array (overlays with higher index values are displayed in front of overlays with lower index values). + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.overlayMapTypes Maps JavaScript API} + */ overlayMapTypes: MVCArray; + + /** + * Controls whether the map icons are clickable or not. A map icon represents a point of interest, also known as a POI. + * To disable the clickability of map icons, pass a value of `false` to this method. + * @see {@link https://developers.google.com/maps/documentation/javascript/reference/map#Map.setClickableIcons Maps JavaScript API} + * @see {@link MapOptions#clickableIcons} + * @see {@link getClickableIcons} + */ setClickableIcons(clickable: boolean): void; } @@ -2917,6 +3305,8 @@ declare namespace google.maps { toString(): string; } + type MVCEventHandler = (this: T, ...args: A) => void; + /***** MVC *****/ /** Base class implementing KVO. */ class MVCObject { @@ -2933,7 +3323,7 @@ declare namespace google.maps { * identifier for this listener that can be used with * google.maps.event.removeListener. */ - addListener(eventName: string, handler: (...args: any[]) => void): MapsEventListener; + addListener(eventName: string, handler: MVCEventHandler): MapsEventListener; /** Binds a View to a Model. */ bindTo(key: string, target: MVCObject, targetKey?: string, noNotify?: boolean): void; changed(key: string): void; diff --git a/types/load-google-maps-api/index.d.ts b/types/load-google-maps-api/index.d.ts index 9aa703b201..1ecccacca0 100644 --- a/types/load-google-maps-api/index.d.ts +++ b/types/load-google-maps-api/index.d.ts @@ -2,7 +2,7 @@ // Project: https://github.com/yuanqing/load-google-maps-api#readme // Definitions by: Oscar Busk // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped -// TypeScript Version: 2.7 +// TypeScript Version: 3.0 /// diff --git a/types/load-google-maps-api/load-google-maps-api-tests.ts b/types/load-google-maps-api/load-google-maps-api-tests.ts index b01336e185..e6544c7fad 100644 --- a/types/load-google-maps-api/load-google-maps-api-tests.ts +++ b/types/load-google-maps-api/load-google-maps-api-tests.ts @@ -2,7 +2,7 @@ import loadGoogleMapsApi = require('load-google-maps-api'); // Example from README.md https://github.com/yuanqing/load-google-maps-api#usage loadGoogleMapsApi().then((googleMaps) => { - new googleMaps.Map(document.querySelector('.map'), { + new googleMaps.Map(document.createElement('div'), { center: { lat: 40.7484405, lng: -73.9944191 @@ -34,6 +34,6 @@ loadGoogleMapsApi({ v: '3.33', }).then(gm => { gm; // $ExpectType typeof maps - const map = new gm.Map(document.querySelector('.map')); // $ExpectType Map + const map = new gm.Map(document.createElement('div')); // $ExpectType Map const polygon = new gm.Polygon(); // $ExpectType Polygon });