viewerjs-sun
v1.0.2TypeScript
JavaScript image viewer.
2/weekUpdated 3 years agoMITUnpacked: 509.3 KB
Published by Chen Fengyuan
npm install viewerjs-sunViewer.js
  
> JavaScript image viewer.
- Website
- jquery-viewer - A jQuery plugin wrapper for Viewer.js.
Table of contents
- Features
- Main
- Getting started
- Keyboard support
- Options
- Methods
- Events
- No conflict
- Browser support
- Contributing
- Versioning
- License
Features
- Supports 45 options
- Supports 23 methods
- Supports 11 events
- Supports modal and inline modes
- Supports touch
- Supports move
- Supports zoom
- Supports rotation
- Supports scale (flip)
- Supports keyboard
- Cross-browser support
Main
``text`
dist/
├── viewer.css
├── viewer.min.css (compressed)
├── viewer.js (UMD)
├── viewer.min.js (UMD, compressed)
├── viewer.common.js (CommonJS, default)
└── viewer.esm.js (ES Module)
Getting started
$3
`shell`
npm install viewerjs
In browser:
`html`
The cdnjs provides CDN support for Viewer.js's CSS and JavaScript. You can find the links here.
$3
#### Syntax
`js`
new Viewer(element[, options])
- element
- Type: HTMLElement
- The target image or container of images for viewing.
- options (optional)
- Type: Object
- The options for viewing. Check out the available options.
#### Example
`html
`
js
// You should import the CSS file.
// import 'viewerjs/dist/viewer.css';
import Viewer from 'viewerjs';// View an image
const viewer = new Viewer(document.getElementById('image'), {
inline: true,
viewed() {
viewer.zoomTo(1);
},
});
// Then, show the image by click it, or call
viewer.show().// View a list of images
const gallery = new Viewer(document.getElementById('images'));
// Then, show one image by click it, or call
gallery.show().
`Keyboard support
> Only available in modal mode.
-
: Exit full screen or close the viewer or exit modal mode or stop play.
- Space: Stop play.
- ←: View the previous image.
- →: View the next image.
- ↑: Zoom in the image.
- ↓: Zoom out the image.
- Ctrl + 0: Zoom out to initial size.
- Ctrl + 1: Zoom in to natural size.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).$3
- Type:
Boolean or String
- Default: Enable a modal backdrop, specify
for a backdrop which doesn't close the modal on click.$3
- Type:
Boolean
- Default: Show the button on the top-right of the viewer.
$3
- Type:
or Number
- Default:
- Options:
- or false: hide the navbar
- 1 or true: show the navbar
- 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 pixelsSpecify the visibility of the navbar.
$3
- Type:
Boolean or Number or Function or Array
- Default:
- Options:
- or false: hide the title
- 1 or true or Function or Array: show the title
- 2: show the title only when the screen width is greater than 768 pixels
- 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 contentSpecify the visibility and the content of the title.
> The name comes from the
alt attribute of an image element or the image name parsed from URL.For example,
title: 4 equals to:`js
new Viewer(image, {
title: [4, (image, imageData) => ${image.alt} (${imageData.naturalWidth} × ${imageData.naturalHeight})]
});
`$3
- Type:
or Number or Object
- Default:
- Options:
- or false: hide the toolbar.
- 1 or true: show the toolbar.
- 2: show the toolbar only when the screen width is greater than 768 pixels.
- 3: show the toolbar only when the screen width is greater than 992 pixels.
- 4: show the toolbar only when the screen width is greater than 1200 pixels.
- { key: Boolean | Number }: show or hide the toolbar.
- { key: String }: customize the size of the button.
- { key: Function }: customize the click handler of the button.
- { key: { show: Boolean | Number, size: String, click: Function }: customize each property of the button.
- Available keys: "zoomIn", "zoomOut", "oneToOne", "reset", "prev", "play", "next", "rotateLeft", "rotateRight", "flipHorizontal" and "flipVertical".
- Available sizes: "small", "medium" (default) and "large".Specify the visibility and layout of the toolbar its buttons.
For example,
toolbar: 4 equals to:`js
new Viewer(image, {
toolbar: {
zoomIn: 4,
zoomOut: 4,
oneToOne: 4,
reset: 4,
prev: 4,
play: {
show: 4,
size: 'large',
},
next: 4,
rotateLeft: 4,
rotateRight: 4,
flipHorizontal: 4,
flipVertical: 4,
},
});
`$3
- Type:
- Default: Custom class name(s) to add to the viewer's root element.
$3
- Type:
or String
- Default:
- An element or a valid selector for Document.querySelectorThe container to put the viewer in modal mode.
> Only available when the
option is set to false.$3
- Type:
Function
- Default: Filter the images for viewing (should return
if the image is viewable, return false to ignore the image).For example:
`js
new Viewer(image, {
filter(image) {
return image.complete;
},
});
`> Note that images without the
attribute set will be ignored by default.$3
- Type:
Boolean
- Default: Enable to request full screen when play.
> Requires the browser supports Full Screen API.
$3
- Type:
- Default: Define the extra attributes to inherit from the original image.
> Note that the basic attributes
and alt will always inherit from the original image.$3
- Type:
Number
- Default: Define the initial index of image for viewing.
> Also used as the default parameter value of the
method.$3
- Type:
Boolean
- Default: Enable inline mode.
$3
- Type:
- Default: The amount of time to delay between automatically cycling an image when playing.
$3
- Type:
- Default: Enable keyboard support.
$3
- Type:
- Default: Indicate if show a loading spinner when load image or not.
$3
- Type:
- Default: Indicate if enable 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.
$3
- Type:
- Default: 200Define the minimum width of the viewer.
> Only available in inline mode (set the
option to true).$3
- Type:
Number
- Default: 100Define the minimum height of the viewer.
> Only available in inline mode (set the
option to true).$3
- Type:
Boolean
- Default: Enable to move the image.
$3
- Type:
- Default: Enable to rotate the image.
$3
- Type:
- Default: Enable to scale the image.
$3
- Type:
- Default: Enable to zoom the image.
$3
- Type:
- Default: Enable to zoom the current image by dragging on the touch screen.
$3
- Type:
- Default: Enable to zoom the image by wheeling mouse.
$3
- Type:
- Default: Enable to slide to the next or previous image by swiping on the touch screen.
$3
- Type:
- Default: Indicate if toggle the image size between its natural size and initial size when double click on the image or not.
method automatically when double click on the image.dblclick event support.$3
- Type:
Boolean
- Default: Show the tooltip with image ratio (percentage) when zoom in or zoom out.
$3
- Type:
- Default: Enable CSS3 Transition for some special elements.
$3
- Type:
- Default: Define the CSS
value of viewer in modal mode.$3
- Type:
Number
- Default: Define the CSS
value of viewer in inline mode.$3
- Type:
Number
- Default: Define the ratio when zoom the image by wheeling mouse.
$3
- Type:
- Default: Define the min ratio of the image when zoom out.
$3
- Type:
- Default: Define the max ratio of the image when zoom in.
$3
- Type:
or Function
- Default: Define where to get the original image URL for viewing.
> If it is a string, it should be one of the attributes of each image element.
> If it is a function, it should return a valid image URL.
For example:
html
`js
new Viewer(image, {
url(image) {
return image.src.replace('?size=160', '');
},
});
`$3
- Type:
- Default: A shortcut of the
event.$3
- Type:
Function
- Default: A shortcut of the
event.$3
- Type:
Function
- Default: A shortcut of the
event.$3
- Type:
Function
- Default: A shortcut of the
event.$3
- Type:
Function
- Default: A shortcut of the
event.$3
- Type:
Function
- Default: A shortcut of the
event.$3
- Type:
Function
- Default: A shortcut of the
event.$3
- Type:
Function
- Default: A shortcut of the
event.$3
- Type:
Function
- Default: A shortcut of the
event.$3
- Type:
Function
- Default: A shortcut of the
event.$3
- Type:
Function
- Default: A shortcut of the
event.Methods
All methods allow 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:
`js
new Viewer(image, {
ready() {
// 2 methods are available here: "show" and "destroy".
},
shown() {
// 9 methods are available here: "hide", "view", "prev", "next", "play", "stop", "full", "exit" and "destroy".
},
viewed() {
// All methods are available here except "show".
this.viewer.zoomTo(1).rotateTo(180);
}
});
`$3
- immediate (optional):
- Type:
- Default:
- Indicates if show the viewer immediately or not.Show the viewer.
> Only available in modal mode.
$3
- immediate (optional):
- Type:
- Default:
- Indicates if hide the viewer immediately or not.hide the viewer.
> Only available in modal mode.
$3
- index (optional):
- Type:
- Default: (inherits from the initialViewIndex option)
- The index of the image for viewingView one of the images with image's index. If the viewer is not shown, will show the viewer first.
`js
viewer.view(1); // View the second image
`$3
- loop (optional):
- Type:
- Default:
- Indicate if turn to view the last one when it is the first one at present.View the previous image.
$3
- loop (optional):
- Type:
- Default:
- Indicate if turn to view the first one when it is the last one at present.View the next image.
$3
- offsetX:
- Type:
- Moving size (px) in the horizontal direction- offsetY (optional):
- Type:
- Moving size (px) in the vertical direction.
- If not present, its default value is Move the image with relative offsets.
js
viewer.move(1);
viewer.move(-1, 0); // Move left
viewer.move(1, 0); // Move right
viewer.move(0, -1); // Move up
viewer.move(0, 1); // Move down
`$3
- x:
- Type:
- The value of the image- y (optional):
- Type:
Number
- The value of the image
- If not present, its default value is x.Move the image to an absolute point.
$3
- ratio:
- Type:
Number
- Zoom in: requires a positive number (ratio > 0)
- Zoom out: requires a negative number (ratio < 0)- hasTooltip (optional):
- Type:
- Default:
- Show tooltipZoom the image with a relative ratio
js
viewer.zoom(0.1);
viewer.zoom(-0.1);
`$3
- ratio:
- Type:
- Requires a positive number (ratio > 0)- hasTooltip (optional):
- Type:
- Default:
- Show tooltipZoom the image to an absolute ratio.
js
viewer.zoomTo(0); // Zoom to zero size (0%)
viewer.zoomTo(1); // Zoom to natural size (100%)
`$3
- degree:
- Type:
- Rotate right: requires a positive number (degree > 0)
- Rotate left: requires a negative number (degree < 0)Rotate the image with a relative degree.
js
viewer.rotate(90);
viewer.rotate(-90);
`$3
- degree:
- Type:
Rotate the image to an absolute degree.
js
viewer.rotateTo(0); // Reset to zero degree
viewer.rotateTo(360); // Rotate a full round
`$3
- scaleX:
- Type:
- Default:
- The scaling factor to apply on the abscissa of the image
- When equal to it does nothing.- scaleY (optional):
- Type:
Number
- The scaling factor to apply on the ordinate of the image
- If not present, its default value is .Scale the image.
`js
viewer.scale(-1); // Flip both horizontal and vertical
viewer.scale(-1, 1); // Flip horizontal
viewer.scale(1, -1); // Flip vertical
`$3
- scaleX:
- Type:
- Default:
- The scaling factor to apply on the abscissa of the image
- When equal to it does nothingScale the abscissa of the image.
`js
viewer.scaleX(-1); // Flip horizontal
`$3
- scaleY:
- Type:
- Default:
- The scaling factor to apply on the ordinate of the image
- When equal to it does nothingScale the ordinate of the image.
`js
viewer.scaleY(-1); // Flip vertical
`$3
- fullscreen (optional):
- Type:
- Default:
- Indicate if request fullscreen or not.Play the images.
$3
Stop play.
$3
Enter modal mode.
> Only available in inline mode.
$3
Exit modal mode.
> Only available in inline mode.
$3
Show the current ratio of the image with percentage.
> Requires the
option set to true.$3
Toggle the image size between its natural size and initial size.
toggleOnDblclick option.$3
Reset the image to its initial state.
$3
Update the viewer instance when the source images changed (added, removed or sorted).
> If you load images dynamically (with XMLHTTPRequest), you can use this method to add the new images to the viewer instance.
$3
Destroy the viewer and remove the instance.
Events
All events can access the viewer instance with
this.viewer in its handler.> Be careful to use these events in other component which has the same event names, e.g.: Bootstrap's modal.
`js
let viewer;image.addEventListener('viewed', function () {
console.log(this.viewer === viewer);
// > true
});
viewer = new Viewer(image);
`$3
- event.bubbles:
- event.cancelable:
- event.detail: This event fires when a viewer instance is ready for viewing.
> In modal mode, this event will not be triggered until you click on one of the images.
$3
- event.bubbles:
- event.cancelable:
- event.detail: This event fires when the viewer modal starts to show.
> Only available in modal mode.
$3
- event.bubbles:
- event.cancelable:
- event.detail: This event fires when the viewer modal has shown.
> Only available in modal mode.
$3
- event.bubbles:
- event.cancelable:
- event.detail: This event fires when the viewer modal starts to hide.
> Only available in modal mode.
$3
- event.bubbles:
- event.cancelable:
- event.detail: This event fires when the viewer modal has hidden.
> Only available in modal mode.
$3
- event.bubbles:
- event.cancelable:
- event.detail.originalImage:
- Type:
- The original image.
- event.detail.index:
- Type:
- The index of the original image.
- event.detail.image:
- Type:
- The current image (a clone of the original image).This event fires when a viewer starts to show (view) an image.
$3
- event.bubbles:
- event.cancelable:
- event.detail: the same as the event.This event fires when a viewer has shown (viewed) an image.
$3
- event.bubbles:
true
- event.cancelable:
- event.detail.originalEvent:
- Type:
- Options: , pointermove, touchmove, and mousemove.
- event.detail.oldRatio:
- Type: Number
- The old (current) ratio of the image.
- event.detail.ratio:
- Type:
- The new (next) ratio of the image ().This event fires when a viewer starts to zoom (in or out) an image.
$3
- event.bubbles:
true
- event.cancelable:
- event.detail: the same as the event.This event fires when a viewer has zoomed (in or out) an image.
$3
- event.bubbles:
true
- event.cancelable:
- event.detail: This event fires when the viewer starts to play.
> You can abort the playing process by calling
.$3
- event.bubbles:
true
- event.cancelable:
- event.detail: This event fires when the viewer starts to stop.
> You can abort the stopping process by calling
.No conflict
If you have to use other viewer with the same namespace, just call the
Viewer.noConflict static method to revert to it.`html
``Browser support
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Opera (latest)
- Edge (latest)
- Internet Explorer 9+
Contributing
Please read through our contributing guidelines.
Versioning
Maintained under the Semantic Versioning guidelines.