项目文章

搜索 TinyTools

viewerjs是一个功能强大的JavaScript图像查看器

8.2k 文档演示 Github仓库 Gitee仓库

Viewer.js

JavaScript 图像查看器

网站
jquery-viewer - Viewer.js 的 jQuery 插件包装器。

功能

支持 53 个选项
支持 23 个方法
支持 17 个事件
支持模态和内联模式
支持触摸
支持移动
支持缩放
支持旋转
支持缩放（翻转）
支持键盘
跨浏览器支持

主要文件

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)

入门

安装

shell 复制代码

npm install viewerjs

在浏览器中：

html 复制代码

<link href="/path/to/viewer.css" rel="stylesheet">
<script src="/path/to/viewer.js"></script>

cdnjs 为 Viewer.js 的 CSS 和 JavaScript 提供 CDN 支持。您可以在此处找到相关链接。

用法

语法

js 复制代码

new Viewer(element[, options])

element
类型：HTMLElement
待查看的目标图片或图片容器。
options（可选）
类型：Object
待查看的选项。请查看可用的 options。

示例

html 复制代码

<!-- a block container is required -->
<div>
  <img id="image" src="picture.jpg" alt="Picture">
</div>

<div>
  <ul id="images">
    <li><img src="picture-1.jpg" alt="Picture 1"></li>
    <li><img src="picture-2.jpg" alt="Picture 2"></li>
    <li><img src="picture-3.jpg" alt="Picture 3"></li>
  </ul>
</div>

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 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')`.
const gallery = new Viewer(document.getElementById('images'));
// Then, show one image by click it, or call `gallery.show()`.

Keyboard support

仅在模态模式下可用。

Esc：退出全屏、关闭查看器、退出模态模式或停止播放。
Space：停止播放。
Tab：切换查看器中按钮的焦点状态。
Enter：触发按钮上的点击事件处理程序。
←：查看上一张图片。
→：查看下一张图片。
↑：放大图片。
↓：缩小图片。
Ctrl + 0：缩小至初始大小。
Ctrl + 1：放大至正常大小。

⬆ 返回目录

Options

您可以使用 new Viewer(image, options) 设置查看器选项。如果您想更改全局默认选项，可以使用 Viewer.setDefaults(options)。

backdrop

Type: Boolean or String
Default: true

启用模态背景，为背景指定static，点击时不会关闭模态。

button

Type: Boolean
Default: true

显示查看器右上角的按钮。

Type: Boolean or Number
Default: true
Options:
- 0 或 false：隐藏导航栏
- 1 或 true：显示导航栏
- 2：仅当屏幕宽度大于 768 像素时显示导航栏
- 3：仅当屏幕宽度大于 992 像素时显示导航栏
- 4：仅当屏幕宽度大于 1200 像素时显示导航栏

指定导航栏的可见性。

title

Type: Boolean or Number or Function or Array
Default: true
Options:
- 0 或 false：隐藏标题
- 1 或 true 或 Function 或 Array：显示标题
- 2：仅在屏幕宽度大于 768 像素时显示标题
- 3：仅在屏幕宽度大于 992 像素时显示标题
- 4：仅在屏幕宽度大于 1200 像素时显示标题
- Function：自定义标题内容
- [Number, Function]：第一个元素指示可见性，第二个元素自定义标题内容

指定标题的可见性和内容。

名称来自图片元素的 alt 属性或从其 URL 解析出的图片名称。

For example, title: 4 equals to:

js 复制代码

new Viewer(image, {
  title: [4, (image, imageData) => `${image.alt} (${imageData.naturalWidth} × ${imageData.naturalHeight})`]
});

