从零写一个 HarmonyOS NEXT 影视聚合播放器,我踩过的 14 个坑

市面上鸿蒙生态的影视聚合工具,几乎全是安卓套壳转译的产物,体验一言难尽。于是我花了业余时间,用纯 ArkTS / ArkUI 从零写了一个 HarmonyOS NEXT 原生的聚合播放器「聚源盒」:多协议站点引擎(CMS / AppYs / XBPQ / JS 插件)、三级弹幕源自动回退、断点续传下载、投屏、直播。

GitHub:github.com/zhaozipengn... Gitee:gitee.com/ZKingp/juyu...

这篇文章不讲架构,只讲踩坑------每一个坑都消耗过至少一轮"改了没反应"的调试时间。全部来自真机实测,希望能帮后来者省下这些夜晚。


坑 1:expandSafeArea 的子布局偏移------进度条凭空消失

现象:播放器底部控制层(进度条 + 按钮)在部分页面状态下整块消失,怎么调 z 序都没用。

根因 :给视频容器加了 expandSafeArea([SYSTEM], [TOP]) 之后,组件自身画在扩展坐标里,但它的子组件布局原点被下移了一个状态栏高度 。我用 position({ y: '100%' }) + markAnchor 锚定在底部的控制层,整个沉到了容器盒子之外,再叠一个 clip(true) 就被裁得干干净净。

排查方法 (这个比结论更重要):用 uitest 的 dumpLayout 导出布局树,对照每个节点的 origBounds(真实布局盒)和 bounds(裁剪后可见盒)------两者出现一个状态栏高度的 y 偏差,实锤。 解法 :根布局已经做过全屏扩展时,删掉子容器上冗余的 expandSafeArea。


坑 2:Column 默认 alignItems 是 Center------"简介"两个字莫名其妙居中

现象:详情区所有标题都左对齐,唯独"简介"居中。

根因 :ArkUI 的 Column 默认 alignItems 是 Center 。其他标题块里的子项都设了 width('100%'),居中看不出来;而"简介"标题是唯一一个没有宽度的 Text,被默认规则居中了。

解法 :要么给块加 .alignItems(HorizontalAlign.Start),要么给 Text 满宽。养成习惯:声明式布局里每个 Column 都显式写对齐。


坑 3:属性链的"就近附着"------padding 挂错了组件

现象:选集标题没有左缩进,和"线路"标题不齐。

根因:这段代码------

ts

scss 复制代码
Column({ space: 8 }) {
  Text('选集')...
  List(...)...
}.width('100%').height(40)
}.width('100%').padding({ left: 16, right: 16 })

padding 想挂在 Column 上,但它的位置在 List 的属性链尾部------ArkUI 属性就近附着给最后一个组件,与换行缩进无关。padding 实际挂在了 List 上,Column 一丝不挂。

解法:属性链永远紧跟目标组件写,块级容器单独换行写属性。


坑 4:@ComponentV2 读 @ObservedV2 单例,不建立响应依赖

现象:历史页点"清空",数据真的清了,UI 纹丝不动;设置页改了壁纸,首页毫无反应,杀掉 App 重开才生效。

根因 :@ComponentV2 直接渲染 @ObservedV2 单例的属性(包括在 build 里通过方法间接读取),不建立响应依赖。数组整体重赋值也不行。

解法 :页面持 @Local 镜像,操作后与页面 onShown 时同步单例。但对常驻 Tab 页(首页/直播页)这招不够------它们没有 onShown 时机,永不重建。最终方案是显式通知:

ts

typescript 复制代码
// AppSettings 单例
private listeners: (() => void)[] = [];
onChange(cb: () => void) { this.listeners.push(cb); }
save() { /* ...落盘... */ this.listeners.forEach(cb => cb()); }


// 消费页
aboutToAppear() {
  this.settings.onChange(() => this.syncSettings());  // 刷 @Local 镜像
  this.syncSettings();
}
aboutToDisappear() { /* offChange 注销 */ }

不改框架、不依赖观察魔法,任何 API 版本都成立。


坑 5:WaterFlow 的列宽不随列数变化

现象:图片尺寸设置从 3 列切到 4 列,列模板变了,海报还按旧列宽渲染,互相压叠。

根因 :FlowItem 的宽度是 onAreaChange 实测容器宽度后算出来的------而列数变化时容器总宽不变,onAreaChange 不会重新触发。

解法 :给组件加 @Monitor('columns'),列数一变就用记录下来的容器净宽重算:

ts

kotlin 复制代码
@Monitor('columns')
onColumnsChange(): void { this.recalcColW(); }

坑 6:Canvas 弹幕一顿一顿------三件套解决

现象:弹幕渲染像 PPT。

根因有三个,缺一不可:

  1. 播放头直接锚定 curTime:引擎进度回调几百毫秒才跳一次,弹幕每几百毫秒瞬移一格。解法是平滑外推:

ts

javascript 复制代码
let t = this.curTime;
if (this.isPlaying) {
  t += Math.min((Date.now() - this.danmuClockAt) / 1000, 1.5);  // 缓冲最多外推 1.5s
}
// 每次引擎回调时刷新 danmuClockAt 锚点
  1. 每帧从第 0 条全量扫描 几千条弹幕。加一个只进不退的头部指针,滚出窗口的直接跳过;绘制循环里遇到未到场的(时间升序)直接 break。
  2. 每帧对可见弹幕 measureText。按条目下标缓存进 Map,换集清空。

三件套上完,30fps 稳稳跑满。


坑 7:AVPlayer 状态机时序------同步赋值全部被拒

