@hyper-proto/iv-viewer 2.3.3 → 3.2.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +82 -50
- package/dist/iv-viewer.es.js +1 -1
- package/dist/iv-viewer.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
# iv-viewer
|
|
2
|
+
|
|
2
3
|
[](#contributors-)
|
|
3
4
|
A zooming and panning plugin inspired by google photos for your web images.
|
|
4
5
|
|
|
5
6
|
### Features
|
|
7
|
+
|
|
6
8
|
<ul>
|
|
7
9
|
<li>Smooth dragging and panning of images.</li>
|
|
8
10
|
<li>Support touch devices.</li>
|
|
@@ -14,10 +16,12 @@ A zooming and panning plugin inspired by google photos for your web images.
|
|
|
14
16
|
<li>Custom Events to listen for the state changes.</li>
|
|
15
17
|
</ul>
|
|
16
18
|
|
|
17
|
-
|
|
18
20
|
|
|
19
21
|
### Install
|
|
22
|
+
|
|
20
23
|
Through npm
|
|
24
|
+
|
|
21
25
|
```
|
|
22
26
|
npm install iv-viewer --save
|
|
23
27
|
```
|
|
@@ -25,38 +29,45 @@ npm install iv-viewer --save
|
|
|
25
29
|
Or get compiled development and production version (css and js) from ./dist
|
|
26
30
|
|
|
27
31
|
### Usage
|
|
32
|
+
|
|
28
33
|
Import ImageViewer and it's style.
|
|
34
|
+
|
|
29
35
|
```js
|
|
30
|
-
import ImageViewer from
|
|
36
|
+
import ImageViewer from "iv-viewer";
|
|
31
37
|
|
|
32
38
|
// or
|
|
33
|
-
const ImageViewer = require(
|
|
39
|
+
const ImageViewer = require("iv-viewer").default;
|
|
34
40
|
|
|
35
41
|
// Import css
|
|
36
|
-
import
|
|
42
|
+
import "iv-viewer/dist/iv-viewer.css";
|
|
37
43
|
```
|
|
44
|
+
|
|
38
45
|
You can choose to import css file inside your scss/less files.
|
|
39
46
|
|
|
40
47
|
You can also use the standalone UMD build by including dist/iv-viewer.js and dist/iv-viewer.css in your page.
|
|
48
|
+
|
|
41
49
|
```html
|
|
42
50
|
<script src="https://unpkg.com/iv-viewer/dist/iv-viewer.js"></script>
|
|
43
51
|
|
|
44
|
-
<link rel="stylesheet" href="https://unpkg.com/iv-viewer/dist/iv-viewer.css"
|
|
52
|
+
<link rel="stylesheet" href="https://unpkg.com/iv-viewer/dist/iv-viewer.css" />
|
|
45
53
|
```
|
|
46
54
|
|
|
47
55
|
### Three different modes
|
|
48
56
|
|
|
49
57
|
#### Full-Screen Mode
|
|
50
|
-
|
|
58
|
+
|
|
59
|
+
If you want to show images in full screen, with predefined styles. You can use FullScreenViewer.
|
|
60
|
+
|
|
51
61
|
```js
|
|
52
|
-
import { FullScreenViewer } from
|
|
62
|
+
import { FullScreenViewer } from "iv-viewer";
|
|
53
63
|
|
|
54
64
|
const viewer = new FullScreenViewer(options); // check options section for supported options
|
|
55
65
|
|
|
56
|
-
viewer.show(
|
|
66
|
+
viewer.show("images/low-res-img", "images/hi-res-img"); //second option is optional. Check better image loading section
|
|
57
67
|
```
|
|
58
68
|
|
|
59
69
|
#### Container Mode
|
|
70
|
+
|
|
60
71
|
If you have your own container to show images (you might have custom layout or gallery), you can use image-viewer in a container mode.
|
|
61
72
|
|
|
62
73
|
```html
|
|
@@ -64,91 +75,102 @@ If you have your own container to show images (you might have custom layout or g
|
|
|
64
75
|
```
|
|
65
76
|
|
|
66
77
|
```js
|
|
67
|
-
import ImageViewer from
|
|
78
|
+
import ImageViewer from "iv-viewer";
|
|
68
79
|
|
|
69
|
-
const container = document.querySelector(
|
|
80
|
+
const container = document.querySelector("#image-container");
|
|
70
81
|
const viewer = new ImageViewer(container, options); //check options section for supported options
|
|
71
82
|
|
|
72
|
-
viewer.load(
|
|
83
|
+
viewer.load("images/low-res-img", "images/hi-res-img"); //second option is optional. Check better image loading section
|
|
73
84
|
```
|
|
74
85
|
|
|
75
86
|
#### Image Mode
|
|
87
|
+
|
|
76
88
|
If you just want to add zoom and pan gesture to your images in a image-viewer style, you can use image-viewer in image mode.
|
|
89
|
+
|
|
77
90
|
```html
|
|
78
91
|
<img id="image" src="image.png" data-high-res-src="hi-res-image.png" />
|
|
79
92
|
```
|
|
80
93
|
|
|
81
94
|
```js
|
|
82
|
-
import ImageViewer from
|
|
95
|
+
import ImageViewer from "iv-viewer";
|
|
83
96
|
|
|
84
|
-
const image = document.querySelector(
|
|
97
|
+
const image = document.querySelector("#image");
|
|
85
98
|
const viewer = new ImageViewer(image, options); // check options section for supported options
|
|
86
99
|
```
|
|
87
100
|
|
|
88
101
|
### Options
|
|
89
|
-
|
|
90
|
-
|
|
|
91
|
-
|
|
|
92
|
-
|
|
|
93
|
-
|
|
|
94
|
-
|
|
|
95
|
-
|
|
|
96
|
-
|
|
|
97
|
-
|
|
|
98
|
-
|
|
|
102
|
+
|
|
103
|
+
| Option | Allowed Value | Default | Description |
|
|
104
|
+
| ---------------- | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
105
|
+
| zoomValue | number in percentage | 100 | It defines the initial zoom value of the image. |
|
|
106
|
+
| maxZoom | number in percentage | 500 | It defines the max limit for the zoom value of the image. |
|
|
107
|
+
| snapView | boolean | true | If true will show snap view. |
|
|
108
|
+
| refreshOnResize | boolean | true | Defines whether to refresh the viewer on resize of window. This is available only for Container and Image mode. On FullScreen mode it will refresh on window resize by default. |
|
|
109
|
+
| zoomOnMouseWheel | boolean | true | Defines weather to allow zoom with mouse scroll or not. |
|
|
110
|
+
| hasZoomButtons | boolean | true | Defines weather to add zoom buttons or not |
|
|
111
|
+
| zoomStep | number | 50 | The number of which the zoom should increase/decrease when the buttons are clicked |
|
|
112
|
+
| listeners | object | null | multiple useful callbacks that could use in-order to get the current state of the viewer |
|
|
99
113
|
|
|
100
114
|
### The Listeners
|
|
115
|
+
|
|
101
116
|
There are multiple listeners you can register with each viewer instance
|
|
117
|
+
|
|
102
118
|
```js
|
|
103
|
-
import ImageViewer from
|
|
119
|
+
import ImageViewer from "iv-viewer";
|
|
104
120
|
|
|
105
|
-
const viewer = new ImageViewer(element, {
|
|
106
|
-
listeners: {
|
|
107
|
-
onInit: callback(data), // called when the instance is initiated
|
|
121
|
+
const viewer = new ImageViewer(element, {
|
|
122
|
+
listeners: {
|
|
123
|
+
onInit: callback(data), // called when the instance is initiated
|
|
108
124
|
onDestroy: callback(), // called when the instance is destroyed
|
|
109
125
|
onImageLoaded: callback(data), // called on image load
|
|
110
126
|
onZoomChange: callback(data), // called on zoom in/out
|
|
111
|
-
}
|
|
127
|
+
},
|
|
112
128
|
});
|
|
113
129
|
```
|
|
130
|
+
|
|
114
131
|
### Callback Data
|
|
132
|
+
|
|
115
133
|
The data passed to each callback is very useful, it contains the current instance with more info that you can use to react to the instance state
|
|
116
134
|
|
|
117
|
-
| Option
|
|
118
|
-
|
|
|
119
|
-
| container
|
|
120
|
-
| snapView
|
|
121
|
-
| zoomValue
|
|
122
|
-
| reachedMin | boolean
|
|
123
|
-
| reachedMax | boolean
|
|
124
|
-
| instance
|
|
135
|
+
| Option | dataType | Description |
|
|
136
|
+
| ---------- | ----------- | -------------------------------------------------------------------------- |
|
|
137
|
+
| container | HTMLElement | The current container of the viewer |
|
|
138
|
+
| snapView | HTMLElement | The snap view element in the viewer |
|
|
139
|
+
| zoomValue | Number | The current zoom value |
|
|
140
|
+
| reachedMin | boolean | A boolean value that determine if the zoom value reached the initial zoom. |
|
|
141
|
+
| reachedMax | boolean | A boolean value that determine if the zoom value reached the maximum zoom. |
|
|
142
|
+
| instance | ImageViewer | The current instance which contains all other info if needed |
|
|
125
143
|
|
|
126
144
|
### API (ImageViewer)
|
|
127
145
|
|
|
128
146
|
Creating an instance
|
|
129
147
|
|
|
130
148
|
```js
|
|
131
|
-
import ImageViewer from
|
|
149
|
+
import ImageViewer from "iv-viewer";
|
|
132
150
|
|
|
133
151
|
const viewer = new ImageViewer(element, options);
|
|
134
152
|
```
|
|
153
|
+
|
|
135
154
|
Here the first argument is the element, which can be container where viewer will be loaded, or it can be a image in which case viewer will be initialized in a image mode.
|
|
136
155
|
|
|
137
156
|
You can also pass a selector directly instead of a DOM element.
|
|
157
|
+
|
|
138
158
|
```js
|
|
139
|
-
const viewer = new ImageViewer(
|
|
159
|
+
const viewer = new ImageViewer("#element", options);
|
|
140
160
|
```
|
|
141
161
|
|
|
142
162
|
Second argument is to provide configuration options for the ImageViewer. This argument is optional.
|
|
143
163
|
|
|
144
164
|
#### Instance methods
|
|
165
|
+
|
|
145
166
|
**load(imgSrc, highResImg)**
|
|
146
167
|
|
|
147
|
-
Load an image to the viewer. You can pass two different resolution of the image as first and second argument (optional). See why do you need it at [better image loading](#better-image-loading) section.
|
|
168
|
+
Load an image to the viewer. You can pass two different resolution of the image as first and second argument (optional). See why do you need it at [better image loading](#better-image-loading) section.
|
|
148
169
|
|
|
149
170
|
```js
|
|
150
|
-
viewer.load(
|
|
171
|
+
viewer.load("image.png", "hi-res-image.png");
|
|
151
172
|
```
|
|
173
|
+
|
|
152
174
|
Note that this is just required for the container mode, as in image mode you can just use `src` and `data-high-res-src` attribute and the image will load by itself. See [image mode](#image-mode) example
|
|
153
175
|
|
|
154
176
|
**zoom(zoomValue, point)**
|
|
@@ -172,6 +194,7 @@ viewer.resetZoom();
|
|
|
172
194
|
**refresh()**
|
|
173
195
|
|
|
174
196
|
Method to manually refresh the viewer. It will reset the zoom and pan. It will also recalculate the dimension of container, window and image in case if that is changed.
|
|
197
|
+
|
|
175
198
|
```js
|
|
176
199
|
viewer.refresh();
|
|
177
200
|
```
|
|
@@ -179,59 +202,68 @@ viewer.refresh();
|
|
|
179
202
|
**destroy()**
|
|
180
203
|
|
|
181
204
|
Destroys the plugin instance and unbind all events. It will also reset the container or the image(if ImageViewer is used in image mode). It returns null which you should assign to viewer variable to completely free up memory.
|
|
205
|
+
|
|
182
206
|
```js
|
|
183
207
|
viewer = viewer.destroy();
|
|
184
208
|
```
|
|
185
209
|
|
|
186
210
|
### API (FullScreenViewer)
|
|
211
|
+
|
|
187
212
|
FullScreenViewer is extended from ImageViewer. So it shares the same ImageViewer api along with some FullScreenViewer API.
|
|
188
213
|
|
|
189
214
|
Creating an instance
|
|
190
215
|
|
|
191
216
|
```js
|
|
192
|
-
import { FullScreenViewer } from
|
|
217
|
+
import { FullScreenViewer } from "iv-viewer";
|
|
193
218
|
|
|
194
219
|
const viewer = new FullScreenViewer(options);
|
|
195
220
|
```
|
|
221
|
+
|
|
196
222
|
Unlike ImageViewer you don't have to pass container for the viewer as it will be initialized in pre-defined full screen container.
|
|
197
223
|
|
|
198
224
|
First argument is to provide configuration options for the FullScreenViewer. This argument is optional.
|
|
199
225
|
|
|
200
226
|
#### Instance methods (FullScreenViewer)
|
|
227
|
+
|
|
201
228
|
FullScreenViewer inherits all the instance method of ImageViewer. In additional to that it has following methods.
|
|
202
229
|
|
|
203
230
|
**show(imgSrc, highResImg)**
|
|
204
231
|
|
|
205
|
-
Show the full screen viewer with passed image on the show method. You can pass two different resolution of the image as first and second argument (optional). See why do you need it at [better image loading](#better-image-loading) section.
|
|
232
|
+
Show the full screen viewer with passed image on the show method. You can pass two different resolution of the image as first and second argument (optional). See why do you need it at [better image loading](#better-image-loading) section.
|
|
206
233
|
|
|
207
234
|
```js
|
|
208
|
-
viewer.show(
|
|
235
|
+
viewer.show("image.png", "hi-res-image.png");
|
|
209
236
|
```
|
|
210
237
|
|
|
211
238
|
**hide()**
|
|
212
239
|
|
|
213
|
-
Hide/Close the fullScreen viewer.
|
|
240
|
+
Hide/Close the fullScreen viewer.
|
|
241
|
+
|
|
214
242
|
```js
|
|
215
243
|
viewer.hide();
|
|
216
244
|
```
|
|
217
245
|
|
|
218
246
|
### Better image loading
|
|
219
|
-
|
|
247
|
+
|
|
248
|
+
To improve the perceived experience, it is always recommended to show the already loaded image or the low quality image on the viewer and let the ImageViewer load high quality image in parallel.
|
|
220
249
|
|
|
221
250
|
It will also try to preview the high quality image while it's loading so it will give a progressive loading effect.
|
|
222
251
|
|
|
223
|
-
ImageViewer provides api to do this.
|
|
252
|
+
ImageViewer provides api to do this.
|
|
224
253
|
Container mode
|
|
254
|
+
|
|
225
255
|
```js
|
|
226
|
-
viewer.load(
|
|
256
|
+
viewer.load("image.png", "hi-res-image.png");
|
|
227
257
|
```
|
|
228
258
|
|
|
229
259
|
FullScreen mode
|
|
260
|
+
|
|
230
261
|
```js
|
|
231
|
-
viewer.show(
|
|
262
|
+
viewer.show("image.png", "hi-res-image.png");
|
|
232
263
|
```
|
|
233
264
|
|
|
234
265
|
Image Mode
|
|
266
|
+
|
|
235
267
|
```html
|
|
236
268
|
<img id="image" src="image.png" data-high-res-src="hi-res-image.png" />
|
|
237
269
|
```
|
|
@@ -241,9 +273,9 @@ In all of the above example it will first try to display the first image and the
|
|
|
241
273
|
The second image is optional, which you should pass when you feel you can improve the image loading experience by first showing low quality image and then progressively update it with high quality image.
|
|
242
274
|
|
|
243
275
|
### Demo
|
|
276
|
+
|
|
244
277
|
codesandbox preview link: [https://8ypwzryom0.codesandbox.io/](https://8ypwzryom0.codesandbox.io/)
|
|
245
278
|
|
|
246
279
|
codesandbox link: [https://codesandbox.io/s/8ypwzryom0](https://codesandbox.io/s/8ypwzryom0)
|
|
247
280
|
|
|
248
|
-
|
|
249
|
-
[See full documentation of iv-viewer](https://s-yadav.github.io/iv-viewer/docs/category/iv-viewer)
|
|
281
|
+
[See full documentation of iv-viewer](https://s-yadav.github.io/iv-viewer/docs/category/iv-viewer)
|
package/dist/iv-viewer.es.js
CHANGED
package/dist/iv-viewer.js
CHANGED
package/package.json
CHANGED