Changelog

Eagle Plugin API changelog, documenting all important feature changes since the first Plugin API version.

Important Notice: Eagle 4.0 Build12 is expected to be released soon but is not yet officially available. New API features marked as requiring Eagle 4.0 Build12+ on this page can only be used after the official version is released.

August 21, 2025

💻 App API Enhancement

New Feature: app.userDataPath Property (Eagle 4.0 build12+)

• Added app.userDataPath property, returns the path to the current user data directory

• Provides quick access to Eagle's user data storage location

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

August 19, 2025

📁 Folder API Enhancements

New Feature: Folder parent Property Modifiable (Eagle 4.0 build12+)

• Added folder.parent property modification support, allowing dynamic adjustment of folder hierarchy

• Support for moving folders to different parent directories or root directory

// Move to another parent folder
folder.parent = 'parent_folder_id';
await folder.save();

// Move to root directory  
folder.parent = null;
await folder.save();

New Feature: Folder iconColor Property Modifiable (Eagle 4.0 build12+)

• Changed folder.iconColor property from read-only to modifiable

• Added eagle.folder.IconColor static constant object, providing predefined color options

• Supported colors: Red, Orange, Yellow, Green, Aqua, Blue, Purple, Pink

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

August 13, 2025

🏷️ Tag API Feature Expansion

New Feature: Tag Filtering and Tag Class Enhancement

• eagle.tag.get() method added name parameter, supporting fuzzy search by tag name

• Tag instance added save() method, supporting tag name modification

• Added Tag instance properties: name (modifiable), count, color, groups, pinyin

// Filter tags
const filteredTags = await eagle.tag.get({ name: "design" });

// Modify tag name  
tag.name = 'new-name';
await tag.save();

⚠️ Note: Modifying tag names will automatically update all files using that tag

August 5, 2025

📄 Item API Performance and Selection Enhancements

New Feature: Performance Optimization

• eagle.item.get() added fields parameter, supporting selective field return for significant query performance improvement

• Added eagle.item.getIdsWithModifiedAt() method, optimized for incremental synchronization

• Added modifiedAt property, recording file last modification time

// Return only needed fields
let items = await eagle.item.get({
    tags: ["Design"],
    fields: ["id", "name", "tags", "modifiedAt"]
});

// Efficient incremental sync
let fileInfo = await eagle.item.getIdsWithModifiedAt();

New Feature: Counting and Selection Methods

• Added eagle.item.count(options) - conditional counting

• Added eagle.item.countAll() - total file count

• Added eagle.item.countSelected() - selected file count

• Added eagle.item.select(itemIds) - programmatic file selection

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

Enhanced Feature: open() Method

• eagle.item.open() added window option, supporting opening files in new window

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

July 31, 2025

🪟 Window API Expansion

New Feature: Window Geometry Control

• Added eagle.window.getSize() - get window size

• Added eagle.window.setBounds(bounds) - set window bounds (position + size)

• Added eagle.window.getBounds() - get window bounds information

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

November 28, 2024

🏷️ TagGroup CRUD Operations

New Feature: Complete Tag Group Management

• Added eagle.tagGroup.create(options) - create new tag group

• Added tagGroup.save() - save modifications

• Added tagGroup.remove() - delete tag group

// Create tag group
await eagle.tagGroup.create({
    name: "new group",
    color: "red", 
    tags: ["tag1", "tag2"]
});

// Modify and save
tagGroup.name = "new name";
await tagGroup.save();

// Delete group
await tagGroup.remove();

🗑️ Item Deletion Feature

New Feature: File Trash Operations

• Added item.moveToTrash() instance method, moving files to system trash

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

July 25, 2024

🪟 Window API Enhancement

New Feature: HTTP Referer Setting

• Added eagle.window.setReferer(url) method, setting referer header for subsequent network requests

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

May 10, 2024

🖱️ Context Menu API

New Feature: Custom Context Menu

• Added eagle.contextMenu.open() method, supporting custom context menus

• Support for multi-level submenus, custom click events, system native styling

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

🪟 Window API Screenshot Feature

New Feature: Page Screenshot

• Added eagle.window.capturePage(rect) method, supporting full page or specified area screenshots

• Returns NativeImage object, convertible to base64 or PNG buffer

// Full page screenshot
const image = await eagle.window.capturePage();

// Specified area screenshot
const image2 = await eagle.window.capturePage({ 
    x: 0, y: 0, width: 100, height: 50 
});

April 17, 2024

🔍 Preview Plugin Feature Enhancement

New Feature: Zoom Control Parameter

• Preview plugin configuration added allowZoom parameter, controlling whether users can zoom preview content

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