Back to Details

managing-media

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Managing Media & Files

媒体与文件管理

Purpose

用途

This skill provides systematic patterns for implementing media and file management components across all formats (images, videos, audio, documents). It covers upload workflows, display patterns, player controls, optimization strategies, and accessibility requirements to ensure performant, accessible, and user-friendly media experiences.
本技能提供了跨所有格式（图片、视频、音频、文档）实现媒体与文件管理组件的系统化模式。它涵盖上传流程、展示模式、播放器控件、优化策略以及无障碍要求，以确保媒体体验具备高性能、可访问性和用户友好性。

When to Use

适用场景

Activate this skill when:
  • Implementing file upload (single, multiple, drag-and-drop)
  • Building image galleries, carousels, or lightboxes
  • Creating video or audio players
  • Displaying PDF or document viewers
  • Optimizing media for performance (responsive images, lazy loading)
  • Handling large file uploads (chunked, resumable)
  • Integrating cloud storage (S3, Cloudinary)
  • Implementing media accessibility (alt text, captions, transcripts)
  • Designing empty states for missing media
在以下场景中启用本技能：
  • 实现文件上传（单文件、多文件、拖拽上传）
  • 构建图片画廊、轮播图或灯箱组件
  • 创建视频或音频播放器
  • 展示PDF或文档查看器
  • 优化媒体性能（响应式图片、懒加载）
  • 处理大文件上传（分块、可恢复）
  • 集成云存储（S3、Cloudinary）
  • 实现媒体无障碍功能（替代文本、字幕、转录文本）
  • 为缺失的媒体设计空状态

Quick Decision Framework

快速决策框架

Select implementation based on media type and requirements:
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
For detailed selection criteria, reference 
references/implementation-guide.md
.
根据媒体类型和需求选择实现方案：
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
。

File Upload Patterns

文件上传模式

Basic Upload (<10MB)

基础上传（<10MB）

For small files with simple requirements:
  • Drag-and-drop zone with visual feedback
  • Click to browse fallback
  • File type and size validation
  • Preview thumbnails for images
  • Progress indicator
  • Reference 
    references/upload-patterns.md
Example: 
examples/basic-upload.tsx
适用于需求简单的小文件：
  • 带视觉反馈的拖拽区域
  • 点击浏览的备选方案
  • 文件类型和大小验证
  • 图片预览缩略图
  • 进度指示器
  • 参考 
    references/upload-patterns.md
示例：
examples/basic-upload.tsx

Advanced Upload (>10MB)

高级上传（>10MB）

For large files requiring reliability:
  • Chunked uploads (resume on failure)
  • Parallel uploads for multiple files
  • Upload queue management
  • Cancel and retry controls
  • Client-side compression
  • Reference 
    references/advanced-upload.md
Example: 
examples/chunked-upload.tsx
适用于需要可靠性的大文件：
  • 分块上传（失败后可恢复）
  • 多文件并行上传
  • 上传队列管理
  • 取消和重试控件
  • 客户端压缩
  • 参考 
    references/advanced-upload.md
示例：
examples/chunked-upload.tsx

Image-Specific Upload

图片专属上传

For image files with editing requirements:
  • Crop and rotate tools
  • Client-side resize before upload
  • Format conversion (PNG → WebP)
  • Alt text input field (accessibility)
  • Reference 
    references/image-upload.md
Example: 
examples/image-upload-crop.tsx
适用于需要编辑的图片文件：
  • 裁剪和旋转工具
  • 上传前客户端调整尺寸
  • 格式转换（PNG → WebP）
  • 替代文本输入框（无障碍需求）
  • 参考 
    references/image-upload.md
示例：
examples/image-upload-crop.tsx

Image Display Components

图片展示组件

Image Gallery

图片画廊

For collections of images:
  • Grid or masonry layout
  • Lazy loading (native or custom)
  • Lightbox on click
  • Zoom and pan controls
  • Keyboard navigation (arrow keys)
  • Responsive design
  • Reference 
    references/gallery-patterns.md
Example: 
examples/image-gallery.tsx
适用于图片集合：
  • 网格或瀑布流布局
  • 懒加载（原生或自定义）
  • 点击打开灯箱
  • 缩放和平移控件
  • 键盘导航（方向键）
  • 响应式设计
  • 参考 
    references/gallery-patterns.md
示例：
examples/image-gallery.tsx

Carousel/Slider