Type: Boolean or Number or Object
Default: true
Options:
- 0 或 false：隐藏工具栏。
- 1 或 true：显示工具栏。
- 2：仅当屏幕宽度大于 768 像素时显示工具栏。
- 3：仅当屏幕宽度大于 992 像素时显示工具栏。
- 4：仅当屏幕宽度大于 1200 像素时显示工具栏。
- { key: Boolean | Number }：显示或隐藏工具栏。
- { key: String }：自定义按钮的大小。
- { key: Function }：自定义按钮的点击处理程序。
- { key: { show: Boolean | Number, size: String, click: Function }：自定义按钮的各个属性。
- 可用的内置键：“放大”、“缩小”、“一对一”、“重置”、“上一个”、“播放”、“下一个”、“向左旋转”、“向右旋转”、“水平翻转”、“垂直翻转”。
- 可用的内置尺寸：“小”、“中”（默认）和“大”。

指定工具栏及其按钮的可见性和布局。

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,
  },
});

see more for custom toolbar.

className

Type: String
Default: ''

添加到查看器根元素的自定义类名。

container

Type: Element or String
Default: 'body'
一个元素或一个有效的 Document.querySelector 选择器

用于将查看器置于模态模式的容器。

仅当“inline”选项设置为“false”时可用。

filter

Type: Function
Default: null

过滤图像以供查看（如果图像可查看则返回“true”，如果忽略图像则返回“false”）。

For example:

js 复制代码

new Viewer(image, {
  filter(image) {
    return image.complete;
  },
});

请注意，未设置src属性的图像将被默认忽略。

fullscreen

Type: Boolean or FullscreenOptions
Default: true

启用播放时请求全屏。

需要浏览器支持全屏 API。

inheritedAttributes

Type: Array
Default: ['crossOrigin', 'decoding', 'isMap', 'loading', 'referrerPolicy', 'sizes', 'srcset', 'useMap']

定义要从原始图像继承的额外属性。

请注意，基本属性 src 和 alt 将始终从原始图像继承。

initialCoverage

Type: Number
Default: 0.9

定义查看图像的初始覆盖率。它必须是介于 0（0%）和 1（100%）之间的正数。

initialViewIndex

Type: Number
Default: 0

定义要查看的图像的初始索引。

也用作 view 方法的默认参数值。

inline

Type: Boolean
Default: false

启用内联模式。

interval

Type: Number
Default: 5000

播放时自动循环图像之间的延迟时间。

keyboard

Type: Boolean
Default: true

启用键盘支持。

focus

Type: Boolean
Default: true

初始化时将焦点放在导航栏中的活动项目上。

需要将“keyboard”选项设置为“true”。

loading

Type: Boolean
Default: true

指示加载图像时是否显示加载旋转器。

loop

Type: Boolean
Default: true

指示是否启用循环查看。

如果当前图像是最后一个，则下一个要查看的图像是第一个，反之亦然。

minWidth

Type: Number
Default: 200

定义查看器的最小宽度。

仅在内联模式下可用（将“inline”选项设置为“true”）。

minHeight

Type: Number
Default: 100

定义查看器的最小高度。

仅在内联模式下可用（将“inline”选项设置为“true”）。

movable

Type: Boolean
Default: true

启用移动图像。

rotatable

Type: Boolean
Default: true

启用旋转图像。

scalable

Type: Boolean
Default: true

启用缩放图像。

zoomable

Type: Boolean
Default: true

启用以缩放图像。

zoomOnTouch

Type: Boolean
Default: true

通过在触摸屏上拖动可以缩放当前图像。

zoomOnWheel

Type: Boolean
Default: true

可以通过滚动鼠标来缩放图像。

slideOnTouch

Type: Boolean
Default: true

通过在触摸屏上滑动即可滑动到下一张或上一张图像。

toggleOnDblclick

Type: Boolean
Default: true

指示双击图片时是否在图片的自然大小和初始大小之间切换。

换句话说，双击图片时是否自动调用 toggle 方法。

需要 dblclick 事件支持。

Type: Boolean
Default: true

放大或缩小时显示具有图像比例（百分比）的工具提示。

transition

Type: Boolean
Default: true

对一些特殊元素启用 CSS3 过渡。

zIndex

Type: Number
Default: 2015

定义模态模式下查看器的 CSS z-index 值。

