77 lines
3.2 KiB
Markdown
77 lines
3.2 KiB
Markdown
# SharedUI/Media
|
||
媒体通用视图与组件。
|
||
|
||
## WakeVideoPlayer
|
||
一个遵循项目 Theme 风格的 SwiftUI 视频播放组件，基于 `AVKit` 封装。
|
||
|
||
支持：
|
||
- 播放 / 暂停
|
||
- 进度条拖动（支持拖动中不打断播放进度回调）
|
||
- 静音切换
|
||
- 全屏播放（`fullScreenCover`）
|
||
- 自动隐藏控件（播放中 2.5s 无操作自动隐藏）
|
||
- 自动播放与循环播放
|
||
- 自定义填充模式（`videoGravity`）
|
||
|
||
### 用法示例
|
||
```swift
|
||
import SwiftUI
|
||
|
||
struct DemoVideoCard: View {
|
||
var body: some View {
|
||
WakeVideoPlayer(
|
||
url: URL(string: "https://devstreaming-cdn.apple.com/videos/wwdc/2020/10653/4/17B5F5F3-4D9E-4BAE-8E8F-2C3C7A01F3F2/cmaf.m3u8")!,
|
||
autoPlay: false,
|
||
isLooping: true,
|
||
showsControls: true,
|
||
allowFullscreen: true,
|
||
muteInitially: false,
|
||
videoGravity: .resizeAspectFill
|
||
)
|
||
.frame(height: 220)
|
||
.clipShape(RoundedRectangle(cornerRadius: Theme.CornerRadius.large, style: .continuous))
|
||
.shadow(color: Theme.Shadows.cardShadow.color, radius: Theme.Shadows.cardShadow.radius, x: Theme.Shadows.cardShadow.x, y: Theme.Shadows.cardShadow.y)
|
||
.padding()
|
||
}
|
||
}
|
||
```
|
||
|
||
### 初始化参数
|
||
- `url: URL` 必填。视频资源地址，支持网络或本地文件 URL。
|
||
- `autoPlay: Bool = true` 首次出现是否自动播放。
|
||
- `isLooping: Bool = false` 是否循环播放。
|
||
- `showsControls: Bool = true` 是否显示自定义控制层。
|
||
- `allowFullscreen: Bool = true` 是否允许进入全屏播放。
|
||
- `muteInitially: Bool = false` 初始是否静音。
|
||
- `videoGravity: AVLayerVideoGravity = .resizeAspectFill` 视频填充模式，如 `.resizeAspect` / `.resizeAspectFill`。
|
||
- `fallbackURL: URL? = nil` 备用码流地址（建议提供 H.264/HLS）。当检测到资源为 HEVC 且当前环境不支持硬解码（如模拟器）时，自动使用该地址播放。
|
||
|
||
### 注意事项
|
||
- 如果是新加入的文件，确保在 Xcode 中将 `WakeVideoPlayer.swift` 添加到对应 Target，否则无法被编译。
|
||
- 远程流地址需确保允许跨域与 HTTPS，示例使用 Apple 公共 HLS 资源。
|
||
- 如果需要画中画（PiP）、双击快退/快进、手势亮度/音量等高级功能，可在此基础上扩展。
|
||
|
||
### HEVC/H.265 支持说明与降级策略
|
||
- 模拟器通常不支持 HEVC 硬解码，表现为“只有声音、无画面”。真机（A9 及以上设备）通常支持。
|
||
- 组件会在加载时异步分析资源轨道编码；若检测到 HEVC 且当前环境不支持硬解码，则：
|
||
- 若提供了 `fallbackURL`（建议为 H.264 或多码率 HLS），将自动切换播放该备用源；
|
||
- 若未提供 `fallbackURL`，会显示顶部黄色提示，建议在真机测试或提供备用码流。
|
||
|
||
示例：
|
||
```swift
|
||
WakeVideoPlayer(
|
||
url: URL(string: "https://example.com/video_h265.mp4")!,
|
||
fallbackURL: URL(string: "https://example.com/video_h264.m3u8")!,
|
||
autoPlay: true,
|
||
isLooping: false,
|
||
showsControls: true,
|
||
allowFullscreen: true,
|
||
muteInitially: false,
|
||
videoGravity: .resizeAspect
|
||
)
|
||
.frame(height: 220)
|
||
```
|
||
|
||
建议优先使用 HLS（.m3u8）主清单，内含多编码/多分辨率分流，兼容性更佳。
|
||
|