更新日志

Eagle Plugin API 更新日志，记录自第一个 Plugin API 版本后的所有重要功能变更。

已更新：Eagle 4.0 Build12 已正式发布。本文中标注「Eagle 4.0 Build12+」的功能现已可用。 若您仍使用旧版本，请先升级至 4.0 build12 或更高版本。

2026年3月24日

📄 Item API 增强

新增功能：标注 CRUD API (Eagle 4.0 build22+)

版本需求：此功能需要 Eagle 4.0 build22 或更高版本。

• 新增 item.comments 只读属性，访问条目的标注数据

• 新增 item.addComment(commentData) 方法，添加图片框选标注或视频时间轴注解

• 新增 item.updateComment(commentId, updateData) 方法，更新现有标注

• 新增 item.removeComment(commentId) 方法，移除标注

let item = await eagle.item.getById('item_id');

// 读取标注
console.log(item.comments);

// 添加图片框选标注
await item.addComment({ x: 350, y: 480, width: 380, height: 400, annotation: "脸部区域" });

// 添加视频时间轴注解
await item.addComment({ duration: 65.5, annotation: "重要场景" });

// 更新标注
await item.updateComment('comment_id', { annotation: "更新后的文字" });

// 移除标注
await item.removeComment('comment_id');

📁 Smart Folder API

新增功能：智能文件夹 CRUD API (Eagle 4.0 build22+)

版本需求：此功能需要 Eagle 4.0 build22 或更高版本。

• 新增 eagle.smartFolder 模块，完整支持智能文件夹管理

• 新增 create()、get()、getAll()、getById()、getByIds()、remove() 方法

• 新增 getRules() 方法，获取可用的筛选规则 schema

• 新增 rule() 流畅构建器和 Condition.create() helper

• SmartFolder 实例支持 save() 和 getItems() 方法

// 使用流畅构建器
const sf = await eagle.smartFolder.create({
    name: '大尺寸图片',
    conditions: [
        eagle.smartFolder.Condition.create('AND', [
            eagle.smartFolder.rule('width')['>']([1920]),
            eagle.smartFolder.rule('type').equal('png'),
        ])
    ]
});

// 查询规则 schema
const rules = await eagle.smartFolder.getRules();

// 获取符合条件的条目
const items = await sf.getItems();

🔧 Manifest 配置增强

新增功能：followCursor 窗口定位 (Eagle 4.0 build22+)

版本需求：此功能需要 Eagle 4.0 build22 或更高版本。

• 新增 followCursor manifest 设置，开启后窗口会自动定位在光标附近

• 适合需要快速交互的工具型插件，让用户能以最短距离触发交互

• 启用后窗口不会记忆位置，每次打开都会跟随光标

{
    "main": {
        "followCursor": true
    }
}

2026年1月22日

💻 App API 增强

新增功能：显示主窗口 (Eagle 4.0 build18+)

版本需求：此功能需要 Eagle 4.0 build18 或更高版本。

• 新增 eagle.app.show() 方法，让插件可以将 Eagle 主应用程序窗口唤起并显示在画面最上方

// 将 Eagle 主窗口显示在最上方
await eagle.app.show();

📄 Item API 增强

新增功能：修改导入时间 (Eagle 4.0 build18+)

版本需求：此功能需要 Eagle 4.0 build18 或更高版本。

• item.importedAt 属性现在支持修改，让插件可以自定义文件的导入时间

• 适用于批量导入历史文件、数据迁移等需要保留原始时间戳的场景

// 修改导入时间
item.importedAt = new Date('2024-01-01').getTime();
await item.save();

2026年1月9日

🔍 AI Search 语意搜索 API

新增功能：AI 语意搜索整合 (Eagle 4.0 build18+)

• 新增 eagle.extraModule.aiSearch 模块，提供 AI 语意搜索功能

• 状态查询方法：

  • isInstalled() - 检查 AI Search 插件是否已安装

  • isReady() - 检查服务是否就绪

  • isStarting() - 检查服务是否正在启动中

  • isSyncing() - 检查是否正在同步数据

