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,49 @@
+---
+title: 几何计算与导出
+description: 使用原图坐标、纯函数和 Canvas 输出裁剪结果。
+order: 20
+toc:
+  - id: controlled-state
+    title: 受控状态
+  - id: geometry
+    title: 几何函数
+  - id: export
+    title: 导出图片
+  - id: cross-origin
+    title: 跨域图片
+---
+
+## 受控状态 {#controlled-state}
+
+```tsx
+const [value, setValue] = React.useState({ x: 0, y: 0, zoom: 1 })
+
+<Cropper
+  src={src}
+  value={value}
+  onValueChange={setValue}
+  onCropComplete={(area) => saveDraft(area)}
+/>
+```
+
+`onCropAreaChange` 在有效裁剪区域变化时调用；`onCropComplete` 在拖拽或滚轮交互结束以及离散键盘操作后调用，更适合触发持久化。
+
+## 几何函数 {#geometry}
+
+`getCoverScale`、`getCropperBounds`、`constrainCropperValue`、`getCropArea` 和 `zoomCropperValueAtPoint` 都是无 DOM 依赖的纯函数，可在自定义 UI 或测试中单独使用。
+
+## 导出图片 {#export}
+
+```tsx
+const blob = await cropImage(src, area, {
+  type: "image/webp",
+  quality: 0.9,
+  width: 1200,
+})
+```
+
+只指定 `width` 或 `height` 时会保持裁剪区域宽高比。`shape: "circle"` 会使用椭圆路径裁剪；需要 JPEG 背景色时可以提供 `background`。
+
+## 跨域图片 {#cross-origin}
+
+跨域 URL 必须由图片服务器返回允许 Canvas 使用的 CORS 响应头，并同时向 `Cropper` 和 `cropImage` 传入 `crossOrigin="anonymous"`。否则浏览器会将 Canvas 标记为 tainted，无法编码 Blob。