WebHomeTV fm SDK 完全参考:play、req、pan、vodInline 等核心 API 清单与示例

原创2026-10-30 10:32:58494 阅读

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 等核心接口,并附最小示例与常见坑位说明。

WebHomeTV 播放页海报示例

一、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 / replay
  • fm.stat() 返回 { state, speed, duration, position, url, title, ... },state:1 其它 / 2 ready / 3 playing / 6 buffering

WebHomeTV 电视端壁纸效果示例

三、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 行为

  1. 预解析当前集:调用 vodInline 时先同步解析当前集,成功后才打开播放页,保证点开即播;
  2. 按需解析有 20 秒超时:解析成功的集会缓存,重复点击不再回调;
  3. 页面必须存活:resolver 跑在 WebHome 页面里,播放期间别跳页、别刷新;
  4. 可复用站点解密函数:这是它优于服务端解析的地方——拿的是页面运行时上下文。

完整模板见 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() 去重,不要相加。

八、新手避坑清单 📌

  1. 所有 fm.*(除 fm.res)都是异步的,漏了 await 是最常见错误;
  2. 旧盒子 WebView 基线是 ES2017:禁用 ?.、??、逻辑赋值、catch {} 省略绑定——语法错误会导致整个扩展静默消失,且 try/catch 救不了;
  3. GM_getValue/GM_setValue 返回 Promise,且值会被 String() 转换,对象请自行 JSON.stringify;
  4. 只拦截已判定为资源的链接,不要拦所有 <a>;点击处理要 try/catch + toast,不静默;
  5. TV 端焦点样式用 :focus(不要用 :focus-visible,旧内核会丢弃整条规则)。

WebHomeTV 首页背景效果图

九、学习路径与配套资料

建议按以下顺序上手:

  1. 读 webhome-devkit/README.md 第 6-8 章(GM API、fm SDK 参考、vodInline 深入);
  2. 用 site-enhance-skeleton.js 作为脚本骨架起步;
  3. 在调试工作台跑 page-analyzer.js 采集页面结构;
  4. 参考 app-capabilities-showcase.html —— App SDK 能力测试台,集中演示 fm.req/res/play/vod/vodInline/pan/cache/ui 全部开放能力;
  5. 完整契约与 Chrome 模式细节见 应用完整开发文档.md 第 16 章(SDK 总览)与第 25 章(扩展开发)。

掌握 fm.play / fm.req / fm.pan / fm.vodInline 这四组接口,就覆盖了 WebHomeTV 扩展开发 90% 的场景,动手写第一个「App 播放」按钮扩展吧!

登录后查看全文
webhtv