轮播图/滑块

For sequential image display:
  • Auto-play (optional, pausable for accessibility)
  • Dot or thumbnail navigation
  • Touch/swipe support
  • ARIA roles for accessibility
  • Infinite loop option
  • Reference 
    references/carousel-patterns.md
Example: 
examples/carousel.tsx
适用于图片顺序展示：
  • 自动播放（可选，支持暂停以满足无障碍需求）
  • 圆点或缩略图导航
  • 触摸/滑动支持
  • 无障碍ARIA角色
  • 无限循环选项
  • 参考 
    references/carousel-patterns.md
示例：
examples/carousel.tsx

Image Optimization

图片优化

Essential optimization strategies:
  • Responsive images using 
    srcset
    and 
    sizes
  • Modern formats (WebP with JPG fallback)
  • Progressive JPEGs
  • Blur-up placeholders
  • CDN integration
  • Reference 
    references/image-optimization.md
核心优化策略：
  • 使用 
    srcset
    和 
    sizes
    实现响应式图片
  • 现代格式（WebP 搭配 JPG 降级方案）
  • 渐进式JPEG
  • 模糊占位图
  • CDN集成
  • 参考 
    references/image-optimization.md

Video Components

视频组件

Video Player

视频播放器

For custom video playback:
  • Custom controls or native
  • Play/pause, volume, fullscreen
  • Captions/subtitles (VTT format)
  • Playback speed control
  • Picture-in-picture support
  • Keyboard shortcuts
  • Reference 
    references/video-player.md
Example: 
examples/video-player.tsx
适用于自定义视频播放：
  • 自定义控件或原生控件
  • 播放/暂停、音量、全屏
  • 字幕/副标题（VTT格式）
  • 播放速度控制
  • 画中画支持
  • 键盘快捷键
  • 参考 
    references/video-player.md
示例：
examples/video-player.tsx

Video Optimization

视频优化

Performance strategies for video:
  • Adaptive streaming (HLS, DASH)
  • Thumbnail preview on hover
  • Lazy loading off-screen videos
  • Preload strategies (
    metadata
    , 
    auto
    , 
    none
    )
  • Multiple quality levels
  • Reference 
    references/video-optimization.md
视频性能优化策略：
  • 自适应流（HLS、DASH）
  • 悬停时显示缩略图预览
  • 懒加载视口外的视频
  • 预加载策略（
    metadata
    、
    auto
    、
    none
    ）
  • 多质量级别
  • 参考 
    references/video-optimization.md

Audio Components

音频组件

Audio Player

音频播放器

For audio playback:
  • Play/pause, seek, volume controls
  • Waveform visualization (optional)
  • Playlist support
  • Download option
  • Playback speed control
  • Visual indicators for accessibility
  • Reference 
    references/audio-player.md
Example: 
examples/audio-player.tsx
适用于音频播放：
  • 播放/暂停、进度跳转、音量控件
  • 波形可视化（可选）
  • 播放列表支持
  • 下载选项
  • 播放速度控制
  • 无障碍视觉指示器
  • 参考 
    references/audio-player.md
示例：
examples/audio-player.tsx

Document Viewers

文档查看器

PDF Viewer

PDF查看器

For PDF document display:
  • Page navigation (prev/next, jump to page)
  • Zoom in/out controls
  • Text search within document
  • Download and print options
  • Thumbnail sidebar
  • Reference 
    references/pdf-viewer.md
Example: 
examples/pdf-viewer.tsx
适用于PDF文档展示：
  • 页面导航（上一页/下一页、跳转到指定页）
  • 缩放控件
  • 文档内文本搜索
  • 下载和打印选项
  • 缩略图侧边栏
  • 参考 
    references/pdf-viewer.md
示例：
examples/pdf-viewer.tsx

Office Document Preview

Office文档预览

For DOCX, XLSX, PPTX files:
  • Read-only preview or editable
  • Cloud-based rendering (Google Docs Viewer, Office Online)
  • Local rendering (limited support)
  • Download option
  • Reference 
    references/office-viewer.md
适用于DOCX、XLSX、PPTX文件：
  • 只读预览或可编辑
  • 基于云的渲染（Google Docs Viewer、Office Online）
  • 本地渲染（支持有限）
  • 下载选项
  • 参考 
    references/office-viewer.md

Performance Optimization

性能优化

File Size Guidelines

文件大小指南

