viewerjs 1.12.0 → 1.14.0

package/README.md

@@ -1,30 +1,30 @@
 # Viewer.js
 
-[![Downloads](https://img.shields.io/npm/dm/viewerjs.svg)](https://www.npmjs.com/package/viewerjs) [![Version](https://img.shields.io/npm/v/viewerjs.svg)](https://www.npmjs.com/package/viewerjs) [![Gzip Size](https://img.shields.io/bundlephobia/minzip/viewerjs.svg)](https://unpkg.com/viewerjs/dist/viewer.common.js)
+[![Coverage Status](https://img.shields.io/codecov/c/github/fengyuanchen/viewerjs.svg)](https://codecov.io/gh/fengyuanchen/viewerjs) [![Downloads](https://img.shields.io/npm/dm/viewerjs.svg)](https://www.npmjs.com/package/viewerjs) [![Version](https://img.shields.io/npm/v/viewerjs.svg)](https://www.npmjs.com/package/viewerjs) [![Gzip Size](https://img.shields.io/bundlephobia/minzip/viewerjs.svg)](https://unpkg.com/viewerjs/dist/viewer.common.js)
 
 > JavaScript image viewer.
 
 - [Website](https://fengyuanchen.github.io/viewerjs)
 - [jquery-viewer](https://github.com/fengyuanchen/jquery-viewer) - A jQuery plugin wrapper for Viewer.js.
 
-## Table of contents
+## Table of Contents
 
 - [Features](#features)
 - [Main Files](#main-files)
-- [Getting started](#getting-started)
-- [Keyboard support](#keyboard-support)
+- [Getting Started](#getting-started)
+- [Keyboard Support](#keyboard-support)
 - [Options](#options)
 - [Methods](#methods)
+- [Static Methods](#static-methods)
 - [Events](#events)
-- [No conflict](#no-conflict)
-- [Browser support](#browser-support)
+- [Browser Support](#browser-support)
 - [Contributing](#contributing)
 - [Versioning](#versioning)
 - [License](#license)
 
 ## Features
 
-- Supports 53 [options](#options)
+- Supports 61 [options](#options)
 - Supports 23 [methods](#methods)
 - Supports 17 [events](#events)
 - Supports modal and inline modes
@@ -34,9 +34,10 @@
 - Supports rotation
 - Supports scale (flip)
 - Supports keyboard
+- Supports image magnification
 - Cross-browser support
 
-## Main files
+## Main Files
 
 ```text
 dist/
@@ -48,7 +49,7 @@ dist/
 └── viewer.esm.js    (ES Module)
 ```
 
-## Getting started
+## Getting Started
 
 ### Installation
 
@@ -75,11 +76,13 @@ new Viewer(element[, options])
 
 - **element**
   - Type: `HTMLElement`
-  - The target image, or a container of images, for viewing.
+  - The target image, or a container of images, to view.
 
 - **options** (optional)
   - Type: `Object`
-  - The options for viewing. See the available [options](#options).
+  - The configuration options. Check out the available [options](#options).
+
+Alternatively, you may use `Viewer.create(element[, options])`.
 
 #### Example
 
@@ -118,7 +121,7 @@ const gallery = new Viewer(document.getElementById('images'));
 // Then show one image by clicking it, or call `gallery.show()`.
 ```
 
-## Keyboard support
+## Keyboard Support
 
 > Only available in modal mode.
 
@@ -156,7 +159,7 @@ Show the button on the top-right of the viewer.
 
 ### navbar
 
-- Type: `Boolean` or `Number`
+- Type: `Boolean` or `Number` or `String` or `Object`
 - Default: `true`
 - Options:
   - `0` or `false`: hide the navbar
@@ -164,9 +167,58 @@ Show the button on the top-right of the viewer.
   - `2`: show the navbar only when the screen width is greater than 768 pixels
   - `3`: show the navbar only when the screen width is greater than 992 pixels
   - `4`: show the navbar only when the screen width is greater than 1200 pixels
+  - `small`: show thumbnails at 24px tall.
+  - `medium`: show thumbnails at 32px tall.
+  - `large`: show thumbnails at 40px tall.
+  - `Object`: configure the navbar with the following properties:
+    - `show` (`Boolean` or `Number`): specify the visibility of the navbar.
+    - `size` (`String`): specify the thumbnail size: `small`, `medium`, or `large`.
+    - `visibleItemCount` (`Number`): specify the number of thumbnail items to render around the active item. The default is calculated from the container width and the width of one thumbnail item.
 
 Specify the visibility of the navbar.
 
+When setting a size, thumbnails use a $9 / 16$ width-to-height ratio.
+
+```js
+navbar: {
+  show: true,
+  size: 'large',
+}
+```
+
+### navigation
+
+- Type: `Boolean` or `Number` or `Object`
+- Default: `false`
+
+- Options:
+  - `0` or `false`: hide the navigation buttons.
+  - `1` or `true`: show the navigation buttons.
+  - `2`: show the navigation buttons only when the screen width is greater than 768 pixels.
+  - `3`: show the navigation buttons only when the screen width is greater than 992 pixels.
+  - `4`: show the navigation buttons only when the screen width is greater than 1200 pixels.
+  - `{ prev: Boolean | Number | Object, next: Boolean | Number | Object }`: show or hide each navigation button.
+  - `{ prev: { show: Boolean | Number, size: String }, next: { show: Boolean | Number, size: String } }`: customize each navigation button.
+  - Available sizes: `small` (32px), `medium` (40px, default), and `large` (48px).
+
+Show the previous and next buttons on the left and right sides of the viewer.
+
+For example:
+
+```js
+new Viewer(image, {
+  navigation: {
+    prev: {
+      size: 'large',
+    },
+    next: {
+      show: 2,
+      size: 'small',
+    },
+  },
+});
+```
+
 ### title
 
 - Type: `Boolean` or `Number` or `Function` or `Array`
@@ -313,6 +365,13 @@ Define the initial index of the image for viewing.
 
 Enable inline mode.
 
+### autoplay
+
+- Type: `Boolean`
+- Default: `true`
+
+Enable to automatically cycle the images when playing.
+
 ### interval
 
 - Type: `Number`
@@ -352,6 +411,13 @@ Indicate if enabling loop viewing or not.
 
 > If the current image is the last one, then the next one to view is the first one, and vice versa.
 
+### preload
+
+- Type: `Boolean`
+- Default: `true`
+
+Enable to preload the next or previous image before viewing it.
+
 ### minWidth
 
 - Type: `Number`
@@ -377,6 +443,29 @@ Define the minimum height of the viewer.
 
 Enable to move the image.
 
+### magnifier
+
+- Type: `Boolean` or `Object`
+- Default: `false`
+- Options:
+  - `size` (`Number`): the size of the magnifier in pixels. Defaults to `100`.
+  - `zoomRatio` (`Number`): the magnification ratio. Defaults to `2`.
+  - `opacity` (`Number`): the opacity of the magnifier, from `0` to `1`. Defaults to `1`.
+
+Show a magnifier over the image when hovering in fullscreen mode. The magnifier is disabled on touch screens.
+
+For example:
+
+```js
+new Viewer(image, {
+  magnifier: {
+    size: 120,
+    zoomRatio: 3,
+    opacity: 0.8,
+  },
+});
+```
+
 ### rotatable
 
 - Type: `Boolean`
@@ -384,6 +473,20 @@ Enable to move the image.
 
 Enable to rotate the image.
 
+### rotateOnGesture
+
+- Type: `Boolean`
+- Default: `true`
+
+Enable to rotate the current image with gesture events, such as a two-finger gesture on Mac Safari.
+
+### rotateOnTouch
+
+- Type: `Boolean`
+- Default: `true`
+
+Enable to rotate the current image with a two-finger gesture on a touch screen.
+
 ### scalable
 
 - Type: `Boolean`
@@ -398,6 +501,13 @@ Enable to scale the image.
 
 Enable to zoom the image.
 
+### zoomOnGesture
+
+- Type: `Boolean`
+- Default: `true`
+
+Enable to zoom the current image with gesture events, such as a pinch gesture on Mac Safari.
+
 ### zoomOnTouch
 
 - Type: `Boolean`
@@ -407,11 +517,13 @@ Enable to zoom the current image by dragging on the touch screen.
 
 ### zoomOnWheel
 
-- Type: `Boolean`
+- Type: `Boolean | String`
 - Default: `true`
 
 Enable to zoom the image by wheeling the mouse.
 
+Set to a modifier key name (`ctrl`, `shift`, `alt`, `meta`), or a combination joined with `+` (e.g. `ctrl+shift`), to only zoom when the given modifier key(s) are held down while wheeling. Otherwise, wheeling falls back to sliding when [`slideOnWheel`](#slideonwheel) is enabled.
+
 ### slideOnTouch
 
 - Type: `Boolean`
@@ -419,6 +531,17 @@ Enable to zoom the image by wheeling the mouse.
 
 Enable to slide to the next or previous image by swiping on the touch screen.
 
+### slideOnWheel
+
+- Type: `Boolean | String`
+- Default: `true`
+
+Enable to slide to the next or previous image by wheeling the mouse.
+
+Set to a modifier key name (`ctrl`, `shift`, `alt`, `meta`), or a combination joined with `+` (e.g. `ctrl+shift`), to only slide when the given modifier key(s) are held down while wheeling.
+
+Takes effect over the navbar, and also over the rest of the viewer when [`zoomOnWheel`](#zoomonwheel) doesn't take effect for that wheel event.
+
 ### toggleOnDblclick
 
 - Type: `Boolean`
@@ -439,11 +562,23 @@ Show the tooltip with image ratio (percentage) when zooming in or zooming out.
 
 ### transition
 
-- Type: `Boolean`
+- Type: `Boolean` or `Object`
 - Default: `true`
 
 Enable CSS3 transitions for some special elements.
 
+When passing an object, set a supported action to `false` to disable only its transition. The supported actions are `show`, `hide`, `view`, `move`, `zoom`, `rotate`, `scale`, `play`, and `tooltip`.
+
+```js
+new Viewer(image, {
+  transition: {
+    hide: false,
+    view: false,
+    zoom: false,
+  },
+});
+```
+
 ### zIndex
 
 - Type: `Number`
@@ -467,18 +602,38 @@ Define the ratio when zooming the image by wheeling the mouse.
 
 ### minZoomRatio
 
-- Type: `Number`
+- Type: `Number` or `Function`
 - Default: `0.01`
 
 Define the min ratio of the image when zooming out.
 
+If it is a function, it receives the current image and image data, and should return the minimum ratio:
+
+```js
+new Viewer(image, {
+  minZoomRatio(image, imageData) {
+    return imageData.naturalWidth > 2000 ? 0.1 : 0.01;
+  },
+});
+```
+
 ### maxZoomRatio
 
-- Type: `Number`
+- Type: `Number` or `Function`
 - Default: `100`
 
 Define the max ratio of the image when zooming in.
 
+If it is a function, it receives the current image and image data, and should return the maximum ratio:
+
+```js
+new Viewer(image, {
+  maxZoomRatio(image, imageData) {
+    return imageData.naturalWidth > 2000 ? 2 : 10;
+  },
+});
+```
+
 ### url
 
 - Type: `String` or `Function`
@@ -615,6 +770,13 @@ Shortcut of the `zoomed` event.
 
 Shortcut of the `play` event.
 
+### playing
+
+- Type: `Function`
+- Default: `null`
+
+Shortcut of the `playing` event.
+
 ### stop
 
 - Type: `Function`
@@ -903,18 +1065,61 @@ Toggle the image size between its current size and natural size.
 
 Reset the image to its initial state.
 
-### update()
+### update([options])
 
-Update the viewer instance when the source images changed (added, removed, or sorted).
+Update the viewer instance when the source images changed (added, removed, or sorted), or update the options while the viewer is open.
 
 > If you load images dynamically (with XMLHTTPRequest), you can use this method to add the new images to the viewer instance.
 
+```js
+viewer.update({
+  slideOnTouch: false,
+});
+```
+
 ### destroy()
 
 Destroy the viewer and remove the instance.
 
 [⬆ back to top](#table-of-contents)
 
+## Static Methods
+
+### create(element[, options])
+
+Create a new `Viewer` instance without using the `new` operator.
+
+```js
+const viewer = Viewer.create(image, {
+  inline: true,
+});
+```
+
+### setDefaults(options)
+
+Change the global default options for subsequently created `Viewer` instances. Instance options override these defaults.
+
+```js
+Viewer.setDefaults({
+  inline: true,
+});
+```
+
+### noConflict
+
+If you have to use another viewer with the same namespace, call the `Viewer.noConflict` static method to revert to it.
+
+```html
+<script src="other-viewer.js"></script>
+<script src="viewer.js"></script>
+<script>
+  Viewer.noConflict();
+  // Code that uses other `Viewer` can follow here.
+</script>
+```
+
+[⬆ back to top](#table-of-contents)
+
 ## Events
 
 All events can access the viewer instance with `this.viewer` in its handler.
@@ -946,7 +1151,8 @@ This event fires when a viewer instance is ready for viewing.
 
 - **event.bubbles**: `true`
 - **event.cancelable**: `true`
-- **event.detail**: `null`
+- **event.detail.originalEvent**:
+  - Type: `Event` or `null`
 
 This event fires when the viewer modal starts to show.
 
@@ -956,7 +1162,7 @@ This event fires when the viewer modal starts to show.
 
 - **event.bubbles**: `true`
 - **event.cancelable**: `true`
-- **event.detail**: `null`
+- **event.detail**: the same as the `show` event.
 
 This event fires when the viewer modal has shown.
 
@@ -966,7 +1172,8 @@ This event fires when the viewer modal has shown.
 
 - **event.bubbles**: `true`
 - **event.cancelable**: `true`
-- **event.detail**: `null`
+- **event.detail.originalEvent**:
+  - Type: `Event` or `null`
 
 This event fires when the viewer modal starts to hide.
 
@@ -976,7 +1183,7 @@ This event fires when the viewer modal starts to hide.
 
 - **event.bubbles**: `true`
 - **event.cancelable**: `false`
-- **event.detail**: `null`
+- **event.detail**: the same as the `hide` event.
 
 This event fires when the viewer modal has hidden.
 
@@ -995,6 +1202,8 @@ This event fires when the viewer modal has hidden.
 - **event.detail.originalImage**:
   - Type: `HTMLImageElement`
   - The original image.
+- **event.detail.originalEvent**:
+  - Type: `Event` or `null`
 
 This event fires when a viewer starts to show (view) an image.
 
@@ -1046,6 +1255,8 @@ This event fires when a viewer has moved an image.
 - **event.detail.oldDegree**:
   - Type: `Number`
   - The old rotation degrees.
+- **event.detail.originalEvent**:
+  - Type: `Event` or `null`
 
 This event fires when a viewer starts to rotate an image.
 
@@ -1073,6 +1284,8 @@ This event fires when a viewer has rotated an image.
 - **event.detail.oldScaleY**:
   - Type: `Number`
   - The old scaling factor in the vertical direction.
+- **event.detail.originalEvent**:
+  - Type: `Event` or `null`
 
 This event fires when a viewer starts to scale an image.
 
@@ -1112,17 +1325,39 @@ This event fires when a viewer has zoomed (in or out) an image.
 
 - **event.bubbles**: `true`
 - **event.cancelable**: `true`
-- **event.detail**: `null`
+- **event.detail.originalEvent**:
+  - Type: `Event` or `null`
 
 This event fires when the viewer starts to play.
 
 > You can abort the playing process by calling `event.preventDefault()`.
 
+### playing
+
+- **event.bubbles**: `true`
+- **event.cancelable**: `true`
+- **event.detail.index**:
+  - Type: `Number`
+  - The index of the original image.
+- **event.detail.image**:
+  - Type: `HTMLImageElement`
+  - The current image (a clone of the original image).
+- **event.detail.originalImage**:
+  - Type: `HTMLImageElement`
+  - The original image.
+- **event.detail.originalEvent**:
+  - Type: `Event` or `null`
+
+This event fires when a viewer starts to play (cycle) an image.
+
+> You can abort the cycling process by calling `event.preventDefault()`.
+
 ### stop
 
 - **event.bubbles**: `true`
 - **event.cancelable**: `true`
-- **event.detail**: `null`
+- **event.detail.originalEvent**:
+  - Type: `Event` or `null`
 
 This event fires when the viewer starts to stop.
 
@@ -1130,20 +1365,7 @@ This event fires when the viewer starts to stop.
 
 [⬆ back to top](#table-of-contents)
 
-## No conflict
-
-If you have to use another viewer with the same namespace, call the `Viewer.noConflict` static method to revert to it.
-
-```html
-<script src="other-viewer.js"></script>
-<script src="viewer.js"></script>
-<script>
-  Viewer.noConflict();
-  // Code that uses other `Viewer` can follow here.
-</script>
-```
-
-## Browser support
+## Browser Support
 
 - Chrome (latest)
 - Firefox (latest)