carguo gsy-compose-integration
模块
gsyVideoPlayer-compose 是 Compose 桥接层，两种模式并存：
| 模式 | 入口 | 说明 |
|---|---|---|
| Wrapper（推荐上手） | GSYVideoPlayerView / GSYAnyVideoPlayerView | AndroidView 直接承载 StandardGSYVideoPlayer / 任意 NormalGSYVideoPlayer 子类，保留全部内置能力 |
| Native（纯 Compose 控件） | rememberGSYPlayerController + GSYPlayerSurface + GSYDefaultControls | 只承载画面，控制层完全用 Compose 自绘 |
| 通用工具 | LifecycleBridge | LifecycleEffect { event -> ... } 用于订阅宿主 Lifecycle |
Wrapper API：GSYVideoPlayerView
见 GSYVideoPlayerView#L28-L36：
| 参数 | 类型 | 说明 |
|---|---|---|
modifier |
Modifier |
通常 Modifier.fillMaxWidth().aspectRatio(16f/9) |
setUp |
(StandardGSYVideoPlayer) -> Unit |
等价 GSYVideoOptionBuilder.build(player) |
setUpKey |
Any? = null |
非空时其变化会重新调用 setUp（典型：传 url） |
autoReleaseOnDispose |
Boolean = true | 离屏自动 player.release() |
autoPauseResume |
Boolean = true | 自动桥 Lifecycle：ON_PAUSE→GSYVideoManager.onPause()、ON_RESUME→onResume() |
onPlayerCreated |
(StandardGSYVideoPlayer) -> Unit |
拿到 player 实例的回调 |
Wrapper API：GSYAnyVideoPlayerView<T : NormalGSYVideoPlayer>
见 GSYAnyVideoPlayerView#L26-L35。相比 GSYVideoPlayerView 多出：
| 参数 | 类型 | 说明 |
|---|---|---|
factory |
(Context) -> T |
传自定义子类（如 ListGSYVideoPlayer、SampleControlVideo、DanmakuVideoPlayer） |
Native API：rememberGSYPlayerController
见 rememberGSYPlayerController#L26-L32：
| 参数 | 默认 | 说明 |
|---|---|---|
url |
null | 非空时内部 LaunchedEffect 触发 controller.setUp(...) |
cacheWithPlay |
false | 边播边缓 |
title |
"" | 标题（透传给底层 player） |
autoPlay |
false | attach 完成后自动 startPlayLogic |
autoPauseResume |
true | 自动订阅 Lifecycle（同 wrapper） |
返回 GSYPlayerController，可以再调 .play() / .pause() / .seekTo(ms) / .setSpeed(...) / .setUp(url, cache, title, autoPlay) / .dispose()；状态订阅走 GSYPlayerState（StateFlow<GSYPlayerState>），事件走 GSYPlayerEvent。
最小可运行示例
Wrapper 模式：
GSYVideoPlayerView(
modifier = Modifier.fillMaxWidth().aspectRatio(16f/9),
setUpKey = url,
setUp = { player ->
GSYVideoOptionBuilder()
.setUrl(url)
.setCacheWithPlay(true)
.setVideoTitle("demo")
.setIsTouchWiget(true)
.setAutoFullWithSize(true)
.build(player)
player.startPlayLogic()
}
)
Native 模式：
val controller = rememberGSYPlayerController(url = url, autoPlay = true)
Box(Modifier.fillMaxWidth().aspectRatio(16f/9)) {
GSYPlayerSurface(controller = controller, modifier = Modifier.matchParentSize())
GSYDefaultControls(controller = controller)
}
生命周期最佳实践
val lifecycle = LocalLifecycleOwner.current.lifecycle
DisposableEffect(lifecycle) {
val obs = LifecycleEventObserver { _, e ->
when (e) {
Lifecycle.Event.ON_PAUSE -> state.pause()
Lifecycle.Event.ON_RESUME -> state.resumeIfNeeded()
Lifecycle.Event.ON_DESTROY-> state.release()
else -> Unit
}
}
lifecycle.addObserver(obs)
onDispose { lifecycle.removeObserver(obs) }
}
Demo 对照
| 场景 | Activity |
|---|---|
| 原生桥接示例 | DetailNativeActivity / BasicWrapperActivity / FullFeatureNativeActivity |
| 广告 + 主片（列表内） | AdInListComposeActivity |
| 列表 + 全屏 | ListWithFullscreenActivity / ListPlayNativeActivity / AutoPlayListActivity |
| 抖音式竖屏 | VerticalShortVideoComposeActivity |
| 滤镜 | DetailFilterComposeActivity |
| 无缝切源 / Exo 切源 | SwitchSeamlessComposeActivity / ExoSwitchSourceComposeActivity / SwitchUrlActivity |
| 字幕 | SubtitleComposeActivity |
| 弹幕 | DanmakuComposeActivity |
| 缓存 / 下载 | CacheDownloadComposeActivity |
| 硬解 / MediaCodec | MediaCodecComposeActivity |
| 悬浮小窗 | FloatingWindowComposeActivity |
| 音频独立 | AudioOnlyComposeActivity |
| 多类型混排 | MoreTypeComposeActivity |
| 多窗口并行 | MultiWindowActivity / MultiWindowParallelComposeActivity |
| 本地文件 | LocalFileComposeActivity |
| 自定义主题 | CustomControlsThemeComposeActivity |
| WebView 详情 | WebDetailComposeActivity |
样例 hosts 全在 compose/host/。
常见坑
- Compose 频繁重组 →
AndroidView的factory只跑一次；不要把setUp放在factory里，放到updateblock，并用remember(url)做去重。 AndroidView内部布局要指定固定高度或aspectRatio，否则 SurfaceView 会 0 高度导致黑屏。- 竖直短视频 +
Pager：切页时用pagerState.currentPage触发state.play(url) / previousState.pause()；释放放在DisposableEffect(pagerState)里。 - 与 Compose 主题深浅色切换：
GSYVideoPlayerCompose是原生 View 层，配色需要单独setBottomProgressBarDrawable等 API。