name: managing-media description: 实现媒体和文件管理组件，包括文件上传（拖放、多文件、可恢复）、图像库（灯箱、轮播、砖石布局）、视频播放器（自定义控件、字幕、自适应流媒体）、音频播放器（波形、播放列表）、文档查看器（PDF、Office）和优化策略（压缩、响应式图像、懒加载、CDN）。在处理文件、显示媒体或构建丰富内容体验时使用。

管理与文件和媒体

目的

此技能提供了实现媒体和文件管理组件的系统模式，涵盖所有格式（图像、视频、音频、文档）。它涵盖了上传工作流、显示模式、播放器控件、优化策略和可访问性要求，以确保高性能、可访问和用户友好的媒体体验。

何时使用

激活此技能当：

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

快速决策框架

基于媒体类型和要求选择实现：

图像                  → 画廊模式 + 懒加载 + 响应式srcset
视频                  → 播放器带控件 + 字幕 + 自适应流媒体
音频                  → 播放器带波形 + 播放列表支持
文档（PDF）         → 查看器带导航 + 搜索 + 下载
文件上传（<10MB）     → 基本拖放带预览
文件上传（>10MB）     → 分块上传带进度 + 恢复
多文件                → 队列管理 + 并行上传

详细选择标准，参考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
视频：Web<100MB，云更大
音频：<10MB
文档：<25MB
提供清晰的错误消息
建议压缩工具

图像优化清单

# 生成优化图像集
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渲染：

逐页渲染
文本选择支持
注释（高级版）
基于工作者性能

npm install react-pdf

查看examples/pdf-react.tsx实现。

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

设计令牌集成

所有媒体组件使用设计令牌技能主题：

颜色令牌用于背景、叠加、控件
间距令牌用于填充和间隙
边框令牌用于缩略图和容器
阴影令牌用于高程
动效令牌用于动画

支持浅色、深色、高对比和自定义主题。参考设计令牌技能主题切换。

示例令牌使用：

.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);
}

响应式策略

图像库

四种响应式方法：

网格布局 - CSS Grid带自动适应列
砖石布局 - Pinterest风格带可变高度
轮播 - 移动端单图像，桌面多图像
堆叠 - 移动端垂直列表，桌面网格

查看examples/responsive-gallery.tsx实现。

视频播放器

响应式考虑：

16:9宽高比容器
移动端全宽
桌面受限宽度
画中画多任务处理
触摸友好控件（更大点击区域）

模式参考references/responsive-media.md。

云存储集成

客户端直接上传

对于AWS S3、Cloudinary等：

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

优点：

减少服务器负载
更快上传（直接到CDN）
无服务器文件大小限制

查看examples/s3-direct-upload.tsx实现。设置参考references/cloud-storage.md。

测试工具

生成模拟媒体：

# 生成测试图像
python scripts/generate_mock_images.py --count 50 --sizes thumb,medium,large

# 生成测试视频元数据
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              # 简单拖放上传
chunked-upload.tsx            # 大文件上传带恢复
image-upload-crop.tsx         # 图像上传带裁剪
image-gallery.tsx             # 网格库带灯箱
carousel.tsx                  # 图像轮播/滑块
video-player.tsx              # 自定义视频播放器
audio-player.tsx              # 音频播放器带控件
audio-waveform.tsx            # 音频带波形可视化
pdf-viewer.tsx                # PDF文档查看器
s3-direct-upload.tsx          # 直接上传到S3
responsive-gallery.tsx        # 响应式图像库模式

资源

脚本（无令牌执行）

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 - 库分析

示例（实现代码）

资产（模板和配置）

assets/upload-config.json - 上传约束和设置
assets/media-templates/ - 占位符图像和图标

跨技能集成

此技能与其他组件技能协作：

表单：文件输入字段、验证、提交
反馈：上传进度、成功/错误消息
AI聊天：图像附件、文件共享
仪表板：媒体小部件、缩略图
设计令牌：所有视觉样式通过令牌系统

下一步

识别媒体类型（图像、视频、音频、文档）
确定上传要求（大小、数量、编辑）
选择显示模式（库、轮播、播放器、查看器）
选择库或实现自定义解决方案
实现可访问性要求
应用优化策略
测试性能和响应式行为
集成云存储（可选）