市面上鸿蒙生态的影视聚合工具,几乎全是安卓套壳转译的产物,体验一言难尽。于是我花了业余时间,用纯 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。
根因有三个,缺一不可:
- 播放头直接锚定
curTime:引擎进度回调几百毫秒才跳一次,弹幕每几百毫秒瞬移一格。解法是平滑外推:
ts
javascript
let t = this.curTime;
if (this.isPlaying) {
t += Math.min((Date.now() - this.danmuClockAt) / 1000, 1.5); // 缓冲最多外推 1.5s
}
// 每次引擎回调时刷新 danmuClockAt 锚点
- 每帧从第 0 条全量扫描 几千条弹幕。加一个只进不退的头部指针,滚出窗口的直接跳过;绘制循环里遇到未到场的(时间升序)直接
break。 - 每帧对可见弹幕
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),不内置任何内容、需自行导入订阅配置,仅供学习交流:
- GitHub:github.com/zhaozipengn...
- Gitee:gitee.com/ZKingp/juyu...
如果帮到了你,一个 Star 是对独立开发者最大的鼓励。欢迎 Issue 交流踩坑。