实现命令面板Skill implementing-command-palettes

---

名称: 实现命令面板 描述: 在React中构建Cmd+K命令面板时使用 - 涵盖使用箭头键进行键盘导航、使用scrollIntoView保持选中项在视图中、使用快捷键匹配进行过滤，以及防止引用不稳定导致的无限重新渲染

实现命令面板

概述

命令面板（Cmd+K / Ctrl+K）需要精确的键盘导航、滚动行为和稳定的引用以避免重新渲染循环。本技能涵盖使命令面板感觉响应迅速的机械模式。

何时使用

• 在React中构建Cmd+K命令面板
• 实现带有视觉选择的箭头键导航
• 在键盘导航期间保持选中项可见
• 通过标签文本和键盘快捷键过滤命令
• 当命令更新时遇到无限重新渲染

快速参考

功能	实现
箭头导航	跟踪 selectedIndex，使用 Math.min/max 进行限制
保持在视图中	scrollIntoView({ block: 'nearest', behavior: 'smooth' })
快捷键匹配	从快捷键中去除空格，与查询匹配
稳定的图标	在组件外部定义图标元素
稳定的处理程序	useCallback + noop 常量用于禁用状态

键盘导航

关键点：条件渲染的包装器模式

这是最常见的错误来源。 键盘效果必须仅在面板打开时运行。使用包装器组件：

// 包装器确保效果仅在打开时运行
export function CommandPalette(props: CommandPaletteProps) {
  if (!props.isOpen) return null;
  return <CommandPaletteContent {...props} />;
}

// 内容组件 - 效果在挂载/卸载时运行
function CommandPaletteContent({ onClose, ... }: CommandPaletteProps) {
  // 效果仅在此面板可见时运行
  useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => { ... };
    window.addEventListener('keydown', handleKeyDown);
    return () => window.removeEventListener('keydown', handleKeyDown);
  }, [deps]);

  return <div>...</div>;
}

为什么这很重要：

• 如果在useEffect钩子之后放置 if (!isOpen) return null，效果在关闭时仍会运行
• 这导致键盘监听器在面板不可见时仍被注册
• 包装器模式确保效果仅在组件实际渲染时运行

输入焦点 + 窗口监听器模式

输入必须获得焦点（以便打字工作），键盘导航必须使用 window.addEventListener。这之所以有效是因为：

• 窗口监听器接收所有按键的keydown事件
• 箭头键不会向输入框插入文本，因此 e.preventDefault() 只是停止页面滚动
• 常规字符键仍能到达输入框进行打字

// 带有autoFocus的输入框 - 不使用setTimeout聚焦
<input
  autoFocus
  type="text"
  value={query}
  onChange={e => {
    setQuery(e.target.value);
    setSelectedIndex(0);  // 查询更改时重置到第一项
  }}
/>

索引管理

const [selectedIndex, setSelectedIndex] = useState(0);

useEffect(() => {
  if (!isOpen) return;

  const handleKeyDown = (e: KeyboardEvent) => {
    switch (e.key) {
      case 'ArrowDown':
        e.preventDefault();
        // 限制到最后一项
        setSelectedIndex(prev => Math.min(prev + 1, filteredItems.length - 1));
        break;
      case 'ArrowUp':
        e.preventDefault();
        // 限制到第一项
        setSelectedIndex(prev => Math.max(prev - 1, 0));
        break;
      case 'Enter':
        e.preventDefault();
        if (filteredItems[selectedIndex]) {
          executeCommand(filteredItems[selectedIndex]);
          close();
        }
        break;
      case 'Escape':
        e.preventDefault();
        close();
        break;
    }
  };

  // 不需要捕获阶段 - 简单的窗口监听器与聚焦的输入框配合使用
  window.addEventListener('keydown', handleKeyDown);
  return () => window.removeEventListener('keydown', handleKeyDown);
}, [isOpen, filteredItems, selectedIndex, close]);

关键模式：

