docs(media): add standalone package guide

2026-09-20 16:44:22 +08:00
parent c519d4e74b
commit eebf29c3d5
17 changed files with 326 additions and 78 deletions
@@ -0,0 +1,34 @@
+---
+title: 资源选择器
+description: 将媒体库复用为受控的单选或多选对话框。
+order: 30
+toc:
+  - id: open-the-picker
+    title: 打开选择器
+  - id: constrain-selection
+    title: 限制选择范围
+  - id: consume-results
+    title: 使用选择结果
+---
+
+## 打开选择器 {#open-the-picker}
+
+`MediaPickerDialog` 会复用完整媒体库相同的 Adapter 和目录模型：
+
+```tsx
+import { MediaPickerDialog } from "@workspace/media"
+
+;<MediaPickerDialog
+  open={open}
+  onOpenChange={setOpen}
+  onConfirm={(assets) => editor.insertImages(assets)}
+/>
+```
+
+## 限制选择范围 {#constrain-selection}
+
+图片专用流程传入 `allowedKinds={["image"]}`。对话框默认单选；消费方可以接受多个资源时传入 `multiple`，编辑已有值时通过 `initialSelection` 恢复选择。
+
+## 使用选择结果 {#consume-results}
+
+确认回调会收到完整的 `MediaAsset` 记录。如果结果需要在签名 URL 失效后继续使用，应保存 Adapter 提供的稳定引用，而不是临时预览地址。