前言
这次来还账了,之前的文章# 【Vue3 实战】从0到1封装一个“框选截图”组件,顺便聊聊 html2canvas 的那些“坑”承诺会把这个框选截图组件封装成npm并开源,这下是真的来了,我给这个插件取名为Region-snap,现在已在github上开源,npm也同步发布了,如标题一样支持Vue和React,还支持Javascript,快去一起使用吧!
背景
话不多说,接下来说说这个插件的背景。做文档预览、在线阅读器或者后台系统时,我们可能遇到这样的需求:
用户在页面上框选一段内容,把它变成图片,再上传、保存,或者交给 OCR 接口识别。
比如,从扫描件里截取一道题,从 PDF 页面里选出一个表格,或者在文档预览中截取一段内容用于反馈。
第一反应通常是:画一个选框,再用 html2canvas 截图,应该就够了。
但真正接入业务后,问题会逐渐出现:
- 容器滚动后,选框和截图内容还能不能对齐?
- 文档缩放后,坐标该怎么换算?
- PDF 本身已经渲染成 canvas,是否还需要重新渲染?
- 用户框选完成后,能不能移动选区、调整大小?
- 第三方 iframe 里的文档,又该怎么截?
region-snap 就是围绕这类需求做的一个区域截图库:在网页内容上拖动框选,再把选区转换成图片。
先看一下实际效果:
完整操作:拖动框选内容 → 调整选区大小 → 点击按钮生成截图。
一、从框选到截图,交互是什么样的?
以试卷预览为例,用户先在题目上拖出一个矩形选区。
框选完成后,组件显示选区尺寸、调整手柄,以及业务自定义的工具栏。
第一步:拖动框选。工具栏会跟随选区显示。
如果第一次没有选完整,可以继续拖动手柄,扩大或缩小选区,也可以直接移动整个选区。
第二步:调整选区,把完整题目纳入截图范围。
确认范围后,点击工具栏里的按钮获取图片。演示页将结果展示在右侧,业务中也可以直接上传、下载,或者提交给 OCR 接口。
第三步:生成截图。输出内容对应左侧选区,不包含选区框和工具栏。
region-snap 提供三个包:
| 包名 | 用途 |
|---|---|
@region-snap/core | 框架无关的核心 |
@region-snap/vue | Vue 3.3+ 组件 |
@region-snap/react | React 17+ 组件 |
下面先从 Vue 接入开始。
二、在 Vue 中接入区域截图
安装组件:
npm i @region-snap/vue
把需要框选的内容放进 RegionSnap,通过工具栏插槽拿到截图方法:
<script setup lang="ts">
import { RegionSnap } from '@region-snap/vue'
async function upload(
getFile: () => Promise<File | null>,
clear: () => void,
) {
try {
const file = await getFile()
if (!file) return
const body = new FormData()
body.append('file', file)
// 替换为你自己的上传或 OCR 接口
const response = await fetch('/api/ocr', {
method: 'POST',
body,
})
if (!response.ok) {
throw new Error('上传失败')
}
clear()
} catch (error) {
console.error('截图或上传失败', error)
}
}
</script>
<template>
<RegionSnap
style="height: 600px"
mask
show-size
:capture-options="{
minWidth: 300,
minHeight: 100,
}"
>
<img
src="/paper.png"
alt="待识别文档"
style="display: block; max-width: 100%"
/>
<template #toolbar="{ getFile, clear, capturing }">
<button
:disabled="capturing"
@click="upload(getFile, clear)"
>
识别文字
</button>
<button @click="clear()">取消</button>
</template>
</RegionSnap>
</template>
这里有几个值得注意的地方。
mask 用于显示选区外的遮罩,show-size 用于展示选区尺寸。组件样式会自动注入,无需额外导入 CSS 文件。
getFile() 返回的是 Promise<File | null>。默认情况下,框选完成后组件会在后台开始截图;如果调用时截图尚未完成,这个方法会等待结果。
示例中的 minWidth 和 minHeight 用于设置输出图片的最小尺寸。选区截图不足这个尺寸时,会居中补白,适合对图片尺寸有要求的接口。
补白不会拉伸原图,也不会凭空增加图像细节。
region-snap 负责选区和图片输出,OCR 识别由业务接口完成。
三、React 的接入方式也类似
安装:
npm i @region-snap/react
通过 renderToolbar 定义工具栏:
import { useState } from 'react'
import { RegionSnap } from '@region-snap/react'
export default function CaptureDemo() {
const [preview, setPreview] = useState<string | null>(null)
return (
<>
<RegionSnap
style={{ height: 600 }}
mask
showSize
renderToolbar={({ getImage, clear, capturing }) => (
<>
<button
disabled={capturing}
onClick={async () => {
try {
const image = await getImage()
if (image) setPreview(image)
} catch (error) {
console.error('截图失败', error)
}
}}
>
生成截图
</button>
<button onClick={clear}>取消</button>
</>
)}
>
<img
src="/paper.png"
alt="待截图文档"
style={{ display: 'block', maxWidth: '100%' }}
/>
</RegionSnap>
{preview && <img src={preview} alt="截图预览" />}
</>
)
}
Vue 和 React 两个版本提供相同的三种输出形式:
| 方法 | 返回结果 | 常见用途 |
|---|---|---|
getImage() | Data URL | 页面预览 |
getBlob() | Blob | 上传、后续图片处理 |
getFile() | File | 文件上传 |
输出支持 PNG、JPEG 和 WebP。
工具栏里的按钮由业务定义,因此可以把“生成截图”换成“识别文字”“保存附件”或者“提交反馈”,复用同一套框选交互。
四、截图背后,其实有三条路径
region-snap 的实现中,一个比较关键的选择是:根据内容和场景,采用不同的截图方式。
1. 图片和 canvas:满足条件时直接裁剪
如果选区完整落在一张符合条件的图片或 canvas 内,组件会优先尝试从源图裁剪。
以 PDF 预览为例,页面可能已经由 pdf.js 渲染成 canvas。此时可以将选区映射到 canvas 内部的像素坐标,使用 drawImage() 裁剪出对应部分。
这样既能省去一次 DOM 重绘,也能利用源内容已有的分辨率。
例如,一张原始宽度为 2400 像素的图片,在页面中显示为 800 CSS 像素。假设没有其他缩放,用户框选了其中 200 CSS 像素宽的部分,按源图分辨率裁剪后,输出宽度约为 600 像素。
直接裁剪需要满足条件。特殊的图片适配方式、遮挡或跨域资源等因素,都可能让这条路径无法使用,此时会回退到渲染器。
2. 普通 DOM:交给渲染器
文字、表格以及混合排版内容,默认由按需加载的 html2canvas 处理,传入对应的选区范围。
因此,region-snap 不需要强制先生成一张完整长图,再从结果中二次裁剪。不过,实际耗时仍然会受到 DOM 复杂度、资源加载和渲染器实现的影响。
前面的试卷示例,展示的就是对普通 DOM 内容进行区域截图。
渲染器也可以替换。例如,页面使用了默认 html2canvas 不支持的颜色语法,可以接入 html2canvas-pro:
import html2canvasPro from 'html2canvas-pro'
import { html2canvasRenderer } from '@region-snap/vue'
const captureOptions = {
renderer: html2canvasRenderer(
{ backgroundColor: null },
html2canvasPro,
),
}
也可以自己实现 CaptureRenderer。它接收内容元素、选区坐标和输出倍率,返回 canvas。
这种设计把框选交互和图像生成分开:业务可以沿用同一套选区交互,再根据页面情况选择渲染方式。
3. 跨域 iframe:共享当前标签页
第三方文档预览是另一种情况。
比如,页面里嵌入了 Office Online 等跨域 iframe。基于 DOM 的渲染器无法直接读取其中的页面内容。
region-snap 为此提供了 createScreenCapture():通过浏览器的屏幕共享能力获取当前标签页画面,再裁剪选区。
import { createScreenCapture } from '@region-snap/vue'
const screen = createScreenCapture()
// 在用户点击事件中调用,浏览器会请求共享授权
await screen.start()
// 将 screen.renderer 传给 captureOptions.renderer
// 使用完毕后停止共享
screen.stop()
这条路径获取的是用户实际看到的画面,因此可以处理跨域 iframe 的可见内容。
按项目当前说明,这一模式面向桌面 Chrome / Edge,需要 HTTPS 或 localhost,并由用户授权共享。单次截图只能获取可见部分,覆盖在内容上的其他弹窗也可能进入截图。
五、滚动、缩放和触屏,才是交互里的细节
画出一个矩形并不难,难的是让它在真实页面里一直对得上。
region-snap 的选区使用这样的数据结构:
interface Region {
x: number
y: number
width: number
height: number
}
这些值以内容区域左上角为原点,使用未经过 CSS transform 缩放的布局像素。
这意味着,文档通过 transform: scale() 放大或缩小时,选区数据本身仍然描述同一块布局区域,组件再负责转换到屏幕位置。
Vue 可以通过 v-model:region 管理选区:
<RegionSnap v-model:region="region">
<!-- 文档内容 -->
</RegionSnap>
React 则可以使用 region 和 onRegionChange,通过受控组件的方式管理选区。
这也方便业务通过代码恢复或设置选区。
不过,缩放与重新排版是两回事。如果内容宽度变化导致文字换行,旧坐标可能已经指向其他内容。组件默认会在检测到内容宽度变化时清除选区。
对于滚动容器,拖动到边缘时可以自动滚动,继续扩展框选范围。
触屏交互则默认采用“长按后框选”,让普通滑动仍然可以用于滚动。对于专门的截图模式,也可以切换成直接拖动框选。
六、超过一屏的文档,可以滚动拼接
共享标签页模式还能进一步用于长图截图。
框选后调用 startScrollCapture(),用户在选区中滚动文档,组件通过比对相邻帧的重叠内容进行拼接。完成后调用 finishScrollCapture(),即可得到长图。
工具栏可以展示当前进度:
<template
#toolbar="{
scrollCapture,
startScrollCapture,
finishScrollCapture,
cancelScrollCapture,
}"
>
<template v-if="scrollCapture">
<span>
{{
scrollCapture.lost
? '请往回滚一点,恢复拼接'
: `已拼接 ${scrollCapture.height}px`
}}
</span>
<button @click="finishScrollCapture()">完成</button>
<button @click="cancelScrollCapture()">取消</button>
</template>
<button v-else @click="startScrollCapture()">
滚动截图
</button>
</template>
这项能力需要支持滚动截图的渲染器,例如 createScreenCapture().renderer。
由于拼接依赖画面重叠,滚动过快、大面积空白、重复内容以及选区内的固定工具条,都可能影响匹配。当前长图高度上限为 16384 像素。
使用时最好选择内容主体区域,保持适中的滚动速度。
七、接入前需要了解的边界
选择截图方式时,可以先按内容判断:
| 内容场景 | 优先考虑 |
|---|---|
| 单张图片、PDF canvas | 源图直接裁剪 |
| 文字、表格、混合 DOM | 默认或自定义渲染器 |
| 跨域 iframe 的可见内容 | 共享标签页截图 |
| 跨域文档的长图 | 共享标签页与滚动拼接 |
普通 DOM 截图的还原效果取决于渲染器支持范围。跨域图片也需要正确的 CORS 配置;开启 useCORS 本身不能替代资源服务器的授权。
授权方面,项目采用 AGPL-3.0 与商业授权双协议。闭源接入前,请先阅读仓库中的授权说明;商业授权可通过项目提供的联系方式咨询。
八、让截图成为业务流程的一部分
区域截图往往只是业务流程的入口。
用户框选一块内容之后,可能要识别文字、上传附件、反馈问题,也可能只是保存一张图。
region-snap 把框选、选区调整、工具栏定位和图片输出集中到一套组件里,再把后续动作交给业务定义。对于文档预览、图片识别和内容反馈这类场景,可以从一个简单的工具栏开始接入。
欢迎体验,也欢迎通过 Issue 反馈具体页面中的兼容问题。
- 在线演示: region-snap 官网
- 项目源码: Jacky010/region-snap
- npm: @region-snap/core