WebHomeTV fm SDK 完全参考:play、req、pan、vodInline 等核心 API 清单与示例
WebHomeTV fm SDK 完全参考:play、req、pan、vodInline 等核心 API 清单与示例
WebHomeTV(webhtv)内置的 fm SDK 是 WebHome 网页与 App 原生能力之间的桥梁:在 App 加载的网页里,你可以直接调用 fm.play() 播放直链、fm.req() 绕过 CORS 请求接口、fm.pan.play() 推送网盘/磁力、fm.vodInline() 实现按集解析的多集播放。本文是一份面向新手的完整 API 清单,覆盖 play、req、pan、vodInline 等核心接口,并附最小示例与常见坑位说明。
一、fm SDK 是什么:能力模型一图看懂
WebHome 的本质是「真实网页 + App 注入的 fm SDK + 注入的扩展脚本」。Native 层(HomeWebController)会在页面里注入两个全局对象:
window.fongmi:完整命名空间(如fongmi.player.playUrl)window.fm:短别名(如fm.play),日常开发都用它
注入完成后会派发 fmsdk 事件。SDK 中除 fm.res() 是同步返回字符串外,其余 fm.* 调用都返回 Promise,记得 await 并捕获异常。
小贴士:脚本里统一用下面这个等待函数,就不用担心 SDK 注入时序问题。
function whenFm() {
if (window.fm) return Promise.resolve(window.fm);
return new Promise(function (resolve) {
window.addEventListener("fmsdk", function () { resolve(window.fm); }, { once: true });
});
}
另外 window.fongmiClient = { mode, isLeanback } 是判断手机/TV 端的唯一可靠依据,不要靠屏幕宽度或 UA 猜测。
二、fm.play / fm.vod:把网页链接交给原生播放器
1. 播放直链 fm.play(url, title, options)
await fm.play("https://example.com/video.m3u8", "影片名", {
pic: "https://example.com/poster.jpg", // 海报
wallPic: "https://example.com/backdrop.jpg", // 播放页背景
headers: { Referer: location.href }, // 防盗链时必带
credentials: "include" // 带 WebView Cookie
});
传了 headers 或 credentials 时,播放 URL 会自动转成 /webResource 网关地址;pic 是海报,wallPic 是播放页背景图,两者互不兜底。
2. 打开 CSP 站点影片 fm.vod(siteKey, vodId, title, pic, { wallPic })
直接跳进对应站点的原生详情/播放链路,vodId 就是该站 Spider 的 vod_id。
3. 播放控制 fm.ctrl(action) / fm.stat()
action支持:play/pause/stop/prev/next/loop/replayfm.stat()返回{ state, speed, duration, position, url, title, ... },state:1 其它 / 2 ready / 3 playing / 6 buffering
三、fm.req / fm.res:网络请求与资源网关
1. fm.req(url, options) —— 无 CORS 限制的 Native 请求
底层是 OkHttp,自动解 gzip/deflate(不支持 br),接 App 统一的 DNS/代理策略。常用 options:
| 字段 | 默认 | 说明 |
|---|---|---|
method |
GET |
自动转大写,GET/HEAD 不发 body |
headers |
{} |
缺省 UA / Accept-Encoding 会自动补 |
body |
"" |
必须是字符串,JSON 自行 stringify |
responseType |
text |
text / json / base64 |
timeout |
30 |
单位秒,最小 1 |
credentials |
- | include 时自动带 WebView 里该域名的 Cookie |
返回 { ok, status, url, headers, cookies, body, error? }。注意请求失败时是 ok:false, status:500, error:<消息>,不会 reject,要自己判断 ok。
2. fm.res(url, options) —— 给 DOM 元素用的资源网关(同步)
生成 http://127.0.0.1:{port}/webResource?url=... 本地地址,用于 img.src、video.src、字幕、CSS 背景。网关透传 Range(视频拖动必需)并回写 CORS 头。
选型口诀:JS 里读 API 数据用 fm.req;DOM 元素加载资源用 fm.res;图片有防盗链时记得带 Referer。
四、fm.vodInline:按集解析多集播放(进阶核心)⭐
当页面能列出多集、但每集地址需要点开才解析(懒加载/解密)时,fm.vodInline(payload) 让你进入 App 原生播放页,用户点哪一集,App 就回调页面里的 resolver 现场解析该集。
1. payload 结构
await fm.vodInline({
vod_id: "demo-1", // 可省略,自动生成
vod_name: "影片名",
vod_pic: "https://...",
vod_play_from: "WebHome", // 线路名
mark: "02", // 进入播放页默认选中的集名
headers: { Referer: location.href },
episodes: [
{ name: "01", pageUrl: "https://site/v/1" },
{ name: "02", url: "https://site/v/2.m3u8" } // 已有直链的集
]
});
episodes[] 常用字段:name(集名)、url(直链或标识)、mediaUrl(已解析好的真实媒体地址,有它就不再回调)、pageUrl(集数页面,按集解析必填)、resolve: true(点击该集才回调)、headers(该集独立请求头)、active(标记当前集)。
2. resolver 协议
window.__fmWebHomeInlineResolver = async function (episode) {
return {
url: "https://example.com/01.m3u8", // 必填,空则视为失败
headers: { Referer: episode.pageUrl } // 可选
};
};
3. 必须了解的 4 条 Native 行为
- 预解析当前集:调用
vodInline时先同步解析当前集,成功后才打开播放页,保证点开即播; - 按需解析有 20 秒超时:解析成功的集会缓存,重复点击不再回调;
- 页面必须存活:resolver 跑在 WebHome 页面里,播放期间别跳页、别刷新;
- 可复用站点解密函数:这是它优于服务端解析的地方——拿的是页面运行时上下文。
完整模板见 inline-episodes.js,实战案例见 ymvid.com.js(复用站点 AES 解密函数解出每集 m3u8)。
五、fm.pan:网盘、磁力与推送
1. 统一推送播放 fm.pan.play({ type, url, password, title, pic, wallPic })
网盘分享、magnet:、ed2k:、thunder:、jianpian:、普通 http 都能推给 App 既有解析链路。推荐 type 取值:quark / aliyun / baidu / uc / xunlei / tianyi / 123 / 115 / mobile / magnet / ed2k / thunder / jianpian / http。开头的 push:// 会自动剥离。
2. 有效性检测 fm.pan.check(items)(别名 fm.check)
const config = await fm.config();
if (config.driveCheck) {
const result = await fm.pan.check([
{ type: "quark", url: "https://pan.quark.cn/s/xxxx", password: "" }
]);
// result.results[i].state: ok 有效 / bad 失效 / locked 需码 /
// unsupported 不支持 / uncertain 风控
}
⚠️ 调用前必须检查 fm.config().driveCheck(受「增强功能 → 网盘检测」开关控制);磁力、电驴、thunder 不要提交检测;结果有内部缓存,检测应异步执行、不阻塞首屏。
六、其余常用接口速查表
| 接口 | 说明 |
|---|---|
fm.cache.set / get / del |
字符串级逻辑缓存(按扩展 id 隔离,建议直接用 GM_getValue/GM_setValue) |
fm.search(keyword, { direct }) |
打开原生搜索,direct: true 直达结果列表 |
fm.openVod() / fm.openSite() |
打开原生点播首页 / 内容源选择器 |
fm.openLive() / fm.openKeep() / fm.openSetting() |
打开直播 / 收藏 / 设置 |
fm.history() |
观看记录数组,可做「返回后补偿进度」 |
fm.device() |
{ uuid, name, ip, type(0 TV/1 手机), serial, ... } |
fm.site() |
当前主页站点 { key, name, homePage, type, header } |
fm.config() |
当前点播配置 { id, url, desc, driveCheck } |
fm.ext.info() |
扩展总开关状态与当前站点匹配/就绪扩展计数 |
fm.ext.log(msg, data) / fm.ext.toast(msg) |
写 App 扩展日志 / 弹原生 toast |
fm.ui.setChrome({ mode }) |
运行时切换 chrome:手机端 normal/edge/immersive,TV 端 tv-full 等 |
fm.ui.getViewport() |
当前 WebView 尺寸、安全区、系统栏高度、chromeMode |
fm.back() / fm.reload() |
触发 App 侧返回 / 清缓存重载主页 |
七、事件与 CSS 变量:SPA 与自适应的钥匙
| 事件 | 何时监听 |
|---|---|
fmsdk |
SDK 注入完成 |
fmurlchange |
SPA 路由变化必听(pushState/replaceState/popstate 被 hook) |
fmviewport |
窗口尺寸、安全区、chrome mode 变化(分屏、折叠屏、TV 工具栏显隐) |
fmresume / fmpause |
App 前后台切换,可用来恢复/暂停轮询 |
fmextload / fmexterror |
扩展执行成功 / 运行期抛错 |
配套 CSS 变量挂在 :root:--fm-web-height、--fm-safe-top/bottom、--fm-chrome-mode 等。注入 UI 的高度请用 var(--fm-web-height, 100vh) 替代裸 100vh;浏览器 env() 与 Native 变量叠加时用 max() 去重,不要相加。
八、新手避坑清单 📌
- 所有
fm.*(除fm.res)都是异步的,漏了await是最常见错误; - 旧盒子 WebView 基线是 ES2017:禁用
?.、??、逻辑赋值、catch {}省略绑定——语法错误会导致整个扩展静默消失,且 try/catch 救不了; GM_getValue/GM_setValue返回 Promise,且值会被String()转换,对象请自行JSON.stringify;- 只拦截已判定为资源的链接,不要拦所有
<a>;点击处理要try/catch+ toast,不静默; - TV 端焦点样式用
:focus(不要用:focus-visible,旧内核会丢弃整条规则)。
九、学习路径与配套资料
建议按以下顺序上手:
- 读 webhome-devkit/README.md 第 6-8 章(GM API、fm SDK 参考、vodInline 深入);
- 用 site-enhance-skeleton.js 作为脚本骨架起步;
- 在调试工作台跑 page-analyzer.js 采集页面结构;
- 参考 app-capabilities-showcase.html —— App SDK 能力测试台,集中演示
fm.req/res/play/vod/vodInline/pan/cache/ui全部开放能力; - 完整契约与 Chrome 模式细节见 应用完整开发文档.md 第 16 章(SDK 总览)与第 25 章(扩展开发)。
掌握 fm.play / fm.req / fm.pan / fm.vodInline 这四组接口,就覆盖了 WebHomeTV 扩展开发 90% 的场景,动手写第一个「App 播放」按钮扩展吧!


