Vercel/Hyper 终端插件开发完全指南

前言

Vercel/Hyper 是一款基于 Electron 构建的现代化终端应用，其插件系统允许开发者扩展和定制终端功能。本文将全面介绍 Hyper 插件开发的工作流程、核心 API 和实用技巧，帮助开发者快速上手插件开发。

开发环境搭建

开发模式运行 Hyper

要开发 Hyper 插件，首先需要以开发模式运行 Hyper：

1. 克隆项目仓库并切换到 canary 分支
2. 安装所有依赖项
3. 在项目根目录创建 hyper.json 配置文件副本
4. 运行 yarn run app 启动开发模式

开发模式下，你将获得更详细的日志输出，并能使用 Electron 的 React/Redux 开发工具。

插件开发目录结构

首次运行后，Hyper 会在项目根目录创建 plugins 文件夹，其中：

• local 子目录用于存放本地开发的插件
• 建议使用符号链接方式关联你的插件项目目录

插件基础开发

插件注册

在 hyper.json 配置文件中，通过 localPlugins 数组注册你的插件：

{
  "localPlugins": ["hyper-awesome-plugin"]
}

插件基本结构

每个插件必须至少实现一个 API 方法。插件的基本结构如下：

// package.json 中定义插件名称和版本
{
  "name": "hyper-awesome-plugin",
  "version": "1.0.0"
}

// 插件主文件
module.exports = {
  // 插件API方法实现
}

调试技巧

• 渲染进程中的 console.log() 会显示在 Electron 开发者工具中
• 主进程中的日志会输出到运行 yarn run app 的终端
• 成功加载的插件会在启动时显示日志：Plugin hyper-awesome-plugin (1.0.0) loaded.

核心 API 详解

组件装饰器

Hyper 允许通过高阶组件(HOC)模式装饰几乎所有内置组件：

exports.decorateTerms = (Terms, {React}) => {
  return class extends React.Component {
    componentDidMount() {
      // 访问底层Term实例
      if (this.props.onDecorated) {
        this.props.onDecorated(this.terms);
      }
    }
    
    render() {
      // 返回装饰后的组件
      return <Terms {...this.props} />;
    }
  }
}

重要提示：必须正确传递 onDecorated 回调，否则会破坏插件链。

快捷键绑定

实现自定义快捷键需要两个步骤：

1. 声明键位映射：

exports.decorateKeymaps = keymaps => ({
  ...keymaps,
  'plugin:action': 'Ctrl+Shift+A'
});

2. 注册命令处理器：

// 渲染进程处理器
this.terms.registerCommands({
  'plugin:action': e => {
    e.preventDefault();
    // 执行操作
  }
});

// 主进程处理器
rpc.on('command plugin:action', () => {
  // 主进程操作
});

菜单定制

可以通过 decorateMenu 修改 Hyper 的菜单结构：

exports.decorateMenu = menu => {
  return menu.map(menuCategory => {
    if (menuCategory.label === 'Edit') {
      return [
        ...menuCategory,
        {type: 'separator'},
        {
          label: '自定义操作',
          click: () => {
            // 通过RPC与渲染进程通信
            focusedWindow?.rpc.emit('custom-action');
          }
        }
      ];
    }
    return menuCategory;
  });
};

光标追踪

获取终端光标信息：

exports.decorateTerm = (Term, {React}) => {
  return class extends React.Component {
    onCursorMove(cursor) {
      const {x, y, col, row} = cursor;
      // 使用光标信息
    }
    
    render() {
      return <Term {...this.props} onCursorMove={this.onCursorMove} />;
    }
  }
}

高级技巧

跨进程通信

主进程与渲染进程间的通信：

// 主进程发送
window.rpc.emit('event-name', data);

// 渲染进程监听
rpc.on('event-name', handler);

// 主进程监听
const {ipcMain} = require('electron');
ipcMain.on('event-name', handler);

Electron API 访问

虽然 Hyper 不直接暴露 Electron API，但插件可以直接引入：

const {dialog, Menu} = require('electron');

Hyper v2 重要变更

1. 渲染引擎：从 hterm 切换到 xterm.js
2. 渲染方式：现在使用 Canvas 而非 DOM 渲染
3. 样式定制：不再支持直接修改 DOM 样式，需通过 xterm.js 配置参数实现

如果现有插件依赖 hterm API，需要进行适配改造。如需新的 xterm.js API 支持，可以向 Hyper 团队提交需求。

最佳实践

1. 命名规范：命令命名采用 <context>:<action> 格式
2. 快捷键设计：考虑平台差异，提供合理的默认键位
3. 错误处理：妥善处理边界情况和错误状态
4. 性能优化：避免频繁的渲染更新和状态变更

通过本文介绍的技术和API，开发者可以创建功能强大的Hyper插件，从简单的UI调整到复杂的终端功能扩展都能实现。