AVPlayer 的每个属性都有状态门槛:

  • surfaceId 只能在 initialized 状态设置(XComponent 的 onLoad 时机刚好,但要防页面重入)
  • setSpeed / loop 只能在 prepared 之后
  • 直接 player.url = xxx 再立刻 prepare(),同步赋值会打在 idle 上被状态机拒绝

解法:封装一层引擎,所有属性赋值存成 pending,状态回调里按门槛依次补发。


坑 8:Video 组件的倍速是"假的"

SDK 26 的 Video 组件:controller.setSpeed 不存在;currentProgressRate 属性只在构造期生效 ,动态改无效;VideoController 也没有倍速方法。 结论 :要真倍速,必须 AVPlayer + XComponent 自己写控制层。这就是整个播放器自研的根本原因。


坑 9:request.agent 的 saveas 契约

下载框架 request.agent 的 saveas 不支持绝对沙箱路径 ,支持的是 './data/storage/...' 这种 base 目录内的相对形态:

ts

ini 复制代码
saveas: '.' + localPath,   // localPath = context.filesDir + '/downloads/xxx.mp4'

而且不同设备/版本会把相对路径解释到 cacheDir 下,需要做一次存在性探测 + 文件搬运自愈,播放按钮拿到的路径才是对的。


坑 10:ArkTS 解不了 deflate-raw------借浏览器的手

弹幕源 list.so 返回的是 deflate 原始压缩的 XML ,而 ArkTS 的 zlib 只支持文件级解压,没有流式 inflate API。 解法 :常驻一个 ArkWeb 容器当"计算器",把字节 base64 塞进去,用浏览器原生的 DecompressionStream('deflate-raw') 解压再传回来:

ts

ini 复制代码
const script = `(async () => {
  const bin = Uint8Array.from(atob('${b64}'), c => c.charCodeAt(0));
  const stream = new Blob([bin]).stream().pipeThrough(new DecompressionStream('deflate-raw'));
  window.__evalResult = await new Response(stream).text();
})();`;

杀鸡用了牛刀,但牛刀就在手边。


坑 11:B 站风控对 buvid3 的格式有要求

匿名请求弹幕接口时带了 Cookie: buvid3=随机hex,返回空响应体 ------风控对 buvid3 有UUID 格式校验 : ts

arduino 复制代码
// 必须是 8-4-4-4-12 的 UUID 形态
'buvid3=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

合法格式 + wbi 签名搜索 + 分 P 对齐,整条匿名链路才通。全程无需任何登录。


坑 12:挖孔避让别拍数值

全屏播放器两侧的悬浮图标,第一次放 30vp 被挖孔挡住;拍脑袋挪到 70vp,用户嫌太靠里。

解法 :display.getDefaultDisplaySync().getCutoutInfo() 实测挖孔边界,图标统一放在挖孔外 10vp。注意两个细节:本 SDK 的 Rect 字段是 left/top/width/height(不是 right/bottom);挖孔 rects 是竖屏自然方向坐标,横屏时挖孔落在左右缘垂直中部,正反两个方向都要避让。


坑 13:cryptoFramework 的 Mac 是 doFinal,不是 digest

给弹弹play API 做签名时踩的:cryptoFramework.createMac('SHA256') 的取结果方法是 doFinal() ------digest() 是 Md 类的。两个类一字之差,编译器报"digest 不存在"时很容易以为导入错了。 顺带:对称密钥从原始字节恢复用 SymKeyGenerator.convertKey({ data }),不是 generateSymKey(那个是随机生成)。


坑 14:底部锚定行互相覆盖吞点击

两个全宽、position(y:'100%') 底部锚定的 Row,因 padding 导致透明盒子互相重叠,声明在后的 z 序更高;一旦给后声明行加了吞掉点击的空 onClick,先声明行按钮的点击就全被吞了。

解法 :收进一个内容自适应高度的底部锚定 Column,子行盒子互不重叠,吞没 onClick 只放 Column 一层。还是用 dumpLayout 对照 bounds 实锤的重叠。


这 14 个坑里,有 9 个的排查都靠同一招:uitest 的 dumpLayout 对照 origBounds 和 bounds。声明式 UI 的"所见"和"所布局"经常不是一回事,工具链给的真实坐标比肉眼和猜测都可靠。

项目完整开源(GPL-3.0),不内置任何内容、需自行导入订阅配置,仅供学习交流:

如果帮到了你,一个 Star 是对独立开发者最大的鼓励。欢迎 Issue 交流踩坑。

相关推荐
程序员大阳18 分钟前
副队长ES6+教程(4)--拓展运算符
javascript·vue.js·es6·收集·拓展运算符·展开
Mh1 小时前
AI 的模型能力越来越强,为什么我的编码能力越来越弱?
前端·javascript·后端
黑土豆2 小时前
网页框一下就能截图Region-snap:我把这套功能封装成了 npm 包,支持 Vue 和 React
前端·javascript·npm
李纲明2 小时前
微信小程序开了 Skyline 后样式全乱、滚动对不上甚至部分组件不能用?Skyline 怎么接才稳
javascript·微信小程序·小程序·devdiy
程序员大阳2 小时前
副队长ES6+教程(7)--ES6+函数新特性
javascript·es6·函数·特性·默认参数·剩余参数·参数解构
晓得迷路了3 小时前
栗子前端技术周刊第 154 期 - Parcel 3 Alpha、JS 调查报告、Vite 漏洞...
前端·javascript·css
afumu3 小时前
在 Chrome 扩展里抓网页 AI 的工具调用:patch fetch 和看 DOM,我两条路都跑过
javascript·chrome·浏览器
M--Y13 小时前
LangGraph 工作流模式
开发语言·javascript·python·langchain·大模型·llm·langgraph
johnjincaaaa18 小时前
猿人学第 18 题「jsvmp 洞察先机」逆向通关实录
javascript·后端