medium-zoom

<a href="https://medium-zoom.francoischalifour.com"><img src="https://yellow-cdn.veclightyear.com/835a84d5/40d495dc-8f0a-421b-96a0-86b90bd60bfd.svg" alt="演示" width="64"></a> <h3 align="center">medium-zoom</h3> 一个像Medium那样缩放图片的JavaScript库 <a href="https://www.npmjs.com/package/medium-zoom"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/4d478d0c-65b1-42fe-a8d7-30d149978f24.svg?style=flat-square" alt="版本"> </a> <a href="https://github.com/francoischalifour/medium-zoom/blob/master/LICENSE"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/d7bb45ba-9523-4d48-b220-922c0e3a3029.svg?style=flat-square" alt="MIT许可证"> </a> <a href="http://npmcharts.com/compare/medium-zoom"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/7e4d3dcd-bdb4-4831-a72c-180d1356528e.svg?style=flat-square" alt="下载量"> </a> <a href="https://unpkg.com/medium-zoom/dist/"> <img src="http://img.badgesize.io/https://unpkg.com/medium-zoom/dist/medium-zoom.min.js?compression=gzip&label=gzip%20size&style=flat-square" alt="gzip大小"> </a> <a href="https://github.com/francoischalifour/medium-zoom/blob/master/package.json"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/33d3138a-305e-4b75-824b-c61d30f3f98d.svg?style=flat-square" alt="无依赖"> </a> <a href="https://medium-zoom.francoischalifour.com"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/325fd340-b5f2-4081-b640-342ed0bfa2b5.gif" alt="Medium Zoom 演示"> </a> <a href="https://codesandbox.io/s/github/francoischalifour/medium-zoom/tree/master/website">🔬 在线试玩</a> ・ <a href="https://medium-zoom.francoischalifour.com">🔎 演示</a> ・ <a href="https://medium-zoom.francoischalifour.com/storybook">📚 Storybook</a> <details> <summary>目录</summary>  </details>

特性

📱 响应式 — 在移动端和桌面端都能缩放
🚀 高性能且轻量 — 优化以达到60帧每秒
⚡️ 支持高清 — 缩放时加载图片的高清版本
🔎 灵活性 — 可以对选定的图片应用缩放
🖱 支持鼠标、键盘和手势 — 点击任意位置、按键或滚动都可关闭缩放
🎂 事件处理 — 缩放进入新状态时触发事件
📦 可定制 — 设置自己的边距、背景和滚动偏移量
🔧 可扩展 — 为缩放添加自己的功能
💎 自定义模板 — 扩展默认外观以匹配你的应用界面
🔌 框架无关 — 适用于React、Vue、Angular、Svelte、Solid等

安装

该模块可在 npm 仓库中找到。

npm install medium-zoom
# 或
yarn add medium-zoom

下载

CDN

使用方法

在浏览器中试用

以模块方式导入库：

import mediumZoom from 'medium-zoom'

或通过script标签导入库：

<script src="node_modules/medium-zoom/dist/medium-zoom.min.js"></script>

就这么简单！你不需要导入任何CSS样式。

假设你给图片添加了data-zoomable属性：

mediumZoom('[data-zoomable]')

[!提示] 如果你想控制何时注入Medium Zoom的CSS样式，可以使用纯JavaScript包：
import mediumZoom from 'medium-zoom/dist/pure'
import 'medium-zoom/dist/style.css'

API

mediumZoom(selector?: string | HTMLElement | HTMLElement[] | NodeList, options?: object): Zoom

选择器

选择器用于将图片附加到缩放。它可以是以下类型之一：

// CSS选择器
mediumZoom('[data-zoomable]')

// HTMLElement
mediumZoom(document.querySelector('#cover'))

// NodeList
mediumZoom(document.querySelectorAll('[data-zoomable]'))

// 数组
const images = [
  document.querySelector('#cover'),
  ...document.querySelectorAll('[data-zoomable]'),
]