• 服务控制方法：

  • open() - 打开 AI Search 插件

  • checkServiceHealth() - 检查服务健康状态

  • getSyncStatus() - 获取详细的同步状态

• 搜索方法：

  • searchByText(query, options) - 文字语意搜索

  • searchByBase64(base64, options) - Base64 图片搜索

  • searchByItemId(itemId, options) - 以项目 ID 搜索相似图片

const aiSearch = eagle.extraModule.aiSearch;

// 检查服务状态
if (await aiSearch.isReady()) {
    // 文字语意搜索
    const result = await aiSearch.searchByText('一只橘色的猫咪', { limit: 10 });

    // 结果包含完整的 Item 对象
    result.results.forEach(r => {
        console.log(`${r.item.name} - 相似度: ${(r.score * 100).toFixed(1)}%`);
    });
}

2026年1月8日

🏷️ TagGroup/Tag API 增量操作方法

新增功能：标签群组增量操作 (Eagle 4.0 build18+)

• tagGroup.addTags() - 增量添加或移动标签到群组，不需要传入完整的标签数组

• tagGroup.removeTags() - 从群组移除指定标签

• eagle.tag.merge() - 合并标签，将来源标签重新命名为目标标签

// 添加标签到群组
await tagGroup.addTags({ tags: ['UI', 'UX'] });

// 移动标签（从原群组移除）
await tagGroup.addTags({ tags: ['Branding'], removeFromSource: true });

// 从群组移除标签
await tagGroup.removeTags({ tags: ['Outdated'] });

// 合并标签
const result = await eagle.tag.merge({ source: 'UI Design', target: 'UI' });

🏷️ TagGroup API 增强

新增功能：标签群组描述属性 (Eagle 4.0 build18+)

• tagGroup 新增 description 属性，可为标签群组添加描述文字

• 支持在 create() 和 save() 方法中设置描述

// 创建带有描述的标签群组
await eagle.tagGroup.create({
    name: "new group",
    description: "群组描述"
});

// 修改标签群组描述
tagGroup.description = "新的描述";
await tagGroup.save();

2026年1月6日

🏷️ Tag API 增强

新增功能：获取常用标签 (Eagle 4.0 build18+)

• 新增 eagle.tag.getStarredTags() 方法，获取用户收藏的常用标签列表

const starred = await eagle.tag.getStarredTags();

文档修正

• 修正 API 方法名称错误：getRecents() → getRecentTags()

2025年8月21日

💻 App API 增强

新增功能：app.userDataPath 属性 (Eagle 4.0 build12+)

• 新增 app.userDataPath 属性，返回当前用户数据目录的路径

• 提供快速访问 Eagle 用户数据存储位置的途径

console.log(eagle.app.userDataPath);
// "C:\Users\User\AppData\Roaming\Eagle"

2025年8月19日

📁 Folder API 增强

新增功能：文件夹 parent 属性可修改 (Eagle 4.0 build12+)

• 新增 folder.parent 属性修改支持，允许动态调整文件夹层级结构

• 支持将文件夹移动到不同父目录或根目录

// 移动到其他父文件夹
folder.parent = 'parent_folder_id';
await folder.save();

// 移动到根目录  
folder.parent = null;
await folder.save();

新增功能：文件夹 iconColor 属性可修改 (Eagle 4.0 build12+)

• 将 folder.iconColor 属性从只读变更为可修改

• 新增 eagle.folder.IconColor 静态常量对象，提供预定义颜色选项

• 支持的颜色：Red, Orange, Yellow, Green, Aqua, Blue, Purple, Pink

folder.iconColor = eagle.folder.IconColor.Blue;
await folder.save();

2025年8月13日

🏷️ Tag API 功能扩展

新增功能：标签过滤和 Tag 类增强

• eagle.tag.get() 方法新增 name 参数，支持按名称模糊搜索标签

• Tag 实例新增 save() 方法，支持修改标签名称

