# ai-procrop-studio

**Repository Path**: jsz315/ai-procrop-studio

## Basic Information

- **Project Name**: ai-procrop-studio
- **Description**: 专业图片裁剪工具
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-22
- **Last Updated**: 2025-11-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
<img width="1200" height="475" alt="GHBanner" src="img.png" />
</div>

# ProCrop Studio

一个功能强大、界面精美的在线图片裁剪工具，专为设计师、内容创作者和开发者打造。支持多种宽高比、固定尺寸预设、自定义尺寸、旋转缩放等功能，让图片裁剪变得简单高效。

## ✨ 功能特性

### 🎯 核心功能
- **智能裁剪** - 基于 `react-easy-crop` 的流畅裁剪体验，支持拖拽调整裁剪区域
- **多种宽高比** - 预设常用宽高比：自由、1:1、4:3、16:9、3:4、9:16
- **固定尺寸预设** - 内置社交媒体常用尺寸：
  - Instagram Post (1080×1080)
  - Instagram Portrait (1080×1350)
  - Instagram Story (1080×1920)
  - Facebook Link (1200×630)
- **自定义尺寸** - 支持输入任意宽度和高度（像素）
- **图片变换** - 缩放（0.2x - 4x）和旋转（0° - 360°）
- **多格式导出** - 支持 PNG、JPEG、WEBP 格式
- **质量控制** - JPEG/WEBP 格式可调节压缩质量（10% - 100%）

### 🎨 界面设计
- **现代化 UI** - 深色主题，采用 Zinc 配色方案
- **响应式布局** - 左侧画布区域 + 右侧控制面板
- **直观操作** - 拖拽上传、点击选择，操作流畅自然
- **实时预览** - 所有调整即时反映在画布上
- **网格辅助线** - 裁剪时显示网格，便于精确对齐

## 🛠️ 技术栈

- **前端框架**: React 19.2.0
- **构建工具**: Vite 6.2.0
- **语言**: TypeScript 5.8.2
- **核心库**: 
  - `react-easy-crop` - 图片裁剪功能
  - `lucide-react` - 图标组件
- **样式**: 原生 CSS + Tailwind CSS 原子类（通过 UnoCSS）
- **开发体验**: 
  - TypeScript 类型安全
  - 热模块替换（HMR）
  - 组件化架构

## 📦 安装与运行

### 前置要求
- Node.js 18+ 
- pnpm（推荐）或 npm

### 安装步骤

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd procrop-studio
   ```

2. **安装依赖**
   ```bash
   pnpm install
   # 或使用 npm
   npm install
   ```

3. **启动开发服务器**
   ```bash
   pnpm dev
   # 或使用 npm
   npm run dev
   ```

4. **访问应用**
   - 本地访问: http://localhost:3000
   - 网络访问: http://0.0.0.0:3000

### 构建生产版本

```bash
pnpm build
# 或
npm run build
```

构建产物将输出到 `dist` 目录。

### 预览生产构建

```bash
pnpm preview
# 或
npm run preview
```

## 🚀 部署指南

项目已成功构建，构建产物位于 `dist` 目录。以下是几种部署方式：

### 方式一：Gitee Pages（推荐）

1. **构建项目**
   ```bash
   pnpm build
   ```

2. **在 Gitee 仓库中启用 Pages**
   - 进入仓库：https://gitee.com/jsz315/ai-procrop-studio
   - 点击「服务」→「Gitee Pages」
   - 选择分支：`master`
   - 选择目录：`dist`
   - 点击「启动」或「更新」

3. **访问部署地址**
   - 部署成功后，访问：`https://jsz315.gitee.io/ai-procrop-studio/`

### 方式二：Vercel（一键部署）

1. **安装 Vercel CLI**
   ```bash
   npm i -g vercel
   ```

