docs(cropper): add bilingual usage guides

2026-09-29 17:09:39 +08:00
parent 23e0867027
commit 844acad316
8 changed files with 340 additions and 0 deletions
@@ -0,0 +1,30 @@
+---
+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}
+
+- 鼠标和触摸拖拽。
+- 双指、滚轮、双击和键盘缩放。
+- 受控与非受控状态。
+- 矩形和圆形视口。
+- 响应容器尺寸变化并自动约束图片位置。
+- 独立的纯几何函数。
+- 使用 Canvas 导出 PNG、JPEG 或 WebP Blob。
+
+## 数据模型 {#data-model}
+
+`CropperValue` 中的 `x`、`y` 是相对视口中心的 CSS 像素偏移，`zoom` 是相对于 cover fit 的缩放倍数。`CropArea` 使用原图像素，因此可以直接交给服务端图片处理服务，也可以传给 `cropImage()` 在浏览器内导出。