medium-zoom

medium-zoom

一个像Medium那样缩放图片的JavaScript库

🔬 在线试玩 ・ 🔎 演示 ・ 📚 Storybook

特性

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

安装

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

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

下载

• 普通版
• 压缩版

CDN

• jsDelivr
• unpkg
• esm.sh

使用方法

在浏览器中试用

以模块方式导入库：

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选择器
• HTMLElement
• NodeList
• Array

// 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)

选项

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

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="我的图片" />

事件

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

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

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

框架集成

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

• React
• React Markdown
• Vue
• Svelte

示例

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

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

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

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

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

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

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

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} />
}

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

调试

缩放的图像不可见

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

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

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

浏览器支持

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

跨浏览器测试由以下机构赞助

贡献

• 运行 yarn 安装 Node 开发依赖
• 运行 yarn start 以监视模式构建库
• 运行 yarn run storybook 在 http://localhost:9001 查看你的更改

请阅读贡献指南以获取更详细的说明。

你也可以使用 npm。

许可证

MIT © François Chalifour