检查器插件开发详解

检查器插件开发详解

检查器插件是 Eagle 4.0 Beta 17 之后新增的类型。它的定位很明确：用户在右侧检查器里选中了某个文件，你就在那里补一块信息。它不是弹窗，是嵌入。

什么时候值得做检查器插件

判断标准只有一条：这块信息是不是「选中即看」的性质？

需要用户选中就能立刻看到、不需要任何额外操作 → 检查器插件。比如：JPG 的拍摄参数和经纬度、音频的时长和采样率、PSD 的图层数、SVG 的画布尺寸、某款自有格式的元数据。

需要点按钮、填参数、跑一段计算 → 窗口插件。检查器插件的默认高度通常只有 100 像素左右，塞不下交互界面。

manifest 怎么写

检查器插件不写 main，写 preview，键名是你要接管的扩展名（多个用逗号隔开），值里嵌套 inspector：

{
    "id": "cc41e899-5fc3-445c-a113-2d9573d6edcc",
    "version": "1.0.0",
    "platform": "all",
    "arch": "all",
    "name": "Inspector Plugin",
    "logo": "/logo.png",
    "keywords": [],
    "devTools": true,
    "preview": {
        "jpg,png": {
            "inspector": {
                "path": "index.html",
                "height": 100,
                "multiSelect": false
            }
        }
    }
}

三个字段：

path：插件的 HTML 文件路径
height：默认高度，像素
multiSelect：多选时是否显示。官方建议非特殊情况一律 false——多选场景下语义往往不明确（显示最后一个？还是合并？）

height 需要仔细调。太小信息显示不全，太大会挤掉检查器里其他插件的区域。建议先用 100 跑通，再根据实际内容微调到 120、150 这种整数。

一个能跑的检查器插件

index.html 的内容和窗口插件几乎一样，区别在于必须适配小尺寸和主题：

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Inspector Plugin Example</title>
    <style>
        html {
            font-size: 11px;
            font-family: sans-serif;
            border-radius: 6px;
            overflow: hidden;
        }
        body {
            padding: 0;
            margin: 0;
            color: transparent;
        }

        /* 不同主题下的配色 */
        body[theme="LIGHT"],
        body[theme="LIGHTGRAY"] {
            color: black;
        }
        body[theme="GRAY"],
        body[theme="BLUE"],
        body[theme="PURPLE"],
        body[theme="DARK"] {
            color: white;
        }
    </style>
</head>
<body>
    Inspector Plugin Example
    <script>
        // 监听插件创建
        eagle.onPluginCreate(async (plugin) => {
            // 取得当前主题
            const theme = await eagle.app.theme;
            document.body.setAttribute('theme', theme);

            // 取得选中的项目
            const item = await eagle.item.getSelected();
            console.log(item);
            console.log(theme);
        });

        // 监听主题变化
        eagle.onThemeChanged((theme) => {
            document.body.setAttribute('theme', theme);
        });
    </script>
</body>
</html>

官方示例里 body 的初始 color 是 transparent，然后靠主题属性再赋真实颜色——这是个值得学的小技巧：它避免了「主题属性还没设上时闪一下黑字」的问题。

把它做成真正有用的东西

上面只是骨架。实战里，检查器插件最有价值的形态是「从文件本身解析出 Eagle 没存的信息」。以 SVG 为例，Eagle 只知道它的尺寸，但你可以解析出里面有多少个路径、多少种颜色：

eagle.onPluginCreate(async () => {
    const theme = await eagle.app.theme;
    document.body.setAttribute('theme', theme);

    const items = await eagle.item.getSelected();
    if (items.length === 0) return;

    const item = items[0];
    const fs = require('fs');

    let paths = 0;
    let colors = new Set();

    try {
        const xml = fs.readFileSync(item.filePath, 'utf8');
        // 统计 path 元素
        paths = (xml.match(/<path[\s>]/g) || []).length;
        // 统计 fill 属性里的颜色
        const fills = xml.match(/fill="([^"]+)"/g) || [];
        fills.forEach((f) => colors.add(f.slice(6, -1)));
    }
    catch (err) {
        eagle.log.error('解析 SVG 失败');
        eagle.log.error(err.stack || err);
        return;
    }

    document.body.textContent = `${item.name} · ${paths} 条路径 · ${colors.size} 种填充色`;
});

eagle.onThemeChanged((theme) => {
    document.body.setAttribute('theme', theme);
});

用 document.body.textContent 一次性替换，比拼 innerHTML 更安全——文件名里可能带尖括号之类的字符。

开发流程

先用最小骨架跑通：只写 preview.inspector 配置和一句静态文字。
添加一个目标格式的文件，在 Eagle 里选中它，确认面板出现了。
在插件区域点右键选「开发者工具」，打开 DevTools 调试。
换成 eagle.item.getSelected() 拿到真实数据，验证字段是否符合预期。
解析文件补充信息，注意所有文件读取都包 try/catch——文件可能已损坏或无权限。
调 height 到合适值，确保在窄侧栏下不溢出。
加入主题适配，并在六套主题下各看一遍。
移除调试代码，把 devTools 改为 false。

常见坑

忘了 overflow: hidden 和 border-radius。 检查器区域是圆角的，内容不做圆角和溢出处理，文字会顶到边框上，视觉上像是渲染坏了。

multiSelect 设成 true 然后按第一个元素渲染。 多选时用户预期是看到聚合信息（几个文件、共多少路径），只显示第一个会让人以为你的插件读不全数据。

延伸注意： * 在检查器里加载大文件到内存。检查器会在每次切换选中时重新执行。解析前先看 item.size，超阈值就直接提示未解析，不要硬读。

整理人：WorkBuddy

2.3 检查器插件开发详解