add-command

name	add-command
description	NaiveTab 浏览器扩展的全局命令快捷键开发指南。当用户要新增/修改命令快捷键（如新增 tab 操作、页面滚动、窗口操作等命令）时使用。涵盖需要修改的完整文件清单、执行环境分类、类型注册等，防止遗漏关键步骤。

NaiveTab Add Command

新增命令快捷键需按以下步骤完成。核心原则：COMMAND_CATEGORIES 是单一数据源，所有命令类型从它派生。

决策树：你的命令在哪执行？

新增命令 → 确定执行环境：
  └─ 'sw'      → Service Worker 执行（chrome.tabs 等浏览器 API）
  └─ 'cs'      → Content Script 执行（DOM 操作：滚动、复制、刷新页面）
  └─ 'newtab'  → NaiveTab 页面执行（localConfig / globalState 操作）

必须修改的文件

Step 1 — src/logic/constants/icons.ts

在 COMMAND_ICONS 中定义图标：

export const COMMAND_ICONS = {
  // ... 已有图标 ...
  myCommand: 'mdi:some-valid-icon',   // ← 先在这里定义
}

图标来自 Iconify，需验证图标名存在。可以复用已有图标（如多个命令共用 mdi:pin-outline）。

Step 2 — src/logic/shortcut/shortcut-command.ts ⚠️ 核心文件

2-A：在 COMMAND_CATEGORIES 对应分类中添加命令

{
  categoryKey: 'commandCategory.tabManagement',
  commands: [
    // ... 已有命令 ...
    { command: 'myCommand', iconName: COMMAND_ICONS.myCommand },
    // 如果非 SW 执行，需标注 execEnv：
    // { command: 'myDomCommand', execEnv: 'cs' as const, iconName: COMMAND_ICONS.myDomCommand },
  ],
}

2-B：如果是新分类，新建一个分类对象：

{
  categoryKey: 'commandCategory.myCategory',
  commands: [
    { command: 'myCommand', iconName: COMMAND_ICONS.myCommand },
  ],
}

2-C：根据 execEnv 更新类型约束（仅在需要时）：

执行环境	需要更新的类型	说明
'cs'	TCsCommandName	新增联合类型成员
'newtab'	TNewtabCommandName	新增联合类型成员
'sw'（默认）	无需额外操作	自动从 TCommandName 排除 CS/newtab 命令后派生

TCommandName、TSwCommandName 会从 COMMAND_CATEGORIES 自动派生，无需手动维护。

2-D：（可选）添加默认 keymap 绑定

在 KEYBOARD_COMMAND_CONFIG.keymap 中添加默认按键绑定：

keymap: {
  // ... 已有绑定 ...
  KeyX: { command: 'myCommand' },   // ← 新增
}

2-E：（仅滚动命令）添加到 REPEATABLE_SCROLL_COMMANDS

如果命令支持按住持续触发（如 scrollUp/Down/Left/Right）：

export const REPEATABLE_SCROLL_COMMANDS = new Set([
  'scrollUp',
  'scrollDown',
  'scrollLeft',
  'scrollRight',
  'myRepeatableCommand',   // ← 新增
] as const)

Step 3 — 根据 execEnv 实现命令逻辑

SW 命令（execEnv: 'sw'，默认值）

在 src/background/commands/registry.ts 中：

// 3-A：实现 handler 函数
const myCommand = (tabId: number) => {
  chrome.tabs.update(tabId, { /* ... */ }).catch(logLastError)
}

// 3-B：在 COMMAND_HANDLERS Record 中注册
const COMMAND_HANDLERS: Record<TSwCommandName, CommandHandler> = {
  // ... 已有条目 ...
  myCommand,
}

⚠️ 缺少 COMMAND_HANDLERS 注册项会导致 TS 编译报错（TSwCommandName 类型约束）。

CS 命令（execEnv: 'cs'）

在 src/contentScripts/index.ts 的 commandExecutors 中添加：

const commandExecutors: Record<string, () => void> = {
  // ... 已有执行器 ...
  myCommand: () => {
    // DOM 操作，例如：
    document.body.style.background = 'red'
  },
}

如果是滚动类命令，还需在 src/contentScripts/scroll.ts 中实现滚动逻辑，并在 src/logic/shortcut/shortcut-command.ts 的 REPEATABLE_SCROLL_COMMANDS 中注册（见 Step 2-E）。

NaiveTab 本地命令（execEnv: 'newtab'）

在 src/logic/shortcut/shortcut-executor.ts 中添加执行器：

// 控制类命令（操作 localConfig / globalState）
const newtabControlExecutors: Record<string, () => void> = {
  // ... 已有执行器 ...
  myCommand: () => {
    localState.value.isFocusMode = !localState.value.isFocusMode
  },
}

newtabCommandExecutors 用于 CS 命令在 newtab 页面的执行（或静默忽略）。如果命令在 newtab 页面无意义，在 newtabCommandExecutors 中添加空函数 () => {} 静默忽略。

Step 4 — src/types/messages.ts

消息类型通常不需要修改。MSG_KEYDOWN、MSG_EXECUTE_COMMAND、MSG_INIT_COMPLETE、MSG_HELLO 已覆盖所有场景。

仅在需要新增消息类型时才修改此文件。

Step 5 — i18n：src/locales/zh-CN.json 和 en-US.json

命令名称（必须）：

{
  "command": {
    "myCommand": "我的命令"
  }
}

分类名称（如果新建了分类）：

{
  "commandCategory": {
    "myCategory": "我的分类"
  }
}

⚠️ zh-CN.json 和 en-US.json 必须同步更新。

---

新增命令的完整检查清单

检查项	SW 命令	CS 命令	Newtab 命令
COMMAND_ICONS 定义图标	✅	✅	✅
COMMAND_CATEGORIES 注册	✅	✅	✅
execEnv 标注（非 SW 时）	不需要	✅ execEnv: 'cs'	✅ execEnv: 'newtab'
类型联合更新（TCs/TNewtab）	不需要	✅	✅
SW handler 实现	✅	不需要	不需要
CS executor 实现	不需要	✅	不需要
newtab executor 实现	不需要	可选（或空函数忽略）	✅
keymap 默认绑定	可选	可选	可选
REPEATABLE_SCROLL_COMMANDS	仅滚动命令	仅滚动命令	不需要
i18n 命令名称	✅	✅	✅
i18n 分类名称（新分类时）	✅	✅	✅

---

无需手动修改（自动处理）

文件	机制
shortcut-command.ts 中的 TCommandName、TSwCommandName	从 COMMAND_CATEGORIES 自动派生
SW_COMMANDS、CS_COMMANDS、NEWTAB_COMMANDS 运行时列表	从 COMMAND_CATEGORIES 过滤派生
getCommandExecEnv()	遍历 COMMAND_CATEGORIES 查找
Setting 面板的命令选择器	遍历 COMMAND_CATEGORIES 分组渲染