如何编写第一个Hyper插件：HOC装饰器模式完整教程

如何编写第一个Hyper插件：HOC装饰器模式完整教程

【免费下载链接】hyperA terminal built on web technologies项目地址: https://gitcode.com/gh_mirrors/hy/hyper

Hyper 是一款基于 Web 技术（React + Electron）构建的现代化终端模拟器，而它最强大的扩展能力就来自Hyper 插件系统。本文将带你从零开始编写第一个 Hyper 插件，重点讲解插件开发中最核心的HOC 装饰器模式（Higher-Order Component，高阶组件）。学完后，你就能像官方生态插件一样，通过装饰器扩展 Hyper 的标签栏、终端面板等任何界面组件，轻松打造属于自己的个性化终端。

🧩 Hyper 插件架构：插件是如何被加载的

在动手写代码之前，先花两分钟理解插件的运行机制，这会让后面的 HOC 装饰器模式变得水到渠成。

Hyper 的插件加载分为两个进程：

• 主进程（Node 侧）：负责读取配置、安装插件、调用onApp、decorateConfig、decorateMenu等生命周期钩子，核心逻辑在 app/plugins.ts；
• 渲染进程（UI 侧）：负责加载 React 组件相关的装饰器（decorateTerm、decorateTab等），核心逻辑在 lib/utils/plugins.ts。

一个插件本质上就是一个普通的 npm 包，只要它至少导出一个官方扩展 API 方法就会被认为有效。所有可暴露的方法集中定义在 app/plugins/extensions.ts，包括组件装饰器、Redux 中间件、快捷键映射、菜单扩展等 40 多种能力。

💡 小提示：配置文件中plugins数组放 npm 包名插件，localPlugins数组放本地开发中的插件目录名，可在 app/config/config-default.json 中看到这两项的默认定义。

📦 一键初始化：创建你的第一个本地插件

我们先把开发环境搭好。Hyper 支持将本地插件放在插件目录的local子目录中，配合配置文件里的localPlugins字段即可加载。

第一步：创建插件目录结构

hyper-awesome-plugin/ ├── index.js # 插件入口，导出扩展方法 └── package.json # 插件名与版本，用于日志显示

第二步：编写最小可运行插件

package.json只需要名称和版本：

{ "name": "hyper-awesome-plugin", "version": "0.1.0", "main": "index.js" }

index.js先导出最简单的配置装饰器，用于验证插件已加载：

exports.decorateConfig = (config) => { console.log('我的第一个 Hyper 插件运行中！'); return { ...config, cursorColor: '#00FFFF' }; };

第三步：注册到配置文件

在hyper.json中把插件目录名加入localPlugins数组，重启 Hyper（或菜单 View → Reload 热加载）。终端里看到类似Plugin hyper-awesome-plugin (0.1.0) loaded.的日志，就说明插件成功加载了——这个加载日志正是由 app/plugins.ts 中的requirePlugins函数打印的。

✅ 恭喜！你已经完成了一个合法的 Hyper 插件。接下来进入正题。

🎯 核心原理：HOC 装饰器模式是怎么工作的

Hyper 的 UI 完全由 React 组件构成（标题栏、标签页、分屏、终端面板……），而它开放给插件的扩展方式就是装饰器：你提供一个函数，接收"原始组件"作为参数，返回一个"包装后的新组件"。

这正是 React 社区的经典模式HOC（高阶组件）——函数接收组件、返回增强组件。以标签栏组件为例，Hyper 内部先把它包上装饰层：

// lib/components/header.tsx 中的真实代码 const Tabs = decorate(Tabs_, 'Tabs');

decorate的实现见 lib/utils/plugins.ts：它会遍历所有已加载插件，寻找名为decorate+ 组件名 的方法（如decorateTabs），依次把组件"套娃"式地包起来。多个插件装饰同一组件时，会按加载顺序形成一条HOC 装饰链——后加载的插件拿到的第一个参数其实已经是前面插件装饰后的组件，这也是为什么装饰器写法必须兼容"入参不一定是原生组件"这一点。

理解了这个链条，就理解了 Hyper 插件 80% 的 UI 扩展技巧。

🛠️ 实战案例：用 HOC 给终端区域注入自定义内容

我们以装饰Terms组件（所有终端面板的容器）为例，写一个"在终端上方显示一行自定义内容"的插件。这个例子覆盖了 HOC 模式的全部关键点：

exports.decorateTerms = (Terms, { React }) => { return class extends React.PureComponent { constructor(props) { super(props); this.terms = null; } // 拿到真实的 Terms 实例引用，并转发给装饰链 onDecorated = (terms) => { this.terms = terms; if (this.props.onDecorated) { this.props.onDecorated(terms); // 关键：不要打断 HOC 链！ } }; render() { return ( <div> <div style={{ color: '#0F0', fontSize: 12 }}> Hello from my first Hyper plugin! </div> <Terms {...this.props} onDecorated={this.onDecorated} /> </div> ); } }; };

三个要点逐一拆解：

1. 透传 props：{...this.props}必须原样传给内层组件，否则会破坏其他插件的功能；
2. onDecorated链式转发：onDecorated是 Hyper 用来把"真实组件实例"层层传回的机制（实现见 lib/utils/plugins.ts）。如果你的装饰器截获了它却不转发，同一条链上其他想拿实例的插件就会拿不到引用，这是最常见的"插件互相打架"原因；
3. 必须返回带render的 React 组件：装饰器若返回了非法值，Hyper 会弹出 "Invalid return value ofdecorateTerms. Norendermethod found" 提示（见 lib/utils/plugins.ts），这是新手第一大坑。

修改后重启 Hyper 或执行 View → Reload，即可看到效果。如果想操作底层终端实例（比如读取选中文字），通过this.terms调用registerCommands、getActiveTerm等方法即可，相关用法示例在 PLUGINS.md 的 "Cursor" 一节有完整演示。

🐛 调试技巧：插件报错先看这三处

• 看日志：渲染进程里插件的console.log输出在 Electron 开发者工具（DevTools）Console；主进程钩子的日志则输出在启动 Hyper 的终端中（详见 PLUGINS.md "Workflow" 一节）；
• 看提示：插件方法名拼错、未导出任何扩展 API 时，会弹出 "does not expose any Hyper extension API methods" 通知（见 app/plugins.ts），此时对照 app/plugins/extensions.ts 核对方法名即可；
• 看组件层级：不确定要装饰哪个组件？打开 React DevTools 浏览组件树，找到目标组件名（如Tab、SplitPane），对应的装饰器就是decorate+ 这个名字。

🚀 总结：从零到插件开发的完整路线

回顾一下这条学习路径：理解插件在双进程中的加载流程 → 用localPlugins跑通最小插件 → 掌握 HOC 装饰器"接收组件、返回增强组件"的核心思想 → 用onDecorated正确接入装饰链 → 通过 DevTools 调试迭代。

这套 HOC 装饰器模式不仅适用于 Hyper，它本质上就是 React 生态的通用组件增强思想——学会它，你写其他 React 插件框架（如编辑器插件、Web 应用扩展）也会如鱼得水。现在，去localPlugins里加上你的插件名，动手写下第一行decorateTerms吧！🎉

【免费下载链接】hyperA terminal built on web technologies项目地址: https://gitcode.com/gh_mirrors/hy/hyper