• 新增 Tag 实例属性：name（可修改）、count、color、groups、pinyin

// 过滤标签
const filteredTags = await eagle.tag.get({ name: "design" });

// 修改标签名称  
tag.name = 'new-name';
await tag.save();

⚠️ 注意：修改标签名称会自动更新所有使用该标签的文件

2025年8月5日

📄 Item API 性能和选择功能大幅增强

新增功能：性能优化

• eagle.item.get() 新增 fields 参数，支持选择性字段返回，大幅提升查询性能

• 新增 eagle.item.getIdsWithModifiedAt() 方法，专为增量同步优化

• 新增 modifiedAt 属性，记录文件最后修改时间

// 只返回需要的字段
let items = await eagle.item.get({
    tags: ["Design"],
    fields: ["id", "name", "tags", "modifiedAt"]
});

// 高效增量同步
let fileInfo = await eagle.item.getIdsWithModifiedAt();

新增功能：计数和选择方法

• 新增 eagle.item.count(options) - 条件计数

• 新增 eagle.item.countAll() - 总文件数

• 新增 eagle.item.countSelected() - 选中文件数

• 新增 eagle.item.select(itemIds) - 程序化选择文件

let count = await eagle.item.count({ isSelected: true });
await eagle.item.select(['ITEM_ID_1', 'ITEM_ID_2']);

增强功能：open() 方法

• eagle.item.open() 新增 window 选项，支持在新窗口打开文件

await eagle.item.open('item_id', { window: true });

2025年7月31日

🪟 Window API 扩展

新增功能：窗口几何控制

• 新增 eagle.window.getSize() - 获取窗口大小

• 新增 eagle.window.setBounds(bounds) - 设置窗口边界（位置+大小）

• 新增 eagle.window.getBounds() - 获取窗口边界信息

await eagle.window.getSize();
await eagle.window.setBounds({ x: 440, y: 225, width: 800, height: 600 });
await eagle.window.getBounds();

2024年11月28日

🏷️ TagGroup CRUD 操作

新增功能：完整的标签分组管理

• 新增 eagle.tagGroup.create(options) - 创建新标签分组

• 新增 tagGroup.save() - 保存修改

• 新增 tagGroup.remove() - 删除标签分组

// 创建标签分组
await eagle.tagGroup.create({
    name: "new group",
    color: "red", 
    tags: ["tag1", "tag2"]
});

// 修改并保存
tagGroup.name = "new name";
await tagGroup.save();

// 删除分组
await tagGroup.remove();

🗑️ Item 删除功能

新增功能：文件回收站操作

• 新增 item.moveToTrash() 实例方法，将文件移至系统回收站

let item = await eagle.item.getById('item_id');
await item.moveToTrash();

2024年7月25日

🪟 Window API 增强

新增功能：HTTP Referer 设置

• 新增 eagle.window.setReferer(url) 方法，为后续网络请求设置 referer header

eagle.window.setReferer("https://example.com");

2024年5月10日

🖱️ Context Menu API

新增功能：自定义右键菜单

• 新增 eagle.contextMenu.open() 方法，支持自定义右键菜单

• 支持多层级子菜单、自定义点击事件、系统原生样式

eagle.contextMenu.open([
    {
        id: "edit",
        label: "编辑",
        submenu: [...],
        click: () => { ... }
    }
]);

🪟 Window API 截图功能

新增功能：页面截图

• 新增 eagle.window.capturePage(rect) 方法，支持全屏或指定区域截图

• 返回 NativeImage 对象，可转换为 base64 或 PNG buffer

// 全屏截图
const image = await eagle.window.capturePage();

// 指定区域截图
const image2 = await eagle.window.capturePage({ 
    x: 0, y: 0, width: 100, height: 50 
});

2024年4月17日

🔍 预览插件功能增强

新增功能：缩放控制参数

• 预览插件配置新增 allowZoom 参数，控制是否允许用户缩放预览内容

"thumbnail": {
    "path": "thumbnail/icns.js",
    "size": 400,
    "allowZoom": false
}