docs(media): add standalone package guide
This commit is contained in:
Maofeng
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: Storage adapter
|
||||
description: Connect queries, uploads, mutations, URL resolution, and pagination to product infrastructure.
|
||||
order: 20
|
||||
toc:
|
||||
- id: implement-the-contract
|
||||
title: Implement the contract
|
||||
- id: separate-display-and-reference-urls
|
||||
title: Separate display and reference URLs
|
||||
- id: preserve-query-semantics
|
||||
title: Preserve query semantics
|
||||
---
|
||||
|
||||
## Implement the contract {#implement-the-contract}
|
||||
|
||||
`MediaAdapter` is the package's complete persistence boundary. Implement its asset queries, folder operations, uploads, updates, and deletes with the product's storage service.
|
||||
|
||||
```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),
|
||||
}
|
||||
```
|
||||
|
||||
## Separate display and reference URLs {#separate-display-and-reference-urls}
|
||||
|
||||
Use `resolveUrl` for short-lived signed URLs or image transformations used while rendering. Use `resolveReference` for the value returned by the picker and stored in another document. When `resolveReference` is absent, images use `defaultMediaReference`, which preserves intrinsic dimensions in the URL.
|
||||
|
||||
## Preserve query semantics {#preserve-query-semantics}
|
||||
|
||||
Treat `MediaAssetQuery` as an immutable request. Apply `allowedKinds`, `filter`, `folder`, and `keyword` before pagination, then return `hasNextPage` based on the filtered result. This keeps desktop and mobile filters consistent.
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Asset picker
|
||||
description: Reuse the media library as a controlled single- or multiple-selection dialog.
|
||||
order: 30
|
||||
toc:
|
||||
- id: open-the-picker
|
||||
title: Open the picker
|
||||
- id: constrain-selection
|
||||
title: Constrain selection
|
||||
- id: consume-results
|
||||
title: Consume results
|
||||
---
|
||||
|
||||
## Open the picker {#open-the-picker}
|
||||
|
||||
`MediaPickerDialog` reuses the same adapter and folder model as the full library:
|
||||
|
||||
```tsx
|
||||
import { MediaPickerDialog } from "@workspace/media"
|
||||
|
||||
;<MediaPickerDialog
|
||||
open={open}
|
||||
onOpenChange={setOpen}
|
||||
onConfirm={(assets) => editor.insertImages(assets)}
|
||||
/>
|
||||
```
|
||||
|
||||
## Constrain selection {#constrain-selection}
|
||||
|
||||
Pass `allowedKinds={["image"]}` for an image-only workflow. The dialog selects one asset by default; pass `multiple` when the consumer accepts several assets, and provide `initialSelection` when editing an existing value.
|
||||
|
||||
## Consume results {#consume-results}
|
||||
|
||||
The confirmation callback receives complete `MediaAsset` records. Store the adapter-provided reference rather than a temporary preview URL when the result must survive signed-URL expiration.
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: Installation and setup
|
||||
description: Add Media, register its catalog, and connect the storage adapter.
|
||||
order: 10
|
||||
toc:
|
||||
- id: add-the-package
|
||||
title: Add the package
|
||||
- id: register-styles-and-catalogs
|
||||
title: Register styles and catalogs
|
||||
- id: provide-media
|
||||
title: Provide media
|
||||
---
|
||||
|
||||
## Add the package {#add-the-package}
|
||||
|
||||
Add Media to the consuming application:
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"@workspace/media": "workspace:*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Register styles and catalogs {#register-styles-and-catalogs}
|
||||
|
||||
Import the stylesheet once so Tailwind includes utilities used by the package:
|
||||
|
||||
```css
|
||||
@import "@workspace/media/globals.css";
|
||||
```
|
||||
|
||||
Add `@workspace/media/locales/{locale}` to the application's internationalization catalog sources.
|
||||
|
||||
## Provide media {#provide-media}
|
||||
|
||||
Mount the adapter once around every media surface that should share storage behavior and notifications:
|
||||
|
||||
```tsx
|
||||
import { MediaLibrary, MediaProvider } from "@workspace/media"
|
||||
|
||||
;<MediaProvider adapter={mediaAdapter} notify={showNotice}>
|
||||
<MediaLibrary />
|
||||
</MediaProvider>
|
||||
```
|
||||
|
||||
The optional `notify` callback turns operation results into the application's toast or notification system.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Overview
|
||||
description: Understand the Media package, its storage boundary, and the workflows it owns.
|
||||
order: 1
|
||||
toc:
|
||||
- id: package-role
|
||||
title: Package role
|
||||
- id: capabilities
|
||||
title: Capabilities
|
||||
- id: design-boundary
|
||||
title: Design boundary
|
||||
---
|
||||
|
||||
## Package role {#package-role}
|
||||
|
||||
`@workspace/media` provides reusable media-library and asset-picker surfaces. The host application supplies persistence through `MediaAdapter`; Media owns browsing, filtering, pagination, uploads, folders, selection, and asset actions.
|
||||
|
||||
## Capabilities {#capabilities}
|
||||
|
||||
- Browse images and videos with search, filters, folders, favorites, and pagination.
|
||||
- Upload to local or cloud storage targets exposed by the adapter.
|
||||
- Create, rename, nest, and delete organizational folders.
|
||||
- Select one or multiple assets through `MediaPickerDialog`.
|
||||
- Resolve display URLs and stable references independently.
|
||||
- Ship `en-US` and `zh-Hans` message catalogs.
|
||||
|
||||
## Design boundary {#design-boundary}
|
||||
|
||||
Media does not choose an API, database, object store, CDN, or signing strategy. The application implements those decisions behind `MediaAdapter` and can replace them without changing the interface components.
|
||||
|
||||
> Folders classify assets inside the library. They do not need to mirror object-storage paths or change public URLs.
|
||||
@@ -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。
|
||||
Reference in New Issue
Block a user