mirror of
https://github.com/visgl/react-map-gl.git
synced 2026-01-18 15:54:22 +00:00
documentation polish (#295)
This commit is contained in:
Anh Mai
GitHub
parent
dd5baee74e
commit
dc2d3eb1af
@ -1,21 +1,21 @@
|
||||
# Overview
|
||||
# Introduction
|
||||
|
||||
react-map-gl is a react friendly API wrapper around
|
||||
react-map-gl is a suite of React components for
|
||||
[Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js).
|
||||
|
||||
## Example
|
||||
|
||||
```js
|
||||
import MapGL from 'react-map-gl';
|
||||
import ReactMapGL from 'react-map-gl';
|
||||
|
||||
<MapGL
|
||||
<ReactMapGL
|
||||
width={400}
|
||||
height={400}
|
||||
latitude={37.7577}
|
||||
longitude={-122.4376}
|
||||
zoom={8}
|
||||
onChangeViewport={viewport => {
|
||||
const {latitude, longitude, zoom} = viewport;
|
||||
onViewportChange={(viewport) => {
|
||||
const {width, height, latitude, longitude, zoom} = viewport;
|
||||
// Optionally call `setState` and use the state to update the map.
|
||||
}}
|
||||
/>
|
||||
|
||||
@ -23,7 +23,7 @@ A simple example to disable mouse wheel:
|
||||
```
|
||||
Then pass it to the map during render:
|
||||
```jsx
|
||||
<MapGL mapControls={new MyMapControls()} ... />
|
||||
<ReactMapGL mapControls={new MyMapControls()} ... />
|
||||
```
|
||||
|
||||
|
||||
|
||||
@ -18,7 +18,7 @@ class Map extends Component {
|
||||
longitude={-122.4376}
|
||||
zoom={8}
|
||||
onViewportChange={(viewport) => {
|
||||
const {latitude, longitude, zoom} = viewport;
|
||||
const {width, height, latitude, longitude, zoom} = viewport;
|
||||
// Optionally call `setState` and use the state to update the map.
|
||||
}}
|
||||
/>
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Get Started
|
||||
|
||||
`ReactMapGL` is a [React](http://facebook.github.io/react/)-friendly
|
||||
`react-map-gl` is a [React](http://facebook.github.io/react/)-friendly
|
||||
wrapper for [MapboxGL](https://www.mapbox.com/mapbox-gl-js/), a WebGL-powered
|
||||
vector and raster tile mapping library. On top of exposing as much of
|
||||
`MapboxGL` as possible, we also introduced our own event handling classes
|
||||
@ -9,7 +9,7 @@ that aim to make working with external overlays, such as
|
||||
|
||||
# Installation
|
||||
|
||||
`ReactMapGL` requires `node >= v4` and `react >= 15.4`.
|
||||
`react-map-gl` requires `node >= v4` and `react >= 15.4`.
|
||||
|
||||
```sh
|
||||
npm install --save react-map-gl
|
||||
@ -35,7 +35,7 @@ class Map extends Component {
|
||||
longitude={-122.4376}
|
||||
zoom={8}
|
||||
onViewportChange={(viewport) => {
|
||||
const {latitude, longitude, zoom} = viewport;
|
||||
const {width, height, latitude, longitude, zoom} = viewport;
|
||||
// Optionally call `setState` and use the state to update the map.
|
||||
}}
|
||||
/>
|
||||
@ -46,25 +46,13 @@ class Map extends Component {
|
||||
|
||||
## Server Side Rendering
|
||||
|
||||
`ReactMapGL` depends on `gl`, which may cause issues when running in a server
|
||||
`react-map-gl` depends on `gl`, which may cause issues when running in a server
|
||||
environment without `gl` installed. You can either make sure that your system
|
||||
has `gl` installed or use the following work-around to ensure you only require
|
||||
`ReactMapGL` on the client.
|
||||
|
||||
```js
|
||||
// is-browser is an npm package, but you can use any other solution to make sure
|
||||
// that you are in a browser environment.
|
||||
import isBrowser from 'is-browser';
|
||||
|
||||
const ReactMapGL = 'div';
|
||||
if (isBrowser) {
|
||||
ReactMapGL = require('react-map-gl').default;
|
||||
}
|
||||
```
|
||||
has `gl` installed or make sure you only import `react-map-gl` on the client.
|
||||
|
||||
## Using with Browserify, Webpack, and other environments
|
||||
|
||||
* `browserify` - `ReactMapGL` is extensively tested with `browserify` and works
|
||||
* `browserify` - `react-map-gl` is extensively tested with `browserify` and works
|
||||
without issue.
|
||||
|
||||
* `webpack 1` - look at the [deck.gl exhibits](https://github.com/uber/deck.gl/tree/master/exhibits)
|
||||
|
||||
@ -1,5 +0,0 @@
|
||||
# Using with Isomorphic Rendering
|
||||
|
||||
Running under Node.js
|
||||
|
||||
TBA
|
||||
@ -8,4 +8,3 @@ without any transformation.
|
||||
|
||||
You can use the package [redux-map-gl](https://github.com/Willyham/redux-map-gl) to save writing this
|
||||
code yourself.
|
||||
|
||||
|
||||
@ -4,26 +4,6 @@
|
||||
|
||||
v3 is a major upgrade of react-map-gl. While we have tried to gently deprecated any changed or removed features, a few breaking changes could not be avoided.
|
||||
|
||||
### Two Map Components
|
||||
|
||||
v3 now exposes two React components: `StaticMap` and `InteractiveMap`.
|
||||
`InteractiveMap` is the default export.
|
||||
|
||||
### StaticMap
|
||||
|
||||
This is the React wrapper around `Mapbox GL JS` and takes in viewport properties
|
||||
such as `width`, `height`, `latitude`, `longitude`. Style diffing and updating
|
||||
logic also live here. See [Source Code](https://github.com/uber/react-map-gl/blob/master/src/components/static-map.js)
|
||||
for more information.
|
||||
|
||||
### InteractiveMap
|
||||
|
||||
This is a wrapper on top of `StaticMap`. It takes all the props
|
||||
of `StaticMap` and additional ones such as `onViewportChange`, `scrollZoom`,
|
||||
`dragRotate`, etc. to control interactivity on the map.
|
||||
See [Source Code](https://github.com/uber/react-map-gl/blob/master/src/components/interactive-map.js)
|
||||
for more information.
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
#### `onChangeViewport` / `onViewportChange` viewport
|
||||
@ -71,6 +51,27 @@ const viewport = new PerspectiveMercatorViewport({width: 600, height: 400}).fitB
|
||||
// }
|
||||
```
|
||||
|
||||
### Two Map Components
|
||||
|
||||
v3 now exposes two React components: `StaticMap` and `InteractiveMap`.
|
||||
`InteractiveMap` is the default export, and designed to be as compatible as
|
||||
possible with the v2 default export.
|
||||
|
||||
#### StaticMap
|
||||
|
||||
This is the React wrapper around `Mapbox GL JS` and takes in viewport properties
|
||||
such as `width`, `height`, `latitude`, `longitude`. Style diffing and updating
|
||||
logic also live here. See [Source Code](https://github.com/uber/react-map-gl/blob/master/src/components/static-map.js)
|
||||
for more information.
|
||||
|
||||
#### InteractiveMap
|
||||
|
||||
This is a wrapper on top of `StaticMap`. It takes all the props
|
||||
of `StaticMap` and additional ones such as `onViewportChange`, `scrollZoom`,
|
||||
`dragRotate`, etc. to control interactivity on the map.
|
||||
See [Source Code](https://github.com/uber/react-map-gl/blob/master/src/components/interactive-map.js)
|
||||
for more information.
|
||||
|
||||
### Deprecations
|
||||
|
||||
We have started to deprecate a few React props. In all the cases below, the old `props` will still work (you'll get a warning in the console), but they will likely be removed in the next major version of react-map-gl so you should start using the new `props` as soon as possible.
|
||||
|
||||
@ -7,63 +7,27 @@ Release date: End of Q2, 2017 (TBD)
|
||||
- **Node Version Requirement** is now **>=v6.4.0**: This is introduced in [Mapbox GL JS v0.38.0](https://github.com/mapbox/mapbox-gl-js/releases/tag/v0.38.0)
|
||||
- **Event Handling**: New event handling architecture that enables full customization of event handling (experimental).
|
||||
- **Multi-Touch Support**: Full support for multi-touch gestures such as pinch-to-zoom and rotate.
|
||||
- **Two Map Components**: `StaticMap` and `InteractiveMap` are now exported from
|
||||
the library, with the default being `InteractiveMap`.
|
||||
- **New Components**: `Popup`, `Marker`, `NavigationControl` have been added to provide parity with `Mapbox GL JS`.
|
||||
`StaticMap` is also added, which provides a static React wrapper around a `mapbox` instance.
|
||||
- **New Props**: `maxPitch`, `minPitch`, `dragPan`, `doubleClickZoom`, `touchZoomRotate`,
|
||||
`scrollZoom` are now provided to allow granular control of map interactivity.
|
||||
- **Documentation**: Significantly expanded and linked with our other geospatial frameworks.
|
||||
- **Examples**: Additional stand-alone examples to get you instantly started with new features.
|
||||
- **Latest Mapbox GL JS**: Bumps `Mapbox GL JS` to the [latest version](https://github.com/mapbox/mapbox-gl-js/releases) and enables us to stay in sync with future versions.
|
||||
- **Improved overlay components**: Vi ewport props (`width` `height` `zoom` `longitude` and `latitude`) are no longer required if you render `SVGOverlay` `CanvasOverlay` or `HTMLOverlay` as a child of the map. Perspective mode is now supported in all overlays.
|
||||
|
||||
## New Props
|
||||
|
||||
##### `{Bool} visible`: exposed on `StaticMap`
|
||||
Allows control visibility of the map component. This uses CSS's `display` property internally.
|
||||
|
||||
##### `{Func} getCursor`: exposed on `InteractiveMap` to determine the current cursor.
|
||||
See [Source Code](https://github.com/uber/react-map-gl/blob/master/src/components/interactive-map.js#L97)
|
||||
for more information.
|
||||
|
||||
##### `{Number} maxPitch, {Number} minPitch`: exposed on `InteractiveMap`
|
||||
Set the minimum and maximum allowed pitch.
|
||||
|
||||
##### `{Bool} dragPan`: exposed on `InteractiveMap`
|
||||
Set panning. Defaults to `true`.
|
||||
|
||||
##### `{Bool} doubleClickZoom`: exposed on `InteractiveMap`
|
||||
Set double clicking to zoom. Defaults to `true`.
|
||||
|
||||
##### `{Bool} touchZoomRotate`: exposed on `InteractiveMap`
|
||||
Set touch interaction. Defaults to `true`.
|
||||
|
||||
##### `{Object} mapControls`: exposed on `InteractiveMap`
|
||||
A map control instance to replace the default map controls.
|
||||
The object must expose one property: `events` as an array of subscribed
|
||||
event names; and two methods: `setState(state)` and `handle(event)`
|
||||
See [Source Code](https://github.com/uber/react-map-gl/blob/master/src/components/interactive-map.js#L88)
|
||||
for more information
|
||||
|
||||
## Experimental Props
|
||||
|
||||
##### `{Object} visibilityConstraints`: exposed on `InteractiveMap`
|
||||
A set of constraints to keep map visible. This automatically takes care of toggling
|
||||
`visible` on the `StaticMap` layer underneath. See
|
||||
[Source Code](https://github.com/uber/react-map-gl/blob/master/src/components/interactive-map.js#L79)
|
||||
for more information.
|
||||
|
||||
## New API
|
||||
|
||||
- `queryRenderedFeatures`: exposed on `StaticMap` and `InteractiveMap`
|
||||
- **Latest Mapbox GL JS**: Bumps `Mapbox GL JS` to the [latest version](https://github.com/mapbox/mapbox-gl-js/releases) and enables us to stay in sync with future versions.
|
||||
|
||||
## Deprecations
|
||||
|
||||
- **Property Names** - some prop names have been modernized, the old ones will still work for now with a warning.
|
||||
- **Internal Properties** such as `isHovering` and `isDragging` have been removed.
|
||||
- **Internal Properties** such as `isHovering`, `isDragging`, `startDragLngLat` have been removed.
|
||||
These were never meant to be useful publicly and have caused confusions in the past.
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
- **Overlay Support** - Three overlays (`ScatterplotOverlay`, `DraggablePointsOverlay`, `ChoroplethOverlay`), ... are now only provided as examples.
|
||||
- **fitBounds**: `fitBounds` has been rewritten to provide a better interface.
|
||||
- **fitBounds**: `fitBounds` has been moved to another repository, [viewport-mercator-project](https://github.com/uber-common/viewport-mercator-project).
|
||||
It is also rewritten to provide a better interface.
|
||||
|
||||
For more information, see `Upgrade Guide`.
|
||||
|
||||
|
||||
@ -23,6 +23,12 @@ export default class Header extends Component {
|
||||
rel="noopener noreferrer">
|
||||
Github <i style={{marginLeft: 2}} className="icon icon-github" />
|
||||
</a>
|
||||
<a
|
||||
href="https://github.com/mapbox/mapbox-gl-js"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer">
|
||||
Mapbox GL JS <i style={{marginLeft: 2}} className="icon icon-github" />
|
||||
</a>
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
@ -9,7 +9,7 @@ export default class Home extends Component {
|
||||
<section id="banner" style={{backgroundImage: 'url(images/hero.jpg)'}}>
|
||||
<div className="container soft">
|
||||
<h1>react-map-gl</h1>
|
||||
<p>A React port of Mapbox GL JS</p>
|
||||
<p>React components for Mapbox GL JS</p>
|
||||
<a href="#/documentation/getting-started" className="btn">Get started</a>
|
||||
</div>
|
||||
</section>
|
||||
@ -36,21 +36,22 @@ export default class Home extends Component {
|
||||
Component Library
|
||||
</h3>
|
||||
<p>
|
||||
react-map-gl comes with additional React component that
|
||||
synchronize with the map camera system.
|
||||
react-map-gl comes with additional React components that
|
||||
synchronize with the map camera system. Use one of the supported
|
||||
overlays to visualize data, or build your own.
|
||||
</p>
|
||||
|
||||
<h3>
|
||||
<img src="images/icon-high-precision.svg" />
|
||||
Perfect Companion to deck.gl
|
||||
Part of Uber Visualization's Framework Suite
|
||||
</h3>
|
||||
<p>
|
||||
deck.gl is a great match with React, supporting
|
||||
efficient WebGL rendering under the Reactive programming
|
||||
paradigm. And when used with Mapbox GL it automatically
|
||||
coordinates with the Mapbox camera system to provide
|
||||
compelling 2D and 3D visualizations on top of your Mapbox
|
||||
based maps.
|
||||
Use together with e.g. <a
|
||||
href="https://github.com/uber/react-map-gl"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer">
|
||||
deck.gl</a> to render performant and compelling 2D and 3D
|
||||
WebGL visualizations on top of your Mapbox GL JS based maps.
|
||||
</p>
|
||||
|
||||
</div>
|
||||
|
||||
@ -39,10 +39,10 @@ const docPages = {
|
||||
pageComponent: PagesComponent,
|
||||
paths: generatePath([
|
||||
{
|
||||
name: 'Overview',
|
||||
name: 'Introduction',
|
||||
children: [
|
||||
{
|
||||
name: 'Overview',
|
||||
name: 'Introduction',
|
||||
content: getDocUrl('README.md')
|
||||
},
|
||||
{
|
||||
@ -62,31 +62,36 @@ const docPages = {
|
||||
name: 'Get Started',
|
||||
content: getDocUrl('get-started/README.md')
|
||||
},
|
||||
{
|
||||
name: 'About Mapbox Tokens',
|
||||
content: getDocUrl('get-started/mapbox-tokens.md')
|
||||
},
|
||||
{
|
||||
name: 'Using with Redux',
|
||||
content: getDocUrl('get-started/using-with-redux.md')
|
||||
},
|
||||
{
|
||||
name: 'Using with Isomorphic Rendering',
|
||||
content: getDocUrl('get-started/using-with-isomorphic-rendering.md')
|
||||
},
|
||||
{
|
||||
name: 'About Mapbox Tokens',
|
||||
content: getDocUrl('get-started/mapbox-tokens.md')
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
name: 'Components',
|
||||
name: 'API Reference',
|
||||
children: [
|
||||
// NOTE: Keep this ordered Alphabetically
|
||||
{
|
||||
name: 'Static Map',
|
||||
content: getDocUrl('components/static-map.md')
|
||||
name: 'CanvasOverlay',
|
||||
content: getDocUrl('overlays/canvas-overlay.md')
|
||||
},
|
||||
{
|
||||
name: 'HTMLOverlay',
|
||||
content: getDocUrl('overlays/html-overlay.md')
|
||||
},
|
||||
{
|
||||
name: 'Interactive Map',
|
||||
content: getDocUrl('components/interactive-map.md')
|
||||
},
|
||||
{
|
||||
name: 'Marker',
|
||||
content: getDocUrl('components/marker.md')
|
||||
},
|
||||
{
|
||||
name: 'Navigation Control',
|
||||
content: getDocUrl('components/navigation-control.md')
|
||||
@ -96,26 +101,13 @@ const docPages = {
|
||||
content: getDocUrl('components/popup.md')
|
||||
},
|
||||
{
|
||||
name: 'Marker',
|
||||
content: getDocUrl('components/marker.md')
|
||||
name: 'Static Map',
|
||||
content: getDocUrl('components/static-map.md')
|
||||
},
|
||||
]
|
||||
},
|
||||
{
|
||||
name: 'Overlays',
|
||||
children: [
|
||||
{
|
||||
name: 'SVGOverlay',
|
||||
content: getDocUrl('overlays/svg-overlay.md')
|
||||
},
|
||||
{
|
||||
name: 'CanvasOverlay',
|
||||
content: getDocUrl('overlays/canvas-overlay.md')
|
||||
},
|
||||
{
|
||||
name: 'HTMLOverlay',
|
||||
content: getDocUrl('overlays/html-overlay.md')
|
||||
},
|
||||
]
|
||||
},
|
||||
{
|
||||
|
||||
@ -4,16 +4,16 @@
|
||||
<title>react-map-gl</title>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<meta name="description" content="deck.gl is a WebGL-powered framework for visual exploratory data analysis of large datasets.">
|
||||
<meta name="description" content="react-map-gl is a suite of React components for Mapbox GL JS">
|
||||
|
||||
<link rel="icon" type="img/ico" href="favicon.ico">
|
||||
<link rel="stylesheet" id="font-link" href="https://d1a3f4spazzrp4.cloudfront.net/uber-fonts/3.1.0/refresh.css">
|
||||
|
||||
<!-— facebook open graph tags -->
|
||||
<meta property="og:url" content="https://uber.github.io/deck.gl/" />
|
||||
<meta property="og:title" content="Large-scale WebGL-powered Data Visualization" />
|
||||
<meta property="og:description" content="deck.gl is a WebGL-powered framework for visual exploratory data analysis of large datasets." />
|
||||
<meta property="og:site_name" content="deck.gl" />
|
||||
<meta property="og:url" content="https://uber.github.io/react-map-gl/" />
|
||||
<meta property="og:title" content="React components for Mapbox GL JS" />
|
||||
<meta property="og:description" content="react-map-gl is a suite of React components for Mapbox GL JS" />
|
||||
<meta property="og:site_name" content="react-map-gl" />
|
||||
<meta property="og:image" content="https://uber.github.io/deck.gl/images/trips-layer-unfurl-4.0.jpg" />
|
||||
<meta property="og:image:type" content="image/jpeg" />
|
||||
<meta property="og:image:width" content="800" />
|
||||
@ -23,8 +23,8 @@
|
||||
<meta name="twitter:card" content="summary_large_image">
|
||||
<meta name="twitter:site" content="@uber">
|
||||
<meta name="twitter:creator" content="@uber">
|
||||
<meta name="twitter:title" content="Large-scale WebGL-powered Data Visualization">
|
||||
<meta name="twitter:description" content="deck.gl is a WebGL-powered framework for visual exploratory data analysis of large datasets.">
|
||||
<meta name="twitter:title" content="React components for Mapbox GL JS">
|
||||
<meta name="twitter:description" content="react-map-gl is a suite of React components for Mapbox GL JS">
|
||||
<meta name="twitter:image" content="https://uber.github.io/deck.gl/images/trips-layer-unfurl-4.0.jpg" />
|
||||
|
||||
<script>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user