• e.preventDefault() 阻止箭头键滚动页面
• Math.min/max 防止索引越界
• 效果依赖于 filteredItems，以便在过滤器更改时更新导航
• 在输入框上使用 autoFocus，而不是 setTimeout(() => ref.current?.focus(), 0)

保持选中项在视图中

使用引用数组

const itemRefs = useRef<(HTMLButtonElement | null)[]>([]);

// 滚动效果 - 在选中项更改时运行
useEffect(() => {
  const selectedItem = itemRefs.current[selectedIndex];
  if (selectedItem) {
    selectedItem.scrollIntoView({
      block: 'nearest',    // 最小滚动 - 仅在需要时滚动
      behavior: 'smooth'   // 平滑动画
    });
  }
}, [selectedIndex]);

// 在渲染中分配引用
{filteredItems.map((item, index) => (
  <button
    key={index}
    ref={el => { itemRefs.current[index] = el; }}
    className={index === selectedIndex ? 'bg-blue-100' : ''}
  >
    {item.label}
  </button>
))}

替代方案：选中项的单引用

const selectedItemRef = useRef<HTMLButtonElement>(null);

useEffect(() => {
  if (isOpen && selectedItemRef.current) {
    selectedItemRef.current.scrollIntoView({
      block: 'nearest',
      behavior: 'smooth',
    });
  }
}, [isOpen, selectedIndex]);

// 仅将引用分配给选中项
<button
  ref={index === selectedIndex ? selectedItemRef : null}
>

为什么使用 block: 'nearest？

• 'nearest' 仅在元素在可见区域外时滚动
• 'center' 即使项目已可见也会滚动，导致令人不适的移动
• 'start' 或 'end' 会始终对齐到顶部/底部

使用快捷键匹配进行过滤

