Chrome扩展截图功能实现

Chrome扩展截图主要逻辑实现

本文档详细描述了一个浏览器扩展程序中的截图功能实现，该功能允许用户通过鼠标拖拽选择网页上的特定区域，并将该区域截取为图片（base64格式）。

一、整体架构

1.1 系统组件

┌─────────────────────────────────────────┐
│          用户界面 (Popup/Page)          │
│        (触发截图，接收结果)             │
└───────────────────┬─────────────────────┘
                    │ 调用 captureScreen()
┌───────────────────▼─────────────────────┐
│          后台脚本 (Background)          │
│  (核心协调逻辑，当前代码所在位置)       │
└───────────────────┬─────────────────────┘
                    │ 注入脚本 + 消息通信
┌───────────────────▼─────────────────────┐
│         内容脚本 (Content Script)       │
│  (在网页中实现选择界面和交互)           │
└─────────────────────────────────────────┘

1.2 文件结构

screenshot-extension/
├── manifest.json          # 扩展配置文件
├── background.ts          # 后台脚本（本文件）
├── content.ts            # 内容脚本（注入部分）
├── popup.html            # 用户界面
├── popup.js              # 界面逻辑
└── styles.css            # 样式文件

二、核心功能模块

2.1 截图主函数 captureScreen()

2.1.1 函数签名

export const captureScreen = (
  onSuccess: (dataUrl: string, message: string) => void,
  onError: (message: string) => void
) => {
  // 实现逻辑...
};

参数说明：

• onSuccess: 成功回调函数，接收base64图片数据和成功消息
• onError: 失败回调函数，接收错误消息

2.1.2 状态变量

// 用于管理截图流程的状态
let isCompleted = false;           // 完成标志，防止重复调用
let currentTabId: number | null = null;      // 当前标签页ID
let globalKeyHandler: ((e: KeyboardEvent) => void) | null = null;  // 全局键盘事件处理器
let messageHandler: ((msg: any, sender: any, response: any) => boolean | void) | null = null; // 消息监听器
let timeoutId: number | null = null;         // 超时计时器ID

2.2 资源管理模块

2.2.1 统一清理函数 cleanup()

const cleanup = () => {
  // 移除全局ESC键监听器
  if (globalKeyHandler) {
    window.removeEventListener('keydown', globalKeyHandler, true);
    globalKeyHandler = null;
  }
  
  // 移除消息监听器
  if (messageHandler) {
    chrome.runtime.onMessage.removeListener(messageHandler);
    messageHandler = null;
  }
  
  // 清除超时计时器
  if (timeoutId) {
    clearTimeout(timeoutId);
    timeoutId = null;
  }
};

清理时机：

1. 用户按ESC取消
2. 选择超时（30秒）
3. 脚本注入失败
4. 收到取消/完成消息

2.2.2 强制停止选择 forceStopSelection()

const forceStopSelection = () => {
  if (currentTabId) {
    chrome.tabs.sendMessage(
      currentTabId,
      { action: "forceStopScreenshot" },
      () => {
        // 忽略可能出现的错误（如标签页关闭）
        if (chrome.runtime.lastError) {
          console.log('Force stop failed:', chrome.runtime.lastError.message);
        }
      }
    );
  }
};

2.3 事件监听模块

2.3.1 全局ESC键监听

globalKeyHandler = (e: KeyboardEvent) => {
  if (e.key === 'Escape' && !isCompleted) {
    isCompleted = true;      // 标记为已完成
    cleanup();               // 清理资源
    forceStopSelection();    // 强制停止内容脚本中的选择
    onError("截图已取消");   // 调用错误回调
  }
};

window.addEventListener('keydown', globalKeyHandler, true);

三、截图流程实现

3.1 初始化阶段

3.1.1 获取当前标签页

chrome.tabs.query(
  { active: true, currentWindow: true },
  (tabs: chrome.tabs.Tab[]) => {
    // 检查标签页是否有效
    if (!tabs[0]?.id || !tabs[0].windowId) {
      cleanup();
      onError("无法获取当前标签页");
      return;
    }
    
    const tabId = tabs[0].id;           // 标签页ID
    const windowId = tabs[0].windowId;  // 窗口ID
    const tabUrl = tabs[0].url;         // 标签页URL
    currentTabId = tabId;               // 保存当前标签页ID
  }
);

3.1.2 检查特殊页面

// 检查是否是浏览器内置页面
if (
  tabUrl &&
  (tabUrl.startsWith("chrome://") ||   // Chrome特殊页面
   tabUrl.startsWith("edge://") ||     // Edge特殊页面
   tabUrl.startsWith("about:"))        // Firefox特殊页面
) {
  cleanup();
  onError("无法在特殊页面上截屏");
  return;
}

