managing-media

管理媒体和文件

用途

此技能提供系统化模式，用于跨所有格式（图像、视频、音频、文档）实现媒体和文件管理组件。内容涵盖上传工作流、显示模式、播放器控件、优化策略和无障碍要求，确保媒体体验高效、易于访问且方便用户使用。

适用场景

在以下情况下启用此技能：

• 实现文件上传（单个、多个、拖放）
• 构建图像库、轮播或灯箱
• 创建视频或音频播放器
• 显示 PDF 或文档查看器
• 优化媒体性能（响应式图像、延迟加载）
• 处理大文件上传（分块、可恢复）
• 集成云存储（S3、Cloudinary）
• 实现媒体无障碍功能（替代文本、字幕、文字稿）
• 为缺失媒体设计空状态

快速决策框架

根据媒体类型和需求选择实现方式：

Images                  → Gallery pattern + lazy loading + responsive srcset
Videos                  → Player with controls + captions + adaptive streaming
Audio                   → Player with waveform + playlist support
Documents (PDF)         → Viewer with navigation + search + download
File Upload (<10MB)     → Basic drag-drop with preview
File Upload (>10MB)     → Chunked upload with progress + resume
Multiple Files          → Queue management + parallel uploads

如需了解详细的选择标准，请参阅 references/implementation-guide.md。

文件上传模式

基础上传（<10MB）

适用于需求简单的小文件：

• 提供视觉反馈的拖放区域
• 点击浏览作为备用方式
• 文件类型和大小验证
• 图像预览缩略图
• 进度指示器
• 参阅 references/upload-patterns.md

示例：examples/basic-upload.tsx

高级上传（>10MB）

适用于需要可靠上传的大文件：

• 分块上传（失败后可恢复）
• 多个文件并行上传
• 上传队列管理
• 取消和重试控件
• 客户端压缩
• 参阅 references/advanced-upload.md

示例：examples/chunked-upload.tsx

图像专用上传

适用于有编辑需求的图像文件：

• 裁剪和旋转工具
• 上传前在客户端调整大小
• 格式转换（PNG → WebP）
• 替代文本输入字段（无障碍功能）
• 参阅 references/image-upload.md

示例：examples/image-upload-crop.tsx

图像显示组件

图像库

适用于图像集合：

• 网格或瀑布流布局
• 延迟加载（原生或自定义）
• 点击打开灯箱
• 缩放和平移控件
• 键盘导航（方向键）
• 响应式设计
• 参阅 references/gallery-patterns.md

示例：examples/image-gallery.tsx

轮播/滑块

适用于按顺序显示图像：

• 自动播放（可选；为满足无障碍需求，可暂停）
• 圆点或缩略图导航
• 支持触摸/滑动
• 用于无障碍功能的 ARIA 角色
• 无限循环选项
• 参阅 references/carousel-patterns.md

示例：examples/carousel.tsx

图像优化

基本优化策略：

• 使用 srcset 和 sizes 提供响应式图像
• 使用现代格式（WebP，并以 JPG 作为备用）
• 渐进式 JPEG
• 模糊渐显占位图
• CDN 集成
• 参阅 references/image-optimization.md

视频组件

视频播放器

适用于自定义视频播放：

• 自定义控件或原生控件
• 播放/暂停、音量、全屏
• 字幕/隐藏字幕（VTT 格式）
• 播放速度控制
• 支持画中画
• 键盘快捷键
• 参阅 references/video-player.md

示例：examples/video-player.tsx

视频优化

视频性能策略：

• 自适应流媒体（HLS、DASH）
• 悬停时预览缩略图
• 对屏幕外的视频进行延迟加载
• 预加载策略（metadata、auto、none）
• 多种画质等级
• 参阅 references/video-optimization.md

音频组件

音频播放器

适用于音频播放：

• 播放/暂停、跳转、音量控件
• 波形可视化（可选）
• 支持播放列表
• 下载选项
• 播放速度控制
• 用于无障碍功能的视觉指示器
• 参阅 references/audio-player.md

示例：examples/audio-player.tsx

文档查看器

