按键映射

vuEPG 把按键映射为按键事件（key action）。每个按键事件包含一组按键、是否阻止浏览器默认行为，以及一个可选的回调。

默认按键事件

/**
 * 默认按键映射：兼顾 PC 键盘与常见机顶盒遥控器。
 * 字符串为 `event.code`；数字为 `event.which` / `event.keyCode`，
 * 只在 `event.code` 缺失（旧内核）或为 `"Unidentified"` 时参与匹配。
 */
const DEFAULT_KEY_ACTIONS: ReadonlyMap<string, KeyAction> = new Map([
  // 38 方向键 · 19 Android 方向键 · 87 W 键
  ["UP", { codes: ["ArrowUp", 87, 19, 38], preventDefault: true, callback: null }],
  // 40 方向键 · 20 Android 方向键 · 83 S 键 · 47 Android S 键
  ["DOWN", { codes: ["ArrowDown", 83, 40, 20, 47], preventDefault: true, callback: null }],
  // 37 方向键 · 21 Android 方向键 · 65 A 键 · 29 Android A 键
  ["LEFT", { codes: ["ArrowLeft", 65, 29, 21, 37], preventDefault: true, callback: null }],
  // 39 方向键 · 22 Android 方向键 · 68 D 键 · 32 Android D 键（亦为空格键）
  ["RIGHT", { codes: ["ArrowRight", 68, 22, 32, 39], preventDefault: true, callback: null }],
  // 13 回车 · 23 Android 确定键 · 66 Android 回车键 · 73、1 沿用自 vue-epg
  [
    "ENTER",
    { codes: ["Enter", "NumpadEnter", 13, 73, 66, 23, 1], preventDefault: true, callback: null },
  ],
  // 8 退格 · 27 Esc · 4 Android 返回键 · 10009 Tizen 返回键 · 461 webOS 返回键
  [
    "BACK",
    {
      codes: ["Backspace", "Escape", 4, 27, 8, 10009, 461],
      preventDefault: true,
      callback: null,
    },
  ],
  ["PAGE", { codes: ["PageUp", "PageDown", 33, 34], preventDefault: true, callback: null }],
  [
    "NUMBER",
    {
      // prettier-ignore
      codes: [
        "Digit0", "Digit1", "Digit2", "Digit3", "Digit4",
        "Digit5", "Digit6", "Digit7", "Digit8", "Digit9",
        "Numpad0", "Numpad1", "Numpad2", "Numpad3", "Numpad4",
        "Numpad5", "Numpad6", "Numpad7", "Numpad8", "Numpad9",
        48, 49, 50, 51, 52, 53, 54, 55, 56, 57,
        96, 97, 98, 99, 100, 101, 102, 103, 104, 105,
      ],
      preventDefault: false,
      callback: null,
    },
  ],
]);

事件	内置行为
UP / DOWN / LEFT / RIGHT	移动焦点，见 移动规则
ENTER	调用当前焦点元素的 click()
BACK	调用返回处理，见 返回处理
PAGE / NUMBER	无，可通过回调自行处理

带内置行为的 6 个事件不可删除，但可以修改它们的按键、preventDefault 与回调；回调在内置行为之后执行。

按键是如何识别的

读取顺序为 event.code → event.which → event.keyCode，取第一个有效值（event.code 缺失、为空或为 "Unidentified" 时回退）。现代浏览器通常只会匹配到 event.code，只提供数字键值的老旧机顶盒浏览器会匹配到数字。因此添加一个按键时，建议同时写上 event.code 和数字键值。

在输入框、文本域、下拉框或可编辑内容中，vuEPG 将文字、Backspace 和左右方向键交给浏览器处理；上下方向键和 Esc / 遥控器返回键仍由 vuEPG 处理。输入时需要处理其他按键，可直接监听输入元素的原生 keydown 事件。

在目标设备上查看键值：

document.addEventListener("keydown", (event) => {
  console.log(event.code, event.which, event.keyCode);
});

自定义

const epg = useVuEPG();

// 新增：按 M 或遥控器菜单键（键值 82）打开菜单
epg.setKeyAction("MENU", {
  codes: ["KeyM", 82],
  preventDefault: true,
  callback: (code, event) => openMenu(),
});

// 修改部分字段
epg.updateKeyAction("NUMBER", {
  preventDefault: true,
  callback: (code) => jumpToChannel(code),
});

// 为已有事件追加 / 移除按键
epg.addKeyCodes("ENTER", ["Space", 32]);
epg.removeKeyCodes("UP", [87]);

// 删除自定义事件
epg.removeKeyAction("MENU");

// 查看当前全部按键事件（只读快照）
console.log(epg.getKeyActions());

修改不存在的事件、删除内置事件时会抛出错误。

暂停

弹出原生输入框、播放全屏视频等场景下，可以暂停 vuEPG 对按键的响应：

const releasePause = epg.pause();
releasePause(); // 只释放本次暂停
epg.resume(); // 强制清除所有暂停
epg.isPaused(); // boolean

多处同时暂停时，应保存并调用各自的释放函数；全部释放后才恢复响应。暂停期间不会调用 preventDefault()，按键完全交还给浏览器。