136 lines
5.2 KiB
Markdown
136 lines
5.2 KiB
Markdown
# svg.panzoom.js
|
|
|
|
> A plugin for [svg.js](https://github.com/svgdotjs/svg.js) that enables panzoom for svg elements
|
|
|
|
## Getting started
|
|
|
|
```
|
|
npm install @svgdotjs/svg.js @svgdotjs/svg.panzoom.js
|
|
```
|
|
|
|
Include this plugin after including the svg.js library in your html document.
|
|
|
|
```
|
|
<script src="node_modules/@svgdotjs/svg.js/dist/svg.js"></script>
|
|
<script src="node_modules/@svgdotjs/svg.panzoom.js/dist/svg.panzoom.js"></script>
|
|
```
|
|
|
|
Or for esm just import it:
|
|
|
|
```
|
|
import { SVG } from '@svgdotjs/svg.js'
|
|
import '@svgdotjs/svg.panzoom.js'
|
|
```
|
|
|
|
To enable pan/zoom on an svg:
|
|
|
|
```js
|
|
// enables panZoom
|
|
var canvas = SVG()
|
|
.addTo('#id')
|
|
.size(1000, 1000)
|
|
.panZoom()
|
|
|
|
// zoom programatically
|
|
canvas.zoom(lvl, point)
|
|
```
|
|
|
|
You can configure `panZoom` by passing options to it.
|
|
|
|
- zoomMin: Minimal zoom level
|
|
- zoomMax: Maximal zoom level
|
|
- zoomFactor: How much is zoomed by one mouse wheel step
|
|
|
|
This could look like this:
|
|
|
|
```js
|
|
var canvas = SVG()
|
|
.addTo('#id')
|
|
.size(1000, 1000)
|
|
.panZoom({ zoomMin: 0.5, zoomMax: 20 })
|
|
```
|
|
|
|
Setting the min and max value will automatically restrict the zoom to the provided level.
|
|
However you are still able to change the zoom out of that bonds by calling `zoom(lvl)` programatically.
|
|
|
|
On touchable devices a pinchZoom gesture is supported. Min and max values also apply here.
|
|
|
|
Zooming is animatable, too:
|
|
|
|
```js
|
|
canvas
|
|
.zoom(1) // uses center of viewport by default
|
|
.animate()
|
|
.zoom(2, { x: 100, y: 100 }) // zoom into specified point
|
|
```
|
|
|
|
To disable `panZoom` or change its options just call it again with `false` or the new options.
|
|
|
|
## Options
|
|
|
|
You can override the default options by passing an object in to the `.panZoom({options})` call.
|
|
|
|
| Option | Default | Description |
|
|
| ------------ | ---------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
| panning | true | Enable panning |
|
|
| pinchZoom | true | Enable pinch to zoom |
|
|
| wheelZoom | true | Enable mouse wheel zoom |
|
|
| panButton | 0 | Which mouse button to use for pan ([info](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent/button)) |
|
|
| oneFingerPan | false | Enables the ability to pan with only one finger instead of two for touchdevices |
|
|
| margins | false | An object {top, left, right, bottom} to restrict the pan area towards this side so that at least x user units of the opposite side are still visible |
|
|
| zoomFactor | 2 | How quickly to zoom when using `wheelZoom` |
|
|
| zoomMin | Number.MIN_VALUE | The minimum zoom level |
|
|
| zoomMax | Number.MAX_VALUE | The maximum zoom level |
|
|
| wheelZoomDeltaModeLinePixels | 17 | The multiplier to convert wheel zoom deltaY values from deltaMode=1 (lines) to deltaMode=0 (pixels) |
|
|
| wheelZoomDeltaModeScreenPixels | 53 | The multiplier to convert wheel zoom deltaY values from deltaMode=2 (screen) to deltaMode=0 (pixels) |
|
|
|
|
### Example:
|
|
|
|
```js
|
|
draw.panZoom({
|
|
wheelZoom: false,
|
|
zoomMin: 0.5,
|
|
zoomMax: 2
|
|
})
|
|
```
|
|
|
|
This will disable wheel zooming and set the maximum zoom to 2 or 200% and the minimum zoom to 0.5 or 50%.
|
|
|
|
## Events
|
|
|
|
Multiple events are fired doing different actions. This allow you to respond
|
|
to actions and in some cases stop an action via `preventDefault()`.
|
|
|
|
`zoom` is fired when a mouse wheel event or programmable `zoom()` triggers
|
|
a zoom. This usually doesn't happen on mobile devices, in which case
|
|
`pinchZoomStart` is fired when a zoom happens.
|
|
|
|
Events fired from SVG.js are [`CustomEvent`s](http://devdocs.io/dom/customevent),
|
|
so the arguments passed from svg.panzoom.js are in in the `.detail` property.
|
|
|
|
| Event Name | Argument Value | preventDefault support |
|
|
| -------------- | ---------------- | ---------------------- |
|
|
| zoom | `{ lvl, focus }` | YES |
|
|
| panStart | `{ event }` | NO |
|
|
| panEnd | `{ event }` | NO |
|
|
| panning | `{ box }` | YES |
|
|
| pinchZoomStart | `{ event }` | YES |
|
|
| pinchZoomEnd | `{ event }` | NO |
|
|
|
|
Where `lvl` is the new zoom level,
|
|
[`focus`](https://svgjs.com/docs/3.0/classes/#svg-point) is th point of zoom, [`box`](https://svgjs.com/docs/3.0/classes/#svg-box) is the new calculated viewbox
|
|
and event is the event that triggered the action.
|
|
|
|
An example of stopping a pinch-zoom action:
|
|
|
|
```js
|
|
var canvas = SVG()
|
|
.addTo('#id')
|
|
.size(1000, 1000)
|
|
.panZoom()
|
|
|
|
canvas.on('pinchZoomStart', function (ev) {
|
|
ev.preventDefault()
|
|
// ...
|
|
})
|
|
```
|