mediumZoom(images)

选项

选项用于自定义缩放。它们被定义为一个具有以下属性的对象：

属性	类型	默认值	描述
`margin`	`number`	`0`	缩放图片外的空间
`background`	`string`	`"#fff"`	遮罩层的背景
`scrollOffset`	`number`	`40`	关闭缩放需要滚动的像素数
`container`	`string` \| `HTMLElement` \| `object`	`null`	渲染缩放的视口<br> 了解更多 →
`template`	`string` \| `HTMLTemplateElement`	`null`	缩放时显示的模板元素<br> 了解更多 →

mediumZoom('[data-zoomable]', {
  margin: 24,
  background: '#BADA55',
  scrollOffset: 0,
  container: '#zoom-container',
  template: '#zoom-template',
})

方法

`open({ target?: HTMLElement }): Promise<Zoom>`

打开缩放并返回一个解析为缩放对象的Promise。

const zoom = mediumZoom('[data-zoomable]')

zoom.open()

动画开始时触发open事件，完成时触发opened事件。

`close(): Promise<Zoom>`

关闭缩放并返回一个解析为缩放对象的Promise。

const zoom = mediumZoom('[data-zoomable]')

zoom.close()

动画开始时触发close事件，完成时触发closed事件。

`toggle({ target?: HTMLElement }): Promise<Zoom>`

当关闭时打开缩放，当打开时关闭缩放，并返回一个解析为缩放对象的Promise。

const zoom = mediumZoom('[data-zoomable]')

zoom.toggle()

`attach(...selectors: string[] | HTMLElement[] | NodeList[] | Array[]): Zoom`

将图片附加到缩放并返回缩放对象。

const zoom = mediumZoom()

zoom.attach('#image-1', '#image-2')
zoom.attach(
  document.querySelector('#image-3'),
  document.querySelectorAll('[data-zoomable]')
)

`detach(...selectors: string[] | HTMLElement[] | NodeList[] | Array[]): Zoom`

从缩放中释放图片并返回缩放对象。

const zoom = mediumZoom('[data-zoomable]')

zoom.detach('#image-1', document.querySelector('#image-2')) // 分离两张图片
zoom.detach() // 分离所有图片

在图片上触发detach事件。

`update(options: object): Zoom`

更新选项并返回缩放对象。

const zoom = mediumZoom('[data-zoomable]')

zoom.update({ background: '#BADA55' })

在缩放的每张图片上触发update事件。

`clone(options?: object): Zoom`

克隆缩放，将提供的选项与当前选项合并，并返回缩放对象。

const zoom = mediumZoom('[data-zoomable]', { background: '#BADA55' })

const clonedZoom = zoom.clone({ margin: 48 })

clonedZoom.getOptions() // => { background: '#BADA55', margin: 48, ... }

`on(type: string, listener: () => void, options?: boolean | AddEventListenerOptions): Zoom`

在缩放的每个目标上注册监听器。

使用与addEventListener相同的options。

const zoom = mediumZoom('[data-zoomable]')

zoom.on('closed', event => {
  // 图片已关闭
})

zoom.on(
  'open',
  event => {
    // 图片已打开（仅跟踪一次）
  },
  { once: true }
)

缩放对象可在event.detail.zoom中访问。

`off(type: string, listener: () => void, options?: boolean | AddEventListenerOptions): Zoom`

移除之前在缩放的每个目标上注册的监听器。

使用与removeEventListener相同的options。

const zoom = mediumZoom('[data-zoomable]')

function listener(event) {
  // ...
}

zoom.on('open', listener)
// ...
zoom.off('open', listener)

缩放对象可在event.detail.zoom中访问。

`getOptions(): object`

以对象形式返回缩放选项。

const zoom = mediumZoom({ background: '#BADA55' })

zoom.getOptions() // => { background: '#BADA55', ... }