3.2 消息处理器

messageHandler = (
  message: any,
  _sender: chrome.runtime.MessageSender,
  _sendResponse: (response?: unknown) => void
) => {
  // 防重复检查
  if (isCompleted) {
    return false;
  }
  
  // 处理选择完成
  if (message.action === 'screenshotSelectionResult' && message.rect) {
    isCompleted = true;
    cleanup();
    
    // 截取整个标签页
    chrome.tabs.captureVisibleTab(
      windowId,
      { format: "png", quality: 100 },
      (dataUrl: string) => {
        if (chrome.runtime.lastError) {
          onError(chrome.runtime.lastError.message || "截屏失败");
          return;
        }
        
        if (dataUrl) {
          // 裁剪图片
          cropImage(dataUrl, message.rect, (croppedDataUrl) => {
            if (croppedDataUrl) {
              onSuccess(croppedDataUrl, "截屏成功！");
            } else {
              onError("图片裁剪失败");
            }
          });
        }
      }
    );
  }
  
  // 处理用户取消
  if (message.action === 'screenshotSelectionCancelled') {
    isCompleted = true;
    cleanup();
    onError("截图已取消");
  }
  
  return false;
};

3.3 超时控制

// 设置30秒超时
timeoutId = window.setTimeout(() => {
  if (isCompleted) return;
  
  console.log('Screenshot timeout');
  isCompleted = true;
  cleanup();
  forceStopSelection();
  onError("截图选择超时，请重试");
}, 30000);

四、内容脚本注入

4.1 注入选择功能

chrome.scripting.executeScript({
    target: { tabId },       // 目标标签页
    func: startSelectionFunction, // 要执行的函数
  }).then(() => {
    console.log("Selection script injected"); // 日志记录注入成功
    // 如果已经完成，强制停止选择
    if (isCompleted) {
      forceStopSelection();
    }
  }).catch((error) => {
    // 如果已经完成，直接返回
    if (isCompleted) return;

    console.error("Failed to inject script:", error); // 记录注入失败
    isCompleted = true;  // 标记为已完成
    cleanup();           // 清理资源
    onError("无法启动选择模式，请刷新页面后重试"); // 调用错误回调
});

4.2 选择功能实现 startSelectionFunction()

4.2.1 变量定义

let selectionOverlay: HTMLDivElement | null = null;   // 选择覆盖层
let isSelecting = false;                              // 是否正在选择
let startX = 0;                                       // 鼠标起始X坐标
let startY = 0;                                       // 鼠标起始Y坐标
let selectionBox: HTMLDivElement | null = null;       // 选择框元素
let keydownHandler: ((e: KeyboardEvent) => void) | null = null; // 键盘事件处理器
let mousedownHandler: ((e: MouseEvent) => void) | null = null; // 鼠标按下处理器
let messageListener: ((msg: any) => void) | null = null; // 消息监听器

4.2.2 清理函数

const cleanupAll = () => {
  // 移除所有事件监听器
  if (keydownHandler) document.removeEventListener('keydown', keydownHandler);
  if (messageListener) chrome.runtime.onMessage.removeListener(messageListener);
  if (selectionOverlay) {
    if (mousedownHandler) selectionOverlay.removeEventListener('mousedown', mousedownHandler);
    selectionOverlay.remove();
  }
  
  // 重置变量
  selectionBox = null;
  isSelecting = false;
};

4.2.3 创建选择界面

const startSelectionMode = () => {
  // 创建覆盖层
  selectionOverlay = document.createElement('div');
  selectionOverlay.id = 'rcc-selection-overlay';
  selectionOverlay.style.cssText = `
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background: rgba(0, 0, 0, 0.3);
    z-index: 2147483646;
    cursor: crosshair;
  `;
  
  // 创建选择框
  selectionBox = document.createElement('div');
  selectionBox.style.cssText = `
    position: absolute;
    border: 2px dashed #1890ff;
    background: rgba(24, 144, 255, 0.1);
    pointer-events: none;
    display: none;
  `;
  
  // 创建提示文字
  const hint = document.createElement('div');
  hint.textContent = '拖拽选择截图区域，按 ESC 取消';
  hint.style.cssText = `
    position: fixed;
    top: 20px;
    left: 50%;
    transform: translateX(-50%);
    background: rgba(0, 0, 0, 0.8);
    color: white;
    padding: 8px 16px;
    border-radius: 4px;
    font-size: 14px;
    z-index: 2147483647;
    pointer-events: none;
  `;
  
  selectionOverlay.appendChild(selectionBox);
  selectionOverlay.appendChild(hint);
  document.body.appendChild(selectionOverlay);
};

4.3 鼠标事件处理

