viewerjs 1.11.9 → 1.13.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 57 [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
 
@@ -56,14 +57,14 @@ dist/
 npm install viewerjs
 ```
 
-In browser:
+In the browser:
 
 ```html
-<link  href="/path/to/viewer.css" rel="stylesheet">
+<link href="/path/to/viewer.css" rel="stylesheet">
 <script src="/path/to/viewer.js"></script>
 ```
 
-The [cdnjs](https://github.com/cdnjs/cdnjs) provides CDN support for Viewer.js's CSS and JavaScript. You can find the links [here](https://cdnjs.com/libraries/viewerjs).
+The [cdnjs](https://github.com/cdnjs/cdnjs) project provides CDN support for Viewer.js CSS and JavaScript. You can find the links [here](https://cdnjs.com/libraries/viewerjs).
 
 ### Usage
 
@@ -75,11 +76,13 @@ new Viewer(element[, options])
 
 - **element**
   - Type: `HTMLElement`
-  - The target image or container of images for viewing.
+  - The target image, or a container of images, to view.
 
 - **options** (optional)
   - Type: `Object`
-  - The options for viewing. Check out the available [options](#options).
+  - The configuration options. Check out the available [options](#options).
+
+Alternatively, you may use `Viewer.create(element[, options])`.
 
 #### Example
 
@@ -110,15 +113,15 @@ const viewer = new Viewer(document.getElementById('image'), {
     viewer.zoomTo(1);
   },
 });
-// Then, show the image by clicking it, or call `viewer.show()`.
+// Then show the image by clicking it, or call `viewer.show()`.
 
 // View a list of images.
-// Note: All images within the container will be found by calling `element.querySelectorAll('img')`.
+// Note: all images within the container will be found by calling `element.querySelectorAll('img')`.
 const gallery = new Viewer(document.getElementById('images'));
-// Then, show one image by click it, or call `gallery.show()`.
+// Then show one image by clicking it, or call `gallery.show()`.
 ```
 
-## Keyboard support
+## Keyboard Support
 
 > Only available in modal mode.
 
@@ -138,7 +141,7 @@ const gallery = new Viewer(document.getElementById('images'));
 ## Options
 
 You may set viewer options with `new Viewer(image, options)`.
-If you want to change the global default options, You may use `Viewer.setDefaults(options)`.
+If you want to change the global default options, you may use `Viewer.setDefaults(options)`.
 
 ### backdrop
 
@@ -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`
@@ -178,9 +230,9 @@ Specify the visibility of the navbar.
   - `3`: show the title only when the screen width is greater than 992 pixels
   - `4`: show the title only when the screen width is greater than 1200 pixels
   - `Function`: customize the title content
-  - `[Number, Function]`: the first element indicate the visibility, the second element customize the title content
+  - `[Number, Function]`: the first element indicates the visibility; the second element customizes the title content
 
-Specify the visibility and the content of the title.
+Specify the visibility and content of the title.
 
 > The name comes from the `alt` attribute of an image element or the image name parsed from its URL.
 
@@ -209,7 +261,7 @@ new Viewer(image, {
   - Available built-in keys: "zoomIn", "zoomOut", "oneToOne", "reset", "prev", "play", "next", "rotateLeft", "rotateRight", "flipHorizontal", "flipVertical".
   - Available built-in sizes: "small", "medium" (default) and "large".
 
-Specify the visibility and layout of the toolbar its buttons.
+Specify the visibility and layout of the toolbar and its buttons.
 
 For example, `toolbar: 4` equals to:
 
@@ -295,7 +347,7 @@ Define the extra attributes to inherit from the original image.
 - Type: `Number`
 - Default: `0.9`
 
-Define the initial coverage of the viewing image. It must a positive number between 0 (0%) and 1 (100%).
+Define the initial coverage of the viewing image. It must be a positive number between 0 (0%) and 1 (100%).
 
 ### initialViewIndex
 
@@ -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`
@@ -424,9 +534,9 @@ Enable to slide to the next or previous image by swiping on the touch screen.
 - Type: `Boolean`
 - Default: `true`
 
-Indicate if toggle the image size between its natural size and initial size when double click on the image or not.
+Indicate whether to toggle the image size between its natural size and initial size when double-clicking the image.
 
-In other words, call the [`toggle`](#toggle) method automatically when double click on the image.
+In other words, call the [`toggle`](#toggle) method automatically when the image is double-clicked.
 
 > Requires [`dblclick`](https://developer.mozilla.org/en-US/docs/Web/Events/dblclick) event support.
 
@@ -439,10 +549,22 @@ Show the tooltip with image ratio (percentage) when zooming in or zooming out.
 
 ### transition
 
-- Type: `Boolean`
+- Type: `Boolean` or `Object`
 - Default: `true`
 
-Enable CSS3 Transition for some special elements.
+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
 
@@ -467,18 +589,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`
@@ -626,9 +768,9 @@ Shortcut of the `stop` event.
 
 ## Methods
 
-All methods allow chain composition.
+All methods support chain composition.
 
-As there are some **asynchronous** processes when start the viewer, you should call a method only when it is available, see the following **lifecycle**:
+As there are some **asynchronous** processes when starting the viewer, you should call a method only when it is available. See the following **lifecycle**:
 
 ```js
 new Viewer(image, {
@@ -856,9 +998,9 @@ viewer.zoomTo(0); // Zoom to zero size (0%)
 viewer.zoomTo(1); // Zoom to natural size (100%)
 
 // Zoom to 50% from the center of the window.
-viewer.zoomTo(.5, {
+viewer.zoomTo(0.5, false, {
   x: window.innerWidth / 2,
-  y: viewer.innerHeight / 2,
+  y: window.innerHeight / 2,
 });
 ```
 
@@ -867,7 +1009,7 @@ viewer.zoomTo(.5, {
 - **fullscreen** (optional):
   - Type: `Boolean` or [`FullscreenOptions`](https://developer.mozilla.org/en-US/docs/Web/API/FullscreenOptions)
   - Default: `false`
-  - Indicate if request fullscreen or not.
+  - Indicates whether to request fullscreen.
 
 Play the images.
 
@@ -903,18 +1045,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.
@@ -1130,20 +1315,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)