移动端竖屏短视频方案 — 设计与折腾记录项目mybilibili模块mybilibili-wapVue3 Vite 移动端 SPA 后端 Go 微服务日期2026-08-26本文记录竖屏视频从数据层到移动端展示、再到全屏方案与安卓 WebView 打包的完整链路以及过程中踩过的坑折腾。一、背景为什么要做竖屏一个移动端视频平台竖屏9:16 短视频是刚需—— 手机上竖着看视频是自然习惯对标抖音/快手。但平台最初所有视频都按横屏处理数据库videos表没有任何方向/宽高字段无从判断横竖屏。转码管道用横屏思维scale1280:-2竖屏源会被拉成超高分辨率。播放器固定 16:9竖屏视频被压扁或留黑边体验差。实测存量数据13 个视频里有 5 个是竖屏360×640说明竖屏内容真实存在、必须支持。二、数据层让横竖屏变成可存储、可查询的字段2.1 数据库加字段ALTERTABLEvideosADDCOLUMNIFNOTEXISTSis_verticalSMALLINTNOTNULLDEFAULT0;-- 0 横屏 (width height)-- 1 竖屏 (height width)迁移文件sql/026_video_orientation.sql含存量回填。2.2 转码时自动探测work-service转码管道本来就用 ffprobe 取时长顺带取宽高判断方向func(w*TranscodeWorker)GetVideoSize(ctx,srcFile)(width,heightint,errerror){// ffprobe -select_streams v:0 -show_entries streamwidth,height}转码开始时探测源文件height width即竖屏随 NATS 进度事件上报。2.3 核心服务回写 出参core-service进度订阅里把is_vertical写回videos表ManuscriptInfopb 加IsVertical字段(27)manuscriptToMap输出让所有列表接口推荐/热门/频道/搜索/相关都能拿到方向。FirstVideoIsVertical()查稿件第一个分P的方向作为稿件级方向。2.4 转码比例顺带修复scale1280:-2→scalemin(1280,iw):-2竖屏源不再被放大到 1280×2276保持竖屏比例宽不超 1280、不放大原宽。三、移动端展示抖音式全屏短视频页新增页面src/views/video/VerticalFeed.vue路由/m/vertical/:aId。3.1 交互设计对标抖音/快手全屏滑动流每屏一条视频100dvh全屏黑底上下滑动切换scroll-snap自动播放当前视频自动播、其他暂停切屏懒加载对应视频详情并换源HLS 用 hls.js右侧操作栏UP主头像(关注)、点赞❤️、评论、收藏⭐、分享↗底部信息作者、标题(2行截断)、简介、旋转唱片音乐条双击点赞心形动画单击播放/暂停300ms 内双击点赞 心形飘出评论面板底部抽屉拉取真实评论加载动画 / 顶部进度条3.2 视频铺满整个屏幕关键认知手机屏幕就是视频本身这是抖音式体验的核心竖屏视频object-fit: cover裁切铺满整屏不露黑边横屏视频object-fit: contain居中 模糊封面铺满背景抖音处理横屏的方式不再是大黑边3.3 竖屏视频点击直达列表项首页推荐/热门、频道、搜索、相关推荐携带isVerticalVideoItem.vue的router-link :to按方向分流video.isVertical ? /m/vertical/ aId : /m/video/ aId→点竖屏视频直接进短视频全屏页横屏仍走普通详情页。退出竖屏 → 回到普通详情页16:9 左右补黑边与横屏一致。四、全屏方案浏览器 Fullscreen API 还是 CSS 应用全屏最大的折腾这是踩坑最多、最容易想当然的地方。全屏有两种别混为一谈。4.1 两种全屏的区别浏览器原生全屏 (Fullscreen API)应用全屏 (CSS)触发document.requestFullscreen()position: fixed; inset:0; 100dvh手势必须在用户点击手势内不需要提示浏览器提示按 ESC 退出无意外退出用户按 ESC 直接退出不会iOS Safari不支持普通元素全屏支持Android WebView默认空操作支持4.2 最初想当然的错误一开始以为要全屏 调浏览器 Fullscreen API于是在openVertical点击手势内requestFullscreen()再跳转在竖屏页onMounted也requestFullscreen()结果被拒无手势加了手动全屏切换按钮、fullscreenchange监听。结果一堆问题手势限制、ESC 意外退出、WebView 里空操作、iOS 不生效。纯属过度设计。4.3 结论只需要 CSS 应用全屏竖屏页用position: fixed; inset: 0; 100dvh铺满视口即可无手势限制、无 ESC 提示、不会被意外退出浏览器、WebView 行为完全一致代码量大幅减少。彻底删掉 Fullscreen APIrequestFullscreen/exitFullscreen/toggleFullscreen/监听器/全屏按钮。五、安卓 WebView 打包如何配合重点目标是把 wap 塞进mybilibili-webview-appAndroid WebView打包成 APK。5.1 WebView 天然就是手机全屏WebView 布局是match_parent铺满整个 Activity→wap 的 CSS 应用全屏 铺满整个手机屏幕。所以 wap 端只用 CSS 应用全屏塞进 WebView 后天然就是真·全屏什么都不用额外做。5.2 浏览器 Fullscreen API 在 WebView 里是空操作requestFullscreen()在 WebView 里默认不生效除非你在WebChromeClient里实现onShowCustomView(View, CustomViewCallback)和onHideCustomView()。所以对 WebView 打包来说Fullscreen API 调了也白调删掉正好。5.3 如果要隐藏 Android 系统栏沉浸式想在竖屏时连状态栏/导航栏都隐藏那是Java 层的事跟 wap 无关// MainActivity沉浸式模式示意WindowCompat.setDecorFitsSystemWindows(getWindow(),false);WindowInsetsControllerCompatcontrollerWindowCompat.getInsetsController(getWindow(),window.getDecorView());controller.hide(WindowInsetsCompat.Type.systemBars());controller.setSystemBarsBehavior(WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE);也可以通过JS BridgeaddJavascriptInterface在进入竖屏页时切沉浸模式。简单原则web 只负责铺满视口隐藏系统栏交给安卓原生层。六、折腾记录踩坑清单6.1 竖屏按钮被顶部导航栏盖住点了没反应详情页.top-nav-bar是z-index: 999的固定头竖屏按钮只有z-index: 20被完全遮住。用无头浏览器elementFromPoint实测命中的是top-nav-bar。修复按钮z-index提到 1000。教训elementFromPoint是验证元素是否真的可点的好工具。6.2 评论数一直拿不到显示 0数据其实一直真实存在是前端字段映射写错位置错误正确详情getVideoInfodata.danmakuCount弹幕数data.commentCount推荐adaptRecommendv.comment_countsnakev.commentCountcamel教训后端manuscriptToMap会convertKeysToCamelsnake→camel而 search-service 返回 snake_case。两个后端字段命名风格不一致前端要分别兼容。6.3 点赞/评论/收藏数量不真实推荐流项没映射likeCount/collectCount→ 初始显示 0收藏按钮只显示收藏/已藏文字、没有数字已赞/已藏/已关注状态没查后端 → 进入时状态永远是未赞/未藏/未关注。修复adaptRecommend补likeCount/collectCount收藏按钮显示真实collectCount每条视频加载后调getInteractionStatuscheckFollow拉真实状态。6.4 分P多P选择不跳转点分P只是高亮播放器没换源。根因三叠加videoParts丢了每个分P的playUrlselectPart没通知播放器之前加的同 aId 跳过重建逻辑让分P切换aId 相同也被跳过。修复分P携带 playUrl新增switchPart()用art.switchUrl()直接换源 重载对应分P弹幕。6.5 进入视频页画面抖动SWR 流程缓存→网络两次applyVideoData都触发播放器 watch 销毁重建 → 视频重载闪一下。修复播放器 watch 里同 aId 数据刷新不重建只真正切换视频时才重建。6.6 分P弹幕栏重复累积artplayer-plugin-danmuku把控件挂到播放器外的#danmaku-emitter-mountart.destroy()不清理它每次重建就多一份。修复destroyPlayer里手动清空 mount 节点。七、关键结论数据先行方向这种元数据要入库并在转码时自动探测才能支撑前端判断。移动端竖屏 铺满视口抖音式的核心是屏幕即视频用cover铺满 横屏模糊背景。全屏别过度设计浏览器 Fullscreen API 只适合桌面/需要真全屏的场景移动 app 用CSS 应用全屏就够了。WebView 打包友好CSS 应用全屏天然填满手机隐藏系统栏交给安卓原生层沉浸模式 / JS Bridge。验证用无头浏览器elementFromPoint、真实鼠标/触屏事件、getAnimations()都是排查为什么没生效的好工具。完