folder（資料夾）

透過 eagle.folder API 可以方便的建立新的資料夾或者存取當前應用中的資料夾，。

// 取得 Eagle 應用當前被選中的資料夾
let folder = (await eagle.folder.getSelected())[0];

// 修改屬性
folder.name = 'New Folder Name';
folder.description = 'New description...';

// 儲存修改
await folder.save();

🦄 最佳實踐： 為了確保數據安全性，請使用 API 提供的 save() 方法進行數據的存取與修改，應避免直接修改 Eagle 資源庫底下的 metadata.json 或任意檔案。

方法

create(options)

建立資料夾

• options Object

  • name string - 資料夾名

  • description string (可選) - 資料夾描述

  • parent string (可選) - 父資料夾 ID，帶此參數等同 createSubfolder(parentId, options)

• 返回 Promise<folder: Folder> - folder 成功新增的資料夾

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

---

createSubfolder(parentId, options)

建立子資料夾

• parentId string - 父資料夾 ID

• options Object

  • name string - 資料夾名

  • description string (可選) - 資料夾描述

• 返回 Promise<folder: Folder> - folder 成功新增的資料夾

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

---

get(options)

獲取指定條件的資料夾。

• options Object - 查詢條件

  • id string (可選) - 資料夾 id

  • ids string[] (可選) - 資料夾 id 數組

  • isSelected boolean (可選) - 正在被選中的資料夾

  • isRecent boolean (可選) - 近期存取的資料夾

• 返回 Promise<folders: Folder[]> - folders 查詢結果

// 取得指定 id 對應的資料夾
let folders = await eagle.folder.get({
    ids: ['folder_id1', 'folder_id2']
});

// 取得應用當前被選中的資料夾
let folders = await eagle.folder.get({
    isSelected: true
});

---

getAll()

獲取所有資料夾。

• 返回 Promise<folders: Folder[]> - folders 查詢結果

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

---

getById(folderId)

獲取對應 folderId 的資料夾。

• folderId string - 資料夾 id

• 返回 Promise<folder: Folder> - folder 查詢結果

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

---

getByIds(folderIds)

獲取對應 folderIds 的資料夾數組。

• folderIds string[] - 資料夾 id 數組

• 返回 Promise<folders: Folder[]> - folders 查詢結果

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

---

getSelected()

獲取當前應用選中的資料夾

• 返回 Promise<folders: Folder[]> - folders

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

---

getRecents()

獲取最近使用的的資料夾

• 返回 Promise<folders: Folder[]> - folders

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

---

open(folderId)

Eagle 將開啓對應 folderId資料夾。

• 返回 Promise<void>

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

// 等價於
let folder = await eagle.folder.getById('folder_id');
await folder.open();

提示：你也可以直接呼叫 folder 實例的 open() 方法開啓資料夾。

---

類：Folder

由 Folder API get返回的 Object 類型，提供修改、儲存功能。

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();

🦄 最佳實踐： 為了確保數據安全性，請使用 Folder 實例提供的 save() 方法進行數據的存取與修改，應避免直接修改 Eagle 資源庫底下的 metadata.json 或任意檔案。

---

實例方法

save()

儲存所有修改

• 返回 Promise<void>

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

// 儲存修改
await folder.save();

---

open()

Eagle 將開啓此資料夾。

• 返回 Promise<void>

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

// 等價於
await eagle.folder.open('folder_id');

提示：你也可以直接呼叫 eagle.folder.open(folderId)方法開啓資料夾。

---

實例屬性

Folder 實例包含以下屬性：

id string

唯讀，資料夾 id。

name string

資料夾名稱。

description string

資料夾描述、介紹。

icon string

唯讀，資料夾圖示。

iconColor string

資料夾圖示顏色。

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

// 設定資料夾顏色為紅色
folder.iconColor = eagle.folder.IconColor.Red;

// 或直接使用字串值
folder.iconColor = 'red';

// 儲存修改
await folder.save();

提示：在 Eagle 4.0 build12 版本之前，此屬性為唯讀狀態，不支援修改。從 Eagle 4.0 build12 版本開始，支援修改此屬性。

createdAt Interger

唯讀，資料夾新增時間(timestamp)。

let date = new Date(folder.createdAt);

parent string

父資料夾 ID。

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

// 獲取父資料夾 ID
console.log(folder.parent);

// 更改父資料夾（將資料夾移動到另一個父資料夾下）
folder.parent = 'parent_folder_id';
await folder.save();

// 移動到根目錄（設為 null 或 undefined）
folder.parent = null;
await folder.save();

提示：在 Eagle 4.0 build12 版本之前，此屬性為唯讀狀態，不支援修改。從 Eagle 4.0 build12 版本開始，支援修改此屬性，可以通過更改此屬性來移動資料夾到不同的父資料夾下。

children Folder[]

唯讀，子資料夾數組。

let children = folder.children;

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

---

靜態屬性

IconColor Object

提供預定義的資料夾圖示顏色常數，用於設定資料夾的 iconColor 屬性。

// 可用的顏色常數
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'

使用範例：

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

// 使用顏色常數設定資料夾顏色
folder.iconColor = eagle.folder.IconColor.Blue;
await folder.save();

// 批量設定多個資料夾顏色
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();
}

🦄 最佳實踐： 建議使用 eagle.folder.IconColor 常數而非直接使用字串值，這樣可以獲得更好的程式碼提示和型別安全。