data-preview

AI-native semantic preview runtime for modern web.

一个零依赖、框架无关、支持 AI 生成页面的智能预览运行时。

Features

• Zero Dependency
• Framework Agnostic
• Hover Preview（PC）/ Tap Preview（Mobile）
• Smart Positioning — 自动适应窗口边界与图片比例
• SPA Compatible — 内置 destroy() 支持路由卸载
• Auto Dark Mode
• Dynamic DOM — 内置 MutationObserver，动态内容自动绑定
• Semantic Protocol Driven

Install

npm install data-preview

Usage

CDN方式

直接集成

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

ESM

现在模块化集成，需要编译

Native HTML

<img src="./thumb.jpg" data-preview />

<script type="module">
  import DataPreview from 'data-preview'
  DataPreview.init()
</script>

React

import { useEffect } from 'react'
import DataPreview from 'data-preview'

export default function App() {
  useEffect(() => {
    DataPreview.init()
    return () => DataPreview.destroy()
  }, [])

  return <img src="/thumb.jpg" data-preview data-preview-src="/large.jpg" />
}

Vue

<script setup>
import { onMounted, onUnmounted } from 'vue'
import DataPreview from 'data-preview'

onMounted(() => DataPreview.init())
onUnmounted(() => DataPreview.destroy())
</script>

<template>
  <img src="/thumb.jpg" data-preview data-preview-src="/large.jpg" />
</template>

Semantic Protocol

data-preview 基于 data-preview 语义协议工作，只需在元素上声明属性，runtime 自动增强交互能力。

最简用法

<img src="demo.jpg" data-preview />

原图与缩略图分离

<img src="thumb.jpg" data-preview data-preview-src="large.jpg" />

自定义标注

<img src="demo.jpg" data-preview data-preview-label="产品展示图" />

非 img 元素

<div data-preview data-preview-src="large.jpg">
  <img src="thumb.jpg" />
</div>

API

DataPreview.init(selector?)

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

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

DataPreview.bind(el)

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

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

DataPreview.bindAll(selector)

手动批量绑定，适合虚拟列表、分页加载等场景（此时建议关闭 MutationObserver 自动绑定）。

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

DataPreview.unbind(el)

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

DataPreview.unbind(el)

DataPreview.destroy()

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

DataPreview.destroy()

Config

在 init() 前修改配置项：

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 |

Mobile

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

TypeScript

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

import DataPreview from 'data-preview'

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

Browser Support

Chrome、Edge、Safari、Firefox 所有现代浏览器。

License

MIT