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,48 @@
+---
+title: 基础使用
+description: 添加样式入口并创建一个可交互的图片裁剪器。
+order: 10
+toc:
+  - id: stylesheet
+    title: 样式入口
+  - id: cropper
+    title: 裁剪器
+  - id: controls
+    title: 外部控件
+---
+
+## 样式入口 {#stylesheet}
+
+在应用的 Tailwind 样式入口中添加：
+
+```css
+@import "@workspace/cropper/globals.css";
+```
+
+## 裁剪器 {#cropper}
+
+组件需要明确的宽度，`aspectRatio` 会确定高度：
+
+```tsx
+import { Cropper, type CropArea } from "@workspace/cropper"
+
+function ProductImageCropper({ src }: { src: string }) {
+  const [area, setArea] = React.useState<CropArea>()
+
+  return (
+    <Cropper
+      src={src}
+      alt="商品图片"
+      aspectRatio={4 / 3}
+      className="w-full max-w-xl rounded-xl"
+      onCropAreaChange={setArea}
+    />
+  )
+}
+```
+
+用户可以拖拽图片、滚动缩放，或者在 Cropper 聚焦时使用方向键、`+`、`-`、`0` 和 `Home`。
+
+## 外部控件 {#controls}
+
+通过 `value` 和 `onValueChange` 控制裁剪状态，即可接入 Slider 或重置按钮。`minZoom` 最小为 `1`，保证图片始终覆盖整个视口。