网页框一下就能截图Region-snap:我把这套功能封装成了 npm 包,支持 Vue 和 React

前言

这次来还账了,之前的文章# 【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 中接入区域截图

安装组件:

css 复制代码
npm i @region-snap/vue

把需要框选的内容放进 RegionSnap,通过工具栏插槽拿到截图方法:

xml 复制代码
<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 的接入方式也类似

安装:

css 复制代码
npm i @region-snap/react

通过 renderToolbar 定义工具栏:

javascript 复制代码
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:

javascript 复制代码
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():通过浏览器的屏幕共享能力获取当前标签页画面,再裁剪选区。

javascript 复制代码
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 的选区使用这样的数据结构:

typescript 复制代码
interface Region {
  x: number
  y: number
  width: number
  height: number
}

这些值以内容区域左上角为原点,使用未经过 CSS transform 缩放的布局像素。

这意味着,文档通过 transform: scale() 放大或缩小时,选区数据本身仍然描述同一块布局区域,组件再负责转换到屏幕位置。

Vue 可以通过 v-model:region 管理选区:

xml 复制代码
<RegionSnap v-model:region="region">
  <!-- 文档内容 -->
</RegionSnap>

React 则可以使用 region 和 onRegionChange,通过受控组件的方式管理选区。

这也方便业务通过代码恢复或设置选区。

不过,缩放与重新排版是两回事。如果内容宽度变化导致文字换行,旧坐标可能已经指向其他内容。组件默认会在检测到内容宽度变化时清除选区。

对于滚动容器,拖动到边缘时可以自动滚动,继续扩展框选范围。

触屏交互则默认采用"长按后框选",让普通滑动仍然可以用于滚动。对于专门的截图模式,也可以切换成直接拖动框选。

六、超过一屏的文档,可以滚动拼接

共享标签页模式还能进一步用于长图截图。

框选后调用 startScrollCapture(),用户在选区中滚动文档,组件通过比对相邻帧的重叠内容进行拼接。完成后调用 finishScrollCapture(),即可得到长图。

工具栏可以展示当前进度:

xml 复制代码
<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 反馈具体页面中的兼容问题。

相关推荐
李纲明23 分钟前
微信小程序开了 Skyline 后样式全乱、滚动对不上甚至部分组件不能用?Skyline 怎么接才稳
javascript·微信小程序·小程序·devdiy
程序员大阳26 分钟前
副队长ES6+教程(7)--ES6+函数新特性
javascript·es6·函数·特性·默认参数·剩余参数·参数解构
zhanlang021728 分钟前
HTML 零基础入门到企业实战全套教程【第六章 6.1】表格标签|实现数据可视化展示
前端·信息可视化·html
恋猫de小郭35 分钟前
Flutter Analyzer 系列坑推进,必看,AI 时代这玩意最吃你内存
android·前端·flutter
Amos_Web39 分钟前
通过 Rspack 源码学 Rust(六):用 enum 表达状态,用 match 完整处理分支
前端
Amos_Web1 小时前
Rspack 源码解析(三十六):BannerPlugin 如何在产物头部注入注释并处理占位符
前端
晓得迷路了1 小时前
栗子前端技术周刊第 154 期 - Parcel 3 Alpha、JS 调查报告、Vite 漏洞...
前端·javascript·css
IT_陈寒1 小时前
Vue开发者必知:5个让你效率翻倍的隐藏技巧
前端·人工智能·后端