# @fisch0920/medium-zoom 中文文档 规范地址：https://npmcn.com/package/%40fisch0920/medium-zoom/ 版本：1\.0\.7 npm 元数据更新时间：2022-04-11T23:24:24.265Z 中文译文更新时间：2026-11-14T20:20:33.174Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40fisch0920/medium-zoom 原文对照：https://npmcn.com/package/%40fisch0920/medium-zoom/?lang=original 源码仓库：https://github.com/francoischalifour/medium-zoom ## 关键信息（来自 npm 元数据） - 包体积（解压后）：82 kB，10 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：0 个 - 首次发布：2022-04-11T23:21:19.911Z - 最新版本发布：2022-04-11T23:24:24.181Z - 近 30 天下载量：239910（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：2（近 12 个月 0 个） ## 中文简介 用于缩放像中图像的 JavaScript 库 ## 安装 ```sh npm install @fisch0920/medium-zoom ``` 也可以使用：`pnpm add @fisch0920/medium-zoom`、`yarn add @fisch0920/medium-zoom`、`bun add @fisch0920/medium-zoom` ## README [![Demo](https://npmcn.com/package/%40fisch0920/medium-zoom/logo.svg)](https://medium-zoom.francoischalifour.com/) ### 中区 用于缩放像中图像的 JavaScript 库 [![version](https://img.shields.io/npm/v/medium-zoom.svg?style=flat-square)](https://www.npmjs.com/package/medium-zoom)[![MIT license](https://img.shields.io/npm/l/medium-zoom.svg?style=flat-square) ](https://github.com/francoischalifour/medium-zoom/blob/master/LICENSE)[![downloads](https://img.shields.io/npm/dm/medium-zoom.svg?style=flat-square)](http://npmcharts.com/compare/medium-zoom) [![gzip size](http://img.badgesize.io/https://unpkg.com/medium-zoom/dist/medium-zoom.min.js?compression=gzip&label=gzip%20size&style=flat-square)](https://unpkg.com/medium-zoom/dist/)[![no dependencies](https://img.shields.io/badge/dependencies-none-lightgrey.svg?style=flat-square) ](https://github.com/francoischalifour/medium-zoom/blob/master/package.json)[![travis](https://img.shields.io/travis/francoischalifour/medium-zoom.svg?style=flat-square)](https://travis-ci.org/francoischalifour/medium-zoom) [![Medium Zoom Demo](https://user-images.githubusercontent.com/6137112/43369906-7623239a-9376-11e8-978b-6e089be499fb.gif)](https://medium-zoom.francoischalifour.com/) **[游戏场](https://codesandbox.io/s/github/francoischalifour/medium-zoom/tree/master/website) ・ [德莫语](https://medium-zoom.francoischalifour.com/) ・ [· 故事本](https://medium-zoom.francoischalifour.com/storybook)** **目录** - [特征](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-features) - [安装](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-installation) - [使用量](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-usage) - [API 密码](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-api) - [选择器](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-selectors) - [选项](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-options) - [方法](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-methods) - [属性](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-attributes) - [活动](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-events) - [实例](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-examples) - [调试](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-debugging) - [浏览器支持](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-browser-support) - [捐款](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-contributing) - [许可证](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-license) ## 特征 - 📱 **响应** —— 说 _移动和桌面上的缩放_ - 🚀 **表演和轻量级** —— 说 _应该能达到60岁 [fps 数据](https://en.wikipedia.org/wiki/Frame_rate)_ - ⚡️ **高定义支持** —— 说 _将您的图像 HD 版本装入缩放_ - 🔎 **灵活性** —— 说 _将缩放应用到选定的图像_ - 🖱 **鼠标、键盘和手势友好** —— 说 _单击任何地方,按键或滚动向外键关闭缩放_ - 🎂 **事件处理** —— 说 _当缩放进入新状态时触发事件_ - 📦 **自定义** —— 说 _设置您自己的边距、 背景和滚动相左_ - 🔧 **可插件** —— 说 _将自己的特性添加到缩放中_ - 💎 **自定义模板** —— 说 _扩展默认视图以匹配您的应用程序的 UI_ ## 安装 该模块可在 [无](https://www.npmjs.com/) 登记. ```sh npm install medium-zoom # or yarn add medium-zoom ``` ###### 下载 - [常规](https://cdn.jsdelivr.net/npm/medium-zoom/dist/medium-zoom.js) - [已缩小](https://cdn.jsdelivr.net/npm/medium-zoom/dist/medium-zoom.min.js) ###### 光盘N - [日记](https://www.jsdelivr.com/package/npm/medium-zoom) - [(单位:公斤)](https://unpkg.com/medium-zoom/) ## 使用量 > [在浏览器里试试](https://codesandbox.io/s/github/francoischalifour/medium-zoom/tree/master/website) 导入库为模块 : ```js import mediumZoom from 'medium-zoom' ``` 或用脚本标记导入库 : ```html ``` 就这样! 您不需要导入任何 CSS 样式 . 假设您添加 `data-zoomable` 图像属性 : ```js mediumZoom('[data-zoomable]') ``` ## API 密码 ```ts mediumZoom(selector?: string | HTMLElement | HTMLElement[] | NodeList, options?: object): Zoom ``` ### 选择器 选择器允许将图像附加到缩放上 。 它可以分为以下几种类型: - [CSS 选择器](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors) - [`HTMLElement`](https://developer.mozilla.org/docs/Web/API/HTMLElement) - [`NodeList`](https://developer.mozilla.org/docs/Web/API/NodeList) - [`Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array) ```js // CSS selector mediumZoom('[data-zoomable]') // HTMLElement mediumZoom(document.querySelector('#cover')) // NodeList mediumZoom(document.querySelectorAll('[data-zoomable]')) // Array 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` | 缩放的取景口 [更多信息](https://npmcn.com/package/%40fisch0920/medium-zoom/docs/container.md) | | `template` | `string` | `HTMLTemplateElement` | `null` | 缩放时要显示的模板元素 [更多信息](https://npmcn.com/package/%40fisch0920/medium-zoom/docs/template.md) | ```js mediumZoom('[data-zoomable]', { margin: 24, background: '#BADA55', scrollOffset: 0, container: '#zoom-container', template: '#zoom-template', }) ``` ### 方法 #### `open({ target?: HTMLElement }): Promise` 打开缩放并返回用缩放解析的保证. ```js const zoom = mediumZoom('[data-zoomable]') zoom.open() ``` _显示事件 [`open`](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-events) 动画开始和 [`opened`](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-events) 完成时._ #### `close(): Promise` 关闭缩放并返回用缩放解析的保证 . ```js const zoom = mediumZoom('[data-zoomable]') zoom.close() ``` _显示事件 [`close`](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-events) 动画开始和 [`closed`](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-events) 完成时._ #### `toggle({ target?: HTMLElement }): Promise` 当关闭时打开缩放 / 当打开时删除缩放 , 并返回与缩放解析的保证 . ```js const zoom = mediumZoom('[data-zoomable]') zoom.toggle() ``` #### `attach(...selectors: string[] | HTMLElement[] | NodeList[] | Array[]): Zoom` 将图像附于缩放并返回缩放. ```js 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` 从缩放中释放图像并返回缩放. ```js const zoom = mediumZoom('[data-zoomable]') zoom.detach('#image-1', document.querySelector('#image-2')) // detach two images zoom.detach() // detach all images ``` _显示事件 [`detach`](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-events) 在图像._ #### `update(options: object): Zoom` 更新选项并返回缩放. ```js const zoom = mediumZoom('[data-zoomable]') zoom.update({ background: '#BADA55' }) ``` _显示事件 [`update`](https://npmcn.com/package/%40fisch0920/medium-zoom/#readme-events) 在缩放的每个图像上._ #### `clone(options?: object): Zoom` 以所提供的选项将 Clones 缩放与当前选项合并并返回缩放 . ```js 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` 在缩放的每个目标上注册听众. 一样 `options` 作为 [`addEventListener`](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener#Parameters) 被使用. ```js const zoom = mediumZoom('[data-zoomable]') zoom.on('closed', event => { // the image has been closed }) zoom.on( 'open', event => { // the image has been opened (tracked only once) }, { once: true } ) ``` 缩放对象可以在 `event.detail.zoom`。 。 。 . #### `off(type: string, listener: () => void, options?: boolean | AddEventListenerOptions): Zoom` 删除缩放每个目标上先前已注册的收听器. 一样 `options` 作为 [`removeEventListener`](https://developer.mozilla.org/docs/Web/API/EventTarget/removeEventListener#Parameters) 被使用. ```js const zoom = mediumZoom('[data-zoomable]') function listener(event) { // ... } zoom.on('open', listener) // ... zoom.off('open', listener) ``` 缩放对象可以在 `event.detail.zoom`。 。 。 . #### `getOptions(): object` 返回缩放选项为对象. ```js const zoom = mediumZoom({ background: '#BADA55' }) zoom.getOptions() // => { background: '#BADA55', ... } ``` #### `getImages(): HTMLElement[]` 返回附在缩放上的图像,作为 [`HTMLElement`编号](https://developer.mozilla.org/docs/Web/API/HTMLElement)。 。 。 . ```js const zoom = mediumZoom('[data-zoomable]') zoom.getImages() // => [HTMLElement, HTMLElement] ``` #### `getZoomedImage(): HTMLElement` 返回当前缩放的图像 [`HTMLElement`](https://developer.mozilla.org/docs/Web/API/HTMLElement) 或者说 `null` 如果没有. ```js const zoom = mediumZoom('[data-zoomable]') zoom.getZoomedImage() // => null zoom.open().then(() => { zoom.getZoomedImage() // => HTMLElement }) ``` ### 属性 #### `data-zoom-src` 指定在缩放时打开的高定义图像。 此图像在用户点击源图像时会加载. ```html My image ``` ### 活动 | 活动 | 说明 | | --- | --- | | 打开 | 立即开火 `open` 方法称为 | | 打开 | 当缩放完成动画时被解除 | | 关闭 | 立即开火 `close` 方法称为 | | 关闭 | 当缩放完成动画时被点燃 | | 调离 | 发射时 `detach` 方法称为 | | 更新 | 发射时 `update` 方法称为 | ```js const zoom = mediumZoom('[data-zoomable]') zoom.on('open', event => { // track when the image is zoomed }) ``` 缩放对象可以在 `event.detail.zoom`。 。 。 . ## 实例 从另一个元素触发缩放 ```js const button = document.querySelector('[data-action="zoom"]') const zoom = mediumZoom('#image') button.addEventListener('click', () => zoom.open()) ``` 跟踪事件( 用于分析) 你可以用这个 `open` 用于跟踪用户与您图像交互次数的事件。 如果您想要收集一些关于用户参与的分析数据, 这会有所帮助 . ```js let counter = 0 const zoom = mediumZoom('#image-tracked') zoom.on('open', event => { console.log(`"${event.target.alt}" has been zoomed ${++counter} times`) }) ``` 关闭后切开缩放 ```js const zoom = mediumZoom('[data-zoomable]') zoom.on('closed', () => zoom.detach(), { once: true }) ``` 附加 j 查询元素 j 查询元素兼容 `medium-zoom` 已转换为数组. ```js mediumZoom($('[data-zoomable]').toArray()) ``` 创建可缩放的回放组件 **使用反应钩** ```js import React from 'react' import mediumZoom from 'medium-zoom' function ImageZoom({ zoom, src, alt, background }) { const zoomRef = React.useRef(zoom.clone({ background })) function attachZoom(image) { zoomRef.current.attach(image) } return {alt} } function App() { const zoom = React.useRef(mediumZoom({ background: '#000', margin: 48 })) render() { return ( ) } } ``` **使用反应类** ```js import React, { Component } from 'react' import mediumZoom from 'medium-zoom' class ImageZoom extends Component { zoom = this.props.zoom.clone({ background: this.props.color, }) attachZoom = image => { this.zoom.attach(image) } render() { return ( {this.props.alt} ) } } class App extends Component { zoom = mediumZoom({ background: '#000', margin: 48 }) render() { return ( ) } } ``` 你看见了 [更多实例](https://npmcn.com/package/%40fisch0920/medium-zoom/examples/) 包括 [反应](https://npmcn.com/package/%40fisch0920/medium-zoom/examples/react) 财务报告和审定财务报表 [阴道](https://npmcn.com/package/%40fisch0920/medium-zoom/examples/vue),或检查 [故事书](https://medium-zoom.francoischalifour.com/storybook)。 。 。 . ## 调试 缩放的图像不可见 图书馆不提供 `z-index` 值在缩放图像上,以避免与其他框架相冲突。 一些框架可规定 `z-index` 他们的元素, 这使得放大的图像不可见. 如果是这样,你可以提供 `z-index` 您 CSS 中的值 : ```css .medium-zoom-overlay, .medium-zoom-image--opened { z-index: 999; } ``` ## 浏览器支持 | 独立 | 边缘 | 颜色 | 火花 | 萨法里 | | --- | --- | --- | --- | --- | | 10个\* 联合国 | 第12条\* 联合国 | 第36条 | 页:1 | 第9条 | \* 联合国 _这些浏览器需要 [`template` 多边填充](https://github.com/webcomponents/template) 使用时 [自定义模板](https://npmcn.com/package/%40fisch0920/medium-zoom/docs/template.md)_。 。 。 . > 交叉浏览器测试由 > > [![BrowserStack](https://user-images.githubusercontent.com/6137112/44587083-35987000-a7b2-11e8-8e0d-8ba15de83802.png)](https://www.browserstack.com/) ## 捐款 - 运行 `yarn` 以安装节点依赖 - 运行 `yarn start` 以监视模式构建库 - 运行 `yarn run storybook` 在http://localhost:9001上查看您的更改 请读一下 [提供指南](https://npmcn.com/package/%40fisch0920/medium-zoom/CONTRIBUTING.md) 更详细的解释. _您还可以使用 [无](https://www.npmjs.com/)。 。 。 ._ ## 许可证 麻省理工学院 [弗朗索瓦·查利福尔](https://francoischalifour.com/) ## 常见问题 ### @fisch0920/medium-zoom 是什么？ 用于缩放像中图像的 JavaScript 库 ### 如何安装 @fisch0920/medium-zoom？ 在项目目录运行 npm install @fisch0920/medium-zoom，或使用 pnpm add / yarn add / bun add。 ### @fisch0920/medium-zoom 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @fisch0920/medium-zoom 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @fisch0920/medium-zoom 可以商用吗？ @fisch0920/medium-zoom 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @fisch0920/medium-zoom 的下载量有多少？ 根据 npm 官方下载统计，@fisch0920/medium-zoom 在 2026/10/15 – 2026/11/13 这 30 天内被下载 239,910 次，日均约 7,997 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @fisch0920/medium-zoom 还在维护吗？ 最新版本 1\.0\.7 发布于 2022/04/12（4 年前）；至今共发布 2 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/04/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。