folder

The eagle.folder API allows you to easily create new folders or access existing ones in the current application.

// Get the currently selected folder in the Eagle application
let folder = (await eagle.folder.getSelected())[0];

// Modify properties
folder.name = 'New Folder Name';
folder.description = 'New description...';

// Save changes
await folder.save();

🦄 Best Practice: To ensure data safety, please use the save() method provided by the API for data access and modification. Avoid directly modifying the metadata.json or any files under the Eagle resource library.

Methods

create(options)

Create a folder.

• options Object

  • name string - Folder name

  • description string (optional) - Folder description

  • parent string (optional) - Parent folder ID; with this parameter, it is equivalent to createSubfolder(parentId, options)

• Returns Promise<folder: Folder> - Successfully created folder

let newFolder = await eagle.folder.create({
    name: 'New Folder',
    description: 'Folder\'s description.',
});

---

createSubfolder(parentId, options)

Create a subfolder.

• parentId string - Parent folder ID

• options Object

  • name string - Folder name

  • description string (optional) - Folder description

• Returns Promise<folder: Folder> - Successfully created folder

let parentFolder = await eagle.folder.getById('folder_id');
let subFolder = await eagle.folder.createSubfolder(parentFolder.id, {
    name: 'Subfolder',
    description: 'Subfolder description.',
});

---

get(options)

Get folders with specified conditions.

• options Object - Query conditions

  • id string (optional) - Folder id

  • ids string[] (optional) - Array of folder ids

  • isSelected boolean (optional) - Currently selected folders

  • isRecent boolean (optional) - Recently accessed folders

• Returns Promise<folders: Folder[]> - Query result folders

// Get the folder corresponding to the specified id
let folders = await eagle.folder.get({
    ids: ['folder_id1', 'folder_id2']
});

// Get currently selected folders in the application
let folders = await eagle.folder.get({
    isSelected: true
});

---

getAll()

Get all folders.

• Returns Promise<folders: Folder[]> - Query result folders

let folders = await eagle.folder.getAll();

---

getById(folderId)

Get the folder corresponding to folderId.

• folderId string - Folder id

• Returns Promise<folder: Folder> - Query result folder

let folder = await eagle.folder.getById('folder_id');

---

getByIds(folderIds)

Get an array of folders corresponding to folderIds.

• folderIds string[] - Array of folder ids

• Returns Promise<folders: Folder[]> - Query result folders

let folders = await eagle.folder.getByIds(['folder_id1', 'folder_id2']);

---

getSelected()

Get the currently selected folders in the application.

• Returns Promise<folders: Folder[]> - folders

let folders = await eagle.folder.getSelected();

---

getRecents()

Get the recently used folders.

• Returns Promise<folders: Folder[]> - folders

let folders = await eagle.folder.getRecents();

---

open(folderId)

Eagle will open the folder corresponding to folderId.

• Returns Promise<void>

await eagle.folder.open('folder_id');

// Equivalent to
let folder = await eagle.folder.getById('folder_id');
await folder.open();

Tip: You can also directly call the folder instance's open() method to open the folder.

---

Class: Folder

An Object type returned by the Folder API get, provides modification and save functions.

let folder = await eagle.folder.getById('folder_id');

console.log(folder.id);
console.log(folder.name);

folder.name = 'new name';
console.log(folder.name);

await folder.save();

🦄 Best Practice: To ensure data security, please use the save() method provided by the Folder instance for data access and modification, and avoid directly modifying the metadata.json or any files under the Eagle repository.

---

Instance Methods

save()

Save all modifications.

• Returns Promise<void>

let folder = await eagle.folder.getById('folder_id');
folder.name = 'New Folder Name';

// Save modifications
await folder.save();

---

open()

Eagle will open this folder.

• Returns Promise<void>

let folder = await eagle.folder.getById('folder_id');
await folder.open();

// Equivalent to
await eagle.folder.open('folder_id');

Tip: You can also directly call eagle.folder.open(folderId) method to open the folder.

---

Instance Properties

The Folder instance includes the following properties:

id string

Read-only, folder id.

name string

Folder name.

description string

Folder description/introduction.

icon string

Read-only, folder icon.

iconColor string

Folder icon color.

let folder = await eagle.folder.getById('folder_id');

// Set folder color to red
folder.iconColor = eagle.folder.IconColor.Red;

// Or use string value directly
folder.iconColor = 'red';

// Save changes
await folder.save();

Note: This property was read-only before Eagle 4.0 build12 and did not support modification. Starting from Eagle 4.0 build12, this property can be modified.

createdAt Integer

Read-only, folder creation time (timestamp).

let date = new Date(folder.createdAt);

parent string

Parent folder ID.

let folder = await eagle.folder.getById('folder_id');

// Get parent folder ID
console.log(folder.parent);

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

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

Note: This property was read-only before Eagle 4.0 build12 and did not support modification. Starting from Eagle 4.0 build12, this property can be modified, allowing you to move folders to different parent folders by changing this property.

children Folder[]

Read-only, an array of child folders.

let children = folder.children;

console.log(children[0]);
await children[0].open();

---

Static Properties

IconColor Object

Provides predefined folder icon color constants for setting the folder's iconColor property.

// Available color constants
eagle.folder.IconColor.Red      // 'red'
eagle.folder.IconColor.Orange   // 'orange' 
eagle.folder.IconColor.Yellow   // 'yellow'
eagle.folder.IconColor.Green    // 'green'
eagle.folder.IconColor.Aqua     // 'aqua'
eagle.folder.IconColor.Blue     // 'blue'
eagle.folder.IconColor.Purple   // 'purple'
eagle.folder.IconColor.Pink     // 'pink'

Usage Examples:

let folder = await eagle.folder.getById('folder_id');

// Use color constants to set folder color
folder.iconColor = eagle.folder.IconColor.Blue;
await folder.save();

// Batch set multiple folder colors
let folders = await eagle.folder.getAll();
for (let i = 0; i < folders.length; i++) {
    if (i % 2 === 0) {
        folders[i].iconColor = eagle.folder.IconColor.Green;
    } else {
        folders[i].iconColor = eagle.folder.IconColor.Purple;
    }
    await folders[i].save();
}

🦄 Best Practice: It's recommended to use eagle.folder.IconColor constants instead of string values directly for better code hints and type safety.