Validate client-side before upload:
  • Images: <5MB recommended
  • Videos: <100MB for web, larger for cloud
  • Audio: <10MB
  • Documents: <25MB
  • Provide clear error messages
  • Suggest compression tools
上传前在客户端验证：
  • 图片：建议<5MB
  • 视频：网页端<100MB，云端可更大
  • 音频：<10MB
  • 文档：<25MB
  • 提供清晰的错误提示
  • 推荐压缩工具

Image Optimization Checklist

图片优化检查清单

bash
undefined
bash
undefined

Generate optimized image set

Generate optimized image set

python scripts/optimize_images.py --input image.jpg --formats webp,jpg,avif

Strategies:
- Compress before upload (client or server)
- Generate multiple sizes (thumbnails, medium, large)
- Use responsive `srcset` for device targeting
- Convert to modern formats (WebP, AVIF)
- Serve via CDN with edge caching

Reference `references/performance-optimization.md` for complete guide.
python scripts/optimize_images.py --input image.jpg --formats webp,jpg,avif

策略：
- 上传前压缩（客户端或服务端）
- 生成多种尺寸（缩略图、中等尺寸、大尺寸）
- 使用响应式 `srcset` 适配不同设备
- 转换为现代格式（WebP、AVIF）
- 通过带边缘缓存的CDN分发

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

Video Optimization Checklist

视频优化检查清单

Strategies:
  • Transcode to multiple qualities (360p, 720p, 1080p)
  • Implement adaptive bitrate streaming
  • Use CDN with edge caching
  • Lazy load videos outside viewport
  • Provide poster images
策略：
  • 转码为多种质量（360p、720p、1080p）
  • 实现自适应比特率流
  • 使用带边缘缓存的CDN
  • 懒加载视口外的视频
  • 提供封面图

Accessibility Requirements

无障碍要求

Images

图片

Essential patterns:
  • Alt text required for meaningful images
  • Empty alt (
    alt=""
    ) for decorative images
  • Use 
    <figure>
    and 
    <figcaption>
    for context
  • Sufficient color contrast for overlays
  • Reference 
    references/accessibility-images.md
核心模式：
  • 有意义的图片必须添加替代文本
  • 装饰性图片使用空替代文本（
    alt=""
    ）
  • 使用 
    <figure>
    和 
    <figcaption>
    提供上下文
  • 叠加层需有足够的颜色对比度
  • 参考 
    references/accessibility-images.md

Videos

视频

Essential patterns:
  • Captions/subtitles for all speech
  • Transcript link provided
  • Keyboard controls (space, arrows, M for mute)
  • Pause auto-play (WCAG requirement)
  • Audio description track (if applicable)
  • Reference 
    references/accessibility-video.md
核心模式：
  • 所有语音内容需配字幕/副标题
  • 提供转录文本链接
  • 键盘控件（空格、方向键、M键静音）
  • 可暂停自动播放（WCAG要求）
  • 音频描述轨道（如适用）
  • 参考 
    references/accessibility-video.md

Audio

音频

Essential patterns:
  • Transcripts available
  • Visual indicators (playing, paused, volume)
  • Keyboard controls
  • ARIA labels for controls
  • Reference 
    references/accessibility-audio.md
To validate accessibility:
bash
node scripts/validate_media_accessibility.js
For complete requirements, reference 
references/accessibility-patterns.md
.
核心模式：
  • 提供转录文本
  • 视觉指示器（播放中、已暂停、音量）
  • 键盘控件
  • 控件添加ARIA标签
  • 参考 
    references/accessibility-audio.md
验证无障碍性：
bash
node scripts/validate_media_accessibility.js
完整要求请参考 
references/accessibility-patterns.md
。

Library Recommendations

库推荐

Image Gallery: react-image-gallery

图片画廊：react-image-gallery

Best for feature-complete galleries:
  • Mobile swipe support
  • Fullscreen mode
  • Thumbnail navigation
  • Lazy loading built-in
  • Responsive out of the box
bash
npm install react-image-gallery
See 
examples/gallery-react-image.tsx
for implementation. Reference 
/xiaolin/react-image-gallery
for documentation.
Alternative: LightGallery (more features, larger bundle)
功能完整的画廊首选：
  • 移动端滑动支持
  • 全屏模式
  • 缩略图导航
  • 内置懒加载
  • 原生响应式
