mirror of
https://github.com/google-map-react/google-map-react.git
synced 2025-12-08 18:26:32 +00:00
New documentation begin
This commit is contained in:
cybice
parent
b9d8530b2f
commit
e64f9819dd
320
API.md
Normal file
320
API.md
Normal file
@ -0,0 +1,320 @@
|
||||
## GoogleMap API
|
||||
|
||||
### parameters
|
||||
|
||||
#### apiKey (string) (_Deprecated use bootstrapURLKeys_)
|
||||
|
||||
Google maps api key. (Optional, but your map will be rate-limited with no key)
|
||||
|
||||
#### bootstrapURLKeys (object)
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
<GoogleMap
|
||||
bootstrapURLKeys={{
|
||||
key: API_KEY,
|
||||
language: 'ru',
|
||||
...otherUrlParams,
|
||||
}}
|
||||
>
|
||||
```
|
||||
|
||||
#### defaultCenter (array or object)
|
||||
|
||||
`[lat, lng]` or `{ lat: lat, lng: lng}`
|
||||
Default lat/lng at which to center the map - changing this prop throws a warning
|
||||
|
||||
#### center (array or object)
|
||||
|
||||
`[lat, lng]` or `{ lat: lat, lng: lng}`
|
||||
Lat/lng at which to center the map
|
||||
|
||||
#### defaultZoom: (number)
|
||||
|
||||
Default map zoom level - changing this prop throws a warning
|
||||
|
||||
#### zoom (number)
|
||||
|
||||
Map zoom level
|
||||
|
||||
#### hoverDistance (number)
|
||||
|
||||
Default: 30
|
||||
|
||||
#### margin (array)
|
||||
|
||||
In onChange callback, gives you a marginBounds argument property, where lat lng will be shifted using margin you have set. For example, you could use a simple check pointInRect to not show Markers near map bounds.
|
||||
|
||||
#### debounced (bool)
|
||||
|
||||
Default: true
|
||||
|
||||
#### layerTypes (string[])
|
||||
|
||||
You can add some "layers" for map like a
|
||||
[traffic](https://developers.google.com/maps/documentation/javascript/examples/layer-traffic) or
|
||||
[transit](https://developers.google.com/maps/documentation/javascript/examples/layer-transit)
|
||||
|
||||
```javascript
|
||||
layerTypes={['TrafficLayer', 'TransitLayer']}
|
||||
```
|
||||
|
||||
### callbacks
|
||||
|
||||
#### options (func|object)
|
||||
|
||||
Set map options such as controls positions / styles, etc.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
createMapOptions: function (maps) {
|
||||
return {
|
||||
panControl: false,
|
||||
mapTypeControl: false,
|
||||
scrollwheel: false,
|
||||
styles: [{ stylers: [{ 'saturation': -100 }, { 'gamma': 0.8 }, { 'lightness': 4 }, { 'visibility': 'on' }] }]
|
||||
}
|
||||
}
|
||||
|
||||
<GoogleMap options={createMapOptions} ... />
|
||||
```
|
||||
See "Custom map options example" in Examples below for a further example.
|
||||
|
||||
#### onClick (func)
|
||||
|
||||
```
|
||||
({ x, y, lat, lng, event })
|
||||
```
|
||||
|
||||
The `event` prop in args is the outer div onClick event, not the gmap-api 'click' event.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
_onClick = ({x, y, lat, lng, event}) => console.log(x, y, lat, lng, event)
|
||||
// ES5 users
|
||||
function _onClick(obj){ console.log(obj.x, obj.y, obj.lat, obj.lng, obj.event);}
|
||||
|
||||
<GoogleMap onClick={_onClick} ... />
|
||||
```
|
||||
|
||||
#### onBoundsChange (func) (_Deprecated use onChange_)
|
||||
|
||||
```
|
||||
({ center, zoom, bounds, marginBounds })
|
||||
```
|
||||
```
|
||||
[lat, lng] = center;
|
||||
[topLat, leftLng, bottomLat, rightLng] = bounds;
|
||||
```
|
||||
|
||||
#### resetBoundsOnResize (bool)
|
||||
|
||||
When true this will reset the map bounds if the parent resizes.
|
||||
|
||||
Default: false
|
||||
|
||||
#### onChildClick (func)
|
||||
|
||||
#### onChildMouseEnter (func)
|
||||
|
||||
#### onChildMouseLeave (func)
|
||||
|
||||
#### onZoomAnimationStart (func)
|
||||
|
||||
#### onZoomAnimationEnd (func)
|
||||
|
||||
#### onMapTypeIdChange (func)
|
||||
When the user changes the map type (HYBRID, ROADMAP, SATELLITE, TERRAIN) this fires
|
||||
|
||||
#### distanceToMouse (func)
|
||||
|
||||
#### googleMapLoader (func)
|
||||
|
||||
#### onGoogleApiLoaded (func)
|
||||
Directly access the maps API - *use at your own risk!*
|
||||
|
||||
```javascript
|
||||
<GoogleMap onGoogleApiLoaded={({map, maps}) => console.log(map, maps)} />
|
||||
```
|
||||
|
||||
To prevent warning message add _yesIWantToUseGoogleMapApiInternals_ property to GoogleMap
|
||||
|
||||
```javascript
|
||||
<GoogleMap onGoogleApiLoaded={({map, maps}) => console.log(map, maps)}
|
||||
yesIWantToUseGoogleMapApiInternals
|
||||
/>
|
||||
```
|
||||
|
||||
## Child Component API
|
||||
|
||||
### parameters
|
||||
|
||||
#### lat (number)
|
||||
Latitude to place the marker component
|
||||
|
||||
#### lng (number)
|
||||
Longitude to place the marker component
|
||||
|
||||
#### $hover (bool) [automatic]
|
||||
GoogleMap passes a $hover prop to hovered components. To detect hover it an uses internal mechanism, explained in x_distance_hover example
|
||||
|
||||
Example:
|
||||
```javascript
|
||||
render() {
|
||||
const style = this.props.$hover ? greatPlaceStyleHover : greatPlaceStyle;
|
||||
|
||||
return (
|
||||
<div style={style}>
|
||||
{this.props.text}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Utility functions
|
||||
|
||||
#### fitBounds (func)
|
||||
Use fitBounds to get zoom and center.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
import { fitBounds } from 'google-map-react/utils';
|
||||
|
||||
const bounds = {
|
||||
nw: {
|
||||
lat: 50.01038826014866,
|
||||
lng: -118.6525866875
|
||||
},
|
||||
se: {
|
||||
lat: 32.698335045970396,
|
||||
lng: -92.0217273125
|
||||
}
|
||||
};
|
||||
|
||||
// Or
|
||||
|
||||
const bounds = {
|
||||
ne: {
|
||||
lat: 50.01038826014866,
|
||||
lng: -118.6525866875
|
||||
},
|
||||
sw: {
|
||||
lat: 32.698335045970396,
|
||||
lng: -92.0217273125
|
||||
}
|
||||
};
|
||||
|
||||
const size = {
|
||||
width: 640, // Map width in pixels
|
||||
height: 380, // Map height in pixels
|
||||
};
|
||||
|
||||
const {center, zoom} = fitBounds(bounds, size);
|
||||
```
|
||||
|
||||
#### tile2LatLng (func)
|
||||
|
||||
#### latLng2Tile (func)
|
||||
|
||||
#### getTilesIds (func)
|
||||
|
||||
## Tips
|
||||
|
||||
### My map doesn't appear
|
||||
|
||||
Make sure the container element has width and height. The map will try to fill the parent container, but if the container has no size, the map will collapse to 0 width / height.
|
||||
|
||||
### Positioning a marker
|
||||
|
||||
Initially any map object has its top left corner at lat lng coordinates. It's up to you to set the object origin to 0,0 coordinates.
|
||||
|
||||
Example (centering the marker):
|
||||
|
||||
```javascript
|
||||
const MARKER_SIZE = 40;
|
||||
const greatPlaceStyle = {
|
||||
position: 'absolute',
|
||||
width: MARKER_SIZE,
|
||||
height: MARKER_SIZE,
|
||||
left: -MARKER_SIZE / 2,
|
||||
top: -MARKER_SIZE / 2
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
render() {
|
||||
return (
|
||||
<div style={greatPlaceStyle}>
|
||||
{this.props.text}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Rendering in a modal
|
||||
|
||||
If at the moment of GoogleMap control created, a modal has no size (width,height=0) or/and not displayed, the simple solution is to add something like this in render:
|
||||
|
||||
```javascript
|
||||
render() {
|
||||
return this.props.modalIsOpen
|
||||
? <GoogleMap />
|
||||
: null;
|
||||
}
|
||||
```
|
||||
|
||||
### Adding a searchbox
|
||||
|
||||
```javascript
|
||||
import React from 'react';
|
||||
|
||||
export default class SearchBox extends React.Component {
|
||||
static propTypes = {
|
||||
placeholder: React.PropTypes.string,
|
||||
onPlacesChanged: React.PropTypes.func
|
||||
}
|
||||
render() {
|
||||
return <input ref="input" {...this.props} type="text"/>;
|
||||
}
|
||||
onPlacesChanged = () => {
|
||||
if (this.props.onPlacesChanged) {
|
||||
this.props.onPlacesChanged(this.searchBox.getPlaces());
|
||||
}
|
||||
}
|
||||
componentDidMount() {
|
||||
var input = React.findDOMNode(this.refs.input);
|
||||
this.searchBox = new google.maps.places.SearchBox(input);
|
||||
this.searchBox.addListener('places_changed', this.onPlacesChanged);
|
||||
}
|
||||
componentWillUnmount() {
|
||||
this.searchBox.removeListener('places_changed', this.onPlacesChanged);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You will need to preload the google maps API, but `google-map-react` checks if the base api is already loaded,
|
||||
and if so, uses it, so it won't load a second copy of the library.
|
||||
|
||||
```html
|
||||
<script type="text/javascript" src="https://maps.google.com/maps/api/js?libraries=places&sensor=false"></script>
|
||||
```
|
||||
|
||||
### Override the default minimum zoom
|
||||
|
||||
*WARNING*: Setting these options can break markers calculation, causing no homeomorphism between screen coordinates and map.
|
||||
|
||||
You can use the `minZoomOverride` associated with the `minZoom` in the custom map options to prevent a minimum zoom from being calculated:
|
||||
|
||||
```javascript
|
||||
function createMapOptions() {
|
||||
return {
|
||||
minZoomOverride: true,
|
||||
minZoom: 2,
|
||||
};
|
||||
}
|
||||
```
|
||||
30
DOC.md
Normal file
30
DOC.md
Normal file
@ -0,0 +1,30 @@
|
||||
# Documentation
|
||||
|
||||
Here I'll try to explain why some methods in google map react are needed and how to use them.
|
||||
|
||||
For all examples I'll use [recompose](github.com/acdlite/recompose)
|
||||
and you must understand what `css-modules` is.
|
||||
|
||||
## Simple example.
|
||||
|
||||
[Simple example](http://www.webpackbin.com/N1N_45Owz)
|
||||
|
||||
At `Map.js` you will see the smallest possible boilerplate for GoogleMapReact component,
|
||||
|
||||
And a `MyMarker.js` is a simple React component.
|
||||
|
||||
I highly recommend you to use GoogleMapReact as a controllable component,
|
||||
and always provide `center`, `zoom` and `onChange` props. (_see withState_)
|
||||
|
||||
## Whats wrong with "Simple example" above
|
||||
|
||||
The wrong part is that React components are placed on the map positioning from top, left corner.
|
||||
|
||||
In most cases it's not the expected behaviour, so we need to change the MyMarker position by changing
|
||||
it's `position` and `left`, `top` css properties, or use `flex` as like as in this example.
|
||||
|
||||
[Good position](http://www.webpackbin.com/VJBKkj_vM)
|
||||
|
||||
Now `MyMarker` centered well, see the `myMarker.css` css changes and `MyMarker.js` layout change.
|
||||
|
||||
## To be continued
|
||||
324
README.md
324
README.md
@ -32,7 +32,6 @@ This algorithm allows you to tweak hover probability of map objects, for example
|
||||
|
||||
## Known Issues
|
||||
|
||||
* Small icons jiggle on Firefox (I don't see this in my older 'GoogleMap' version, so I will find the problem soon)
|
||||
* Older browsers (http://caniuse.com/#feat=promises) will need a ES6 Promise polyfill in order to work.
|
||||
|
||||
## Installation
|
||||
@ -129,328 +128,11 @@ npm run start
|
||||
# open browser at localhost:4000
|
||||
```
|
||||
|
||||
## GoogleMap API
|
||||
## API
|
||||
|
||||
### parameters
|
||||
[API](./API.md)
|
||||
|
||||
#### apiKey (string) (_Deprecated use bootstrapURLKeys_)
|
||||
|
||||
Google maps api key. (Optional, but your map will be rate-limited with no key)
|
||||
|
||||
#### bootstrapURLKeys (object)
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
<GoogleMap
|
||||
bootstrapURLKeys={{
|
||||
key: API_KEY,
|
||||
language: 'ru',
|
||||
...otherUrlParams,
|
||||
}}
|
||||
>
|
||||
```
|
||||
|
||||
#### defaultCenter (array or object)
|
||||
|
||||
`[lat, lng]` or `{ lat: lat, lng: lng}`
|
||||
Default lat/lng at which to center the map - changing this prop throws a warning
|
||||
|
||||
#### center (array or object)
|
||||
|
||||
`[lat, lng]` or `{ lat: lat, lng: lng}`
|
||||
Lat/lng at which to center the map
|
||||
|
||||
#### defaultZoom: (number)
|
||||
|
||||
Default map zoom level - changing this prop throws a warning
|
||||
|
||||
#### zoom (number)
|
||||
|
||||
Map zoom level
|
||||
|
||||
#### hoverDistance (number)
|
||||
|
||||
Default: 30
|
||||
|
||||
#### margin (array)
|
||||
|
||||
In onChange callback, gives you a marginBounds argument property, where lat lng will be shifted using margin you have set. For example, you could use a simple check pointInRect to not show Markers near map bounds.
|
||||
|
||||
#### debounced (bool)
|
||||
|
||||
Default: true
|
||||
|
||||
#### layerTypes (string[])
|
||||
|
||||
You can add some "layers" for map like a
|
||||
[traffic](https://developers.google.com/maps/documentation/javascript/examples/layer-traffic) or
|
||||
[transit](https://developers.google.com/maps/documentation/javascript/examples/layer-transit)
|
||||
|
||||
```javascript
|
||||
layerTypes={['TrafficLayer', 'TransitLayer']}
|
||||
```
|
||||
|
||||
#### resetBoundsOnResize (bool)
|
||||
|
||||
When true this will reset the map bounds if the parent resizes.
|
||||
|
||||
Default: false
|
||||
|
||||
### callbacks
|
||||
|
||||
#### options (func|object)
|
||||
|
||||
Set map options such as controls positions / styles, etc.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
createMapOptions: function (maps) {
|
||||
return {
|
||||
panControl: false,
|
||||
mapTypeControl: false,
|
||||
scrollwheel: false,
|
||||
styles: [{ stylers: [{ 'saturation': -100 }, { 'gamma': 0.8 }, { 'lightness': 4 }, { 'visibility': 'on' }] }]
|
||||
}
|
||||
}
|
||||
|
||||
<GoogleMap options={createMapOptions} ... />
|
||||
```
|
||||
See "Custom map options example" in Examples below for a further example.
|
||||
|
||||
#### onClick (func)
|
||||
|
||||
```
|
||||
({ x, y, lat, lng, event })
|
||||
```
|
||||
|
||||
The `event` prop in args is the outer div onClick event, not the gmap-api 'click' event.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
_onClick = ({x, y, lat, lng, event}) => console.log(x, y, lat, lng, event)
|
||||
// ES5 users
|
||||
function _onClick(obj){ console.log(obj.x, obj.y, obj.lat, obj.lng, obj.event);}
|
||||
|
||||
<GoogleMap onClick={_onClick} ... />
|
||||
```
|
||||
|
||||
#### onBoundsChange (func) (_Deprecated use onChange_)
|
||||
|
||||
```
|
||||
({ center, zoom, bounds, marginBounds })
|
||||
```
|
||||
```
|
||||
[lat, lng] = center;
|
||||
[topLat, leftLng, bottomLat, rightLng] = bounds;
|
||||
```
|
||||
|
||||
#### onChildClick (func)
|
||||
|
||||
#### onChildMouseEnter (func)
|
||||
|
||||
#### onChildMouseLeave (func)
|
||||
|
||||
#### onZoomAnimationStart (func)
|
||||
|
||||
#### onZoomAnimationEnd (func)
|
||||
|
||||
#### onMapTypeIdChange (func)
|
||||
When the user changes the map type (HYBRID, ROADMAP, SATELLITE, TERRAIN) this fires
|
||||
|
||||
#### distanceToMouse (func)
|
||||
|
||||
#### googleMapLoader (func)
|
||||
|
||||
#### onGoogleApiLoaded (func)
|
||||
Directly access the maps API - *use at your own risk!*
|
||||
|
||||
```javascript
|
||||
<GoogleMap onGoogleApiLoaded={({map, maps}) => console.log(map, maps)} />
|
||||
```
|
||||
|
||||
To prevent warning message add _yesIWantToUseGoogleMapApiInternals_ property to GoogleMap
|
||||
|
||||
```javascript
|
||||
<GoogleMap onGoogleApiLoaded={({map, maps}) => console.log(map, maps)}
|
||||
yesIWantToUseGoogleMapApiInternals
|
||||
/>
|
||||
```
|
||||
|
||||
## Child Component API
|
||||
|
||||
### parameters
|
||||
|
||||
#### lat (number)
|
||||
Latitude to place the marker component
|
||||
|
||||
#### lng (number)
|
||||
Longitude to place the marker component
|
||||
|
||||
#### $hover (bool) [automatic]
|
||||
GoogleMap passes a $hover prop to hovered components. To detect hover it an uses internal mechanism, explained in x_distance_hover example
|
||||
|
||||
Example:
|
||||
```javascript
|
||||
render() {
|
||||
const style = this.props.$hover ? greatPlaceStyleHover : greatPlaceStyle;
|
||||
|
||||
return (
|
||||
<div style={style}>
|
||||
{this.props.text}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Utility functions
|
||||
|
||||
#### fitBounds (func)
|
||||
Use fitBounds to get zoom and center.
|
||||
|
||||
Example:
|
||||
|
||||
```javascript
|
||||
import { fitBounds } from 'google-map-react/utils';
|
||||
|
||||
const bounds = {
|
||||
nw: {
|
||||
lat: 50.01038826014866,
|
||||
lng: -118.6525866875
|
||||
},
|
||||
se: {
|
||||
lat: 32.698335045970396,
|
||||
lng: -92.0217273125
|
||||
}
|
||||
};
|
||||
|
||||
// Or
|
||||
|
||||
const bounds = {
|
||||
ne: {
|
||||
lat: 50.01038826014866,
|
||||
lng: -118.6525866875
|
||||
},
|
||||
sw: {
|
||||
lat: 32.698335045970396,
|
||||
lng: -92.0217273125
|
||||
}
|
||||
};
|
||||
|
||||
const size = {
|
||||
width: 640, // Map width in pixels
|
||||
height: 380, // Map height in pixels
|
||||
};
|
||||
|
||||
const {center, zoom} = fitBounds(bounds, size);
|
||||
```
|
||||
|
||||
#### tile2LatLng (func)
|
||||
|
||||
#### latLng2Tile (func)
|
||||
|
||||
#### getTilesIds (func)
|
||||
|
||||
## Tips
|
||||
|
||||
### My map doesn't appear
|
||||
|
||||
Make sure the container element has width and height. The map will try to fill the parent container, but if the container has no size, the map will collapse to 0 width / height.
|
||||
|
||||
### Positioning a marker
|
||||
|
||||
Initially any map object has its top left corner at lat lng coordinates. It's up to you to set the object origin to 0,0 coordinates.
|
||||
|
||||
Example (centering the marker):
|
||||
|
||||
```javascript
|
||||
const MARKER_SIZE = 40;
|
||||
const greatPlaceStyle = {
|
||||
position: 'absolute',
|
||||
width: MARKER_SIZE,
|
||||
height: MARKER_SIZE,
|
||||
left: -MARKER_SIZE / 2,
|
||||
top: -MARKER_SIZE / 2
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
render() {
|
||||
return (
|
||||
<div style={greatPlaceStyle}>
|
||||
{this.props.text}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Rendering in a modal
|
||||
|
||||
If at the moment of GoogleMap control created, a modal has no size (width,height=0) or/and not displayed, the simple solution is to add something like this in render:
|
||||
|
||||
```javascript
|
||||
render() {
|
||||
return this.props.modalIsOpen
|
||||
? <GoogleMap />
|
||||
: null;
|
||||
}
|
||||
```
|
||||
|
||||
### Adding a searchbox
|
||||
|
||||
```javascript
|
||||
import React from 'react';
|
||||
|
||||
export default class SearchBox extends React.Component {
|
||||
static propTypes = {
|
||||
placeholder: React.PropTypes.string,
|
||||
onPlacesChanged: React.PropTypes.func
|
||||
}
|
||||
render() {
|
||||
return <input ref="input" {...this.props} type="text"/>;
|
||||
}
|
||||
onPlacesChanged = () => {
|
||||
if (this.props.onPlacesChanged) {
|
||||
this.props.onPlacesChanged(this.searchBox.getPlaces());
|
||||
}
|
||||
}
|
||||
componentDidMount() {
|
||||
var input = React.findDOMNode(this.refs.input);
|
||||
this.searchBox = new google.maps.places.SearchBox(input);
|
||||
this.searchBox.addListener('places_changed', this.onPlacesChanged);
|
||||
}
|
||||
componentWillUnmount() {
|
||||
this.searchBox.removeListener('places_changed', this.onPlacesChanged);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You will need to preload the google maps API, but `google-map-react` checks if the base api is already loaded,
|
||||
and if so, uses it, so it won't load a second copy of the library.
|
||||
|
||||
```html
|
||||
<script type="text/javascript" src="https://maps.google.com/maps/api/js?libraries=places&sensor=false"></script>
|
||||
```
|
||||
|
||||
### Override the default minimum zoom
|
||||
|
||||
*WARNING*: Setting these options can break markers calculation, causing no homeomorphism between screen coordinates and map.
|
||||
|
||||
You can use the `minZoomOverride` associated with the `minZoom` in the custom map options to prevent a minimum zoom from being calculated:
|
||||
|
||||
```javascript
|
||||
function createMapOptions() {
|
||||
return {
|
||||
minZoomOverride: true,
|
||||
minZoom: 2,
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
[NEW DOCS](./DOC.md)
|
||||
|
||||
(*Really big thanks to [April Arcus](https://github.com/AprilArcus) for documentation fixes*)
|
||||
(*thank you [Dan Abramov](http://gaearon.github.io/react-dnd/) for titles structure*)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user