4.3.1 鼠标按下事件

mousedownHandler = (e: MouseEvent) => {
  e.preventDefault();
  e.stopPropagation();
  
  startX = e.clientX;
  startY = e.clientY;
  
  // 显示选择框
  if (selectionBox) {
    selectionBox.style.display = 'block';
    selectionBox.style.left = startX + 'px';
    selectionBox.style.top = startY + 'px';
    selectionBox.style.width = '0px';
    selectionBox.style.height = '0px';
  }
  
  // 动态更新选择框
  const handleMouseMove = (e: MouseEvent) => {
    const currentX = e.clientX;
    const currentY = e.clientY;
    
    const left = Math.min(startX, currentX);
    const top = Math.min(startY, currentY);
    const width = Math.abs(currentX - startX);
    const height = Math.abs(currentY - startY);
    
    if (selectionBox) {
      selectionBox.style.left = left + 'px';
      selectionBox.style.top = top + 'px';
      selectionBox.style.width = width + 'px';
      selectionBox.style.height = height + 'px';
    }
  };
  
  // 选择完成
  const handleMouseUp = (e: MouseEvent) => {
    e.preventDefault();
    e.stopPropagation();
    
    const currentX = e.clientX;
    const currentY = e.clientY;
    
    const left = Math.min(startX, currentX);
    const top = Math.min(startY, currentY);
    const width = Math.abs(currentX - startX);
    const height = Math.abs(currentY - startY);
    //起始点 (100, 100) → 结束点 (200, 150)
    //left = min(100, 200) = 100
    //top = min(100, 150) = 100
    //width = |200 - 100| = 100
    //height = |150 - 100| = 50
    
    // 最小选择区域检查
    if (width < 10 || height < 10) {
      stopSelectionMode();
      return;
    }
    
    // 收集选择区域信息
    const rect = {
      x: left,
      y: top,
      width,
      height,
      viewportWidth: window.innerWidth,//视口宽度
      viewportHeight: window.innerHeight,//视口高度
      devicePixelRatio: window.devicePixelRatio || 1 //设备像素比
    };
    
    cleanupAll();
    
    // 发送结果到后台
    chrome.runtime.sendMessage({
      action: 'screenshotSelectionResult',
      rect
    });
  };
  
  document.addEventListener('mousemove', handleMouseMove);
  document.addEventListener('mouseup', handleMouseUp, { once: true });
};

4.4 键盘事件处理

keydownHandler = (e: KeyboardEvent) => {
  if (e.key === 'Escape') {
    stopSelectionMode();
  }
};

document.addEventListener('keydown', keydownHandler);

五、图片裁剪模块

5.1 裁剪函数 cropImage()

function cropImage(
  dataUrl: string,
  rect: { 
    x: number;
    y: number;
    width: number;
    height: number;
    viewportWidth?: number;
    viewportHeight?: number;
    devicePixelRatio?: number;
  },
  callback: (croppedDataUrl: string | null) => void
) {
  const img = new Image();
  
  img.onload = () => {
    // 计算缩放比例
    const viewportWidth = rect.viewportWidth || window.innerWidth;
    const viewportHeight = rect.viewportHeight || window.innerHeight;
    const devicePixelRatio = rect.devicePixelRatio || (img.width / viewportWidth);
    const scale = devicePixelRatio;
    
    // 创建画布
    const canvas = document.createElement("canvas");
    canvas.width = rect.width;
    canvas.height = rect.height;
    
    const ctx = canvas.getContext("2d");
    if (!ctx) {
      callback(null);
      return;
    }
    
    // 设置高质量渲染
    ctx.imageSmoothingEnabled = true;
    ctx.imageSmoothingQuality = "high";
    
    // 裁剪并绘制
    ctx.drawImage(
      img,                        // 源图像
      rect.x * scale,             // 源图像裁剪起点X（考虑设备像素比）
      rect.y * scale,             // 源图像裁剪起点Y（考虑设备像素比）
      rect.width * scale,         // 源图像裁剪宽度（考虑设备像素比）
      rect.height * scale,        // 源图像裁剪高度（考虑设备像素比）
      0,                          // 画布绘制起点X
      0,                          // 画布绘制起点Y
      rect.width,                 // 画布绘制宽度（原始选择宽度）
      rect.height                 // 画布绘制高度（原始选择高度）
    );
    
    // 转换为base64
    const croppedDataUrl = canvas.toDataURL("image/png");
    callback(croppedDataUrl);
  };
  
  img.onerror = () => {
    callback(null);
  };
  
  img.src = dataUrl;
}

5.2 像素比处理说明

问题：

• 网页中的坐标是逻辑像素
• 截图得到的是物理像素
• 高DPI屏幕需要缩放计算

