search

TimUnderhay / ngx-panzoom

Pan/Zoom library for Angular
74 stars 24 forks source link

readme

ngx-panzoom

An Angular component for panning and zooming an element or elements using the mouse and mousewheel. Provides rudimentary support for touchscreens (read section on mobile support). It was adapted from the angular-pan-zoom library for AngularJS, but it has been heavily modified. Many thanks go out to Martin Vindahl Olsen for having written it, and for his blessing in this undertaking.

It is built using Angular CLI 13.x in partial Ivy compilation mode. It is therefore no longer compatible with legacy Angular version which are still using the View Engine. It is only tested with the corresponding version of Angular.

This library deliberately parts with certain received Angular wisdom of using only Angular-ish methods to accomplish things. We use native event listeners. We apply CSS transforms directly to the DOM. But as this library doesn't fit the traditional Angular model, as its purpose is only to apply CSS transforms to a certain part of the DOM, without moving or changing anything else, it has no impact on an application's state (except if the app consumes modelChanged observables). By using this approach, it is hoped that compatibility and performance will be maximised.

This Module is on Life Support -- New Maintainer Needed!

Doubtless many will have noticed that there has been little by way of support for this library as of late. Sadly, other life priorities just don't allow the time for it, and that doesn't seem likely to change in the near future. If there is some brave soul out there would like to take over the maintenance of this module, please do contact me and I'll be happy to discuss it with you.

Demo

Click here for a demo of the module. The demo source can be found here.

Features

Version 18.x Changes

Version 17.x Changes

Version 16.x Changes

Version 15.x Changes

Version 14.x Changes

Version 13.x Changes

Version 12.x Changes

Version 12 Potentially Breaking Changes

Version 11.x Changes

Version 10.x Changes

