更新日誌

Eagle Plugin API 更新日誌，記錄自第一個 Plugin API 版本後的所有重要功能變更。

已更新：Eagle 4.0 Build12 已正式釋出。本文中標註「Eagle 4.0 Build12+」的功能現已可用。 若您仍使用較舊版本，請先升級至 4.0 build12 或以上版本。

2026年1月9日

🔍 AI Search 語意搜尋 API

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

此功能尚未發佈：此功能需要安裝未來的「AI Search」插件才能使用。詳細發佈時間請關注 Eagle 官網。

• 新增 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
}