zIndexInline

Type: Number
Default: 0

以内联模式定义查看器的 CSS z-index 值。

zoomRatio

Type: Number
Default: 0.1

通过滚动鼠标定义缩放图像时的比例。

minZoomRatio

Type: Number
Default: 0.01

定义缩小时图像的最小比例。

maxZoomRatio

Type: Number
Default: 100

定义图像放大时的最大比例。

url

Type: String or Function
Default: 'src'

定义从何处获取原始图片 URL 以供查看。

如果是字符串，则应为每个图片元素的属性之一。
如果是函数，则应返回有效的图片 URL。

For example:

html 复制代码

<img src="picture.jpg?size=160">

js 复制代码

new Viewer(image, {
  url(image) {
    return image.src.replace('?size=160', '');
  },
});

ready

Type: Function
Default: null

ready 事件的快捷方式。

show

Type: Function
Default: null

show 事件的快捷方式。

shown

Type: Function
Default: null

shown 事件的快捷方式。

hide

Type: Function
Default: null

hide 事件的快捷方式。

hidden

Type: Function
Default: null

hidden 事件的快捷方式。

view

Type: Function
Default: null

view 事件的快捷方式。

viewed

Type: Function
Default: null

Shortcut of the viewed event.

move

Type: Function
Default: null

Shortcut of the move event.

moved

Type: Function
Default: null

Shortcut of the moved event.

rotate

Type: Function
Default: null

Shortcut of the rotate event.

rotated

Type: Function
Default: null

Shortcut of the rotated event.

scale

Type: Function
Default: null

Shortcut of the scale event.

scaled

Type: Function
Default: null

Shortcut of the scaled event.

zoom

Type: Function
Default: null

Shortcut of the zoom event.

zoomed

Type: Function
Default: null

Shortcut of the zoomed event.

play

Type: Function
Default: null

Shortcut of the play event.

stop

Type: Function
Default: null

Shortcut of the stop event.

⬆ back to top

Methods

所有方法都允许链式组合。

由于启动查看器时存在一些异步过程，因此您应该仅在方法可用时调用该方法，请参阅以下生命周期：

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);
  }
});

show([immediate])

immediate (optional):
- Type: Boolean
- Default: false
- Indicates if show the viewer immediately or not.

Show the viewer.

Only available in modal mode.

hide([immediate])

immediate (optional):
- Type: Boolean
- Default: false
- Indicates if hide the viewer immediately or not.

Hide the viewer.

Only available in modal mode.

view([index])

index (optional):
- Type: Number
- Default: 0 (inherits from the initialViewIndex option)
- The index of the image for viewing

查看带有图像索引的其中一张图片。如果查看器被隐藏，则会首先显示该图片。

js 复制代码

viewer.view(1); // View the second image

prev([loop=false])

loop (optional):
- Type: Boolean
- Default: false
- Indicate if turn to view the last one when it is the first one at present.

View the previous image.

next([loop=false])

loop (optional):
- Type: Boolean
- Default: false
- Indicate if turn to view the first one when it is the last one at present.

View the next image.

move(x[, y = x])

x:
- Type: Number
- The moving distance in the horizontal direction.
y (optional):
- Type: Number
- The moving distance in the vertical direction.
- If not present, its default value is x

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

moveTo(x[, y = x])

x:
- Type: Number
- The new position in the horizontal direction.
y (optional):
- Type: Number
- The new position in the vertical direction.
- If not present, its default value is x.

Move the image to an absolute point.

rotate(degree)

degree:
- Type: Number
- 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);

rotateTo(degree)

degree:
- Type: Number

Rotate the image to an absolute degree.

js 复制代码

viewer.rotateTo(0); // Reset to zero degree
viewer.rotateTo(360); // Rotate a full round

scale(scaleX[, scaleY])

scaleX:
- Type: Number
- Default: 1
- The scaling factor to apply on the abscissa of the image
- When equal to 1 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 scaleX.

Scale the image.

js 复制代码

