基于 Svelte 3 + Rollup 构建的 KaiOS 第三方哔哩哔哩(B站)客户端,使用 AI 辅助开发。
下载最新安装包 👉 Releases
- 🏠 首页推荐 — 个性化视频推荐信息流
- 👥 关注列表 — 已关注 UP 主的视频与动态
- 🔍 搜索 — 关键词搜索视频
- 🔐 账号登录 — 扫码登录,支持 Cookie 持久化
▶️ 视频播放 — 自适应码率播放,全屏模式,音量控制- 💬 视频评论 — 查看评论(支持多层级楼中楼)
- 📜 历史记录 — 观看历史,播放进度上报
- ⭐ 收藏列表 — 查看收藏夹及内容
- 🎧 听视频 — 纯音频播放页:封面 + 进度条,可最小化成底部迷你条,播放列表本地持久化
- ⚙️ 设置 — 基础应用设置
- 📋 软键菜单 — 软键栏的二级 / 三级操作(主页三个 Tab、视频页、全屏页)
- 🚪 退出应用 — 所有菜单(主页三个 Tab / 视频页 / 全屏页)的最后一项:退出前先把路由归位到首页,再关掉应用
- 弹幕
- 用户主页
- 一键三连(点赞 / 收藏 / 投币)
- 关注 / 取关
- 评论回复(软键已显示「待实现」,接口层
addReply还在)
| 类别 | 技术 |
|---|---|
| UI 框架 | Svelte 3 |
| 构建工具 | Rollup |
| 路由 | svelte-spa-router |
| CSS 兼容 | PostCSS(CSS 变量展开 / gap 降级 / preset-env) |
| ES 降级 | Babel + Terser → ES5(目标 Firefox 48 / KaiOS 2.4) |
| 二维码 | qrcode-generator |
| 许可证 | AGPL-3.0 |
├── public/ # 静态资源 (图标, manifest.webapp)
├── scripts/
│ ├── dev-server.js # 开发服务器 (Express + 代理)
│ ├── install-device.js # 打包并安装到真机 (adb + 设备调试协议)
│ ├── device-test.js # 真机自动测试 (冒烟检查 + 截图)
│ ├── device-console.js # 抓应用内 console 输出 / 执行 JS
│ ├── test-keyboard.js # 按键框架无头自测 (Node, 不需要真机)
│ └── lib/
│ └── ui-probe.js # 注入页面运行的 UI 探针 (被 device-test.js 使用)
├── src/
│ ├── main.js # 入口
│ ├── App.svelte # 根组件 + 路由
│ ├── app.css # 全局样式 + CSS 变量
│ └── lib/
│ ├── api/ # B站 API 封装
│ │ ├── auth.js # 登录鉴权
│ │ ├── bili.js # 请求基础层 (WBI 签名)
│ │ ├── dynamic.js # 动态
│ │ ├── feed.js # 推荐信息流
│ │ ├── followings.js# 关注
│ │ ├── interact.js # 互动 (点赞/收藏/投币)
│ │ ├── user.js # 用户信息
│ │ ├── video.js # 视频详情/播放
│ │ └── wbi.js # WBI 签名算法
│ ├── components/ # UI 组件
│ ├── keyboard/ # 按键导航框架 (按键总线/作用域/焦点漫游)
│ ├── menu/ # 全局二级菜单
│ │ └── appMenu.js # 三个 Tab 的菜单构造器 + 退出应用项(两套菜单共用)
│ ├── player/ # 视频播放器 (含听视频的播放引擎 engine.js)
│ ├── router/ # 路由工具
│ ├── stores/ # Svelte stores (状态管理)
│ │ ├── home.js # 首页推荐流 (数据缓存 / 焦点位置)
│ │ ├── following.js # 关注页状态 (tab / 数据缓存 / 焦点位置)
│ │ ├── softkey.js # 软键菜单 (二级/三级: 层级栈 / 高亮 / 面包屑)
│ │ └── keytest.js # 按键检测数据 (真机核对用, 可从 adb 拉取)
│ ├── utils/ # 工具函数
│ │ └── commenttree.js # 评论对话树 (按 parent 建树, 多层级)
│ └── views/ # 页面视图
│ ├── ImageViewer.svelte # 图片全屏查看 (左右切图)
│ ├── KeyTest.svelte # 按键检测页 (真机核对实体键 ↔ 框架映射)
│ └── MenuTest.svelte # 菜单测试页 (真机试软键栏的二级/三级菜单)
├── index.html # HTML 模板
├── rollup.config.js # Rollup 构建配置
└── package.json
- Node.js ≥ 14
- npm
# 安装依赖
npm install
# 启动开发服务器 (Express + B站 API 代理)
npm run dev# 清理 + 构建
npm run build构建产物输出到 build/ 目录,包含:
| 文件 | 说明 |
|---|---|
app.js |
IIFE 格式单文件 bundle(ES5) |
app.css |
PostCSS 处理后的样式(CSS 变量已展开) |
index.html |
入口页面 |
manifest.webapp |
KaiOS 应用清单 |
icons/ |
应用图标 |
KaiOS 没有 adb install:应用必须以 packaged app 的形式装进 /data/local/webapps,
WebIDE / OmniSD / make-kaios-install 走的都是同一条路:
build/ 打包成 application.zip (manifest.webapp 在压缩包根目录)
↓ adb push
/data/local/tmp/b2g/<appId>/application.zip
↓ 转发调试端口 + webapps actor 的 install 请求
设备安装应用
一条命令搞定(打包 → 推送 → 安装 → 启动,并打印安装结果):
npm run build
node scripts/install-device.js前置条件:
| 条件 | 说明 |
|---|---|
| 调试模式 | 手机拨号 *#*#33284#*#*(状态栏出现 bug 图标),或 设置 → 设备 → 开发者 → 调试器 → 选择 ADB 和 DevTools。重启手机后会被清除,需要重新打开 |
| USB 授权 | adb devices 能看到设备(device 状态而不是 unauthorized) |
| 依赖 | adb 在 PATH 里;打包还需要 zip(Windows 用 PowerShell 的 Compress-Archive,脚本已自动选择) |
脚本内部做的事(排障时可按此手工执行):
# 1. 打包(appId 取自 manifest 的 origin:app://bilibili.com → bilibili.com)
cd build && zip -Xr ../application.zip $(ls) && cd ..
# 2. 推送安装包(/data/local/tmp 是 tmpfs,重启会清空)
adb shell mkdir -p /data/local/tmp/b2g/bilibili.com
adb push application.zip /data/local/tmp/b2g/bilibili.com/application.zip
# 3. 转发设备调试端口(同一端口要先 --remove,否则旧监听会让连接被拒)
adb forward --remove tcp:6000
adb forward tcp:6000 localfilesystem:/data/local/debugger-socket
# 然后向 root actor 发 listTabs 拿到 webappsActor,向它发:
# { type: "close", manifestURL: "app://bilibili.com/manifest.webapp" } # 旧实例要先关, 否则手机上仍是旧代码
# { type: "install", appId: "bilibili.com", appType: 2 } # appType 2 = packaged
# { type: "launch", manifestURL: "app://bilibili.com/manifest.webapp" }要点:
- appId 就是
manifest.webapp里origin的主机名,它同时决定安装目录名和app://地址;改 origin 就等于换了个新应用(登录态不会跟着走)。 - 设备调试 socket 同一时间只接受一个客户端,别和 WebIDE 或另一个脚本同时连(后连的会被拒绝)。
- 重装后一定要 close → install → launch 一次,只 install 的话手机上跑的还是旧代码。
- 安装脚本会打印权限等级(
systemXHR需要privileged及以上)、installed状态和是否已在运行。 - 应用数据(localStorage 里的登录态等)在重装后保留;
/data/local/tmp里的安装包重启后需要重新推送。
KaiOS 没有 am / input / screencap,可用的通道是下面这些。
1)系统与平台日志(logcat)
adb logcat -c # 清空缓冲
adb logcat | grep -E 'BrowserElement|FocusManager' # 按键与焦点(调试 UI 最常用)
adb logcat -s Gecko:V GeckoConsole:V # 按 tag 过滤
adb shell b2g-ps # 应用进程列表 (b2g 是 KaiOS 的浏览器进程, 不是 Android)实测有用的几类行(示例为本机真实抓取):
# 按键是否真的送达应用、落在哪个元素上 (KaiOS 会打印 DOM key 名与焦点元素)
Gecko : [BrowserElement] event type: keydown, key: SoftLeft, target: [object HTMLDivElement], class: feed-card svelte-…
Gecko : [BrowserElement] event type: keydown, key: ArrowDown, target: [object HTMLIFrameElement], src: app://bilibili.com/index.html, id: browser9
FocusManager: -> focus is now on, tag: DIV, id: , class: feed-card svelte-…
# 输入法 (若 T9/内置键盘异常会看到这条, 说明 inputcontextfocus 无人处理)
Gecko : MozKeyboard.js: A frame with input-manage permission did not handle the inputcontextfocus event dispatched.
# systemXHR 权限是否被使用
: XMLHttpRequest nsXMLHttpRequest::getPermission:0,type:0
# 调试连接相关
GeckoDump: XXX FIXME : Got a mozContentEvent: transport-closed
注意:SoftLeft / SoftRight / Enter / ArrowUp 等是 DOM key 名,不是 Linux 键码。
2)应用内日志(console.* 与未捕获异常)
应用内的 console.log/warn/error 和未捕获异常不会进 logcat(本机实测 0 条),
要拿到它们得连设备调试协议的 console actor(WebIDE 的控制台走的是同一条路):
node scripts/device-console.js # 跟踪 (Ctrl-C 退出)
node scripts/device-console.js --once # 打印已缓存的消息后退出
node scripts/device-console.js --eval 'location.hash' # 在应用里执行一段 JS, 并打印返回值输出形如:
已连接 app://bilibili.com/manifest.webapp 的 console actor (appId 哔哩哔哩),下面是应用内输出:
[log] hello-from-eval #/profile 哔哩哔哩
[eval] 返回: {"route":"#/profile","navables":6,"softkeys":{"left":"","center":"打开","right":""}}
--eval 也能当“真机自检”用,比如查软键文案、焦点元素、标题是否被截断、图标是否渲染:
node scripts/device-console.js --once --eval 'JSON.stringify({
route: location.hash,
softkeys: document.querySelector(".softkey-bar").innerText.replace(/\s*\n\s*/g,"|"),
title: document.querySelector(".title") && getComputedStyle(document.querySelector(".title")).maxHeight
})'3)按键注入与截图(自动化 UI 用)
- 按键:设备没有
input命令,用sendevent直接写/dev/input/event1(matrix_keypad)。 本机实测映射:139→SoftLeft、158→SoftRight、352→Enter、103/108/105/106→方向键、14→Backspace。adb shell "sendevent /dev/input/event1 1 108 1; sendevent /dev/input/event1 0 0 0; \ sendevent /dev/input/event1 1 108 0; sendevent /dev/input/event1 0 0 0"
- 截图:
screencap在 KaiOS 上不可用(没有 SurfaceFlinger),走调试协议的deviceActor.screenshotToDataURL(返回 240×320 PNG dataURL),install-device.js里那段协议客户端可以直接复用。
改完东西不用人肉点一遍:把当前构建装到真机,然后跑冒烟检查。
npm run build
node scripts/install-device.js # 装上要测的版本
node scripts/device-test.js # 跑检查, 退出码 0 = 全过, 1 = 有失败项常用参数:
node scripts/device-test.js --shot ./shots # 每个页面存一张真机截图 (240x320 PNG)
node scripts/device-test.js --only home,player # 只跑指定页面
node scripts/device-test.js --only back-key # 只验证右软键返回实跑输出(14 个页面 + 8 段真机按键):
设备: app://bilibili.com/manifest.webapp 视口 240x320
✓ home softkeys={"left":"刷新","center":"打开","right":"更多"} navables=8
✓ following softkeys={"left":"刷新","center":"打开","right":"更多"} navables=22
✓ profile softkeys={"left":"","center":"打开","right":"更多"} navables=6
✓ history softkeys={"left":"刷新","center":"播放","right":""} navables=30
✓ favorites softkeys={"left":"刷新","center":"打开","right":""} navables=9
✓ settings softkeys={"left":"","center":"","right":""} navables=5
✓ about softkeys={"left":"","center":"","right":""} navables=11
✓ keytest softkeys={"left":"","center":"选择","right":""} navables=19
✓ menu-test softkeys={"left":"","center":"选择","right":"更多"} navables=6
✓ search softkeys={"left":"刷新","center":"","right":"搜索"} navables=10
✓ search-results softkeys={"left":"刷新","center":"打开","right":""} navables=20
✓ user softkeys={"left":"刷新","center":"","right":""} navables=11
✓ player softkeys={"left":"全屏","center":"播放","right":"更多"} navables=0
✓ fullscreen softkeys={"left":"隐藏","center":"播放","right":"更多"} navables=0
✓ menu 二级/三级菜单: 展开 → 进三级 → 退格回退 → 执行动作 全通过
✓ video-menu 视频页菜单: 二级 5 入口 (含末项「退出应用」) + 播放控制/互动三级菜单 + 副提示 + 快进 5 秒 全通过
✓ fullscreen-menu 全屏菜单: 右软键开关菜单 + 比详情页多一项「视频分辨率」 + 副提示跟着绑定走 + 中键提示跟着播放状态走 全通过
✓ fullscreen-quality全屏菜单切分辨率: 换流 + 位置接着走 + 设置里的默认分辨率跟着变 全通过
✓ fullscreen-nobar关掉设置: 软键栏藏起来 + 右软键照样展开完整菜单 + 关菜单后继续藏 全通过
✓ back-key 返回键 #/settings → #/profile
✓ tab-menu 三个 Tab: 右软键变「更多」+ 原动作进菜单 + 末项「退出应用」 全通过
✓ search-back 菜单跳搜索页后返回键能退回主页 全通过
✓ exit-app 退出应用: 主页菜单和视频页菜单都能退出 + 路由先重置到 / + 真把应用关掉 + 重开落在首页 全通过
结果: 23/23 项通过
上面是加听视频之前的实跑结果。新增的
listen用例、以及 PAGES 里多出来的 听视频页(以及三个列表页右软键改成「更多」之后的变化)还没在真机上跑过 —— 写这轮功能时设备掉线了。脚本已经备好,设备连上就能跑。
检查项(全部在真机上判定):
| 检查 | 判定方式 | 能抓住的典型问题 |
|---|---|---|
| 页面可达 | 导航后等待,探针能取到快照 + 软键栏 | 路由写错、渲染崩溃、白屏 |
| 软键文案 | 与 PAGES 表里的期望值逐项比对 |
软键没接处理器、标签与行为不符 |
| 软键栏藏起来 | getClientRects().length 判定栏有没有真的画出来 |
沉浸模式关不掉、藏了之后菜单也一起打不开 |
| 子页面返回键 | 注入右软键(sendevent 158),断言路由变化 |
子页面出不去、返回层级错乱 |
| 字形是否存在 | canvas 位图与空白/豆腐块位图比对 | emoji 图标在 KaiOS 上渲染成空白 |
| 图片是否加载 | complete && naturalWidth === 0 |
坏图、协议相对 URL、缺封面 |
| 列表是否被裁 | 可滚动容器盒模型 vs 最近裁剪祖先 | 底部内容永远滚不到 |
| 是否超出视口 | 元素右边界 vs 240px | 长文本把布局撑破(全屏播放器按横屏设计,豁免) |
| 焦点是否可见 | 活动元素矩形是否落在视口内 | 焦点跑到屏幕外 |
| 视频分辨率 | 菜单里切档 → 比对 <video> 宽度 + settings.quality |
切了档没换流 / 设置没跟着持久化 |
| JS 异常 | 订阅 console actor 的 pageError 事件 |
未捕获异常 |
实现原理(四个原语,都通过设备调试协议 + adb):
| 原语 | 通道 |
|---|---|
| 读页面状态 | consoleActor.evaluateJS 注入 scripts/lib/ui-probe.js,返回 JSON 快照 |
| 真机按键 | adb shell sendevent /dev/input/event1 … 注入真实按键 |
| 截图 | deviceActor.screenshotToDataURL |
| 页面异常 | consoleActor.startListeners(['PageError']) |
扩展方式:
- 加检查项:改
scripts/lib/ui-probe.js(在issues里push({t, …})即可,device-test.js会按t分类报错)。 - 加页面/改期望:
scripts/device-test.js的PAGES表(路径 + 等待时间 + 期望软键)。 - 加一次性验证:
node scripts/device-console.js --eval '<js>'在真机上执行并打印返回值。
注意事项:
- 设备调试 socket 同时只接受一个客户端,别和 WebIDE /
device-console.js同时跑。 - 页面数据来自 B 站接口,网络抖动会产生误报,建议先确认页面数据正常再判失败。
- 登录态相关的页面(首页/收藏/历史/关注)需要手机上是已登录状态。
--shot输出的截图就是手机当时真实画面,可直接贴进 issue。- 所有请求都带超时(默认 20s,整个脚本上限 20min)。设备调试协议偶发漏回包(页面卡死、USB 掉线),没有超时保护的话脚本会永久挂住、看起来像"卡死"。超时按失败项计入结果,脚本继续往下跑。
本项目专为 KaiOS 2.4(基于 Firefox 48 / Gecko 引擎)优化:
- CSS 变量 — 构建时通过
postcss-css-variables全部展开为具体值,运行时无需var()支持 - Flexbox gap — 通过
postcss-gap-properties降级;flexbox gap 在 Firefox 48 上无完美 polyfill,小间距(4-8px)视觉差异可接受 - ES5 输出 — Babel
preset-env+ Terser 确保ecma:5输出,无箭头函数、模板字符串等现代语法 - 单文件 bundle — IIFE 格式,
inlineDynamicImports: true,KaiOS 不支持 ES module loader - 图标字形 — KaiOS 系统字体不含 emoji(
💬/⭐/🪙/👁… 会渲染为空白或豆腐块),界面图标统一使用字体内置符号(❤ ▶ ❝ ★ ◎ ▤ ● ∅等),新增图标前需在真机确认字形存在 - 文字截断 — Gecko 48 不支持
-webkit-line-clamp,标题类样式需额外给出max-height兜底 - 登录接口形态 — web 扫码登录的
qrcode/poll成功响应改为只在Set-Cookie响应头里下发SESSDATA/bili_jct/DedeUserID(响应里的url只剩ticket)。KaiOS 的mozSystemXHR 可以读到该响应头(实测),但不会使用 cookie jar 发请求,因此必须从响应头取值:extractCookies()同时兼容"URL 参数"与"响应头"两种形态,并对响应头里的值做 URL 解码(SESSDATA 含逗号,须原样回传)
返回归返回键,软键归页面。 软键是"页面动作"键(可被页面自由定义),返回是"导航"键(全局统一),两者不再混用。
| 物理键 | 规范名 | 全局作用 | 页面可覆盖 |
|---|---|---|---|
| 返回键(退格键 / 方向键右边的「←」) | Back |
返回上一级(全局兜底) | 可 |
| Smart Touch 返回键 | GoBack / BrowserBack |
返回上一级 | 可 |
| 通话键 | Call |
不拦截(交给系统拨号) | 不可 |
| 挂断键 | EndCall |
不拦截(交给系统挂断) | 不可 |
| 左软键 | SoftLeft |
无 | 页面主操作 |
| 右软键 | SoftRight |
无(不再兜底返回) | 页面动作 |
| 中键 | Enter |
激活当前焦点元素 | 页面可改 |
| 方向键 | Up/Down/Left/Right |
焦点漫游 | 页面可改 |
| 位置 | 约定 |
|---|---|
| 左软键 | 页面主操作(首页=刷新、播放器详情=全屏、播放器评论=待实现、动态详情=评论/待实现、全屏页=隐藏/显示软键栏、听视频页=最小化) |
| 中间 | 中键(OK)当前会做什么的提示(打开/播放/暂停),本身不接收按键 |
| 右软键 | 页面自己定义(主页三个 Tab = 更多菜单、视频页 = 更多菜单、全屏页 = 更多菜单、听视频页 = 更多菜单、搜索页 = 搜索);没定义就是什么都不做 |
- 方向键:上下移动焦点(列表内自动滚动居中),左右在详情/评论等子 Tab 间切换
- 中键:打开/播放/暂停;评论列表中展开子评论
- 动态详情的中键提示跟着内容走:这条动态能播视频(视频动态本身,或转发的原动态是视频)→ 中键显示「播放」,按中键直接进播放器;没有视频可播 → 中键不显示任何文案(没绑定的键不显示提示)。切到「评论」Tab → 中键提示跟着焦点走(焦点在某条评论上 = 「展开」/「收起」,焦点不在评论上就不显示)
- 「我的」页不绑左右软键:进页面焦点落在用户卡片上,中键(OK)打开当前选中项(用户卡片 / 历史记录 / 收藏 / 设置 / 关于 / 登出),软键栏只留中间的"打开"提示
- 关于页的「开发者」:直接在应用里进他的个人主页(
/user?uid=29529884),不是window.open拉起外部浏览器看网页空间 —— KaiOS 上外部浏览器体验差,而且应用内已经有这套用户主页了 - 搜索页:左软键=刷新热搜,右软键=搜索;中间提示跟着焦点走(焦点在热搜列表里="打开",输入框里中键什么都不做、就不显示文案);↑ 从热搜列表顶部回到输入框,输入框里再按 ↑ 原地不动。输入框里不绑中键搜索 —— 输入文本时按 OK 容易误触,搜索走右软键
- 主页三个 Tab(首页 / 关注 / 我的):右软键 = 「更多」二级菜单(原来绑在右软键上的动作都收进去了:首页 = 搜索,关注 = 切 Tab,我的 = 原来没绑右软键 → 菜单里只剩「退出应用」);菜单最后一项固定是 「退出应用」(退出前先把路由重置到
/,再关掉应用窗口)。菜单里跳到搜索页后,返回键能正常退回主页(搜索页一进来焦点在输入框上,空输入框的退格键不再被输入法吃掉) - 视频页:右软键 = 「更多」菜单(二级菜单 5 个入口,按顺手程度排:UP 主页 / 播放控制(快进/快退/音量加/音量减,带「长按 → 键」这类副提示)/ 互动(一键三连/点赞/投币/收藏)/ 分享 / 退出应用;除 UP 主页和「退出应用」外都有子项 = 三级菜单);播放器固定 240P(小屏够看又省流量,B 站没这一档时会给最低可用档);设置里关掉「打开视频立刻播放」时,中键 = 去加载并播放(此时页面只显示封面)
- 全屏播放器:↑ 后退 10 秒,↓ 短按前进 10 秒、长按直接进 2 倍速(长按不会先跳 10 秒,松手恢复原速);←/→ 与硬件音量键调系统音量;中键 = 播放/暂停,中键提示跟着真实播放状态走(正在播放显示「暂停」,已暂停显示「播放」);右软键 = 显示/隐藏二级菜单(文案「更多」,和视频详情页同一份菜单、同一侧同一个文案),菜单里多一项 「视频分辨率」(三级:240P / 360P / 480P / 720P,当前档用 ✓ 标出;切完跟着设置里的「全屏默认分辨率」一起持久化,下次进全屏就用它);左软键 = 显示/隐藏整条软键栏(文案「隐藏」/「显示」,写的是按下之后会做什么;按一下就切,藏的只是那一行提示,菜单照常能展开)。页面按横屏布局(视频转 90°),宽高按视口算不写死,详见「全屏播放器」章
- 听视频页(纯音频):← 短按 = 上一首 / 长按 = 快退、→ 短按 = 下一首 / 长按 = 快进(按住不放,每 0.8 秒跳 5 秒)、↑ 系统音量+、↓ 系统音量−、中键 = 播放/暂停(提示跟着播放状态走)、左软键 = 最小化(收起页面,底部浮迷你条,声音继续)、右软键 = 「更多」菜单(UP主页/播放控制(上一首/下一首/快退/快进/音量加/音量减/2 倍速开关)/播放列表/播放模式/点赞/投币/收藏/一键三连/查看评论/退出播放),详见「听视频」章
- 模态组件打开时独占按键(左软键=取消,右软键=发送,Enter=发送);评论回复框暂时下线(见「评论」章),模态独占这套机制本身留着给回复功能做回来用
- 返回键家族:退格键
Backspace(规范名Back,官方语义就是"返回上一级")、Smart Touch 的GoBack/BrowserBack都能当"返回"用(顶层页面也拦下来:首页/关注/我的按返回键不退出应用,退出走菜单里的「退出应用」,主页/视频页/全屏页的菜单里都有) - 通话键
Call/ 挂断键EndCall永远不拦截:它们关系到打电话本身,网页吞掉用户就没法拨号、没法挂断。框架在按键总线的最前面就把这两个键放行(NEVER_INTERCEPT)——不进任何作用域、不preventDefault,连页面显式声明也接管不到(连页面显式声明也接管不到) - 有硬件音量键的机型(
VolumeUp/VolumeDown/VolumeMute)在播放器里调音量,只调系统音量(见下面「音量只走系统」);系统类按键(电源/相机/拨号/挂断/短信/通知/语音助手)一律不拦截,长按才能退出应用 - 左软键在这类机型上是
KEY_MENU,DOM 层拿到的 key 名是SoftLeft(不是F1/ContextMenu)。按下时系统会同时弹自己的菜单 —— 这是 OS 行为,网页拦不住,但按键本身能正常绑定。实测副作用:菜单弹着的这段时间应用被挂到后台,XHR 回调不会回来(实测 45 秒不返回,菜单关掉后才恢复)—— 所以用左软键做"刷新"时,页面先保持旧内容不变,等菜单关掉数据才更新;刷新逻辑不要在await之后才去清空列表,否则菜单期间会白屏
为什么把右软键从返回家族里摘出去:以前右软键兜底返回,副作用是每个子页面的右软键都被"返回"占住,页面自己声明的动作还容易被全局兜底抢走(旧实现里就出过"右软键在二级页仍然触发搜索"的回归)。现在返回只有一个入口(返回键),软键栏的文案和按键行为严格一一对应,没绑定的键就不显示文案。
播放器里调音量(长按 ↑↓、硬件音量键)只调系统音量,应用自己不维护"应用内音量"。
原因:KaiOS 2.4 的 navigator.volumeManager 只有 requestUp() / requestDown() / requestShow() 三个方法 —— 真机实测确认没有当前音量的读数,也没有 input 事件。应用读不到系统在第几档。
所以:
- 媒体元素不设
volume(保持 1.0),不叠第二层增益 —— 听到的声音就等于系统音量 - 应用不画自己的音量滑块 —— 读不到系统档位,画出来的条只会和系统对不上
- 调音量时
requestUp()/requestDown()会让系统自己弹出音量气泡(真机实测是紫色圆形气泡,显示1/15这样的档位),反馈交给系统 - 静音是另一回事:系统音量接口在 2.4 上没有静音方法,静音由应用把媒体元素
muted置位,状态存在settings.muted,普通播放器和全屏播放器共用
以前播放器有一根自己的音量条,绑的是
settings.volume,而调音量的动作只改系统音量 —— 两边永远对不上(滑块一直停在 100% 不动)。现在这套应用内音量整个去掉了,settings.volume字段也一并删掉(旧数据里残留的字段读出来时会丢弃)。
设置页里有个开关「打开视频立刻播放」:
| 设置 | 行为 |
|---|---|
| 开(默认) | 打开视频页 → 拉播放地址 → 直接播(老行为) |
| 关 | 打开视频页 → 不拉播放地址、不建 <video> 元素(一个字节的视频数据都不下),只显示封面;按中键(OK)才去拉地址并开始播 |
关掉之后:
- 播放器区域显示封面图 +「按 OK 播放」提示,中键的软键文案仍然是「播放」(文案必须和行为一致)
- 封面/标题/详情照常显示 —— 视频信息(
/x/web-interface/view)还是会拉,只是视频流不拉 - 播放地址在用户按中键的那一刻才去拉(
/x/player/playurl的 MP4 单流,/x/player/wbi/playurl的 DASH 兜底),拉完<video>元素自动播起来,进度接着历史记录里的位置 - 全屏播放器同理:进去先显示封面,按中键才加载(右软键是菜单键)
- 省流量也省电:翻列表看到封面就够了,不用点一个下一段视频
老版本存过的设置里没有这个字段,缺省按「开」处理 —— 不然老用户升级后打开视频会突然不播。
设置页里还有个开关「全屏播放显示软键栏」:
| 设置 | 行为 |
|---|---|
| 开(默认) | 全屏页照常显示底部那条软键栏:右软键 = 显示/隐藏二级菜单(文案「更多」,菜单内容与视频详情页同一份、同一侧);中键提示跟着播放状态走(播放中「暂停」/ 暂停中「播放」);左软键空着 |
| 关 | 全屏把整条软键栏藏起来(沉浸模式,画面铺满);但菜单照常能用 —— 按右软键照样展开二级菜单,6 个入口一个不少 |
关掉之后的行为要分清两件事:
- 藏的是「那一行提示」,不是菜单。软键栏只是看不见了,页面派给软键的动作(这里是右软键展开菜单)照常生效 —— 菜单面板是另一个图层,不受这个开关影响。
- 菜单开着的时候软键栏会临时露出来:菜单的操作提示(「关闭」/「选择」)就写在这一行上,而且菜单面板是贴着软键栏上沿摆的,栏不见了底下就空一条。菜单一关,栏继续藏着,不会又冒出来。
全屏页的左软键就是这个开关:文案「隐藏」/「显示」,写的是按下之后会做什么(栏显示着 →「隐藏」,栏藏着 →「显示」)。按一下就切,直接改的就是这个设置项,所以别的地方也跟着变。
老版本存过的设置里没有这个字段,缺省按「开」处理。
设置页里的「全屏默认分辨率」和全屏菜单里的「视频分辨率」是同一个设置,两处都能改:
- 设置页改 → 下次进全屏就用那一档
- 全屏菜单里改 → 立刻换流(播放位置接着走,不从头开始),同时把设置里的「全屏默认分辨率」一起改掉并持久化
| 档位 | qn | 用在哪 |
|---|---|---|
| 240P | 6 | 视频详情页的播放器固定这一档 |
| 360P | 16 | 全屏默认档 |
| 480P | 32 | |
| 720P | 64 |
B 站给什么档就是什么档 —— 不是每个视频都有 240P/480P(没登录一般只有 360P,登录了还要看视频本身)。请求 240P 而 B 站没有这一档时,它会把清晰度抬到可用档(比如 360P)。真机实测(登录态、某个视频):accept_quality = [64, 16],请求 240P/480P 都被抬回 360P,请求 720P 才真给到 1280×720。
视频详情页为什么固定 240P:详情页那个小播放器不需要高画质,240P 又最省流量。但得走 MP4 单流(/x/player/playurl + platform=html5 + fnval=1)—— DASH 压根没有 240P 档(最低 360P),而原来的代码走 DASH 再取"id 最小的那档",等于永远拿 360P,请求什么档都没用。全屏页同理改成 MP4 优先,清晰度才真的跟着请求走。
#/listen?bvid=<bvid> —— 一个只出声不出画面的播放页,适合在 240×320 的屏上听视频。
- 封面图 + 标题 + 进度条(已播 / 总长)
- 播放控制行(上一首 / 播放·暂停 / 下一首)的正上方一个
+、正下方一个−—— 那是音量提示:↑ 键加音量、↓ 键减音量,上下摆正好对上方向键(符号用 CSS 画,不吃字体字形) - 方向键:← 短按 = 上一首 / 长按 = 快退、→ 短按 = 下一首 / 长按 = 快进(按住不放,每 0.8 秒跳 5 秒)、↑ 系统音量+、↓ 系统音量−
- 中键 = 播放 / 暂停(文案跟着播放状态走:正在播显示「暂停」)
- 左软键 = 最小化:收起这一页,底部浮一条迷你条(封面 + 标题 + 进度),声音继续放
- 右软键 = 更多 → 二级菜单:
UP 主页/播放控制 ▸(上一首 / 下一首 / 快退 / 快进 / 音量加 / 音量减 / 2 倍速开关,副提示写的就是这一页方向键的实际绑定)/播放列表 ▸/播放模式 ▸/互动 ▸/分享 ▸/查看评论/退出播放/退出应用
音频元素不在听视频页里 —— 页面一卸载元素就没了,声音跟着断。它挂在根组件(App.svelte)里,跨路由不销毁,引擎(src/lib/player/engine.js)通过 setAudioElement() 拿引用。页面卸载时只把「迷你条」显示出来,播放照旧。
播放列表存在 localStorage(player:playlist:v1),关掉应用还在。里面存的是视频信息(bvid / cid / 标题 / 封面 / 作者 / 时长),不是播放地址 —— B 站的流地址带有效期,存下来过阵子就失效,所以每次真正播的时候才重新拉。
| 在哪儿加 | 加的是 |
|---|---|
| 视频详情页的「更多」菜单 →「添加到播放列表」 | 当前这个视频 |
| 历史 / 搜索结果 / 收藏夹内容页的「更多」菜单 →「添加到播放列表」 | 当前选中的那个视频(读焦点元素上的 data-bvid) |
| 首页 / 关注页(视频 Tab)的「更多」菜单 →「添加到播放列表」 | 当前选中的那个视频 |
| 收藏夹页的「更多」菜单 →「添加到播放列表」 | 整个收藏夹追加到播放列表末尾(已有的跳过) |
| 收藏夹页的「更多」菜单 →「替换当前播放列表」 | 整个收藏夹替换掉播放列表(列表名也跟着换成收藏夹名) |
播放列表在听视频页菜单里是三级菜单(✓ 标着当前这首),选中即切过去播。
从视频详情页点「听视频」:这个视频会直接放到播放列表最顶上(已经在列表里的挪到最前,不会重复),然后开始播 —— 想听的那首就该排在第一个,后面的歌顺着往后排,播完接着往下走。
只有这一个入口会自动播。 别的入口(直接开 #/listen?bvid=xxx、从「我的」页进、菜单里跳回来)都不自动播:原来在放就接着放,原来暂停着就还暂停着,页面显示的是引擎里正在放的那首(标题、封面都跟着它走)。什么都没在放的时候,中键放的就是 URL 里那首。
播放模式有四种:顺序播放(默认,播完最后一首就停)、列表循环(播完回到第一首)、单曲循环(这一首反复播)、随机播放。在听视频页的「更多 → 播放模式」里选,当前那个用 ✓ 标出,页面上也有一个小标签写着。
它存在 localStorage(player:playmode:v1),关掉应用还在,下次进来还是用户上次选的那个;没存过(或存坏了)就是顺序播放。
拉不到流、媒体元素报错、或者快进时整段缓存不下来 —— 这三种都算「这首放不了」,会自动跳到下一首并提示一句。顺序播放到最后一首就停,连着三首放不了也停(免得在列表里空转)。单曲循环时也当下一首处理 —— 反复播一首放不了的歌没意义。
快进时要把整段音频缓存下来(老 Gecko 把边下边播的 m4s 当直播流,可跳范围只有播放头那一截)。缓存存在 IndexedDB(bili-audio-cache)里,关掉应用还在,下次直接读出来播,不用重新下。
- 只用 IndexedDB 1.0 的 API(
put/get/delete/clear/count/openCursor/createIndex)。2.0 的那些(store.getKey、index.getAll之类)一个都不用 —— Gecko 48 上它们有的是有的是没有的,版本之间还会飘。 - 分两个仓:
tracks(音频本体)和meta(大小 + 时间)。算占用、回收的时候只碰轻的meta,不用游标扫几十兆的音频。 - 事务里不
await:IndexedDB 的事务在没有待处理请求时会自动提交,中途await一下这条事务就废了。 - IndexedDB 打不开(配额满 / 被占 / 压根没有)就退回内存缓存 —— 少个缓存不要紧,不能把播放搞坏。
- 「设置」页里有「听视频缓存限制」(默认 50MB)和「清理听视频缓存」。清理时正在放的那首会留着 —— 它正被媒体元素用着,
revoke掉那个 blob: URL 声音会断。
有在放东西的时候,任意页面的右软键「更多」菜单里会多一项 「正在播放」(三级:回到听视频 / 播放·暂停 / 下一个 / 上一个)。没在放东西时这一项不出现 —— 菜单里放一个点不动的项没意义。
迷你条是纯显示的:不注册按键作用域、不抢中键和方向键,页面自己的按键行为不能被这条浮层打断。要跳回听视频页,走上面那个「正在播放」。
全屏播放页是按横屏设计的:竖屏设备上把视频内容转 90°,用户把手机横过来看才是正的。所以这个页面的宽高不能写死 320/240,得按视口算。
盒子怎么摆:<video>(和封面)的盒子按"横屏"尺寸摆 —— 宽 = 屏高(100vh)、高 = 屏宽(100vw) —— 再整体 rotate(90deg)。转之前用 translate(-50%, -50%) 把盒子中心对到屏幕中心,rotate 绕自己的中心转,转完正好是"屏宽 × 屏高",铺满整屏:
video, .cover {
position: absolute;
top: 50%;
left: 50%;
width: 100vh;
height: 100vw;
max-width: none;
transform: translate(-50%, -50%) rotate(90deg);
object-fit: contain;
}两个必须写的声明(少一个就出 bug):
max-width: none—— 全局有img { max-width: 100% }(app.css),会把封面的宽度从 320 夹到父容器宽 240,盒子变成 240×240 的正方形,转完不居中、右边空掉一条。真机实测过:改之前封面框在left:-40,右边 40px 是黑的。object-fit: contain——<video>默认是fill,16:9 的视频会被拉成 4:3。现在按原比例显示(真机实测 640×360 的片子在 320×240 盒子里显示成 320×180,上下留黑边)。
其它去写死的地方:
| 位置 | 之前 | 现在 |
|---|---|---|
| 页面容器 | width:100%; height:100% |
top/left/right/bottom: 0 |
| 进度条容器 | 320px × 320px |
100vw × 100vh |
| 提示文字位置 | top: 140px |
top: 50% + translate(-50%,-50%) |
| 加载中/出错文案 | padding-top: 100px |
容器 flex 居中 |
| 封面请求尺寸 | biliImg(poster, 320, 180) |
按视口长边算(Math.max(innerWidth, innerHeight)) |
| 屏幕方向 | 写死竖屏 | isLandscape 标志 —— 屏幕本来就是横的就不转 |
进度条是竖着贴在屏幕左边的 —— 手机横过来看时它就是横屏的底部进度条;时间字符每个转 90°,横过来看才是正的。
lib/player/VideoPlayer.svelte 里的播放区之前写死 height: 135px(= 240 × 9/16),换屏幕宽度就拉变形了。现在按视口宽度算:
.player-area {
width: 100%;
height: 56.25vw; /* 16:9 */
max-height: 45vh; /* 屏幕太矮时别把播放区撑太大 */
}Firefox 48 不支持 aspect-ratio,只能用 vw 换算(9 ÷ 16 = 56.25%)。前提是播放区铺满视口宽 —— .screen 是 100vw,Player 是顶层路由不在 MainLayout 里,所以 .player-area 的宽度就等于视口宽,换算精确。
封面地址也跟着走:biliImg(poster, 320, 180) → 按视口宽算的 @240w_135h.jpg(posterW/posterH 由 updateSize() 算,带 resize 监听)。
验证时踩的坑:
getComputedStyle().height返回的是计算后的 px 值,不管源码写的是135px还是56.25vw,结果都是135px—— 没法用计算样式判断"有没有写死"。要查源码得读 CSSOM(document.styleSheets[].cssRules[].cssText)。
首页和关注页都会被反复进出(点一条视频 → 播放器 → 返回),所以它们需要记住三件事:数据还在不在、看到第几条、(关注页)还在哪个 tab。
状态全部放在模块级 store 里,组件销毁也不丢:
| 页面 | 状态放哪 | 记住的东西 |
|---|---|---|
| 首页 | src/lib/stores/home.js |
推荐流数据、分页游标、加载状态、焦点在第几条 |
| 关注页 | src/lib/stores/following.js |
视频/动态两个 tab 的数据、分页游标、加载状态、当前 tab、每个 tab 各自记一份焦点位置 |
共同的行为:
- 只有手动刷新才重新拉:左软键 / 数字键 0 = 刷新当前列表(清缓存重拉,焦点回到最上面);其余情况(返回、切 tab)都不发请求
- 返回时用缓存,焦点回到上次看的那一条
- 焦点由页面独占:
FeedList的自动聚焦在首页/关注页是关掉的(autoFocus={false}),否则两处抢焦点会出现"刚设好又被拉回第一条" - 焦点位置用捕获阶段的
focus事件记录(Gecko 48 没有focusin),位置本身放普通对象不走 store —— 焦点每动一次就写一次,走 store 会让整个列表跟着重算 - 加载状态也在 store 里:路由切换时组件可能被换掉、新旧实例短暂共存,第二个实例会看到"已经在拉了",不会重复发请求
顺带修掉的一个坑:首页的推荐流原来寄居在
queue(播放队列)里。queue是"当前播放列表",关注页/收藏夹/搜索结果都会往里写 —— 从关注页点一个视频再回首页,首页会把"关注的视频"当成推荐流显示。现在首页有自己的 store,queue只负责播放列表。另一个坑:svelte-spa-router 是按路由条目决定换不换组件的。
/home、/following、/profile之前各写了一条路由(都指向MainLayout),切 Tab 时它会把整个MainLayout销毁重建,新旧两个实例短暂共存 —— 旧实例先响应了 location 变化挂了一份新页面,紧接着路由又把组件换掉,于是同一个页面被挂载两次,关注页因此发过两次请求、同一页数据被追加两遍。现在主 Tab 共用一条"*"路由,切 Tab 不再换组件。
路由带上 uid 就是那个人的主页 —— 自己的主页和别人的主页走同一条路由、同一套代码:
#/user?uid=946974
页面三个 tab(资料 / 投稿 / 动态),内容分别来自这几个接口(文档见 bilibili-api-collect 镜像 的 docs/user/):
| tab | 接口 | 说明 |
|---|---|---|
| 资料 | GET /x/web-interface/card + GET /x/space/wbi/acc/info |
名片给昵称/头像/签名/等级/粉丝数/关注数/投稿数/获赞数,空间信息给性别/生日/认证;两个接口分开拉,一个失败另一个还能用 |
| 投稿 | GET /x/space/arc/search |
投稿视频列表(pn/ps/order 分页) |
| 动态 | GET /x/polymer/web-dynamic/v1/feed/space |
该用户的动态(offset 游标翻页) |
名片接口的字段是分层的,取错位置就会显示成 0(投稿数/获赞数之前就踩过这个坑):
| 字段 | 位置 | 备注 |
|---|---|---|
| 昵称/头像/签名/性别/等级/认证 | data.card.* |
名片主体 |
| 粉丝数/关注数 | data.card.fans / data.card.attention |
|
| 投稿数/获赞数 | data.archive_count / data.like_num |
在顶层,不在 data.card 里面 |
| 是否关注 | data.following |
是布尔值,不是关注数 |
所以 src/lib/api/user.js 里有一层 mapUserProfile() 专门把这些字段拍平成一份资料({ uid, name, face, sign, level, sex, birthday, official, fans, attention, archive, likeNum }),视图层直接用字段名,不用再关心接口的嵌套结构。
入口:
- 我的 → 点用户卡片 = 进自己的主页
- 关注页 → 动态列表里点作者名 = 进那个人的主页(动态列表抽成了
components/DynamicList.svelte,关注页和用户主页共用;一条动态拆成"头部"和"正文"两个焦点,头部打开作者主页,正文打开动态详情)
状态记忆和首页/关注页同一套思路,但按 uid 分开缓存(src/lib/stores/userpage.js):看过谁的数据、看到第几条、停在哪个 tab,都记着;换个人再切回来还是原样。
按键:上下键在列表里漫游(到底了自动加载下一页),左右方向键切 tab,左软键刷新当前 tab,中键打开当前选中的视频/动态。右软键在这一页不派活(没绑就不显示文案)。
B 站的动态不止"视频动态"一种,光主体(major)就有十几种类型,字段位置各不相同。之前只实现了有限几种,其余点进详情就加载失败。现在统一在 src/lib/api/dynamic.js 里解析成一种结构,视图层只认这一种。
两个容易踩的坑(都是真机实测出来的):
-
必须按
major.type分派,不能靠"哪个字段存在"判断。 接口返回的 major 对象里archive/pgc/draw/article/opus/ … 所有键都在,不匹配的类型对应的值才是null。而且DYNAMIC_TYPE_DRAW(带图)和DYNAMIC_TYPE_ARTICLE(专栏)现在的主体现在都是MAJOR_TYPE_OPUS。 -
转发动态的 major 是
null,原动态在item.orig。item.orig是一个完整的动态 item(带自己的 modules / author / major),不在 major 里面。转发动态自己的desc.text只在转发者写了评论时才有内容,否则是"转发动态"这四个字。
支持的类型和取法:
| 动态主体类型 | 内容 | 取自 |
|---|---|---|
MAJOR_TYPE_ARCHIVE |
视频 | major.archive |
MAJOR_TYPE_OPUS / MAJOR_TYPE_DRAW |
图文(标题 + 正文 + 图片) | major.opus(pics)/ major.draw(items) |
MAJOR_TYPE_ARTICLE |
专栏 | major.article |
MAJOR_TYPE_UGC_SEASON |
合集 | major.ugc_season |
MAJOR_TYPE_PGC |
剧集(番剧/电影) | major.pgc |
MAJOR_TYPE_COURSES |
课程 | major.courses |
MAJOR_TYPE_COMMON |
一般类型(装扮/点评/分享) | major.common |
MAJOR_TYPE_UPOWER_COMMON |
充电相关 | major.upower_common |
MAJOR_TYPE_LIVE / MAJOR_TYPE_LIVE_RCMD |
直播间 | major.live / major.live_rcmd(content 是 JSON 串,标题在 live_play_info 里) |
MAJOR_TYPE_MUSIC |
音频 | major.music |
MAJOR_TYPE_NONE |
动态失效 | major.none.tips |
| 转发动态 | 原作者 + 原内容 + 原主体 | item.orig |
另外 module_dynamic.additional 是"相关内容卡片"(游戏/商品/预约/投票/视频跳转),也一并解析出来显示。
列表接口的 features 必须带 itemOpusStyle:不带的话图文动态只返回老式的 MAJOR_TYPE_DRAW(只有图片,没有正文),带上才返回 MAJOR_TYPE_OPUS(标题 + 正文 + 图片)。真机实测:同一条动态,带 features 返回 OPUS + 完整 summary,不带返回 DRAW + 只有 items 数组。
评论对象随动态类型变:评论挂在哪个对象上取决于动态类型 —— 视频 → 视频 aid(type=1)、带图 → 相册 id(type=11)、专栏 → cv 号(type=12)、音频 → au 号(type=14)、转发/纯文字 → 动态本身 id(type=17)、收藏夹 → 收藏夹 id(type=19)。接口在 basic.comment_id_str + basic.comment_type 里直接给了,拿不到时按动态类型兜底。之前这里固定用视频 bvid,非视频动态一律报"该动态没有可评论的视频"。
详情接口 GET /x/polymer/web-dynamic/v1/detail 的 features 参数是必填(文档标注),少了会 4101139 加载失败,所以带的是 web 端默认的一整套开关。
中键(OK)提示跟着内容走:视频动态、或转发动态的原动态是视频 → 中键显示「播放」,按中键直接进播放器;没有视频可播 → 中键不显示文案(没绑定的键不显示提示)。切到「评论」Tab → 中键提示跟着焦点走(焦点在某条评论上 = 「展开」/「收起」,焦点不在评论上就不显示)。
带图片的动态:中键进大图看。图片是可聚焦的,焦点落在某张图上时中键提示是「查看」,按中键进图片查看器:
-
路由
#/image-viewer?imgs=<编码后的 JSON 数组>&i=<序号>,图片数组直接通过 URL 参数传过去 -
URL 参数里的 JSON 必须
encodeURIComponent—— 否则 URL 里的&和=会把参数切碎 -
详情页里怎么选图:进页面焦点自动落在第一张图上,上下键在图片之间移动(走到头就恢复滚动正文);按中键从选中的那张开始看
-
查看器里的按键:
键 没放大时 放大后 左软键 上一张 放大 右软键 下一张 缩小 中键(OK) 放大 复原 ↑ ↓ ← → 调整图片位置(平移) 调整图片位置(平移) 软键文案跟着状态走(放大时变成"放大/缩小",缩回原大小又变回"上一张/下一张")。图片按屏宽适配,缩放用
transform: scale,平移用translate;图片没超出屏幕的那个方向就挪不动(边界会夹住)。方向键的方向跟
translate的符号是反的:translate正值是"图片往右/下移",对应"视野往左/上移"。所以按 → 想看图片右边时,代码里要传负值(Right: () => pan(-1, 0))。早先写反了,按 → 图片反而往右跑。
图片的显示尺寸(240×320 屏上图片有两个位置,规格不一样):
| 位置 | 布局 | 尺寸 |
|---|---|---|
| 动态详情页 | 一行一张,满宽显示,高度按原图比例自然撑开,超出屏幕可见高度的部分裁掉 | width:100% + height:auto;容器 max-height:calc(100vh - 60px) + overflow:hidden |
| 动态列表(关注页动态流) | 九宫格风格,一行几张小图 | 固定 50×50,object-fit:cover 裁成方图,最多 3 张 |
详情页为什么是"满宽 + 裁切"而不是"缩到一屏内":详情页内容区净宽 224px(240 − 左右各 8px padding)。竖图按满宽渲染是 224×336,比内容区(320 − tab栏32 − 软键栏28 = 260)高,会超出一屏。处理方式是保持原图比例按满宽渲染、高度不压缩,超出的 76px 由 .image-item 的 max-height + overflow:hidden 裁掉 —— 所以图是完整的(没被压扁、没被缩成小图),只是底下那一截看不全,完整图按中键进图片查看器看。
踩过的坑:先用 max-height:250px; width:auto 把图缩到 167×250 塞进一屏,结果左右一大片留白,看着像"图没显示全"。满宽才是一张图该有的样子。
列表里的缩略图走 biliImg(src, 50, 50)(裁成方图),详情页和查看器走 biliImg(src, 240, 0)(@240w.jpg,只给宽不给高,等比缩放)。B 站图片后缀实测:@240w.jpg 可用;@100w_100h.jpg 其实也是等比缩放(不是裁剪),之前看着是方的其实是 CSS object-fit:cover 裁的;@240w.webp 加载失败(设备不支持 webp)。
详情页切 Tab 回来要重新聚焦:切到「评论」Tab 时详情内容被销毁,回来后焦点没了 —— 中键既没提示也没反应。所以 changeTab(0) 切回详情时要重新把焦点落到第一张图上。
视频页和动态详情页共用 components/CommentSection.svelte。
B 站的评论是对话树:一级评论 → 二级评论(回复一级)→ 三级评论(回复二级)→ …
- 一级评论列表
GET /x/v2/reply只返回一级评论,每条带rcount(子评论条数)和parent(一级为 0) - 子评论
GET /x/v2/reply/reply?root=<根评论rpid>一次就能拿回整棵子树。返回的data.replies见过两种形态:平铺的(每条带parent)和嵌套的(每条自带replies数组)。只按嵌套展开的话,遇到平铺的响应就会把所有回复都当成同一层 —— 这就是之前"多层级评论显示错位"的根因 - 所以统一在
src/lib/utils/commenttree.js里处理:先递归拍平,再按parent建树,按层级缩进打平渲染(最多缩 3 层,240px 宽的屏幕缩太多正文就没地方了)
「回复 @某某」用 parent 字段反查作者,不用正则去正文里抠 —— 正文里的 @ 是用户自己打的,正则抠出来的名字经常是错的。
展开状态只有一份:CommentSection 自己管。之前播放器里也存了一份 subRepliesMap,两份状态互不相通,结果是"按了中键没反应"(状态改了,但渲染的是另一份)。现在中键在评论列表里 = 展开/收起当前评论的子评论,交给框架的 activateFocused(),页面不再自己处理。
回复功能暂时下线:软键文案从「回复」改成「待实现」,按下去给一个 toast 提示。评论只保留浏览。接口层的 api/interact.js 里 addReply 还在,等回复功能做回来时直接用。
首页推荐流 / 关注页动态流 / 用户主页投稿列表,卡片底部都只显示播放量和点赞量两项,用的是同一个组件(components/FeedCard.svelte,列表层是 components/FeedList.svelte)。
三个数据源的字段完全不一样,在 src/lib/api/videocard.js 里统一成同一种形状:
| 卡片字段 | 首页推荐流 | 关注页动态流 | 用户主页投稿 |
|---|---|---|---|
stat.play |
stat.view(数字) |
stat.play("275.7万" 字符串) |
v.play(数字) |
stat.like |
stat.like |
动态的 module_stat.like.count |
接口没有 → null |
点赞数怎么补齐:投稿列表的接口(x/space/arc/search 的 vlist)不返回点赞数,而 B 站也没有批量查的接口(archive/stats 那种批量端点已经没了),只能一个视频一个视频地查(x/web-interface/view)。
一次打 30 个请求既费流量又容易撞风控,所以做成焦点驱动:用户的 D-pad 走到哪张卡,才给那张卡查一个,查到的结果缓存在列表组件里(同一个视频不会查第二次)。还没查到时显示 — 而不是 0 —— 0 会被当成"没人赞",占位才诚实。
顺带修掉的:历史记录页的字段取错了 —— 历史接口的视频信息藏在 history 对象里(顶层只有 uri/cover/author_mid),之前取顶层的 bvid/pic/owner 全是 undefined,封面是空的、bvid 成了 avundefined(点进去根本播不了)。搜索结果页也把 like 写成了 v.lavorites(少个 f),点赞数一直是 undefined。
B 站对这几个接口的风控比推荐流严,直接照文档写会被挡:
- 投稿接口用 wbi 版会被拒:
x/space/wbi/arc/search在设备上返回-403 访问权限不足/-352 风控校验失败(它还要dm_img_list/dm_img_str这两个风控参数)。改用非 wbi 的老端点x/space/arc/search,不用签名就能正常返回。 - 设备标识要用服务器发的真 buvid:应用启动时访问一次
bilibili.com,服务器回的Set-Cookie里有buvid3/b_nut。之前应用是自己随机生成一套 buvid 发出去的,风控不认 —— 空间动态接口直接-412 request was banned。现在getBuvid()每次都先从 cookie jar 里读真实的 buvid,读不到才自己生成。 - 空间详细信息接口基本拿不到:
x/space/wbi/acc/info在设备上返回-352 风控校验失败(不签名的非 wbi 版x/space/acc/info也一样是-401 非法访问)。所以资料页以名片x/web-interface/card为主力,空间信息只当补充 —— 拿不到也不影响昵称/头像/签名/粉丝/关注/投稿/获赞这些字段。这个接口的超时还特意调短到 6 秒,免得它卡住把整页资料拖到超时。
src/lib/keyboard/ 是全应用唯一的按键入口。视图不再各自监听 window,而是注册"按键作用域"(scope),由总线统一分发。
设计参考了 KaiUI 的 SoftKey 组件(KaiOS 官方生态里最常用的组件库):软键的文案和处理器由同一个对象持有,组件卸载时一起释放。
| 文件 | 职责 |
|---|---|
keys.js |
按键归一化:把 KaiOS 各机型不一致的 e.key / keyCode 统一成规范名 |
scopes.js |
作用域注册表:优先级、独占、按实例注销、软键栏所有权、软键菜单所有权 |
roving.js |
焦点漫游:[data-navable] 收集、上下移动、区域边界、滚动居中、激活 |
index.js |
按键总线:分发顺序、输入框策略、默认行为、长按 |
modalkeys.js |
模态框独占作用域(评论回复框下线了,机制留着) |
device.js |
设备能力探测(有没有相机键/音量键/挂断键) |
../stores/softkey.js |
软键菜单(软键栏的二级/三级操作):层级栈、高亮、面包屑 |
同一个物理键在不同机型/固件/输入法状态下上报的 DOM key 并不统一(方向键可能是 ArrowUp 也可能是 Up,中键可能是 Enter 也可能是 Accept,甚至 Unidentified + keyCode)。所有按键判断都必须先归一化,按键表统一用规范名。
键名取自 Gecko 48 的 dom/events/KeyNameList.h(KaiOS 2.4 实际能产生的 key),keyCode 取自 dom/interfaces/events/nsIDOMKeyEvent.idl:
| 规范名 | DOM key | keyCode | 说明 |
|---|---|---|---|
Up / Down / Left / Right |
ArrowUp / … |
38 / 40 / 37 / 39 | 方向键(每台机器都有) |
Enter |
Enter / Accept |
13 | 中键 |
SoftLeft / SoftRight |
SoftLeft / SoftRight |
0 | 左右软键。SoftRight 是页面动作键,不是返回键 |
Back |
Backspace |
8 | 返回键(官方语义就是"返回上一级";应用里的"返回"统一绑它) |
BrowserBack |
BrowserBack |
0 | 浏览器返回键 |
GoBack |
GoBack |
0 | Smart Touch 返回键(KaiOS 3,如 Nokia 8000 4G) |
EndCall |
EndCall |
95(实测) | 挂断键(官方语义"结束当前操作")——不拦截,交给系统 |
VolumeUp / VolumeDown |
VolumeUp / VolumeDown |
183 / 182 | 音量键(Gecko 48 的值) |
Mute |
VolumeMute |
181 | 静音键 |
Symbol |
Symbol |
0 | 符号输入键(# * - + @) |
Camera / Power / Call / HeadsetHook / Notification / LaunchWebBrowser / LaunchMail |
同名 | 0(HeadsetHook 实测 112) |
系统/其它应用的键,应用不应吞掉 |
0–9、*、# |
同名字符 | 48–57 | 数字键与符号键 |
DOM_VK —— 它们的 keyCode 是 0,只能靠 e.key 识别。官方文档也明确要求用 KeyboardEvent#key(code 会随键盘布局变,不可靠)。
e.key === 'Unidentified' 的事件也能正确还原。自学习到的映射优先于静态表。
上表的 keyCode 一半来自 Gecko 源码,一半是这台机器上按出来的。下面这张表是逐个实体键实测的结果(内核层 getevent + DOM 层同时抓,按键映射对得上):
| 实体键 | Linux key | DOM e.key |
规范名 | e.keyCode |
备注 |
|---|---|---|---|---|---|
左软键 / 菜单键 ≡ |
KEY_MENU (139) |
SoftLeft |
SoftLeft |
0 | 能进页面,但系统同时会弹菜单 |
| 右软键 | KEY_BACK (158) |
SoftRight |
SoftRight |
0 | e.code 是 BrowserBack;不是返回键 |
| 返回键(退格 / 方向键右边的「←」) | KEY_BACKSPACE (14) |
Backspace |
Back |
8 | 应用的"返回"绑它 |
| 方向键 | 103/105/106/108 | ArrowUp/Left/Right/Down |
Up/Left/Right/Down |
38/37/39/40 | |
| 中键 OK | KEY_OK (352) |
Enter |
Enter |
13 | 长按会触发 MicrophoneToggle(语音助手) |
| 挂断键 | KEY_END (107) |
EndCall |
EndCall |
95 | Gecko 48 的 IDL 里没有这一项,是 KaiOS 自己加的 |
| 通话键 | KEY_SEND (231) |
Call |
Call |
0 | |
| 音量 + / − | KEY_VOLUMEUP/DOWN (115/114) |
VolumeUp/VolumeDown |
同名 | 183 / 182 | 与 KaiOS 2.4 的静态表一致 |
| 媒体键 | KEY_MEDIA (226) |
HeadsetHook |
HeadsetHook |
112 | Gecko 里 112 是 F1 |
| 数字键 | KEY_1…KEY_0 |
1…0 |
同名字符 | 49…48 | |
| 相机键 | KEY_CAMERA (207) |
— | — | — | 被系统吃掉,直接开相机,页面收不到 |
| 电源键 | KEY_POWER (116) |
— | — | — | 被系统吃掉(熄屏/退出) |
| 语音键 | KEY_VOICECOMMAND (217) |
— | — | — | 被系统吃掉 |
* / # |
KEY_NUMERIC_STAR/POUND |
— | — | — | 走 gpio-keys / qpnp_pon,页面收不到 |
要点:
- 返回键 = 退格键 / 方向键右边的「←」,DOM key 名是
Backspace,框架归一化成Back。应用的"返回"统一绑它,右软键(SoftRight)不再兜底返回,留给页面自己派活。 - 左软键(
≡)是可以用的 —— 它上报的是KEY_MENU,DOM 层拿到的就是SoftLeft,框架能正常拦截。只是按下时系统会同时弹自己的菜单,这是 OS 行为,网页拦不住。 - 相机键 / 电源键 / 语音键根本到不了页面,任何"拦截系统键"的写法都没意义 —— 框架的
SYSTEM_KEYS把它们列为不拦截,系统键长按才能退出应用,官方要求如此。 - 通话键 / 挂断键能到页面,但框架不碰它们 ——
NEVER_INTERCEPT在总线最前面就把Call/EndCall放行,网页既不处理也不preventDefault,拨号和挂断都归系统。 - 页面刚加载完的第一发按键会被 Gecko 的 chrome 吞掉(不是 bug),自动化测试时先空打一发预热。
应用内有一个按键检测页(设置 → 按键检测,路由 #/keytest),用于在真机上核对实体键与框架映射:
- 捕获阶段监听
keydown,拿未经框架处理的原始事件 - 表格逐行对照「规范名 / 硬件 / 实测 e.key / keyCode(实测/期望) / 判定」
- 「一致」= 原始 key 与 keyCode 都对得上;「别名」= 框架仍能归一化,但和官方表格的原始名不同;「码差」= 静态兜底表在这台机器上不准
- 页面会吃掉所有按键(
catchAll),不会被任何键带走;清空/返回是页面底部的按钮,不绑快捷键 - 同时显示运行时自学习表和当前生效的按键作用域(谁在抢键一目了然)
也可以直接从 adb 把结果拉回机器上比对:
node scripts/device-console.js --eval 'JSON.stringify(window.__keytest.seen)'应用内有一个菜单测试页(设置 → 菜单测试,路由 #/menu-test),用于在真机上试软键栏的二级/三级菜单:
- 6 个变体可以切(↑↓ 选中、中键切换):基础两级 / 带禁用项 / 四级深菜单 / 空菜单 / 视频页同结构 / 分组 + 副提示
- 页面画出当前变体的菜单树(缩进 + 「有子项」「禁用」标记),照着按就不会按错
- 每执行一个菜单动作,页面会记一笔「最近动作」——关掉菜单就能看到刚才到底按中了哪一项
- 右软键开菜单,↑↓ 选,中键进下一级/执行,退格回上一级
自动化也能跑一遍(真机按键注入 + 断言菜单层级/面包屑/高亮/箭头位置):
node scripts/device-test.js --only menu --shot ./shots视频页那套分组菜单另有一个用例(分组/副提示/顺序/自动滚动/快进 5 秒):
node scripts/device-test.js --only video-menu --shot ./shotsGecko 48(KaiOS 2.4)上 <button> 作为 flex 容器时,它的子元素不会被当成 flex item 排布 —— 按钮的内容被塞进一个匿名块里按普通块/行内流排。
真机(Nokia 6300 4G)实测:
| 写法 | 子元素 flex: 0 0 100px 的实际宽度 |
期望 |
|---|---|---|
<div style="display:flex"> |
100px ✅ | 100px |
<button style="display:flex"> |
236px ❌ | 100px |
后果:菜单项「文字撑满 + 右边一个小箭头」在真机上会被挤成两行(箭头掉到下一行),flex-wrap: nowrap 也拦不住。
所以菜单项用 <div role="button"> 而不是 <button>(本项目其它可点的行 —— 设置项、按键检测页的按钮 —— 本来也都是 div + role="button")。
scripts/device-test.js 的 menu 用例会量箭头的位置(同一行 / 压在文字上 / 没贴右边),防止改回 button 之后又踩坑。
菜单项右对齐的东西(副提示「长按 → 键」、子菜单的小箭头)紧贴着 12px 的右内边距,也就是紧贴屏幕右边缘。曾经给列表加过一个"换一级就横向滑进来"的动画(transform: translateX(12px)),结果:
- 动画进行中的这 180ms,右侧的副提示和箭头被挤出屏幕(提示文字最后一个字被切掉)
- 真机慢 / 动画被系统卡住时,位移长期停在那里,箭头直接跑到屏幕外面看不见
所以菜单不做横向动画;换一级的提示交给面包屑和层级圆点。面板只保留一个竖向的升起动画(translateY),并且给 .menu-layer 加了 overflow: hidden —— 万一动画卡住,面板也不会盖到软键栏上。
不是每台机器都有全部硬件键(每台 KaiOS 都有方向键 + 左右软键;相机/音量/挂断键看机型)。KaiOS 提供了特性探测 API:
import { hasDeviceKey, initDeviceKeys } from '../keyboard/device.js';
await hasDeviceKey('volume'); // 'volume' | 'camera' | 'endcall' | 'qwerty'- KaiOS 2.5:
navigator.hasFeature('device.capability.volume-key') - KaiOS 3.0:
DeviceCapabilityManager.get('device.key.volume') - KaiOS 2.4:没有这个 API,一律返回
false(调用方走降级逻辑)
需要 manifest 里的 feature-detection 权限。
import { onKey, roam } from '../keyboard/index.js';
onMount(() => {
// onKey 返回注销函数, 直接交给 onMount 的返回值 → 组件销毁时自动清理
return onKey('my-page', {
SoftLeft: () => refresh(), // keydown 立即触发
SoftRight: () => navigate('/home'),
Down: () => roam(+1, () => loadMore()) // 到底了回调 loadMore
});
});- 键名用规范名(
Up/Down/Enter/SoftLeft/SoftRight/Back/数字字符) - 值可以是函数,或
{ press, long, release, repeat, threshold }(长按用):press松手时触发、long按住threshold毫秒后触发、release松手时必定触发 - 函数返回
false表示"我没处理这个键" → 总线不preventDefault,浏览器默认行为照常发生 onKey(name, map, { priority })声明优先级,大的优先(默认 0;模态 100、播放器 10、全局返回 -100)
有些页面需要吃掉所有按键 —— 比如按键检测页:任何键都不能把页面带走(否则按退格键/右软键就退出了,根本测不完)。
onKey 的 catchAll 选项负责这件事:接管本作用域没有具名声明的任何按键。
return onKey('keytest', {}, {
priority: 50,
catchAll: (e, key) => {
// 方向键/中键放行: 框架默认行为 (焦点漫游 + 激活按钮) 要继续工作
if (key === 'Up' || key === 'Down' || key === 'Left' || key === 'Right' || key === 'Enter') {
return false;
}
// 系统键放行: 官方要求永远别拦着用户离开应用
if (SYSTEM_KEYS.indexOf(key) >= 0) return false;
return true; // 其余一律吞掉 (会被 preventDefault)
}
});通话键 / 挂断键根本走不到
catchAll—— 总线在最前面就把它们放行了(NEVER_INTERCEPT),连catchAll都吞不掉。
规则:
- 同作用域内具名声明优先于
catchAll catchAll返回false表示"不处理" → 总线继续往下找更低优先级的作用域- 高优先级的
catchAll会盖过低优先级作用域的具名处理器 - 模态独占作用域不受影响,仍然优先于
catchAll
src/main.js 注册了一个 priority = -100 的全局作用域,专门管"返回":
onKey('app-back', {
Back: handleBack, // 返回键 (退格键 / 「←」), 主力
GoBack: handleBack, // Smart Touch 返回键
BrowserBack: handleBack // 浏览器返回键
}, { priority: -100, global: true });规则:
- 右软键
SoftRight不在里面 —— 软键是页面动作键,页面想用就自己声明;没声明就什么都不做 - 通话键
Call/ 挂断键EndCall也不在里面 —— 它们在总线最前面就被放行了(NEVER_INTERCEPT),连页面都接管不到,网页不能拦着用户打电话 - 顶层页面(
/home、/following、/profile)的返回键也拦下来 —— 按了不会退出应用(有意为之,避免误触退出);退出应用走主页菜单最后那项「退出应用」- 实现上这两行是配套的:顶层那条分支提前
return(返回undefined),而按键总线把"没返回 false"当成"处理了" → 照样preventDefault。想改成能退出,就得让这个分支return false
- 实现上这两行是配套的:顶层那条分支提前
- 长按连发时只退一层(
e.repeat保护),否则一次长按会连续 pop 掉多级路由 - 页面自己声明了同名键就以页面为准(优先级更高),全局只在没人管时兜底
- 输入框聚焦时退格键让给输入法删字(
isTextKey('Back')为真);但输入框是空的时候不退给输入法 —— 空框没有字可删,这时退格键当"返回"用(模态框则自己声明Back的行为)
参考 KaiUI 的 SoftKey:软键的文案和处理器由同一个作用域持有,卸载时一起释放。否则会出现两类问题:
- 页面注册了按键处理器但忘了设文案 → 软键栏还显示上一个页面的文案
- 页面已经卸载但文案还在 → 软键栏写着"刷新",按下去却没人响应
onKey 的 softkeys 选项让作用域接管软键栏:
// 文案固定:直接声明在作用域里
return onKey('history', {
SoftLeft: () => refresh(),
SoftRight: () => navigate('/home')
}, { softkeys: ['刷新', '返回', '播放'] }); // [左, 右, 中]
// 文案随状态变:作用域只接管生命周期,文案自己用 setSoftkeys 改
$: setSoftkeys($isLogin ? "刷新" : "登录", "返回", "打开");
return onKey('home', { ... }, { softkeys: true });作用域注销时自动还原成接管之前的文案。模态框也是这么做的 —— 打开时显示"取消/发送",关闭时自动还原成播放器页面的文案:
const closeScope = openModalScope('reply', {
SoftLeft: () => close(),
SoftRight: () => send(),
Enter: () => send()
}, { softkeys: ['取消', '发送', ''] });还原用的是"声明栈"而不是简单栈:Svelte 3 路由切换时是新组件先
onMount、旧组件后onDestroy(和 React 相反),简单栈会还原错。声明栈按下标取最后一个持有者,与注销顺序无关。
软键栏只有三个格子,一个页面能派的动作却有十几个(分享 / 收藏 / 稍后再看 / 复制链接…),塞不下。所以把软键栏当成一级菜单:某个软键变成「更多」,按它展开二级菜单;二级菜单里的项如果还有子项,再展开就是三级菜单。
一级: [ 全屏 ] [ 播放 ] [ 更多 ▸ ] ← 软键栏
二级: ┌──────────────────────────────────┐
│ 更多操作 ●● │ ← 面板 + 面包屑 + 层级点
│ ──────────────────────────────── │
│ UP 主页 │
│ 分享 ▸ │ ← 有子项 → 三级
│ 收藏 ▸ │
└──────────────────────────────────┘
三级: ┌──────────────────────────────────┐
│ ‹ 更多操作 › 分享 ●● │ ← 面包屑能看出从哪来
│ ──────────────────────────────── │
│ 复制链接 │
│ 分享给好友 │
└──────────────────────────────────┘
onKey 的 menu 选项让作用域接管这个菜单(和 softkeys 一样跟着作用域一起释放,不会漏到下一个页面):
// 菜单树可以是一个对象, 也可以是一个**函数** —— 函数在菜单打开的那一刻才求值,
// 所以菜单项能跟着页面的异步状态走 (作者信息没到时「UP 主页」就是灰的)
return onKey('video-player', {
SoftLeft: () => toggleFullscreen()
}, {
softkeys: true,
menu: () => ({
slot: 'right', // 菜单占右软键 (默认; 只能 left / right)
label: '更多', // 右软键显示的文案
title: '更多操作', // 面板标题 / 面包屑第一级
items: [
// 二级只放入口; 有子项的按中键进三级菜单
{ label: 'UP 主页', disabled: !ownerMid, action: () => goUp() },
{
label: '播放控制',
items: [
// hint: 副提示 (右对齐的小字), 告诉用户"这个功能还有更快的键"
{ label: '快进', hint: '长按 → 键', action: () => seek(5) },
{ label: '音量加', hint: '长按 ↑ 键', action: () => volume(1) }
]
},
{ label: '互动', items: [ { label: '点赞', action: () => like() } ] },
// group: 分组标题, 只需要写在每组的第一项, 后面的项自动继承
{ group: '其它', label: '分享', items: [ { label: '复制链接', action: () => copy() } ] }
]
})
});菜单项支持的字段:
| 字段 | 作用 |
|---|---|
label |
项的文字 |
group |
所属分组的标题(MD3 list subheader)。只写在每组第一项,后面的项自动继承,不用重复写 |
hint |
右对齐的副提示(小号弱化色),例如「长按 → 键」—— 提示这个功能还有更快的键 |
icon |
文字前面的图标(可选) |
disabled |
置灰,按中键没反应 |
items |
有子项 → 右边画箭头,按中键进三级菜单 |
action |
叶子项的动作 |
分组 + 副提示是给「动作很多」的页面用的。视频页的二级菜单只留入口,具体动作都收进三级菜单,二级一眼能扫完:
更多操作 ●● ← 二级菜单 (详情页 5 个入口)
UP 主页
播放控制 ▸
互动 ▸
分享 ▸
退出应用
更多操作 › 播放控制 ●● ← 三级菜单
快进 长按 → 键
快退 长按 ← 键
音量加 长按 ↑ 键
音量减 长按 ↓ 键
更多操作 › 互动 ●● ← 三级菜单
一键三连
点赞
投币
收藏
菜单变长(十几项)会超出面板高度,所以高亮移动时列表会自动滚动,把选中项滚到可视区中间 —— 否则用户会看着高亮跑出屏幕。自动滚动那段代码有个坑:响应式语句的条件里必须出现 index(高亮下标),否则 Svelte 不会因为高亮移动而重跑它,选中项滚出去就再也拉不回来。
视频页和全屏播放页共用同一份菜单(src/lib/player/videoMenu.js)—— 菜单树只写一份,各自把自己的动作(seek / 音量 / 互动 / 跳转)传进去:
// 视频详情页: 菜单挂右软键
buildVideoMenu({ slot: 'right', label: '更多', seekStep: 5, seek: d => seek(d), ... })
// 全屏播放页: 菜单也挂右软键 (和详情页同一侧, 位置统一)
buildVideoMenu({
slot: 'right', label: '更多', seekStep: 10, ...,
// 副提示里的按键跟着**本页的绑定**走 (全屏画面转了 90°, 方向键也转了 90°)
hints: { forward: '短按 ↓ 键', back: '短按 ↑ 键', volUp: '短按 → 键', volDown: '短按 ← 键' }
});全屏页比详情页多一项「视频分辨率」(详情页的播放器固定 240P,不需要调)—— 页面传 quality / qualities / onQuality 才有这一项:
// 全屏播放页: 菜单里能切分辨率, 当前档用 ✓ 标出
buildVideoMenu({
...,
quality: currentQuality, // 当前档 (qn)
qualities: [{ label: '240P', value: 6 }, { label: '720P', value: 64 }, ...],
onQuality: qn => changeQuality(qn) // 切档: 换流 + 写回设置
});切档时播放位置接着走(换流会把播放头重置成 0,得记下位置等新的流 loadedmetadata 再跳回去),并且顺手把设置里的「全屏默认分辨率」一起改掉(持久化)。
末项固定是 「退出应用」(全局收口,和主页那套菜单同一份文案、同一份行为,由 buildExitItem() 统一造)。不想让它出现在菜单里、或者想让它灰着按不动,都可以手动关:
buildVideoMenu({ ... , exit: false }) // 菜单里根本没有这一项
buildVideoMenu({ ... , exitDisabled: true }) // 这一项灰着, 按中键没反应软键栏能整条藏起来,但菜单不受影响 —— onKey 的 hideSoftkeys 选项把那一行提示藏掉(沉浸模式),页面派给软键的动作照常生效:
// 全屏播放页: 设置里关掉「全屏播放显示软键栏」→ 整条软键栏藏起来
onKey('fullscreen-player', { /* … */ }, {
softkeys: true,
hideSoftkeys: !fullscreenMenu, // 藏的是提示行, 不是菜单
menu: () => buildMenu() // 菜单**一直都在**: 右软键照样能展开它
});藏栏时菜单打开,软键栏会临时露出来 —— 菜单的操作提示(「关闭」/「选择」)写在这一行上,而且菜单面板贴着软键栏上沿摆,栏不见了底下就空一条;菜单一关,栏继续藏着。
全局二级菜单(src/lib/menu/appMenu.js)—— 主页三个 Tab(首页 / 关注 / 我的)的右软键统一变成「更多」,原来绑在右软键上的动作收进菜单,最后一项固定是「退出应用」:
// 首页: 搜索收进菜单, 右软键不再自己派活
onKey('home', { /* … */ }, {
softkeys: true,
menu: () => buildAppMenu([
{ label: '搜索', disabled: !$isLogin, action: () => navigate('/search') }
])
// buildAppMenu 会自动在最后追加「退出应用」
// (exit: false = 不要这一项, exitDisabled: true = 灰着按不动)
});| 页面 | 二级菜单 |
|---|---|
| 首页 | 搜索(没登录时置灰) → 退出应用 |
| 关注 | 切到动态 / 切到视频(跟着当前 Tab 走) → 退出应用 |
| 我的 | 退出应用(这一页原来没绑右软键) |
「退出应用」先归位再退出:先把路由重置到 /(首页),等路由处理完,再 window.close() 关掉应用窗口。window.close() 在 KaiOS 2.4(Gecko 48)上是真的能结束应用 —— 实测(真机 Nokia 6300 4G):调完之后 console actor 消失,b2g-ps 里也没有这个应用了。路由先归位是为了下次进来落在首页,不会停在奇怪的位置。这一项由 buildExitItem() 统一造(src/lib/menu/appMenu.js),主页那套菜单和视频页/全屏页那套共用同一份 —— 两边行为不一样的话,用户按到会觉得「这软件的退出怎么两副样子」。
副提示必须和实际绑定对得上(本项目的硬规矩:文案必须和行为一致)。全屏播放页的画面转了 90°,方向键也跟着转(↑/↓ 快退快进、←/→ 音量),所以它的提示写「短按 ↓ 键」,而不是详情页的「长按 → 键」。
菜单打开时的按键(stores/softkey.js 管层级,SoftkeyBar.svelte 管画和派按键):
| 按键 | 行为 |
|---|---|
Up / Down |
在当前层移动高亮(到头绕回另一头,菜单是闭环) |
Enter |
激活高亮项:有子项就进下一级,是叶子就执行动作并关掉菜单 |
Right |
有子项 → 进下一级(等价于 Enter) |
Left |
回到上一级 |
Back(退格键) |
回到上一级;已在二级就整个关掉 |
SoftLeft |
和返回键同义(二级=关闭,三级=上一级) |
菜单打开期间独占按键(页面收不到上下键,也不会偷偷换软键文案),软键栏临时变成菜单的操作提示:二级 = 左「关闭」/ 中「选择」,三级 = 左「上一级」/ 中「选择」;关掉菜单后软键栏立刻恢复成页面自己的文案 —— 菜单不碰 ui.softkeys。
注册了菜单就别再自己绑那个软键:菜单接管后优先级高于页面(文案必须和行为一致),页面再绑一次会打架。页面想自己派活、只想"按某个键打开菜单"时,用
openSoftkeyMenu(tree)手动开,软键文案仍然归页面。
状态都在 src/lib/stores/softkey.js(层级栈 / 高亮下标 / 面包屑),层级用栈表示:stack[0] 是二级,stack[1] 是三级;每层记着自己是从哪一项进来的(parentIndex),往回退时高亮还原到父菜单那一项。
页面没有注册对应按键时,框架自动提供:
Up/Down→ 在[data-navable]元素之间移动焦点,滚动到可视区中央Enter→ 激活当前焦点元素(等价于点击它)
所以绝大多数页面只需要注册软键即可。
x = x 在 Svelte 3 里不会触发重新渲染。 编译器把它变成 $$invalidate(0, x),而引用没变 → Svelte 判定"值没变" → 不标脏 → 界面永远不动。
let subMap = {};
function bump() {
subMap[rpid] = state;
subMap = subMap; // ❌ 没反应
}正确写法是换引用:
function setSub(rpid, state) {
const next = { ...subMap };
next[rpid] = state;
subMap = next; // ✅ 新对象 → 标脏 → 重新渲染
}这个坑很隐蔽:JS 层面 subMap 确实变了(所以读它的地方拿得到新值),但 DOM 不更新。评论展开"按了中键没反应"就是踩了这个 —— 展开状态改了、软键提示也变了(提示是另一条链路),唯独子评论列表不渲染。
scripts/test-keyboard.js 里有一条测试扫源码里的自赋值写法,防止再踩。
列表容器加 data-nav-root 后,上下键只在该区域内移动,不会跳到别的区域:
<div class="feed-list scroll-y" data-nav-root>…</div>- 输入框聚焦时:只有文字类按键(数字/字母/空格/退格/标点)让给输入法;方向键、中键、软键仍然交给页面(页面显式注册了才生效)
- 例外:空输入框里的退格键 —— 没有字可删,就不喂给输入法,交给页面当"返回"用。应用的返回键就是退格键,搜索页一进来焦点就在输入框上,不这么处理的话用户按返回键没反应,直接卡在那一页(主页菜单里点「搜索」跳过去后回不来的老毛病)
- 模态框打开时:注册一个独占作用域,只有模态能响应按键,且只对它声明的按键
preventDefault—— 输入框照常编辑文字、移动光标
import { openModalScope } from '../keyboard/modalkeys.js';
const closeScope = openModalScope('reply', {
SoftLeft: () => close(),
SoftRight: () => send(),
Enter: () => send(),
Back: () => (!value ? close() : false) // 非空时返回 false → 退格正常删字
}, { softkeys: ['取消', '发送', ''] }); // 关闭时软键栏自动还原模态框也拿不到挂断键 ——
EndCall/Call在总线最前面就放行了,网页不能拦着用户打电话(以前评论回复框把挂断键当"取消",用户想挂电话结果把回复框关了)。
按键框架的纯逻辑可以在 Node 里跑(不需要真机):
node scripts/test-keyboard.js覆盖按键归一化、跨版本 keyCode 自学习、作用域优先级与实例隔离、输入框策略、模态独占、软键栏所有权与还原、焦点漫游的首/末/边界、记住并恢复焦点位置(focusIndex / focusAt)、长按与 keyup 收尾、catchAll 整页拦截。
- bilibili-api-collect (镜像) — B站 API 文档参考
- KaiUI — KaiOS 组件库(软键栏的设计参考)
- Svelte — UI 框架
- Rollup — 模块打包