🖼️ X-Pic Annotator

✨ 特性

• 📸 智能截图: 支持全页面截图和自定义区域选择截图
• ✏️ 多种标注工具: 画笔、矩形、圆形、箭头、文字等丰富工具
• 🎨 自定义样式: 支持颜色选择、线宽调节、字体大小设置
• 📱 响应式设计: 完美适配桌面和移动设备
• 🔧 框架无关: 支持原生JS、React、Vue、Angular等所有框架
• 💾 灵活导出: 支持PNG格式下载和自定义保存处理
• 🔲 可扩展性: 支持自定义按钮，扩展工具栏功能
• ⚡ 轻量高效: 小体积，高性能，无额外依赖
• 🌐 浏览器兼容: 支持所有现代浏览器

🚀 快速开始

安装

# 使用 npm
npm install x-pic-annotator

# 使用 yarn
yarn add x-pic-annotator

# 使用 pnpm
pnpm add x-pic-annotator

基础使用

import XPicAnnotator from 'x-pic-annotator';

// 全页面截图
const annotator = new XPicAnnotator({
  onSave: (imageData) => {
    console.log('截图保存:', imageData);
    // 下载图片
    const link = document.createElement('a');
    link.download = 'screenshot.png';
    link.href = imageData;
    link.click();
  }
});

// 开始全页面截图
annotator.startScreenshot('full');

// 或者区域截图
const areaAnnotator = new XPicAnnotator({ screenshotMode: 'area' });
areaAnnotator.startScreenshot('area');

// 自定义按钮示例
const customAnnotator = new XPicAnnotator({
  customButtons: [
    {
      text: '上传到服务器',
      icon: '📤',
      tooltip: '将截图上传到服务器',
      onClick: (imageData, context, button) => {
        // 自定义上传逻辑
        uploadToServer(imageData);
      }
    },
    {
      text: '添加水印',
      icon: '🏷️',
      style: { background: '#fd7e14' },
      onClick: (imageData, context) => {
        // 在画布上添加水印
        context.ctx.fillText('水印文字', 10, 30);
        context.redraw();
      }
    }
  ]
});
customAnnotator.startScreenshot();

📖 文档

• 完整 API 文档
• 框架集成指南
• 常见问题解答

🎯 主要 API

构造函数选项

| 参数 | 类型 | 默认值 | 描述 | |------|------|--------|---------| | container | HTMLElement | document.body | 插件容器元素 | | onSave | Function | null | 保存截图时的回调函数 | | onCancel | Function | null | 取消截图时的回调函数 | | tools | Array | ['pen', 'rectangle', 'circle', 'arrow', 'text'] | 可用的标注工具 | | colors | Array | ['#ff0000', '#00ff00', '#0000ff', ...] | 可选的颜色列表 | | lineWidth | Number | 3 | 默认线宽 | | fontSize | Number | 16 | 默认字体大小 | | screenshotMode | String | 'full' | 截图模式（'full' 或 'area'） | | customButtons | Array | [] | 自定义按钮配置 |

主要方法

• startScreenshot(mode): 开始截图和标注（mode: 'full' 或 'area'）
• destroy(): 销毁插件实例，释放资源

🔧 框架集成

React

import { useRef, useEffect } from 'react';
import XPicAnnotator from 'x-pic-annotator';

function ScreenshotButton() {
  const annotatorRef = useRef(null);

  const handleScreenshot = () => {
    annotatorRef.current = new XPicAnnotator({
      onSave: (imageData) => {
        console.log('截图保存:', imageData);
      }
    });
    annotatorRef.current.startScreenshot();
  };

  useEffect(() => {
    return () => {
      if (annotatorRef.current) {
        annotatorRef.current.destroy();
      }
    };
  }, []);

  return <button onClick={handleScreenshot}>开始截图</button>;
}

Vue

<template>
  <button @click="startScreenshot">开始截图</button>
</template>

<script>
import XPicAnnotator from 'x-pic-annotator';

export default {
  data() {
    return {
      annotator: null
    };
  },
  methods: {
    startScreenshot() {
      this.annotator = new XPicAnnotator({
        onSave: (imageData) => {
          console.log('截图保存:', imageData);
        }
      });
      this.annotator.startScreenshot();
    }
  },
  beforeUnmount() {
    if (this.annotator) {
      this.annotator.destroy();
    }
  }
};
</script>

Angular

import { Component, OnDestroy } from '@angular/core';
import XPicAnnotator from 'x-pic-annotator';

@Component({
  selector: 'app-screenshot',
  template: '<button (click)="startScreenshot()">开始截图</button>'
})
export class ScreenshotComponent implements OnDestroy {
  private annotator: XPicAnnotator | null = null;

  startScreenshot() {
    this.annotator = new XPicAnnotator({
      onSave: (imageData) => {
        console.log('Screenshot saved:', imageData);
      }
    });
    this.annotator.startScreenshot();
  }

  ngOnDestroy() {
    if (this.annotator) {
      this.annotator.destroy();
    }
  }
}

📱 示例演示

查看 examples/ 目录获取完整的集成示例：

• 原生 JavaScript 示例
• React 集成示例
• Vue 集成示例
• Angular 集成示例

🛠️ 开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建生产版本
npm run build

🤝 贡献

欢迎提交 Pull Request 或 Issue！

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

📄 许可证

本项目基于 MIT 许可证开源。

🙏 致谢

• html2canvas - 强大的页面截图库
• 所有贡献者和使用者的支持