bash
npm install react-image-gallery
实现示例请见 
examples/gallery-react-image.tsx
。 文档请参考 
/xiaolin/react-image-gallery
。
替代方案： LightGallery（功能更多，包体积更大）

Video: video.js

视频：video.js

Best for custom video players:
  • Plugin ecosystem
  • HLS and DASH support
  • Accessible controls
  • Theming support
  • Extensive documentation
bash
npm install video.js
See 
examples/video-js-player.tsx
for implementation.
自定义视频播放器首选：
  • 插件生态系统
  • 支持HLS和DASH
  • 无障碍控件
  • 主题支持
  • 详细文档
bash
npm install video.js
实现示例请见 
examples/video-js-player.tsx
。

Audio: wavesurfer.js

音频：wavesurfer.js

Best for waveform visualization:
  • Beautiful waveform display
  • Timeline interactions
  • Plugin support
  • Responsive
  • Lightweight
bash
npm install wavesurfer.js
See 
examples/audio-waveform.tsx
for implementation.
波形可视化首选：
  • 美观的波形展示
  • 时间轴交互
  • 插件支持
  • 响应式
  • 轻量
bash
npm install wavesurfer.js
实现示例请见 
examples/audio-waveform.tsx
。

PDF: react-pdf

PDF：react-pdf

Best for PDF rendering in React:
  • Page-by-page rendering
  • Text selection support
  • Annotations (premium)
  • Worker-based for performance
bash
npm install react-pdf
See 
examples/pdf-react.tsx
for implementation.
For detailed comparison, reference 
references/library-comparison.md
.
React中PDF渲染首选：
  • 分页渲染
  • 支持文本选择
  • 注释（付费功能）
  • 基于Worker提升性能
bash
npm install react-pdf
实现示例请见 
examples/pdf-react.tsx
。
详细对比请参考 
references/library-comparison.md
。

Design Token Integration

设计令牌集成

All media components use the design-tokens skill for theming:
  • Color tokens for backgrounds, overlays, controls
  • Spacing tokens for padding and gaps
  • Border tokens for thumbnails and containers
  • Shadow tokens for elevation
  • Motion tokens for animations
Supports light, dark, high-contrast, and custom themes. Reference the design-tokens skill for theme switching.
Example token usage:
css
.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);
}
所有媒体组件使用design-tokens技能实现主题化：
  • 颜色令牌用于背景、叠加层、控件
  • 间距令牌用于内边距和间距
  • 边框令牌用于缩略图和容器
  • 阴影令牌用于层级
  • 动效令牌用于动画
支持浅色、深色、高对比度和自定义主题。 主题切换请参考design-tokens技能。
令牌使用示例：
css
.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);
}

Responsive Strategies

响应式策略

Image Galleries

图片画廊

Four responsive approaches:
  1. Grid layout - CSS Grid with auto-fit columns
  2. Masonry layout - Pinterest-style with variable heights
  3. Carousel - Single image on mobile, multiple on desktop
  4. Stack - Vertical list on mobile, grid on desktop
See 
examples/responsive-gallery.tsx
for implementations.
四种响应式方案：
  1. 网格布局 - 带auto-fit列的CSS Grid
  2. 瀑布流布局 - 类似Pinterest的可变高度布局
  3. 轮播图 - 移动端单张图片，桌面端多张图片
  4. 堆叠布局 - 移动端垂直列表，桌面端网格
实现示例请见 
examples/responsive-gallery.tsx
。

Video Players

视频播放器

Responsive considerations:
  • 16:9 aspect ratio container
  • Full-width on mobile
  • Constrained width on desktop
  • Picture-in-picture for multitasking
  • Touch-friendly controls (larger hit areas)
Reference 
references/responsive-media.md
for patterns.
响应式注意事项：
  • 16:9宽高比容器
  • 移动端全屏宽度
  • 桌面端限制宽度
  • 画中画支持多任务处理
  • 触控友好的控件（更大的点击区域）
模式参考 
references/responsive-media.md
。

Cloud Storage Integration

云存储集成

Client-Side Direct Upload

客户端直接上传

For AWS S3, Cloudinary, etc.:
  1. Request signed URL from backend
  2. Upload directly to cloud storage
  3. Notify backend of completion
  4. Display uploaded media
Benefits:
  • Reduces server load
  • Faster uploads (direct to CDN)
  • No file size limits on your server