解决方案：

const devicePixelRatio = window.devicePixelRatio || 1;
const scale = devicePixelRatio;

// 实际裁剪时乘以缩放比例
rect.x * scale,      // 考虑高DPI屏幕
rect.y * scale,
rect.width * scale,
rect.height * scale

六、数据流分析

6.1 完整流程图

用户操作 → 系统响应 → 数据流转 → 最终结果
   ↓          ↓          ↓          ↓
点击截图 → 获取标签页 → 检查权限 → 准备环境
   ↓          ↓          ↓          ↓
选择区域 → 注入脚本 → 创建界面 → 等待交互
   ↓          ↓          ↓          ↓
拖拽框选 → 事件处理 → 计算坐标 → 发送消息
   ↓          ↓          ↓          ↓
确认选择 → 截全屏 → 裁剪图片 → 返回数据
   ↓          ↓          ↓          ↓
显示结果 → 清理资源 → 状态重置 → 流程结束

6.2 消息通信流程

┌──────────┐     ESC取消     ┌──────────┐
│  用户    ├────────────────►│ 全局监听 │
└────┬─────┘                 └────┬─────┘
     │                            │
     │ 点击截图                   │ 传递消息
     ▼                            ▼
┌──────────┐    注入脚本     ┌──────────┐
│  Popup   ├────────────────►│  后台    │
└────┬─────┘                 └────┬─────┘
     │                            │
     │ 返回结果                   │ 发送消息
     ▼                            ▼
┌──────────┐    选择完成     ┌──────────┐
│  结果    │◄────────────────┤ 内容脚本 │
└──────────┘                 └──────────┘

6.3 错误处理流程

┌──────────────┐
│  开始截图    │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ 检查标签页   │───失败───► 清理资源，返回错误
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ 检查特殊页面 │───失败───► 清理资源，返回错误
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ 注入内容脚本 │───失败───► 清理资源，返回错误
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ 用户选择阶段 │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ 可能的失败： │
│ 1. ESC取消   │
│ 2. 选择太小  │
│ 3. 超时      │
│ 4. 截图失败  │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  清理资源    │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ 返回错误信息 │
└──────────────┘

---

附录：完整代码索引

文件/函数	作用	位置
captureScreen()	主入口函数	background.ts
cleanup()	资源清理	background.ts: cleanup()
forceStopSelection()	强制停止	background.ts: forceStopSelection()
startSelectionFunction()	选择功能	注入的内容脚本
cropImage()	图片裁剪	background.ts: cropImage()
messageHandler	消息处理	background.ts: messageHandler
globalKeyHandler	全局ESC监听	background.ts: globalKeyHandler

本实现提供了一个完整、健壮的截图功能解决方案，具有良好的可扩展性和可维护性。

七、截图涉及到的ChromeAPI

1、Tabs API（标签页管理）

用于查询和操作浏览器标签页，是截图功能的核心依赖。

API 方法/属性	用途
chrome.tabs.query	查询符合条件的标签页（如当前活动标签页）。
chrome.tabs.sendMessage	向指定标签页的内容脚本发送消息（用于强制停止选择模式）。
chrome.tabs.captureVisibleTab	截取指定窗口的可见区域（生成完整页面的截图数据）。
tabs.Tab.id	标签页的唯一标识（用于后续操作的目标标识）。
tabs.Tab.windowId	标签页所属窗口的 ID（用于截取窗口级别的截图）。
tabs.Tab.url	标签页的 URL（用于检查是否为特殊页面，如 chrome://）。

2、Scripting API（脚本注入）

用于将自定义 JavaScript 代码注入到网页上下文中，实现页面内的交互逻辑（如选择覆盖层）。

API 方法/属性	用途
chrome.scripting.executeScript	向指定标签页注入并执行 JavaScript 函数（用于创建选择覆盖层）。

3、Runtime API（运行时通信）

用于扩展内部（后台脚本、内容脚本、弹出页）之间的消息传递和生命周期管理。

API 方法/属性	用途
chrome.runtime.onMessage	监听来自其他扩展组件（如内容脚本）的消息。
chrome.runtime.sendMessage	向其他扩展组件发送消息（如内容脚本通知后台选择完成或取消）。
chrome.runtime.lastError	获取最近一次 API 调用的错误信息（用于错误处理）。

4、总结表格

API 类别	核心方法/属性	关键作用
Tabs	query, sendMessage, captureVisibleTab, Tab.id, Tab.windowId, Tab.url	管理标签页、获取上下文信息、执行截图
Scripting	executeScript	注入页面脚本，实现前端交互（如选择覆盖层）
Runtime	onMessage, sendMessage, lastError	扩展内部通信、错误捕获