viewer.scale(-1); // Flip both horizontal and vertical
viewer.scale(-1, 1); // Flip horizontal
viewer.scale(1, -1); // Flip vertical

scaleX(scaleX)

scaleX:
- Type: Number
- Default: 1
- The scaling factor to apply on the abscissa of the image
- When equal to 1 it does nothing

Scale the abscissa of the image.

js 复制代码

viewer.scaleX(-1); // Flip horizontal

scaleY(scaleY)

scaleY:
- Type: Number
- Default: 1
- The scaling factor to apply on the ordinate of the image
- When equal to 1 it does nothing

Scale the ordinate of the image.

js 复制代码

viewer.scaleY(-1); // Flip vertical

zoom(ratio[, showTooltip[, pivot]])

ratio:
- Type: Number
- Zoom in: requires a positive number (ratio > 0)
- Zoom out: requires a negative number (ratio < 0)
showTooltip (optional):
- Type: Boolean
- Default: false
- Indicates whether to show the tooltip.
pivot (optional):
- Type: Object
- Default: null
- Schema: { x: Number, y: Number }
- The pivot point coordinate for zooming.

Zoom the image with a relative ratio

js 复制代码

viewer.zoom(0.1);
viewer.zoom(-0.1);

zoomTo(ratio[, showTooltip[, pivot]])

ratio:
- Type: Number
- Requires a positive number (ratio > 0)
showTooltip (optional):
- Type: Boolean
- Default: false
- Indicates whether to show the tooltip.
pivot (optional):
- Type: Object
- Default: null
- Schema: { x: Number, y: Number }
- The pivot point coordinate for zooming.

Zoom the image to an absolute ratio.

js 复制代码

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, {
  x: window.innerWidth / 2,
  y: viewer.innerHeight / 2,
});

play([fullscreen])

fullscreen (optional):
- Type: Boolean or FullscreenOptions
- Default: false
- Indicate if request fullscreen or not.

Play the images.

stop()

Stop play.

full()

Enter the modal mode.

Only available in inline mode.

exit()

Exit the modal mode.

Only available in inline mode.

tooltip()

Show the current ratio of the image by percentage.

Requires the tooltip option set to true.

toggle()

Toggle the image size between its current size and natural size.

Used by the toggleOnDblclick option.

reset()

Reset the image to its initial state.

update()

当源图像发生更改（添加、删除或排序）时，更新查看器实例。

如果您动态加载图像（使用 XMLHTTPRequest），则可以使用此方法将新图像添加到查看器实例。

destroy()

Destroy the viewer and remove the instance.

⬆ back to top

Events

所有事件都可以在其处理程序中使用 this.viewer 来访问查看器实例。

请谨慎将这些事件与其他具有相同事件名称的组件一起使用，例如：Bootstrap 的模态框。

js 复制代码

let viewer;

image.addEventListener('viewed', function () {
  console.log(this.viewer === viewer);
  // > true
});

viewer = new Viewer(image);

ready

event.bubbles: true
event.cancelable: true
event.detail: null

当查看器实例准备好查看时，此事件会触发。

在模态模式下，只有点击其中一张图片时才会触发此事件。

show

event.bubbles: true
event.cancelable: true
event.detail: null

This event fires when the viewer modal starts to show.

Only available in modal mode.

shown

event.bubbles: true
event.cancelable: true
event.detail: null

This event fires when the viewer modal has shown.

Only available in modal mode.

hide

event.bubbles: true
event.cancelable: true
event.detail: null

This event fires when the viewer modal starts to hide.

Only available in modal mode.

hidden

event.bubbles: true
event.cancelable: false
event.detail: null

This event fires when the viewer modal has hidden.

Only available in modal mode.

view

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.

This event fires when a viewer starts to show (view) an image.

viewed

event.bubbles: true
event.cancelable: false
event.detail: the same as the view event.

This event fires when a viewer has shown (viewed) an image.

move

