介绍

vuEPG 致力于让 Vue 页面更容易接入焦点管理与空间导航，减少现代浏览器和运营商存量盒子开发中的适配与调试工作。

vuEPG 为 Vue 网页提供焦点管理与空间导航，适用于现代浏览器及 TV、IPTV、机顶盒。它内置键盘和遥控器按键映射，也提供逻辑 API 接入手柄、虚拟控制器或原生回调；页面保留原有组件、样式和业务逻辑。

它支持 Vue 2.7 与 Vue 3，已在各大运营商机顶盒项目中实际落地。运营商存量盒子的应用维护，常需要兼顾 Android 4.x 设备与旧 WebView；对应工程使用 Vue 2.7，并配合 ES5 应用构建与必要 polyfill；完整工程见 Android 4.x 机顶盒接入。

焦点是怎样移动的

• v-epg-item 标记可获得焦点的元素；
• v-epg-group 组织有独立入口与边界的导航区域；
• 方向键按元素的真实位置寻找目标，先在组内查找，再逐层向外；
• 确定键触发当前元素的 click，返回键调用注册的返回处理函数。

粉色框表示 vuEPG 当前焦点。点击分组或卡片试试。

vuEPG 使用逻辑焦点：通过焦点 class 表示当前选中项。焦点样式由页面决定，无需采用固定的 TV UI 组件。

输入从哪里来

网页在普通浏览器中直接接收键盘事件。TV 遥控器也可能发送相同事件；如果网页运行在原生应用的 WebView 内，原生应用可以通过 JavaScript 回调把按键传入，见原生按键接入。手柄和虚拟控制器可以使用相同的逻辑 API。

常用能力

• 动态页面：导航跳过隐藏、卸载或禁用的目标，失效焦点在可用分组恢复。
• 默认入口：进入分组时落在指定元素；入口也可以根据业务状态改变。
• 方向拦截：用 DOM 事件处理特殊跳转和边界，适合循环导航、弹窗等交互。
• 自动滚动：标记实际滚动容器，使获得焦点的元素保持可见。
• 返回处理：组件注册自己的返回逻辑，弹窗关闭后恢复页面处理。
• 输入接入：支持浏览器键盘映射，也能连接原生遥控器回调或虚拟遥控器。

从哪里开始

快速开始完成插件安装和第一个页面。导航演示用于体验方向规则和事件；完整示例展示页面、滚动和弹窗如何配合，也可以复制成独立工程。

已有 vuEPG 1.x、vue-epg 或 vue-tv-focusable 项目，可从迁移指南查看指令、事件和 API 对照。

致谢

• vue-epg：本项目的起点