# 更新日誌

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

## 2026年3月24日

### 📄 Item API 增強

**新增功能：標註 CRUD API (Eagle 4.0 build22+)**

{% hint style="danger" %}
**版本需求**：此功能需要 Eagle 4.0 build22 或更高版本。
{% endhint %}

* 新增 [`item.comments`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#comments-object) 唯讀屬性，存取項目的標註資料
* 新增 [`item.addComment(commentData)`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#add-comment) 方法，新增圖片框選標註或影片時間軸註解
* 新增 [`item.updateComment(commentId, updateData)`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#update-comment) 方法，更新現有標註
* 新增 [`item.removeComment(commentId)`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#remove-comment) 方法，移除標註

```javascript
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+)**

{% hint style="danger" %}
**版本需求**：此功能需要 Eagle 4.0 build22 或更高版本。
{% endhint %}

* 新增 [`eagle.smartFolder`](https://developer.eagle.cool/plugin-api/zh-tw/api/smart-folder) 模組，完整支援智慧型資料夾管理
* 新增 `create()`、`get()`、`getAll()`、`getById()`、`getByIds()`、`remove()` 方法
* 新增 `getRules()` 方法，取得可用的篩選規則 schema
* 新增 `rule()` 流暢建構器和 `Condition.create()` helper
* SmartFolder 實例支援 `save()` 和 `getItems()` 方法

```javascript
// 使用流暢建構器
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+)**

{% hint style="danger" %}
**版本需求**：此功能需要 Eagle 4.0 build22 或更高版本。
{% endhint %}

* 新增 `followCursor` manifest 設定，開啟後視窗會自動定位在游標附近
* 適合需要快速互動的工具型插件，讓用戶能以最短距離觸發交互
* 啟用後視窗不會記憶位置，每次開啟都會跟隨游標

```json
{
    "main": {
        "followCursor": true
    }
}
```

## 2026年1月22日

### 💻 App API 增強

**新增功能：顯示主視窗 (Eagle 4.0 build18+)**

{% hint style="danger" %}
**版本需求**：此功能需要 Eagle 4.0 build18 或更高版本。
{% endhint %}

* 新增 [`eagle.app.show()`](https://developer.eagle.cool/plugin-api/zh-tw/api/app#show) 方法，讓插件可以將 Eagle 主應用程序視窗喚起並顯示在畫面最上方

```javascript
// 將 Eagle 主視窗顯示在最上方
await eagle.app.show();
```

### 📄 Item API 增強

**新增功能：修改導入時間 (Eagle 4.0 build18+)**

{% hint style="danger" %}
**版本需求**：此功能需要 Eagle 4.0 build18 或更高版本。
{% endhint %}

* [`item.importedAt`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#importedat-interger) 屬性現在支援修改，讓插件可以自訂檔案的導入時間
* 適用於批次匯入歷史檔案、資料遷移等需要保留原始時間戳記的場景

```javascript
// 修改導入時間
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`](https://developer.eagle.cool/plugin-api/zh-tw/extra-module/ai-search) 模組，提供 AI 語意搜尋功能
* **狀態查詢方法**：
  * `isInstalled()` - 檢查 AI Search 插件是否已安裝
  * `isReady()` - 檢查服務是否就緒
  * `isStarting()` - 檢查服務是否正在啟動中
  * `isSyncing()` - 檢查是否正在同步資料
* **服務控制方法**：
  * `open()` - 開啟 AI Search 插件
  * `checkServiceHealth()` - 檢查服務健康狀態
  * `getSyncStatus()` - 取得詳細的同步狀態
* **搜尋方法**：
  * `searchByText(query, options)` - 文字語意搜尋
  * `searchByBase64(base64, options)` - Base64 圖片搜尋
  * `searchByItemId(itemId, options)` - 以項目 ID 搜尋相似圖片

```javascript
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()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag-group#addtags) - 增量添加或移動標籤到群組，不需要傳入完整的標籤陣列
* [`tagGroup.removeTags()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag-group#removetags) - 從群組移除指定標籤
* [`eagle.tag.merge()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag#merge) - 合併標籤，將來源標籤重新命名為目標標籤

```javascript
// 添加標籤到群組
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`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag-group) 新增 `description` 屬性，可為標籤群組添加描述文字
* 支援在 `create()` 和 `save()` 方法中設定描述

```javascript
// 建立帶有描述的標籤群組
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()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag#starred) 方法，取得使用者收藏的常用標籤列表

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

**文件修正**

* 修正 API 方法名稱錯誤：`getRecents()` → [`getRecentTags()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag#dwsxw)

## 2025年8月21日

### 💻 App API 增強

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

* 新增 [`app.userDataPath`](https://developer.eagle.cool/plugin-api/zh-tw/api/app#ud9km) 屬性，返回當前使用者資料目錄的路徑
* 提供快速存取 Eagle 使用者資料儲存位置的途徑

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

## 2025年8月19日

### 📁 Folder API 增強

**新增功能：資料夾 parent 屬性可修改 (Eagle 4.0 build12+)**

* 新增 [`folder.parent`](https://developer.eagle.cool/plugin-api/zh-tw/api/folder#woenk) 屬性修改支援，允許動態調整資料夾層級結構
* 支援將資料夾移動到不同父目錄或根目錄

```javascript
// 移動到其他父資料夾
folder.parent = 'parent_folder_id';
await folder.save();

// 移動到根目錄  
folder.parent = null;
await folder.save();
```

**新增功能：資料夾 iconColor 屬性可修改 (Eagle 4.0 build12+)**

* 將 [`folder.iconColor`](https://developer.eagle.cool/plugin-api/zh-tw/api/folder#woenk) 屬性從唯讀變更為可修改
* 新增 [`eagle.folder.IconColor`](https://developer.eagle.cool/plugin-api/zh-tw/api/folder#static-properties) 靜態常數物件，提供預定義顏色選項
* 支援的顏色：Red, Orange, Yellow, Green, Aqua, Blue, Purple, Pink

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

## 2025年8月13日

### 🏷️ Tag API 功能擴展

**新增功能：標籤過濾和 Tag 類別增強**

* [`eagle.tag.get()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag#x9nu2) 方法新增 `name` 參數，支援按名稱模糊搜尋標籤
* Tag 實例新增 [`save()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag#instance-methods) 方法，支援修改標籤名稱
* 新增 Tag 實例屬性：[`name`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag#instance-properties)（可修改）、`count`、`color`、`groups`、`pinyin`

```javascript
// 過濾標籤
const filteredTags = await eagle.tag.get({ name: "design" });

// 修改標籤名稱  
tag.name = 'new-name';
await tag.save();
```

⚠️ **注意：修改標籤名稱會自動更新所有使用該標籤的檔案**

## 2025年8月5日

### 📄 Item API 性能和選擇功能大幅增強

**新增功能：性能優化**

* [`eagle.item.get()`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#bdcw2) 新增 `fields` 參數，支援選擇性欄位返回，大幅提升查詢性能
* 新增 [`eagle.item.getIdsWithModifiedAt()`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#getidswithmodifiedat) 方法，專為增量同步優化
* 新增 [`modifiedAt`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#woenk) 屬性，記錄檔案最後修改時間

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

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

**新增功能：計數和選擇方法**

* 新增 [`eagle.item.count(options)`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#count) - 條件計數
* 新增 [`eagle.item.countAll()`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#countall) - 總檔案數
* 新增 [`eagle.item.countSelected()`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#countselected) - 選中檔案數
* 新增 [`eagle.item.select(itemIds)`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#select) - 程式化選擇檔案

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

**增強功能：open() 方法**

* [`eagle.item.open()`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#yxkul) 新增 `window` 選項，支援在新視窗開啟檔案

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

## 2025年7月31日

### 🪟 Window API 擴展

**新增功能：視窗幾何控制**

* 新增 [`eagle.window.getSize()`](https://developer.eagle.cool/plugin-api/zh-tw/api/window#mq0dz) - 取得視窗大小
* 新增 [`eagle.window.setBounds(bounds)`](https://developer.eagle.cool/plugin-api/zh-tw/api/window#setbounds-bounds) - 設定視窗邊界（位置+大小）
* 新增 [`eagle.window.getBounds()`](https://developer.eagle.cool/plugin-api/zh-tw/api/window#getbounds) - 取得視窗邊界資訊

```javascript
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)`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag-group#x9nu2) - 創建新標籤群組
* 新增 [`tagGroup.save()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag-group#x9nu2) - 保存修改
* 新增 [`tagGroup.remove()`](https://developer.eagle.cool/plugin-api/zh-tw/api/tag-group#x9nu2) - 刪除標籤群組

```javascript
// 創建標籤群組
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()`](https://developer.eagle.cool/plugin-api/zh-tw/api/item#movetotrash) 實例方法，將檔案移至系統垃圾桶

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

## 2024年7月25日

### 🪟 Window API 增強

**新增功能：HTTP Referer 設定**

* 新增 [`eagle.window.setReferer(url)`](https://developer.eagle.cool/plugin-api/zh-tw/api/window#4a6f) 方法，為後續網路請求設定 referer header

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

## 2024年5月10日

### 🖱️ Context Menu API

**新增功能：自定義右鍵選單**

* 新增 [`eagle.contextMenu.open()`](https://developer.eagle.cool/plugin-api/zh-tw/api/context-menu#tkp0d) 方法，支援自定義右鍵選單
* 支援多層次子選單、自定義點擊事件、系統原生樣式

```javascript
eagle.contextMenu.open([
    {
        id: "edit",
        label: "編輯",
        submenu: [...],
        click: () => { ... }
    }
]);
```

### 🪟 Window API 截圖功能

**新增功能：頁面截圖**

* 新增 [`eagle.window.capturePage(rect)`](https://developer.eagle.cool/plugin-api/zh-tw/api/window#yvfx9) 方法，支援全頁或指定區域截圖
* 返回 NativeImage 物件，可轉換為 base64 或 PNG buffer

```javascript
// 全頁截圖
const image = await eagle.window.capturePage();

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

## 2024年4月17日

### 🔍 預覽插件功能增強

**新增功能：縮放控制參數**

* 預覽插件配置新增 [`allowZoom`](https://developer.eagle.cool/plugin-api/zh-tw/get-started/plugin-types/preview) 參數，控制是否允許使用者縮放預覽內容

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