See 
examples/s3-direct-upload.tsx
for implementation. Reference 
references/cloud-storage.md
for setup.
适用于AWS S3、Cloudinary等：
  1. 从后端请求签名URL
  2. 直接上传到云存储
  3. 通知后端上传完成
  4. 展示已上传的媒体
优势：
  • 降低服务器负载
  • 更快的上传速度（直接到CDN）
  • 服务器无文件大小限制
实现示例请见 
examples/s3-direct-upload.tsx
。 设置指南参考 
references/cloud-storage.md
。

Testing Tools

测试工具

Generate mock media:
bash
undefined
生成模拟媒体：
bash
undefined

Generate test images

Generate test images

python scripts/generate_mock_images.py --count 50 --sizes thumb,medium,large
python scripts/generate_mock_images.py --count 50 --sizes thumb,medium,large

Generate test video metadata

Generate test video metadata

python scripts/generate_video_metadata.py --duration 300

Validate media accessibility:
```bash
node scripts/validate_media_accessibility.js
Analyze performance:
bash
node scripts/analyze_media_performance.js --files images/*.jpg
python scripts/generate_video_metadata.py --duration 300

验证媒体无障碍性：
```bash
node scripts/validate_media_accessibility.js
分析性能：
bash
node scripts/analyze_media_performance.js --files images/*.jpg

Working Examples

可用示例

Start with the example matching the requirements:
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
根据需求选择对应的示例：
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

Resources

资源

Scripts (Token-Free Execution)

脚本（无需令牌即可执行）

  • scripts/optimize_images.py
    - Batch image optimization
  • scripts/generate_mock_images.py
    - Test image generation
  • scripts/validate_media_accessibility.js
    - Accessibility validation
  • scripts/analyze_media_performance.js
    - Performance analysis
  • scripts/optimize_images.py
    - 批量图片优化
  • scripts/generate_mock_images.py
    - 测试图片生成
  • scripts/validate_media_accessibility.js
    - 无障碍性验证
  • scripts/analyze_media_performance.js
    - 性能分析

References (Detailed Documentation)

参考文档（详细说明）

  • references/upload-patterns.md
    - File upload implementations
  • references/gallery-patterns.md
    - Image gallery designs
  • references/video-player.md
    - Video player features
  • references/audio-player.md
    - Audio player patterns
  • references/pdf-viewer.md
    - Document viewer setup
  • references/accessibility-patterns.md
    - Media accessibility
  • references/performance-optimization.md
    - Optimization strategies
  • references/cloud-storage.md
    - Cloud integration guides
  • references/library-comparison.md
    - Library analysis
  • 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 (Implementation Code)

示例（实现代码）

  • See 
    examples/
    directory for working implementations
  • 请查看 
    examples/
    目录下的可用实现

Assets (Templates and Configs)

资源（模板和配置）

  • assets/upload-config.json
    - Upload constraints and settings
  • assets/media-templates/
    - Placeholder images and icons
  • assets/upload-config.json
    - 上传限制和设置
  • assets/media-templates/
    - 占位图片和图标

Cross-Skill Integration

跨技能集成

This skill works with other component skills:
  • Forms: File input fields, validation, submission
  • Feedback: Upload progress, success/error messages
  • AI Chat: Image attachments, file sharing
  • Dashboards: Media widgets, thumbnails
  • Design Tokens: All visual styling via token system
本技能可与其他组件技能配合使用：
  • Forms：文件输入字段、验证、提交
  • Feedback：上传进度、成功/错误提示
  • AI Chat：图片附件、文件分享
  • Dashboards：媒体小部件、缩略图
  • Design Tokens：通过令牌系统实现所有视觉样式

Next Steps

后续步骤

  1. Identify the media type (images, video, audio, documents)
  2. Determine upload requirements (size, quantity, editing)
  3. Choose display pattern (gallery, carousel, player, viewer)
  4. Select library or implement custom solution
  5. Implement accessibility requirements
  6. Apply optimization strategies
  7. Test performance and responsive behavior
  8. Integrate with cloud storage (optional)
  1. 确定媒体类型（图片、视频、音频、文档）
  2. 明确上传需求（大小、数量、编辑）
  3. 选择展示模式（画廊、轮播、播放器、查看器）
  4. 选择库或实现自定义方案
  5. 实现无障碍要求
  6. 应用优化策略
  7. 测试性能和响应式表现
  8. 集成云存储（可选）