hwc-media-content

媒体与富内容

使用 Stimulus 和 Turbo Frames 实现以媒体为核心的 Hotwire 功能。

核心工作流

1. 确定媒体模式：上传／预览、播放控制、进度持久化，或嵌入式媒体库集成。
2. 在 Stimulus values 中保存媒体状态；通过 value 回调和 targets 对接第三方 API。
3. 优先使用浏览器原生 API（URL.createObjectURL、画中画、IntersectionObserver、MediaSession）。
4. 在 disconnect() 中清理所有已分配的资源（观察器、blob URL、播放器实例、计时器）。
5. 仅持久化有意保留的客户端状态（例如播放进度），并在加载时进行协调。

注意事项

• 图片／文件预览渲染后，撤销 blob URL。
• 对浏览器 API（画中画／Web Share／MediaSession）优先使用功能检测。
• 避免混杂传输相关事项；媒体渲染归此处处理，流编排归实时功能处理。
• 对基于时间的 UI（歌词、轮播、进度组件）采用增量式 frame 更新。

按需加载参考资料

仅打开当前请求所需的文件。

• 通过 blob URL 预览上传内容：references/2024-09-17-stimulus-image-upload-previews.md
• 渐进式图片加载和 Blurhash：references/2024-04-23-stimulus-progressive-image-loading-blurhash.md
• 画中画行为：references/2024-06-04-stimulus-picture-in-picture.md
• 视频进度持久化：references/2024-10-29-stimulus-video-progress-tracker.md
• WaveSurfer 标记添加流程：references/2024-07-02-stimulus-wavesurfer-add-markers.md
• WaveSurfer 标记移除流程：references/2024-07-30-stimulus-wavesurfer-remove-markers.md
• 与时间同步的歌词 frame 更新：references/2024-04-09-turbo-frames-scrolling-lyrics.md
• 使用 Turbo Frames 实现 Swiper 自动播放：references/2025-01-14-turbo-frames-swiper-autoplay.md

完整目录请参阅 references/INDEX.md。

转交给相邻技能

• 推送式数据更新或自定义 Turbo Stream 操作：使用 hwc-realtime-streaming
• 分页／标签／筛选导航相关问题：使用 hwc-navigation-content
• 表单生命周期和验证处理：使用 hwc-forms-validation
• 通用加载／进度／过渡 UX：使用 hwc-ux-feedback
• 纯 Stimulus API 架构：使用 hwc-stimulus-fundamentals