@composy/screenshot-core

网页截图库，支持 DOM 截图、区域选择、水印、剪贴板复制等功能。

功能特性

• 🎯 DOM 截图 — 指定元素或整个页面截图
• ✂️ 区域选择 — 交互式框选截图区域
• 💧 水印 — 自定义文字水印
• 📋 剪贴板 — 一键复制到系统剪贴板
• 🎨 设计令牌 — CSS 变量驱动，支持主题定制
• 📦 多格式导出 — PNG / JPEG / WebP
• 🔌 框架无关 — 纯 TypeScript，无运行时依赖

安装

npm install @composy/screenshot-core

快速开始

import { ScreenCapture } from '@composy/screenshot-core'

const capture = new ScreenCapture({
  container: '#app',
  format: 'png',
  quality: 0.9,
})

// 截取指定元素
const result = await capture.capture('#content')
result.download('screenshot.png')

// 截取整个页面
const fullPageResult = await capture.captureFullPage()

// 区域选择截图
const regionResult = await capture.selectAndCapture()

// 复制到剪贴板
await result.copyToClipboard()

API

ScreenCapture

const sc = new ScreenCapture(options)

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | container | HTMLElement \| string | - | 容器元素或 CSS 选择器 | | format | 'png' \| 'jpeg' \| 'webp' | 'png' | 导出格式 | | quality | number | 0.92 | 图片质量 (0-1) | | scale | number | devicePixelRatio | 缩放比例 | | backgroundColor | string | '' | 背景颜色 | | watermark | WatermarkOptions | - | 水印配置 | | useCORS | boolean | false | 是否使用 CORS | | ignoreElements | string[] | [] | 忽略的 CSS 选择器 | | onBeforeCapture | () => void \| Promise<void> | - | 截图前钩子 | | onAfterCapture | (result) => void \| Promise<void> | - | 截图后钩子 |

方法

| 方法 | 说明 | |------|------| | capture(target?) | 截取指定元素 | | captureRegion(rect) | 截取指定矩形区域 | | selectAndCapture(options?) | 交互式框选截图 | | captureFullPage() | 全页面截图 | | download(filename?, format?, quality?) | 下载截图 | | getLastResult() | 获取最近一次截图结果 | | updateOptions(options) | 更新配置 | | destroy() | 销毁实例 |

CaptureResult

const result = await capture.capture()

| 方法 | 说明 | |------|------| | toBlob(format?, quality?) | 转为 Blob | | toDataURL(format?, quality?) | 转为 DataURL | | download(filename?, format?, quality?) | 下载为文件 | | copyToClipboard(format?, quality?) | 复制到剪贴板 | | clone() | 克隆截图结果 |

RegionSelector

import { RegionSelector } from '@composy/screenshot-core'

const selector = new RegionSelector({
  crosshair: true,
  showSize: true,
})
const rect = await selector.select()
selector.destroy()

EventEmitter

const emitter = new EventEmitter()
emitter.on('event', (payload) => { ... })
emitter.emit('event', data)
emitter.removeAllListeners()

设计令牌

组件使用 CSS 变量驱动样式，支持主题定制：

/* 自定义截图选择器样式 */
:root {
  --ldesign-screenshot-color-mask-bg: rgba(0, 0, 0, 0.6);
  --ldesign-screenshot-color-selection-border: #ff6600;
  --ldesign-screenshot-color-label-bg: #ff6600;
  --ldesign-screenshot-label-font-size: 14px;
}

CSS 变量列表

| 变量 | 默认值 | 说明 | |------|--------|------| | --ldesign-screenshot-color-mask-bg | var(--ld-gray-900) | 遮罩背景色 | | --ldesign-screenshot-color-selection-border | var(--ld-primary-500) | 选区边框颜色 | | --ldesign-screenshot-color-selection-bg | rgba(59,130,246,0.1) | 选区背景色 | | --ldesign-screenshot-color-label-bg | var(--ld-primary-500) | 尺寸标签背景色 | | --ldesign-screenshot-color-label-text | var(--ld-gray-50) | 尺寸标签文字颜色 | | --ldesign-screenshot-selection-border-width | 2px | 选区边框宽度 | | --ldesign-screenshot-label-font-size | 12px | 标签字体大小 | | --ldesign-screenshot-z-index-overlay | 999999 | 遮罩层 z-index |

无障碍

• 截图区域自动添加 role="img" 和 aria-label
• 区域选择器支持键盘操作：Escape 取消，Enter 确认
• 区域选择器支持触摸设备

导出格式

// ES Module
import { ScreenCapture } from '@composy/screenshot-core'

// CommonJS
const { ScreenCapture } = require('@composy/screenshot-core')

// UMD (CDN)
<script src="https://cdn.jsdelivr.net/npm/@composy/screenshot-core/dist/index.min.js"></script>
<script>
  const capture = new LDesignScreenshot.ScreenCapture({ ... })
</script>

License

MIT