ArmpitCropper

English | 简体中文

一个强大的 Ant Design Upload 图片裁剪组件，支持高级质量控制和文件大小管理。

✨ 特性

• 🖼️ 图片裁剪: 支持矩形和圆形裁剪
• 🔍 缩放控制: 可调节图片缩放的滑块
• 🔄 旋转功能: 图片旋转功能
• 📐 宽高比: 动态宽高比调整
• 🎛️ 质量控制: 实时图片质量调整和压缩预览
• 📊 文件大小管理: 实时文件大小显示和限制执行
• 🚫 大小限制: 可配置的最大文件大小和视觉警告
• 🎨 网格显示: 可选的裁剪网格覆盖
• 🔄 重置功能: 一键重置所有调整
• 🌐 国际化支持: 自动语言检测
• 📱 响应式: 移动端友好设计

📦 安装

pnpm add armpit-cropper

🚀 快速开始

import { Upload } from 'antd';
import ArmpitCropper from 'armpit-cropper';
import 'armpit-cropper/dist/style.css'; // 引入样式

const Demo = () => (
  <ArmpitCropper>
    <Upload>+ 添加图片</Upload>
  </ArmpitCropper>
);

🎮 演示

克隆仓库并运行演示：

git clone https://github.com/name-q/ArmpitCropper.git
cd ArmpitCropper
pnpm install
pnpm run dev

打开浏览器访问 http://localhost:5173 查看演示。

📖 API

| 属性 | 类型 | 默认值 | 描述 | |------|------|---------|-------------| | quality | number | 0.8 | 图片质量 (0-1) | | fillColor | string | 'white' | 裁剪图片的填充颜色 | | maxFileSize | string \| number | '2MB' | 最大文件大小（如 '100KB', '2MB', '1.5GB'） | | outputType | string | 'image/jpeg' | 导出图片的 MIME 类型，同时用于预览计算与最终导出。使用 'image/jpeg' 或 'image/webp' 时质量滑块会影响体积；'image/png' 为无损格式会忽略质量。 | | renameWithTimestamp | boolean | true | 是否使用时间戳作为导出文件名（如 1694500000000.jpg），默认开启。 | | enableZoom | boolean | true | 启用缩放滑块 | | enableRotation | boolean | false | 启用旋转滑块 | | enableAspectRatio | boolean | false | 启用宽高比滑块 | | enableQuality | boolean | true | 启用质量滑块 | | showResetBtn | boolean | false | 显示重置按钮 | | aspectRatio | number | 1 | 裁剪宽高比 | | minZoom | number | 1 | 最小缩放级别 | | maxZoom | number | 3 | 最大缩放级别 | | minQuality | number | 0.1 | 最小质量 | | maxQuality | number | 1.0 | 最大质量 | | cropShape | 'rect' \| 'round' | 'rect' | 裁剪形状 | | showGrid | boolean | false | 显示裁剪网格 | | modalTitle | string | '编辑图片' | 模态框标题 | | modalWidth | number \| string | - | 模态框宽度 | | beforeCrop | function | - | 裁剪模态框打开前的回调 |

🔥 高级功能

质量控制

质量滑块允许实时调整图片压缩并实时预览文件大小：

<ArmpitCropper
  enableQuality={true}
  minQuality={0.1}
  maxQuality={1.0}
  quality={0.8}
>
  <Upload>上传</Upload>
</ArmpitCropper>

导出类型（MIME）

预览显示的体积与最终导出文件使用相同的 outputType。有损格式（JPEG/WebP）会响应质量变化；PNG 为无损格式，质量变化不影响体积。

// 导出为 JPEG（默认）—— 质量滑块会影响体积
<ArmpitCropper outputType="image/jpeg" quality={0.8} enableQuality>
  <Upload>上传</Upload>
</ArmpitCropper>

// 导出为 WebP —— 质量滑块会影响体积
<ArmpitCropper outputType="image/webp" quality={0.8} enableQuality>
  <Upload>上传</Upload>
</ArmpitCropper>

// 导出为 PNG —— 质量滑块不会改变体积（PNG 为无损）
<ArmpitCropper outputType="image/png" enableQuality>
  <Upload>上传</Upload>
</ArmpitCropper>

文件大小限制

设置最大文件大小并自动验证：

<ArmpitCropper
  maxFileSize="1MB"
  enableQuality={true}
>
  <Upload>上传</Upload>
</ArmpitCropper>

支持的文件大小格式：

• '100KB' 或 '100kb' - 100千字节
• '2MB' 或 '2mb' - 2兆字节
• '1.5GB' 或 '1.5gb' - 1.5G字节
• 1048576 - 原始字节数（1MB）

当文件大小超出限制时：

• 确定按钮被禁用
• 出现红色警告消息
• 文件大小以红色显示

完整示例

import React from 'react';
import { Upload, Button } from 'antd';
import { UploadOutlined } from '@ant-design/icons';
import ArmpitCropper from 'armpit-cropper';

const App = () => {
  return (
    <ArmpitCropper
      enableZoom
      enableRotation
      enableAspectRatio
      enableQuality
      showResetBtn
      maxFileSize="2MB"
      quality={0.8}
      aspectRatio={16/9}
      cropShape="rect"
      showGrid
    >
      <Upload>
        <Button icon={<UploadOutlined />}>
          上传图片
        </Button>
      </Upload>
    </ArmpitCropper>
  );
};

export default App;

📄 许可证

MIT License (c) name-q