---
title: 概览
description: 在 React 中完成图片平移、缩放、裁剪计算与 Canvas 导出。
order: 1
toc:
  - id: package-role
    title: Package 定位
  - id: capabilities
    title: 功能
  - id: data-model
    title: 数据模型
---

## Package 定位 {#package-role}

`@workspace/cropper` 提供固定视口式图片裁剪：用户在裁剪视口内移动和缩放图片，组件持续返回原图像素坐标中的裁剪区域。组件只负责交互和几何计算，不负责上传、存储或修改原始文件。

## 功能 {#capabilities}

- 鼠标和触摸拖拽。
- 双指、滚轮、双击和键盘缩放。
- 受控与非受控状态。
- 矩形和圆形视口。
- 支持数字或 `"宽:高"` 格式的视口比例。
- 支持 URL 和本地 `Blob` 图片源，并自动释放临时 object URL。
- 响应容器尺寸变化并自动约束图片位置。
- 独立的纯几何函数。
- 通过组件 ref 重置、读取区域并导出结果。
- 使用 Canvas 导出 PNG、JPEG 或 WebP Blob/base64。

## 数据模型 {#data-model}

`CropperValue` 中的 `x`、`y` 是相对视口中心的 CSS 像素偏移，`zoom` 是相对于 cover fit 的缩放倍数。`CropArea` 使用原图像素，因此可以直接交给服务端图片处理服务，也可以传给 `cropImage()` 在浏览器内导出。