PDF 查看器

用于 PDF 文档展示：

• 页面导航（上一页／下一页、跳转到指定页面）
• 放大／缩小控件
• 在文档中搜索文本
• 下载和打印选项
• 缩略图侧边栏
• 参考 references/pdf-viewer.md

示例：examples/pdf-viewer.tsx

Office 文档预览

适用于 DOCX、XLSX、PPTX 文件：

• 只读预览或可编辑
• 基于云端的渲染（Google Docs Viewer、Office Online）
• 本地渲染（支持有限）
• 下载选项
• 参考 references/office-viewer.md

性能优化

文件大小指南

上传前在客户端进行验证：

• 图片：建议小于 5MB
• 视频：网页端小于 100MB，云端可更大
• 音频：小于 10MB
• 文档：小于 25MB
• 提供清晰的错误消息
• 推荐压缩工具

图片优化检查清单

# Generate optimized image set
python scripts/optimize_images.py --input image.jpg --formats webp,jpg,avif

策略：

• 上传前压缩（客户端或服务端）
• 生成多种尺寸（缩略图、中等、大图）
• 使用响应式 srcset 针对不同设备提供图片
• 转换为现代格式（WebP、AVIF）
• 通过 CDN 和边缘缓存提供内容

完整指南请参考 references/performance-optimization.md。

视频优化检查清单

策略：

• 转码为多种画质（360p、720p、1080p）
• 实现自适应比特率流
• 使用 CDN 和边缘缓存
• 延迟加载视口外的视频
• 提供海报图片

无障碍要求

图片

基本模式：

• 有意义的图片必须提供替代文本
• 装饰性图片使用空替代文本（alt=""）
• 使用 <figure> 和 <figcaption> 提供上下文
• 确保叠加层具有足够的颜色对比度
• 参考 references/accessibility-images.md

视频

基本模式：

• 为所有语音提供字幕
• 提供文字稿链接
• 键盘控件（空格键、方向键、M 键静音）
• 暂停自动播放（WCAG 要求）
• 音频描述轨道（如适用）
• 参考 references/accessibility-video.md

音频

基本模式：

• 提供文字稿
• 提供视觉指示器（播放、暂停、音量）
• 键盘控件
• 为控件添加 ARIA 标签
• 参考 references/accessibility-audio.md

验证无障碍功能：

node scripts/validate_media_accessibility.js

完整要求请参考 references/accessibility-patterns.md。

库推荐

图片图库：react-image-gallery

适用于功能完备的图库：

• 支持移动端滑动
• 全屏模式
• 缩略图导航
• 内置延迟加载
• 开箱即用的响应式布局

npm install react-image-gallery

实现示例请参阅 examples/gallery-react-image.tsx。 文档请参考 /xiaolin/react-image-gallery。

替代方案： LightGallery（功能更多，打包体积更大）

视频：video.js

适用于自定义视频播放器：

• 插件生态
• 支持 HLS 和 DASH
• 无障碍控件
• 支持主题
• 文档详尽

npm install video.js

实现示例请参阅 examples/video-js-player.tsx。

音频：wavesurfer.js

适用于波形可视化：

• 精美的波形显示
• 时间轴交互
• 支持插件
• 响应式
• 轻量

npm install wavesurfer.js

实现示例请参阅 examples/audio-waveform.tsx。

PDF：react-pdf

适用于在 React 中渲染 PDF：

• 逐页渲染
• 支持文本选择
• 注释（高级版）
• 基于 Worker，性能更佳

npm install react-pdf

实现示例请参阅 examples/pdf-react.tsx。

详细比较请参考 references/library-comparison.md。

设计令牌集成

所有媒体组件都使用 design-tokens 技能进行主题设置：

• 用于背景、叠加层和控件的颜色令牌
• 用于内边距和间距的间距令牌
• 用于缩略图和容器的边框令牌
• 用于海拔效果的阴影令牌
• 用于动画的动效令牌

支持浅色、深色、高对比度和自定义主题。 主题切换请参考 design-tokens 技能。

令牌用法示例：

