diff --git a/docs/components/interactive-map.md b/docs/components/interactive-map.md index cc536f6a..934aa215 100644 --- a/docs/components/interactive-map.md +++ b/docs/components/interactive-map.md @@ -19,7 +19,7 @@ class Map extends Component { zoom={8} onViewportChange={(viewport) => { const {width, height, latitude, longitude, zoom} = viewport; - // Optionally call `setState` and use the state to update the map. + // call `setState` and use the state to update the map. }} /> ); @@ -116,6 +116,50 @@ Parameters + `state.isDragging` - If the map is being dragged. + `state.isHovering` - If the pointer is over a clickable feature. +##### `transitionDuration` {Number} +Duration of transition in milliseconds. If specified, the map's viewport will smoothly move from the previous props to the current one. Default `0`; + +##### `transitionInterpolator` {Object} +An interpolator object that defines the transition behavior between two map states. `react-map-gl` offers two interpolators: +- `LinearInterpolator` - similar to Mapbox's `easeTo` behavior. +- `FlyToInterpolator` - similar to Mapbox's `flyTo` behavior. + +You may import them as follows: +```jsx +import ReactMapGL, {LinearInterpolator, FlyToInterpolator} from 'react-map-gl'; + + +``` + +Default: `new LinearInterpolator()` + +For details about using transition interpolators, see [transitions](/docs/user-guide/transitions.md). + +##### `transitionEasing` {Function} +Easing function that maps a value from `[0, 1]` to `[0, 1]`. Default to `t => t` (linear). Check out [http://easings.net/](http://easings.net/) for common easing curves. + +##### `transitionInterruption` {Number} +What to do if an ongoing transition is interrupted by another transition. There are 3 options: +- `TRANSITION_EVENTS.BREAK` - Start new transition from the current view. This is the default. +- `TRANSITION_EVENTS.SNAP_TO_END` - Jump to the end of the previous transition before starting the new transition. +- `TRANSITION_EVENTS.IGNORE` - Complete the previous transition and ignore the new viewport change. + +You may import the constants as follows: +``` +import {TRANSITION_EVENTS} from 'react-map-gl'; +``` + +##### `onTransitionStart` {Function} + +Callback that is fired when a transition is triggered. + +##### `onTransitionInterrupt` {Function} +Callback that is fired when an ongoing transition is interrupted by another transition. + +##### `onTransitionEnd` {Function} + +Callback that is fired when a transition is complete. + ## Methods Same methods as [StaticMap](/docs/components/static-map.md). diff --git a/docs/user-guide/transitions.md b/docs/user-guide/transitions.md index 8002ce5b..bf5397ab 100644 --- a/docs/user-guide/transitions.md +++ b/docs/user-guide/transitions.md @@ -1,19 +1,59 @@ -## Transitions +# Transitions -`react-map-gl` does not expose the transition API for `mapbox-gl-js` since it is designed to be a stateless component, and needs to synchronize with separate overlay systems such as deck.gl. +`react-map-gl` does not expose the transition API from `mapbox-gl-js` since it is designed to be a stateless component, and needs to synchronize with separate overlay systems such as deck.gl. -Instead it is recommended to use a separate module like [react-motion](https://github.com/chenglou/react-motion) to animate properties. +Instead, transitions can be defined using [InteractiveMap](/docs/components/interactive-map.md)'s transition props. For example: +```jsx +import ReactMapGL, {LinearInterpolator, FlyToInterpolator} from 'react-map-gl'; +// 3rd-party easing functions +import d3 from 'd3-ease'; -```js - - {({ latitude, longitude }) => } - + transitionDuration={1000} + transitionInterpolator={new FlyToInterpolator()} + transitionEasing={d3.easeCubic} + onTransitionEnd={() => { + // do something + }} > ``` + +See [viewport transition](#examples/viewport-transition) for a complete example. + +## InteractiveMap's Transition Props + +See properties of [InteractiveMap](/docs/components/interactive-map.md). + +- `transitionDuration` {Number} +- `transitionInterpolator` {Object} +- `transitionEasing` {Function} +- `transitionInterruption` {Number} +- `onTransitionStart` {Function} +- `onTransitionInterrupt` {Function} +- `onTransitionEnd` {Function} + +## Transition Interpolators + +A `TransitionInterpolator` instance must be supplied to the `transitionInterpolator` prop. It contains the following methods: +- `arePropsEqual(currentProps, nextProps)` - called to determine if transition should be triggered when viewport props update. +- `initiateProps(startProps, endProps)` - called before transition starts to pre-process the start and end viewport props. +- `interpolateProps(startProps, endProps, t)` - called to get viewport props in transition. `t` is a time factor between `[0, 1]`. + +### `LinearInterpolator` + +Interpolates all viewport props linearly. This interpolator offers similar behavior to Mapbox's `easeTo` when combined with a `transitionEasing` function. You may optionally limit the transition to selected viewport props, for example `new LinearInterpolator(['pitch', 'bearing'])` animates pitch and bearing while the user is still allowed to pan and zoom. + +##### constructor + +`new LinearInterpolator([transitionProps])` + +Parameters: +- `transitionProps` {Array} (optional) - list of prop names to interpolate. Default: `['longitude', 'latitude', 'zoom', 'pitch', 'bearing']`. + +### `FlyToInterpolator` + +This interpolator offers similar behavior to Mapbox's `flyTo` method. + +##### constructor + +`new FlyToInterpolator()` diff --git a/examples/viewport-animation/package.json b/examples/viewport-animation/package.json index 44fa5de6..2d4d3413 100644 --- a/examples/viewport-animation/package.json +++ b/examples/viewport-animation/package.json @@ -7,7 +7,7 @@ "immutable": "^3.8.1", "react": "^16.0.0", "react-dom": "^16.0.0", - "react-map-gl": "^3.1.0", + "react-map-gl": ">=3.2.0-alpha.1", "tween.js": "^16.6.0" }, "devDependencies": {