如何为INAV Configurator新增一个配置页签：开发者完整指南（附代码示例）

INAV Configurator 是开源飞控软件 INAV 的桌面配置工具，基于 Electron 开发。如果你想为它新增一个配置页签（Tab），本文会带你走通从页面文件、导航入口、动态加载注册到国际化文案的完整流程，并给出关键代码示例。

一、先看懂 INAV Configurator 的页签架构

INAV Configurator 的每个功能页签都由三个部分协作完成，理解这个架构是动手的前提：

其中 js/gui.js 维护着defaultAllowedTabsWhenConnected（连接飞控后可用页签）和defaultAllowedTabsWhenDisconnected（未连接时可用页签）两个白名单，TABS对象（js/gui.js）则是所有页签模块的注册中心。

页签名称由导航条目的 class 去掉tab_前缀得到（见 js/configurator_main.js 中的tabClass.substring(4)），所以class 名必须和 JS 文件名、switch 分支三者严格一致。

二、本地运行项目：开发环境一键搭建

先克隆仓库并启动开发环境，改动后刷新窗口即可看到效果：

git clone https://gitcode.com/gh_mirrors/ina/inav-configurator cd inav-configurator yarn install npm start

项目使用 Vite + Electron Forge 构建（见 package.json），启动后即可看到如下启动画面：

三、新增页签五步法：以mytab为例

第 1 步：创建页面文件tabs/mytab.html和tabs/mytab.js

以简单页签 tabs/search.html 为参考，HTML 负责界面骨架：

<div class="tab-mytab"> <div class="content_wrapper"> <div class="options-section gui_box grey"> <div class="gui_box_titlebar"> <div class="spacer_box_title">'use strict'; import { GUI, TABS } from './../js/gui'; import i18n from './../js/localization'; TABS.mytab = {}; TABS.mytab.initialize = function (callback) { if (GUI.active_tab !== 'mytab') { GUI.active_tab = 'mytab'; } import('./mytab.html?raw').then(({ default: html }) => { GUI.load(html, function () { i18n.localize(); // 翻译>case 'mytab': import('./../tabs/mytab').then(() => TABS.mytab.initialize(content_ready)); break;

这里用动态import()实现懒加载——只有用户真正点击该页签时，代码才会被下载执行，保证主窗口启动速度。

第 3 步：在index.html添加导航条目

打开 index.html，找到#tabs区域。两个<ul>分别对应不同状态：

• ul.mode-disconnected：未连接飞控时可见（如 landing、firmware_flasher）
• ul.mode-connected：连接飞控后可见（如 setup、pid_tuning）

按需求位置插入（以连接后可见为例）：

<li class="tab_mytab"> <a href="#">this.defaultAllowedTabsWhenConnected = [ 'failsafe', // ... 其他页签 'search', 'mytab' // 新增 ];

第 5 步：补充国际化文案与样式

国际化：在 locale/en/messages.json 中按现有格式添加词条，data-i18n属性会据此取值翻译：

"tabMyTab": { "message": "My Tab" }, "mytabHello": { "message": "Hello from my new tab!" }

如需支持中文等其他语言，可在 locale/ 下的zh_CN、ru等目录同步添加。

样式：新建src/css/tabs/mytab.css，然后在 src/css/styles.css 的@import列表中加一行：

@import 'tabs/mytab.css';

四、避坑指南：4 个高频错误

1. 命名不一致：tab_mytabclass、case 'mytab'、文件名mytab.js、白名单'mytab'四处必须完全相同，否则点击无反应或控制台出现Tab not found: mytab。
2. 忘记GUI.content_ready(callback)：不调用该回调，加载动画不会消失，页签会一直显示空白转圈状态。
3. cleanup中漏清资源：页签切换时框架会调用当前页签的cleanup（js/gui.js），轮询定时器（interval）、MSP 回调必须在这里释放，否则后台资源泄漏。
4. 图标缺失：class="tabicon ic_xxx"引用的是内置图标集，新页签建议先复用现有图标（如ic_config），避免图标不显示。

五、总结：一张图回顾页签注册链路

用户点击侧边栏 ↓ index.html <li class="tab_mytab"> ↓ configurator_main.js switch (tab) → 白名单校验（gui.js） ↓ import('./mytab.js') 懒加载 ↓ TABS.mytab.initialize → GUI.load(html) → i18n.localize() → GUI.content_ready

掌握以上 5 个步骤，你就可以在 INAV Configurator 中扩展任何自定义配置页签了。建议动手时先通读 tabs/search.js 和 tabs/search.html 这对最精简的官方示例，它们是理解整个页签框架的最佳起点。