Version 10.x is compiled using Angular 10.x. Per the Angular guidance at the time of writing (https://angular.io/guide/creating-libraries), Ivy is not used for the NPM repo build. The following changes have been made:

Version 10 Potentially Breaking Changes

Differences From the Original

Dependencies

Mobile Support -- Actively Soliciting PR's

I am actively soliciting pull requests for mobile support. Read on.

The library implements some basic support that may work with some mobile devices, though pinch-to-zoom still needs considerable work. As the application that this library was developed for was never intended for use with mobile devices, there are no plans to implement full mobile support. As long as this remains the case, I respecfully ask for no more issues concerning mobile support, please. I realise that this will limit adoption, but for an enterprising developer out there, I can't imagine that adding mobile support would be nearly as big of a challenge as it was to port the library to Angular from AngularJS!

Installation

npm install ngx-panzoom --save

app.module.ts:

import { NgxPanZoomModule } from 'ngx-panzoom';

@NgModule({
  imports: [  ...,
              NgxPanZoomModule
           ],
  ...
})

export class MyAppModule { }

Usage

This library exposes a component called 'pan-zoom', under which you may place any standard Angular template code. Though the events which trigger panning and zooming are run outside of Angular and thus themselves will not trigger change detection, it should not break change detection for any sub-components.

A configuration object is required, which gets passed in using [config]="myConfig".

It also exposes an API which can be used to interact with the pan/zoom view. The API is obtained through the configuration object (more below).

Top Tip

Be sure to place your pan-zoom component underneath an element with a definite height/width, like an absolute-positioned div. You may not see anything if you don't do this.

import { PanZoomConfig, PanZoomAPI, PanZoomModel, PanZoomConfigOptions } from 'ngx-panzoom';

@Component({
  selector: 'my-component'
  template: `

    <div style="position: absolute; top: 100px; bottom: 0; left: 0; right: 0;">

      <pan-zoom [config]="panZoomConfig">

        <div style="position: relative;">

          <img src="https://github.com/TimUnderhay/ngx-panzoom/raw/master/myimage1.jpg">

        </div>

      </pan-zoom>

    </div>
  `
})

export class MyComponent {
  ...
  panZoomConfig: PanZoomConfig = new PanZoomConfig();
  ...
}

Configuration

You must first create and then pass in a configuration object (of type PanZoomConfig) via the config input property. This configuration object also contains RXJS Observables which can be used to work with the API and also observe changes to the panzoom view. The parameters can either be passed in as a PanZoomConfigOptions object, or set after the creation of the PanZoomConfig instance.

panZoomConfig: PanZoomConfig = new PanZoomConfig(options?: PanZoomConfigOptions);

The following attributes are defined:

Name Type Default Description
api BehaviorSubject\<PanZoomAPI> Not Applicable Subscribe to this observable to obtain access to the API for controlling panzoom programattically. See section below on getting at the API.
zoomLevels number 5 Number of discrete zoom levels, each one representing a scale. The higher the number, the more zoomed in it is.
neutralZoomLevel number 2 The zoom level at which the contents render at 1:1 scale.
scalePerZoomLevel number 2.0 The difference in actual scale between two adjacent zoom levels.
initialZoomLevel number neutralZoomLevel The initially selected zoom level.
initialPanX number 0 The initial pan in the horizontal direction.
initialPanY number 0 The initial pan in the vertical direction.
initialZoomToFit rectangle null When defined, will initially zoom to fit the given rectangle (see API for explanation of zoom to fit). This overrides the initialZoomLevel, initialPanX, and initialPanY values.
zoomToFitZoomLevelFactor number 0.95 A number to indicate how closely zoom to fit will work. 1.0 is a perfect fit. Lowering the number will reveal a bit of the surrounding contents.
zoomOnDoubleClick boolean true Enable or disable zooming in on double click.
zoomButtonIncrement number 1.0 The number of zoom levels to zoom on double click.
zoomStepDuration number 0.2 Number of seconds to animate between two adjacent zoom levels.
zoomOnMouseWheel boolean true Enable or disable zoom in/out on mouse wheel.
invertMouseWheel boolean false Invert the behaviour of the mouse wheel (or two finger trackpad gesture).
freeMouseWheel boolean true By setting this to true, the mouse wheel will freely zoom the view without respect to discreet zoom levels. With false, moving the mouse wheel will zoom the view by zoomButtonIncrement.
freeMouseWheelFactor number 0.08 How much to zoom the view with every tick of the wheel, if using freeMouseWheel.
friction number 10.0 Constant which controls the friction when dragging and then letting go. The higher the number, the more quickly the animation will come to a stop.
haltSpeed number 100.0 Constant which controls when the pan animation has slowed down enough to be terminated. The lower the number, the longer it will take to come to a stop.
panOnClickDrag boolean true Enable or disable pan on clicking and dragging the mouse.
modelChanged BehaviorSubject<PanZoomModel> Not Applicable An RXJS observable which can be subscribed to in order to observe changes to the panzoom view. The model will be passed to the callback function.
keepInBounds boolean false When true, it will not be possible to pan the contents off the screen -- it will snap back when trying to do so. It will not be possible to zoom further out than the neutral zoom level. REMEMBER that the initial zoom level must either be less than or equal to the neutral zoom level, or weird things will happen.
keepInBoundsRestoreForce number 0.5 Constant to control how quickly the contents snap back into place after attempting to pan out of bounds.
keepInBoundsDragPullback number 0.7 Constant to control the perceived force preventing dragging the contents out of bounds.
dragMouseButton string 'left' Controls which mouse button drags the view. Valid options are left, middle, and right. NOTE: Using middle and right will disable the default 'auxclick' and 'contextmenu' handlers, respectively. ALSO NOTE: Chrome seems to have a bug that doesn't the permit the 'mousemove' event to fire after middle-click drag until it receives a normal left 'click' event. If anyone can shed any light on this, I'd be happy to hear from you. It's such an edge case, though, that I won't be opening a bug report, but feel free to do so if this affects you.
noDragFromElementClass string null If set, this will prevent click-drag on elements who have a parent element containing a specific class name.
acceleratePan boolean true Controls whether the pan frame will be hardware accelerated.
dynamicContentDimensions boolean false If true, a ResizeObserver will be used to detect changes in the content dimensions. Useful if the content dimensions can't be predicted. Alternatively, the API methods detectContentDimensions() or contentDimensionsChanged() can also be used. ResizeObservers may not work in some older or mobile web browsers. See https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver for info on browser compatibility.

API

The panzoom library provides an API for interacting with, observing, and controlling it. The following methods and objects are available from the PanZoomAPI:

PanZoom API Interfaces:

interface PanZoomModel {
  zoomLevel: number;
  isPanning?: boolean;
  pan: Point; // how far the view has been moved on the x and y axes.  It is not adjusted for scale
}

interface Point {
  x: number;
  y: number;
}

interface Rect {
  x: number; // the x0 (top left) coordinate
  y: number; // the y0 (top left) coordinate
  width: number; // the x1 (bottom right) coordinate
  height: number; // the y1 (bottom right) coordinate
}

Getting at the API

The panzoom API is exposed through an RxJS observable as a property of the PanZoomConfig class, named api, to which you simply subscribe to obtain the API object. The subscription callback method will be passed the API as its only parameter, of type PanZoomAPI. Because it uses a BehaviorSubject, the callback will immediately trigger when subscribed to, assuming panzoom has already been initialised. If panzoom hasn't yet been initialised, the subscription callback will fire as soon as initialisation occurs.

import { PanZoomConfig, PanZoomAPI, PanZoomModel } from 'ngx-panzoom';
import { Subscription } from 'rxjs';

@Component({ ... })

export class MyComponent implements OnInit, OnDestroy {

  panZoomConfig: PanZoomConfig = new PanZoomConfig();
  private panZoomAPI: PanZoomAPI;
  private apiSubscription: Subscription;

  ngOnInit(): void {
    this.apiSubscription = this.panzoomConfig.api.subscribe( (api: PanZoomAPI) => this.panZoomAPI = api );
  }

  ngOnDestroy(): void {
    this.apiSubscription.unsubscribe();  // don't forget to unsubscribe.  you don't want a memory leak!
  }

}

Now that we have our API stored in this.panZoomAPI, we can access it thusly:

this.panZoomAPI.zoomIn();
this.panZoomAPI.zoomOut();

'Events'

The PanZoomConfig class has an RXJS observable (modelChanged) which can be used to monitor the pan/zoom state from another component. The observable emits type PanZoomModel (see above section on API Interfaces). For instance, when the zoom level reaches a certain level, you may want to display a custom control or content on your page. Another use may be to do something when the panzoom centre point is over a certain part of the view.

Example modelChanged Subscription

import { PanZoomConfig, PanZoomAPI, PanZoomModel } from 'ngx-panzoom';

@Component({ ... })

export class MyComponent implements OnInit, OnDestroy {

  panZoomConfig: PanZoomConfig = new PanZoomConfig();
  private modelChangedSubscription: Subscription;

  ngOnInit(): void {
    this.modelChangedSubscription = this.panzoomConfig.modelChanged.subscribe( (model: PanZoomModel) => this.onModelChanged(model) );
  }

  ngOnDestroy(): void {
    this.modelChangedSubscription.unsubscribe();  // don't forget to unsubscribe.  you don't want a memory leak!
  }

  onModelChanged(model: PanZoomModel): void {
    // do something after receiving your model update here
  }

}

Contributing

Pull requests are welcome.

Reference

Martin Vindahl Olsen's original angular-pan-zoom project on GitHub