[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
This commit is contained in:
Dmitry Demensky
2019-12-23 10:30:58 -06:00
committed by Andrew Branch
parent cc23ed1761
commit 93901a2c0d
4 changed files with 401 additions and 11 deletions
+2 -2
View File
@@ -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<Element> | StreetViewPanorama | null | undefined
marker.getOpacity(); // $ExpectType number | null | undefined
+396 -6
View File
@@ -16,7 +16,7 @@
// Gavin Nitta <https://github.com/gshigeto>
// 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<E extends Element = Element> 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<N extends keyof MapHandlerMap>(
eventName: N,
handler: MVCEventHandler<this, MapHandlerMap[N]>,
): MapsEventListener;
/** @deprecated */
addListener(eventName: string, handler: MVCEventHandler<this, any[]>): 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 `<div>` 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<MVCArray<Node>>;
/**
* 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<MapType>;
/**
* 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<T extends MVCObject, A extends any[]> = (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<this, any[]>): MapsEventListener;
/** Binds a View to a Model. */
bindTo(key: string, target: MVCObject, targetKey?: string, noNotify?: boolean): void;
changed(key: string): void;
+1 -1
View File
@@ -2,7 +2,7 @@
// Project: https://github.com/yuanqing/load-google-maps-api#readme
// Definitions by: Oscar Busk <https://github.com/oBusk>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// TypeScript Version: 2.7
// TypeScript Version: 3.0
/// <reference types="googlemaps" />
@@ -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<HTMLDivElement>
const polygon = new gm.Polygon(); // $ExpectType Polygon
});