`getImages(): HTMLElement[]`

以HTMLElement数组形式返回附加到缩放的图片。

const zoom = mediumZoom('[data-zoomable]')

zoom.getImages() // => [HTMLElement, HTMLElement]

`getZoomedImage(): HTMLElement`

返回当前缩放的图像作为 HTMLElement 或 null（如果没有）。

const zoom = mediumZoom('[data-zoomable]')

zoom.getZoomedImage() // => null
zoom.open().then(() => {
  zoom.getZoomedImage() // => HTMLElement
})

属性

`data-zoom-src`

指定在缩放时打开的高清图像。当用户点击源图像时，此图像会加载。

<img src="https://raw.githubusercontent.com/francoischalifour/medium-zoom/master/image-thumbnail.jpg" data-zoom-src="image-hd.jpg" alt="我的图片" />

事件

事件	描述
open	当调用 `open` 方法时立即触发
opened	当缩放动画完成时触发
close	当调用 `close` 方法时立即触发
closed	当缩小动画完成时触发
detach	当调用 `detach` 方法时触发
update	当调用 `update` 方法时触发

const zoom = mediumZoom('[data-zoomable]')

zoom.on('open', event => {
  // 在图像被缩放时进行跟踪
})

缩放对象可以通过 event.detail.zoom 访问。

框架集成

Medium Zoom 是一个可以与任何框架一起使用的 JavaScript 库。以下是一些可以快速入门的集成方案：

示例

<details> <summary>从另一个元素触发缩放</summary>

const button = document.querySelector('[data-action="zoom"]')
const zoom = mediumZoom('#image')

button.addEventListener('click', () => zoom.open())

</details> <details> <summary>跟踪事件（用于分析）</summary>

你可以使用 open 事件来跟踪用户与图像交互的次数。这对于收集用户参与度的分析数据很有用。

let counter = 0
const zoom = mediumZoom('#image-tracked')

zoom.on('open', event => {
  console.log(`"${event.target.alt}" 已被缩放 ${++counter} 次`)
})

</details> <details> <summary>关闭后分离缩放</summary>

const zoom = mediumZoom('[data-zoomable]')

zoom.on('closed', () => zoom.detach(), { once: true })

</details> <details> <summary>附加 jQuery 元素</summary>

jQuery 元素在转换为数组后与 medium-zoom 兼容。

mediumZoom($('[data-zoomable]').toArray())

</details> <details> <summary>创建可缩放的 React 组件</summary>

import React, { useRef } from 'react'
import mediumZoom from 'medium-zoom'

export function ImageZoom({ options, ...props }) {
  const zoomRef = useRef(null)

  function getZoom() {
    if (zoomRef.current === null) {
      zoomRef.current = mediumZoom(options)
    }

    return zoomRef.current
  }

  function attachZoom(image) {
    const zoom = getZoom()

    if (image) {
      zoom.attach(image)
    } else {
      zoom.detach()
    }
  }

  return <img {...props} ref={attachZoom} />
}

</details>

你可以查看更多示例，包括 React 和 Vue，或者查看 storybook。

调试

缩放的图像不可见

该库不为缩放的图像提供 z-index 值，以避免与其他框架冲突。某些框架可能为其元素指定了 z-index，导致缩放的图像不可见。

如果出现这种情况，你可以在 CSS 中提供 z-index 值：

.medium-zoom-overlay,
.medium-zoom-image--opened {
  z-index: 999;
}

浏览器支持

IE	Edge	Chrome	Firefox	Safari
10<sup>*</sup>	12<sup>*</sup>	36	34	9

* 这些浏览器在使用自定义模板时需要 template 填充。

<blockquote> 跨浏览器测试由以下机构赞助 <a href="https://www.browserstack.com"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/f1d6ad9e-0b2e-458a-b0a7-f1a462fd58dd.png" alt="BrowserStack" height="35"> </a> </blockquote>