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,41 @@
+---
+title: 存储 Adapter
+description: 将查询、上传、变更、URL 解析和分页连接到产品基础设施。
+order: 20
+toc:
+  - id: implement-the-contract
+    title: 实现完整契约
+  - id: separate-display-and-reference-urls
+    title: 区分展示与引用 URL
+  - id: preserve-query-semantics
+    title: 保持查询语义
+---
+
+## 实现完整契约 {#implement-the-contract}
+
+`MediaAdapter` 是这个包完整的持久化边界。通过产品的存储服务实现资源查询、目录操作、上传、更新和删除。
+
+```ts
+import type { MediaAdapter } from "@workspace/media"
+
+export const mediaAdapter: MediaAdapter = {
+  listAssets: (query) => api.media.list(query),
+  listFolders: () => api.media.listFolders(),
+  upload: (input) => api.media.upload(input),
+  createFolder: (input) => api.media.createFolder(input),
+  updateFolder: (input) => api.media.updateFolder(input),
+  deleteFolder: (id) => api.media.deleteFolder(id),
+  moveAsset: (id, folderId) => api.media.move(id, folderId),
+  renameAsset: (id, name) => api.media.rename(id, name),
+  updateFavorite: (id, favorite) => api.media.favorite(id, favorite),
+  deleteAsset: (id) => api.media.delete(id),
+}
+```
+
+## 区分展示与引用 URL {#separate-display-and-reference-urls}
+
+使用 `resolveUrl` 返回渲染时需要的短期签名 URL 或图片转换地址。使用 `resolveReference` 返回选择器写入其他文档的值。未提供 `resolveReference` 时，图片会使用 `defaultMediaReference`，在 URL 中保留固有尺寸。
+
+## 保持查询语义 {#preserve-query-semantics}
+
+将 `MediaAssetQuery` 当作不可变请求。在分页前依次应用 `allowedKinds`、`filter`、`folder` 和 `keyword`，然后根据筛选后的结果返回 `hasNextPage`。这样可以保持桌面端与移动端筛选行为一致。
@@ -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 提供的稳定引用，而不是临时预览地址。
@@ -0,0 +1,48 @@
+---
+title: 安装与设置
+description: 添加 Media、注册词典并连接存储 Adapter。
+order: 10
+toc:
+  - id: add-the-package
+    title: 添加包
+  - id: register-styles-and-catalogs
+    title: 注册样式与词典
+  - id: provide-media
+    title: 提供媒体能力
+---
+
+## 添加包 {#add-the-package}
+
+在使用方应用中添加 Media：
+
+```json
+{
+  "dependencies": {
+    "@workspace/media": "workspace:*"
+  }
+}
+```
+
+## 注册样式与词典 {#register-styles-and-catalogs}
+
+导入一次样式表，让 Tailwind 包含 Media 使用的工具类：
+
+```css
+@import "@workspace/media/globals.css";
+```
+
+将 `@workspace/media/locales/{locale}` 加入应用的国际化 catalog sources。
+
+## 提供媒体能力 {#provide-media}
+
+在需要共享存储行为和通知方式的媒体界面外统一挂载 Adapter：
+
+```tsx
+import { MediaLibrary, MediaProvider } from "@workspace/media"
+
+;<MediaProvider adapter={mediaAdapter} notify={showNotice}>
+  <MediaLibrary />
+</MediaProvider>
+```
+
+可选的 `notify` 回调会把操作结果接入应用自己的 Toast 或通知系统。
@@ -0,0 +1,31 @@
+---
+title: 概览
+description: 了解 Media 包、存储边界以及它负责的媒体工作流。
+order: 1
+toc:
+  - id: package-role
+    title: 包的职责
+  - id: capabilities
+    title: 功能范围
+  - id: design-boundary
+    title: 设计边界
+---
+
+## 包的职责 {#package-role}
+
+`@workspace/media` 提供可复用的媒体库和资源选择界面。宿主应用通过 `MediaAdapter` 提供持久化能力；Media 负责浏览、筛选、分页、上传、目录、选择和资源操作。
+
+## 功能范围 {#capabilities}
+
+- 通过搜索、筛选、目录、收藏和分页浏览图片与视频。
+- 上传到 Adapter 暴露的本地或云端存储目标。
+- 创建、重命名、嵌套和删除分类目录。
+- 通过 `MediaPickerDialog` 单选或多选资源。
+- 分别解析展示 URL 和稳定引用。
+- 提供 `en-US` 与 `zh-Hans` 消息词典。
+
+## 设计边界 {#design-boundary}
+
+Media 不会替应用选择 API、数据库、对象存储、CDN 或签名策略。应用在 `MediaAdapter` 后实现这些决策，替换实现时无需修改界面组件。
+
+> 目录只用于媒体库内部分类，不必对应对象存储路径，也不需要改变公开 URL。