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: Geometry and export
+description: Work with source coordinates, pure functions, and Canvas output.
+order: 20
+toc:
+  - id: controlled-state
+    title: Controlled state
+  - id: geometry
+    title: Geometry functions
+  - id: export
+    title: Exporting an image
+  - id: cross-origin
+    title: Cross-origin images
+---
+
+## Controlled state {#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` runs whenever a valid crop changes. `onCropComplete` runs after drag or wheel interaction and after discrete keyboard operations, making it a better persistence boundary.
+
+## Geometry functions {#geometry}
+
+`getCoverScale`, `getCropperBounds`, `constrainCropperValue`, `getCropArea`, and `zoomCropperValueAtPoint` are DOM-independent pure functions that can be reused in custom interfaces and tests.
+
+## Exporting an image {#export}
+
+```tsx
+const blob = await cropImage(src, area, {
+  type: "image/webp",
+  quality: 0.9,
+  width: 1200,
+})
+```
+
+Supplying only `width` or `height` preserves the crop aspect ratio. `shape: "circle"` clips through an ellipse; provide `background` when an opaque JPEG background is required.
+
+## Cross-origin images {#cross-origin}
+
+A remote image server must return CORS headers that permit Canvas use. Pass `crossOrigin="anonymous"` to `Cropper` and the matching `crossOrigin` option to `cropImage`; otherwise the browser may taint the Canvas and prevent Blob encoding.