2. **部署**
   ```bash
   vercel
   ```
   或直接访问 [Vercel](https://vercel.com) 并导入 Gitee 仓库。

### 方式三：Netlify

1. **安装 Netlify CLI**
   ```bash
   npm i -g netlify-cli
   ```

2. **部署**
   ```bash
   netlify deploy --prod --dir=dist
   ```
   或访问 [Netlify](https://netlify.com) 并连接 Gitee 仓库。

### 方式四：手动部署

将 `dist` 目录中的文件上传到任何静态网站托管服务即可。

## 📖 使用指南

### 基本操作

1. **上传图片**
   - 点击顶部 "New Image" 按钮
   - 或直接点击画布中央的上传区域
   - 支持 JPG、PNG、WEBP 格式

2. **选择宽高比**
   - 在右侧面板的 "Aspect Ratio" 区域
   - 点击预设按钮（Free、1:1、4:3 等）
   - 选择后裁剪框会自动调整比例

3. **使用固定尺寸**
   - 在 "Output Dimensions" 区域
   - 选择预设尺寸（如 IG Post）
   - 或输入自定义宽度和高度

4. **调整图片**
   - **缩放**: 使用 "Zoom" 滑块（0.2x - 4x）
   - **旋转**: 使用 "Rotation" 滑块（0° - 360°）
   - **移动**: 直接拖拽图片调整位置

5. **导出图片**
   - 选择导出格式（PNG/JPEG/WEBP）
   - 调整质量（仅 JPEG/WEBP）
   - 点击顶部 "Export" 按钮下载

### 高级技巧

- **精确裁剪**: 使用固定尺寸模式，确保输出尺寸完全符合要求
- **保持质量**: PNG 格式无损，适合需要高质量的场景
- **文件大小**: JPEG/WEBP 格式可调节质量，平衡文件大小和画质
- **批量处理**: 可以连续上传多张图片进行处理

## 📁 项目结构

```
procrop-studio/
├── components/
│   ├── ImageCropper.tsx      # 图片裁剪组件
│   └── ui/
│       └── Slider.tsx         # 滑块组件
├── utils/
│   └── canvasUtils.ts         # Canvas 处理工具函数
├── App.tsx                    # 主应用组件
├── index.tsx                  # 应用入口
├── types.ts                   # TypeScript 类型定义
├── vite.config.ts             # Vite 配置
├── tsconfig.json              # TypeScript 配置
└── package.json               # 项目依赖配置
```

## 🎯 核心组件说明

### ImageCropper
图片裁剪核心组件，封装了 `react-easy-crop` 的功能，支持：
- 宽高比控制
- 缩放和旋转
- 固定尺寸模式
- 裁剪区域像素坐标计算

### canvasUtils
Canvas 处理工具函数，负责：
- 图片加载和创建
- 旋转角度计算
- 裁剪区域提取
- 尺寸调整和缩放
- 格式转换和质量控制

## 🔧 配置说明

### Vite 配置
- **端口**: 3000
- **主机**: 0.0.0.0（允许网络访问）
- **路径别名**: `@` 指向项目根目录

### 环境变量
项目支持环境变量配置（当前版本未使用 API，但已预留配置）：
- `GEMINI_API_KEY` - Gemini API 密钥（如需要）

## 🌟 特色亮点

1. **零依赖裁剪** - 所有图片处理在浏览器端完成，无需服务器
2. **高性能** - 使用 Canvas API，处理速度快
3. **类型安全** - 完整的 TypeScript 类型定义
4. **用户体验** - 流畅的交互，即时的视觉反馈
5. **代码质量** - 组件化设计，易于维护和扩展

## 📝 开发计划

- [ ] 添加图片翻转功能（水平/垂直）
- [ ] 支持批量裁剪
- [ ] 添加更多社交媒体预设尺寸
- [ ] 支持拖拽排序预设
- [ ] 添加撤销/重做功能
- [ ] 支持快捷键操作
- [ ] 添加图片滤镜效果

## 📄 许可证

MIT License

## 🙏 致谢

- [react-easy-crop](https://github.com/ricardo-ch/react-easy-crop) - 优秀的图片裁剪库
- [lucide-react](https://lucide.dev/) - 精美的图标库
- [Vite](https://vitejs.dev/) - 快速的构建工具

---

<div align="center">
Made with ❤️ using React + TypeScript + Vite
</div>