const filteredCommands = commands.filter(command => {
  const q = query.toLowerCase().trim();
  if (!q) return true;

  // 标准标签匹配
  if (command.label.toLowerCase().includes(q)) return true;

  // 快捷键匹配："gd" 匹配 "g d"，"gb" 匹配 "g b"
  if (command.shortcut) {
    const shortcutNoSpaces = command.shortcut.toLowerCase().replace(/\s+/g, '');
    if (shortcutNoSpaces.startsWith(q) || shortcutNoSpaces.includes(q)) {
      return true;
    }
  }

  // 对于编号项目（PR、问题），按数字匹配
  if (command.type === 'pr') {
    const numberMatch = q.match(/^#?(\d+)$/);
    if (numberMatch) {
      return String(command.pr.number).startsWith(numberMatch[1]);
    }
  }

  return false;
});

为什么从快捷键中去除空格？ 用户连续打字时不带空格。快捷键 "g d" 应在用户输入 "gd" 时匹配。

防止重新渲染循环

当命令对象每次渲染都被重新创建时，命令面板经常遭受无限重新渲染的问题。

问题：不稳定的引用

// 错误：图标每次渲染都被重新创建
function usePageCommands() {
  const commands = useMemo(() => [{
    label: '同步',
    icon: <RefreshCw size={16} />,  // 每次渲染都创建新元素！
    action: () => onSync(),          // 每次渲染都创建新函数！
  }], [onSync]);  // 即使有依赖项，图标也是新的

  useRegisterCommands(commands);  // 触发重新注册 → 重新渲染循环
}

解决方案：稳定的引用

// 正确：图标在组件外部定义
const refreshIcon = <RefreshCw size={16} />;
const refreshSpinIcon = <RefreshCw size={16} className="animate-spin" />;
const noop = () => {};

function usePageCommands({ onSync, isSyncing }: Props) {
  // 记忆化处理程序
  const handleSync = useCallback(() => onSync?.(), [onSync]);

  const commands = useMemo(() => [{
    label: isSyncing ? '同步中...' : '同步',
    icon: isSyncing ? refreshSpinIcon : refreshIcon,  // 稳定的引用
    action: isSyncing ? noop : handleSync,             // noop，不是undefined
  }], [isSyncing, handleSync]);

  useRegisterCommands(commands);
}

基于标签的变更检测

不比较对象引用，而是通过标签比较：

export function useRegisterCommands(commands: CommandItem[]) {
  const { registerCommands, unregisterCommands } = useCommandPalette();

  // 基于标签创建稳定的ID，而不是对象引用
  const commandIds = useMemo(
    () => commands.map(c => {
      if (c.type === 'nav') return `nav:${c.path}`;
      return `action:${c.label}`;
    }).sort().join('|'),
    [commands]
  );

  const commandsRef = useRef<CommandItem[]>(commands);
  useEffect(() => { commandsRef.current = commands; });

  const prevIdsRef = useRef<string>('');

  useEffect(() => {
    // 仅在实际结构更改时注册
    if (commandIds !== prevIdsRef.current) {
      registerCommands(commandsRef.current);
      prevIdsRef.current = commandIds;
      return () => unregisterCommands(commandsRef.current);
    }
  }, [commandIds, registerCommands, unregisterCommands]);
}

命令类型模式

type CommandItem =
  | { type: 'action'; label: string; icon?: React.ReactNode; action: () => void; shortcut?: string }
  | { type: 'nav'; label: string; icon?: React.ReactNode; path: string; shortcut?: string }
  | { type: 'file'; file: FileType; label: string; icon?: React.ReactNode }
  | { type: 'pr'; pr: PRType; label: string; icon?: React.ReactNode };

// 基于类型执行
function executeCommand(command: CommandItem) {
  switch (command.type) {
    case 'action':
      command.action();
      break;
    case 'nav':
      navigate(command.path);
      break;
    case 'file':
      onFileSelect(command.file);
      break;
    case 'pr':
      navigate(`/repos/${command.owner}/${command.repo}/pulls/${command.pr.number}`);
      break;
  }
}

常见错误

错误	为什么失败	修复方法
图标在useMemo内部	每次渲染都创建新的图标元素	在组件外部将图标定义为常量
过滤器更改时不重置索引	箭头键从错误位置开始	在onChange中调用 setSelectedIndex(0)
scrollIntoView中使用 block: 'center'	当项目已可见时令人不适的滚动	使用 block: 'nearest'
缺少 e.preventDefault()	箭头键滚动页面并移动选择	为ArrowUp/Down添加preventDefault
忘记在useEffect中清理	事件监听器累积	返回清理函数
禁用操作使用 undefined	类型错误或点击无效	使用 noop 常量
在窗口监听器上使用 { capture: true }	不需要且可能导致问题	使用简单的 addEventListener，不带选项
聚焦容器而不是输入框	打字无效，用户体验差	在输入框上使用 autoFocus，窗口监听器处理箭头键
使用 setTimeout 进行聚焦	竞争条件，聚焦可能失败	在输入框上使用 autoFocus 属性
在输入元素上使用 onKeyDown	有效但不如窗口监听器可靠	在useEffect中使用 window.addEventListener
使用引用来避免重新注册监听器	过时的闭包，错过更新	在数组中包含依赖项，让监听器重新注册
在useEffect之后使用 if (!isOpen) return null	效果在关闭时仍运行，监听器始终活跃	使用包装器组件模式（见上文）
条件 bg-accent-light 与 bg-transparent 一起使用	Tailwind CSS冲突 - 两者都设置背景颜色，编译顺序决定结果	将背景类放在条件中：${selected ? 'bg-accent-light' : 'bg-transparent hover:bg-gray-100'}

测试清单

• [ ] Cmd+K打开面板，Escape关闭
• [ ] 箭头向下移动到下一项（停在最后一项）
• [ ] 箭头向上移动到上一项（停在第一项）
• [ ] Enter执行选中命令并关闭面板
• [ ] 导航长列表时选中项滚动到视图中
• [ ] 打字将选择重置到第一个匹配项
• [ ] 像"gd"这样的快捷键匹配具有快捷键"g d"的命令
• [ ] 没有关于重新渲染或最大更新深度的控制台错误