🚀 两步集成

Step 1

一行代码接入

无需构建工具，直接在 HTML 中引入 UMD 脚本即可。

Step 2

声明属性

给任何 <img> 加上 data-preview，零结构性改动。

HTML<script src="https://unpkg.com/data-preview/dist/data-preview.umd.js"></script>
<script>DataPreview.init()</script>
<img src="thumb.jpg" data-preview data-preview-src="large.jpg" />

🤖 天然适合 AI 生成

LLM 只需在输出 HTML 中添加 data-preview 属性，无需操心任何交互逻辑。声明即所得。

AI Prompt → HTML用户：生成一个商品列表页
AI：<div class="product">
      <img src="p1.jpg" data-preview data-preview-src="p1-hd.jpg" />
      ...
    </div>

基于 data-preview 语义协议，以下四种用法涵盖所有场景。鼠标悬停图片体验预览效果。

非 img 元素

摄影 城市天际线 收藏级高清摄影作品
悬停或长按查看大图

<div data-preview data-preview-src="large.jpg" data-preview-label="城市天际线 · 摄影作品 · 1920×1080 高清原图">
  <span>摄影</span>
  <strong>城市天际线</strong>
  <span>收藏级高清摄影作品</span>
</div> 任意容器元素皆可触发预览，附带标题、标签与说明

🖱️ 交互方式

🖼️ PC：悬浮 → 预览图标 → 悬停弹出大图 👆 移动端：点击触发预览 🌙 自动深色模式

⚙️ 配置项

在 init() 前修改 DataPreview.config 对象：

DataPreview.config.imgPad = 12
DataPreview.config.maxWRatio = 0.85
DataPreview.init()

配置项	默认值	说明
imgPad	8	预览框内边距 (px)
maxWRatio	0.9	预览框最大宽度占窗口比例
maxHRatio	0.85	预览框最大高度占窗口比例
delayHide	150	鼠标离开后隐藏延迟 (ms)
badgeOffset	6	预览图标距离元素右上角的偏移量 (px)

🌐 语义协议

所有 HTML 属性一览：

属性	说明
data-preview	标记元素支持预览（必需）
data-preview-src	大图 URL（省略则复用 src/currentSrc）
data-preview-label	预览图底部标注文本（省略则显示尺寸）

🧩 框架无关

React / Vue / Solid / 原生 HTML — 所有框架的用法一致，仅需在生命周期中调用 init() 与 destroy()。

HTML (UMD)

ESM

import DataPreview from 'data-preview' DataPreview.init()

React

useEffect(() => { DataPreview.init() return () => DataPreview.destroy() }, [])

Vue

onMounted(() => DataPreview.init()) onUnmounted(() => DataPreview.destroy())

📱 移动端

通过 (pointer: coarse) 自动识别触摸设备，点击触发预览，点击遮罩或 ✕ 关闭。无需额外配置。

📘 TypeScript

包含内置类型声明，无需安装 @types。

import DataPreview from 'data-preview'
DataPreview.config.imgPad = 12
DataPreview.init()

🌍 浏览器支持

Chrome · Edge · Safari · Firefox 所有现代浏览器。UMD + ESM 双格式，兼容各类工程场景。

🔧 API 参考

所有方法挂载在全局 DataPreview 对象上：

DataPreview.init(selector?)

全局初始化。扫描页面中所有匹配元素并绑定，同时启动 MutationObserver 监听后续动态插入的元素。

DataPreview.init()                  // 默认绑定 [data-preview]
DataPreview.init('.product-card') // 自定义选择器

DataPreview.bind(el)

手动绑定单个元素，幂等，重复调用无副作用。

DataPreview.bind(document.querySelector('.my-img'))

DataPreview.bindAll(selector)

手动批量绑定，适合虚拟列表、分页加载等场景。

DataPreview.bindAll('.product-list img')

DataPreview.unbind(el)

解绑单个元素，移除所有事件监听。

DataPreview.unbind(el)

DataPreview.destroy()

完全销毁 runtime，清理 DOM、事件监听、MutationObserver、预加载缓存。适用于 SPA 路由切换。

DataPreview.destroy()