event.bubbles: true
event.cancelable: true
event.detail.x:
- Type: Number
- The new position in the horizontal direction.
event.detail.y:
- Type: Number
- The new position in the vertical direction.
event.detail.oldX:
- Type: Number
- The old position in the horizontal direction.
event.detail.oldY:
- Type: Number
- The old position in the vertical direction.
event.detail.originalEvent:
- Type: Event or null
- Options: pointermove, touchmove, and mousemove.

This event fires when a viewer starts to move an image.

moved

event.bubbles: true
event.cancelable: false
event.detail: the same as the move event.

This event fires when a viewer has moved an image.

rotate

event.bubbles: true
event.cancelable: true
event.detail.degree:
- Type: Number
- The new rotation degrees.
event.detail.oldDegree:
- Type: Number
- The old rotation degrees.

This event fires when a viewer starts to rotate an image.

rotated

event.bubbles: true
event.cancelable: false
event.detail: the same as the rotate event.

This event fires when a viewer has rotated an image.

scale

event.bubbles: true
event.cancelable: true
event.detail.scaleX:
- Type: Number
- The new scaling factor in the horizontal direction.
event.detail.scaleY:
- Type: Number
- The new scaling factor in the vertical direction.
event.detail.oldScaleX:
- Type: Number
- The old scaling factor in the horizontal direction.
event.detail.oldScaleY:
- Type: Number
- The old scaling factor in the vertical direction.

This event fires when a viewer starts to scale an image.

scaled

event.bubbles: true
event.cancelable: false
event.detail: the same as the scale event.

This event fires when a viewer has scaled an image.

zoom

event.bubbles: true
event.cancelable: true
event.detail.ratio:
- Type: Number
- The new (next) ratio of the image (imageData.width / imageData.naturalWidth).
event.detail.oldRatio:
- Type: Number
- The old (current) ratio of the image.
event.detail.originalEvent:
- Type: Event or null
- Options: wheel, pointermove, touchmove, and mousemove.

This event fires when a viewer starts to zoom (in or out) an image.

zoomed

event.bubbles: true
event.cancelable: false
event.detail: the same as the zoom event.

This event fires when a viewer has zoomed (in or out) an image.

play

event.bubbles: true
event.cancelable: true
event.detail: null

This event fires when the viewer starts to play.

You can abort the playing process by calling event.preventDefault().

stop

event.bubbles: true
event.cancelable: true
event.detail: null

This event fires when the viewer starts to stop.

You can abort the stopping process by calling event.preventDefault().

⬆ back to top

No conflict

如果您必须使用具有相同命名空间的另一个查看器，请调用“Viewer.noConflict”静态方法来恢复它。

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

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.

License

⬆ 返回目录

关于项目

Viewerjs是一个功能强大的JavaScript图像查看器。

MIT

Javascript

8,159

1248

123

2015-12-24

2025-01-05

viewerjs是一个功能强大的JavaScript图像查看器

Viewer.js

目录

功能

主要文件

入门

安装

用法

语法

示例

Keyboard support

Options

backdrop

button

navbar

title

toolbar

className

container

filter

fullscreen

inheritedAttributes

initialCoverage

initialViewIndex

inline

interval

keyboard

focus

loading

loop

minWidth

minHeight

movable

rotatable

scalable

zoomable

zoomOnTouch

zoomOnWheel

slideOnTouch

toggleOnDblclick

tooltip

transition

zIndex

zIndexInline

zoomRatio

minZoomRatio

maxZoomRatio

url

ready

show

shown

hide

hidden

view

viewed

move

moved

rotate

rotated

scale

scaled

zoom

zoomed

play

stop

Methods

show([immediate])

hide([immediate])

view([index])

prev([loop=false])

next([loop=false])

move(x[, y = x])

moveTo(x[, y = x])

rotate(degree)

rotateTo(degree)

scale(scaleX[, scaleY])

scaleX(scaleX)

scaleY(scaleY)

zoom(ratio[, showTooltip[, pivot]])

zoomTo(ratio[, showTooltip[, pivot]])