Cropper
图片裁切：容器 + 底图 + 遮罩 + 裁切框（含裁切视图 + 8 resize 角点）。几何逻辑委托 @chenzy-design/core 的 CropperFoundation（框架无关，纯原生 DOM/canvas，不引第三方）。支持 rect/round/roundRect 三形状、aspectRatio 比例约束、8 角点自由/约束 resize、裁切框拖拽、遮罩拖拽移动底图、滚轮以指针为中心缩放（min/max/step 钳制）、受控 rotate/zoom、容器 resize 重排、preview 实时预览、getCropperCanvas() ref 取裁切结果 canvas。受控 aspectRatio/rotate/zoom 只读不回写，onZoomChange 仅通知。
如何引入
import { Cropper } from '@chenzy-design/svelte';基础用法
传入 src；shape 切换 rect / round / roundRect；getCropperCanvas 取结果。
自定义裁切框比例
aspectRatio 固定裁切框比例（此处 3:4），拖动时以此比例变化。
受控旋转 / 缩放
rotate、zoom 受控旋转缩放，onZoomChange 回传最新缩放值。
旋转
缩放
裁切框设置
cropperBoxStyle 自定义裁切框样式，showResizeBox 控制调整块显隐。
展示调整块
实时预览裁切效果
preview 指定预览容器，裁切态变化时实时渲染预览。
旋转
缩放
实时预览
API 参考
Cropper
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
src | 待裁切图片地址 | string | undefined |
shape | 裁切框形状；round 仅渲染 4 个边中点角点并圆形裁切 | 'rect'|'round'|'roundRect' | 'rect' |
aspectRatio | 受控裁切比例(w/h)；设置后角点 resize 走比例约束（只读不回写） | number | undefined |
defaultAspectRatio | 图片加载时裁切框初始比例（仅 aspectRatio 未设时生效） | number | 1 |
rotate | 受控旋转角度(deg)，变化经 core 重算图片中心（只读不回写） | number | 0 |
zoom | 受控缩放；图片加载后先做适配缩放，此值在其基础上再缩放（只读不回写） | number | 1 |
minZoom | 滚轮缩放下限 | number | 0.1 |
maxZoom | 滚轮缩放上限 | number | 3 |
zoomStep | 每次滚轮缩放步长 | number | 0.1 |
showResizeBox | 是否显示裁切框 resize 角点 | boolean | true |
cropperBoxStyle | 裁切框附加内联样式 | string | undefined |
cropperBoxClassName | 裁切框附加类名 | string | undefined |
fill | 裁切结果中非图片区域的填充色 | string | 'rgba(0, 0, 0, 0)' |
preview | 返回预览容器元素；提供后实时渲染裁切预览 | () => HTMLElement | null | undefined | undefined |
imgProps | 透传给底图 <img> 的属性 | Record<string, unknown> | undefined |
onZoomChange | 缩放变化回调 | (zoom: number) => void | undefined |
ariaLabel | 容器 aria-label（未设走 locale Cropper.container） | string | undefined |
class | 容器附加类名 | string | undefined |
style | 容器附加内联样式 | string | undefined |
Events
| 事件 | 载荷 | 说明 |
|---|---|---|
onZoomChange | — | 滚轮缩放导致 zoom 变化时触发 |
Methods
| 属性 | 类型 | 说明 |
|---|---|---|
getCropperCanvas | — | 按当前裁切框/图片/rotate/zoom 生成裁切结果 canvas（HTMLCanvasElement）；需真实 canvas 2D 上下文 |
Accessibility
- 容器 role=group + aria-label（走 locale Cropper.container 或 ariaLabel）；底图/裁切视图 img 为装饰(alt="")；角点/遮罩/裁切框 role=presentation，交互经鼠标/滚轮（对齐 Semi 原生实现，无键盘 resize）。
设计变量
| 变量 | 默认值 | 用法 |
|---|---|---|
--cd-cropper-box-outline-color | var(--cd-color-primary) | 裁切框 outline 颜色 |
--cd-cropper-corner-bg | var(--cd-color-primary) | 裁切框 8 角点填充色（品牌色，对齐 Semi $color-cropper_box_corner-bg） |
--cd-cropper-mask-bg | var(--cd-color-overlay-bg) | 裁切框外遮罩层背景色（半透明暗色） |