Maofeng
90 lines
4.0 KiB
Plaintext
90 lines
4.0 KiB
Plaintext
---
|
|
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: api
|
|
title: API
|
|
- 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}
|
|
|
|
The shortest path exports the current result through the component ref:
|
|
|
|
```tsx
|
|
import { Cropper, type CropperHandle } from "@workspace/cropper"
|
|
|
|
const cropperRef = React.useRef<CropperHandle>(null)
|
|
|
|
const result = await cropperRef.current?.getCropImage({
|
|
outputType: "base64",
|
|
type: "image/jpeg",
|
|
quality: 0.9,
|
|
width: 1200,
|
|
})
|
|
|
|
<Cropper ref={cropperRef} src={src} />
|
|
```
|
|
|
|
`getCropImage()` returns `undefined` until the image is ready. `outputType` defaults to `"blob"`; `"base64"` returns a data URL suitable for previews or form values. Quality must be between `0` and `1`.
|
|
|
|
Use the pure function when no component instance is available:
|
|
|
|
```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. `getCropImage(source, area, options)` is the corresponding pure function for Blob/base64 output.
|
|
|
|
## API {#api}
|
|
|
|
| Prop | Type | Description |
|
|
| ------------------------------ | ----------------------------------- | ------------------------------------------------ |
|
|
| `src` | `string \| Blob` | An image URL, Blob, or File. |
|
|
| `aspectRatio` | `number \| \`${number}:${number}\`` | Crop viewport ratio; defaults to `1`. |
|
|
| `width` / `height` | matching `CSSProperties` value | Optional inline container dimensions. |
|
|
| `value` / `defaultValue` | `CropperValue` | Controlled or uncontrolled translation and zoom. |
|
|
| `minZoom` / `maxZoom` | `number` | Zoom range; defaults to `1` through `4`. |
|
|
| `shape` | `"rectangle" \| "circle"` | Viewport shape. |
|
|
| `showGrid` | `boolean` | Whether to render the rule-of-thirds grid. |
|
|
| `onCropAreaChange` | `(area) => void` | Runs when the valid source-image crop changes. |
|
|
| `onCropComplete` | `(area, value) => void` | Runs after an interaction or reset completes. |
|
|
| `onImageLoad` / `onImageError` | callbacks | Observe image loading state. |
|
|
|
|
`CropperHandle` exposes `element`, `getCropArea()`, `getCropImage(options)`, and `reset()`. Use `rootRef` when a raw DOM ref is needed; the component `ref` is reserved for the imperative handle.
|
|
|
|
## 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.
|