.upload-zone {
  border: var(--upload-zone-border);
  background: var(--upload-zone-bg);
  padding: var(--upload-zone-padding);
  border-radius: var(--upload-zone-border-radius);
}

.image-gallery {
  gap: var(--gallery-gap);
}

.video-player {
  background: var(--video-player-bg);
  border-radius: var(--video-border-radius);
}

响应式策略

图片图库

四种响应式方案：

1. 网格布局 - 使用 CSS Grid 和 auto-fit 列
2. 瀑布流布局 - Pinterest 风格，高度不一
3. 轮播 - 移动端显示单张图片，桌面端显示多张
4. 堆叠 - 移动端显示垂直列表，桌面端显示网格

请参阅 examples/responsive-gallery.tsx 中的实现。

视频播放器

响应式注意事项：

• 使用 16:9 宽高比容器
• 移动端占满宽度
• 桌面端限制宽度
• 支持画中画，便于多任务处理
• 适合触控的控件（更大的可点击区域）

请参阅 references/responsive-media.md 了解相关模式。

云存储集成

客户端直接上传

适用于 AWS S3、Cloudinary 等：

1. 从后端请求签名 URL
2. 直接上传到云存储
3. 通知后端上传完成
4. 显示已上传的媒体

优势：

• 减轻服务器负载
• 上传速度更快（直接上传到 CDN）
• 不受服务器文件大小限制

请参阅 examples/s3-direct-upload.tsx 查看实现。 请参阅 references/cloud-storage.md 了解设置方法。

测试工具

生成模拟媒体：

# Generate test images
python scripts/generate_mock_images.py --count 50 --sizes thumb,medium,large

# Generate test video metadata
python scripts/generate_video_metadata.py --duration 300

验证媒体的无障碍性：

node scripts/validate_media_accessibility.js

分析性能：

node scripts/analyze_media_performance.js --files images/*.jpg

可运行示例

从符合需求的示例开始：

basic-upload.tsx              # Simple drag-drop upload
chunked-upload.tsx            # Large file upload with resume
image-upload-crop.tsx         # Image upload with cropping
image-gallery.tsx             # Grid gallery with lightbox
carousel.tsx                  # Image carousel/slider
video-player.tsx              # Custom video player
audio-player.tsx              # Audio player with controls
audio-waveform.tsx            # Audio with waveform visualization
pdf-viewer.tsx                # PDF document viewer
s3-direct-upload.tsx          # Direct upload to S3
responsive-gallery.tsx        # Responsive image gallery patterns

资源

脚本（无令牌执行）

• scripts/optimize_images.py - 批量优化图片
• scripts/generate_mock_images.py - 生成测试图片
• scripts/validate_media_accessibility.js - 无障碍性验证
• scripts/analyze_media_performance.js - 性能分析

参考资料（详细文档）

• references/upload-patterns.md - 文件上传实现
• references/gallery-patterns.md - 图片图库设计
• references/video-player.md - 视频播放器功能
• references/audio-player.md - 音频播放器模式
• references/pdf-viewer.md - 文档查看器设置
• references/accessibility-patterns.md - 媒体无障碍性
• references/performance-optimization.md - 优化策略
• references/cloud-storage.md - 云集成指南
• references/library-comparison.md - 库分析

示例（实现代码）

• 请参阅 examples/ 目录中的可运行实现

资源文件（模板和配置）

• assets/upload-config.json - 上传限制和设置
• assets/media-templates/ - 占位图片和图标

跨技能集成

此技能可与其他组件技能配合使用：

• 表单：文件输入字段、验证、提交
• 反馈：上传进度、成功／错误消息
• AI Chat：图片附件、文件共享
• 仪表板：媒体组件、缩略图
• 设计令牌：所有视觉样式均通过令牌系统实现

后续步骤

1. 确定媒体类型（图片、视频、音频、文档）
2. 确定上传要求（大小、数量、编辑）
3. 选择显示模式（图库、轮播、播放器、查看器）
4. 选择库或实现自定义方案
5. 实现无障碍性要求
6. 应用优化策略
7. 测试性能和响应式行为
8. 集成云存储（可选）