smartFolder（智慧型資料夾）

透過 eagle.smartFolder API 可以方便的建立、查詢、修改及刪除智慧型資料夾。

版本需求：此功能需要 Eagle 4.0 build22 或更高版本。

// 使用流暢建構器建立智慧型資料夾
const sf = await eagle.smartFolder.create({
    name: '大尺寸 PNG',
    conditions: [
        eagle.smartFolder.Condition.create('AND', [
            eagle.smartFolder.rule('width')['>']([1920]),
            eagle.smartFolder.rule('type').equal('png'),
        ])
    ]
});

// 修改屬性
sf.name = '超大尺寸 PNG';
sf.iconColor = 'blue';

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

🦄 最佳實踐： 使用 getRules() 方法可以取得所有可用的篩選規則 schema，搭配 rule() 流暢建構器和 Condition.create() helper 能更安全地建構條件。

方法

create(options)

建立智慧型資料夾

• options Object

  • name string - 智慧型資料夾名稱

  • conditions Object[] - 篩選條件

  • description string (可選) - 描述

  • iconColor string (可選) - 圖示顏色

  • parent string (可選) - 父智慧型資料夾 ID

• 返回 Promise<smartFolder: SmartFolder> - smartFolder 成功新增的智慧型資料夾

// 使用原始 JSON 格式
let sf = await eagle.smartFolder.create({
    name: '貓咪圖片',
    conditions: [
        {
            rules: [
                { property: 'name', method: 'contain', value: 'cat' }
            ],
            match: 'AND'
        }
    ]
});

// 使用流暢建構器
let sf2 = await eagle.smartFolder.create({
    name: '大尺寸圖片',
    conditions: [
        eagle.smartFolder.Condition.create('AND', [
            eagle.smartFolder.rule('width')['>']([1920]),
            eagle.smartFolder.rule('height')['>']([1080]),
        ])
    ],
    iconColor: 'blue'
});

---

get(options)

取得指定條件的智慧型資料夾。

• options Object - 查詢條件

  • id string (可選) - 智慧型資料夾 id

  • ids string[] (可選) - 智慧型資料夾 id 陣列

• 返回 Promise<smartFolders: SmartFolder[]> - smartFolders 查詢結果

// 取得指定 id 對應的智慧型資料夾
let smartFolders = await eagle.smartFolder.get({
    ids: ['sf_id1', 'sf_id2']
});

---

getAll()

取得所有智慧型資料夾。

• 返回 Promise<smartFolders: SmartFolder[]> - smartFolders 查詢結果

let smartFolders = await eagle.smartFolder.getAll();

---

getById(smartFolderId)

取得對應 smartFolderId 的智慧型資料夾。

• smartFolderId string - 智慧型資料夾 id

• 返回 Promise<smartFolder: SmartFolder> - smartFolder 查詢結果

let sf = await eagle.smartFolder.getById('smart_folder_id');

---

getByIds(smartFolderIds)

取得對應 smartFolderIds 的智慧型資料夾陣列。

• smartFolderIds string[] - 智慧型資料夾 id 陣列

• 返回 Promise<smartFolders: SmartFolder[]> - smartFolders 查詢結果

let smartFolders = await eagle.smartFolder.getByIds(['sf_id1', 'sf_id2']);

---

remove(smartFolderId)

刪除指定的智慧型資料夾。

• smartFolderId string - 智慧型資料夾 id

• 返回 Promise<result: boolean>

await eagle.smartFolder.remove('smart_folder_id');

---

getRules()

取得可用的篩選規則 schema。回傳每個 property 支援的 methods、valueType、options 等資訊。

• 返回 Promise<rules: Object> - 規則 schema 物件

const rules = await eagle.smartFolder.getRules();
console.log(rules);
// {
//     name: { methods: ['contain', 'equal', ...], valueType: 'string' },
//     width: { methods: ['=', '>=', '>', ...], valueType: 'number' },
//     type: { methods: ['equal', 'unequal'], valueType: 'string', options: [...] },
//     ...
// }

提示：先呼叫 getRules() 取得可用的 property 和 method，再使用 rule() 建構器建構條件，可避免無效的篩選條件。

---

rule(property)

流暢建構器，用於建構單一篩選規則。回傳一個包含所有可用 method 的物件，呼叫 method 後會產生對應的 Rule 物件。

• property string - 篩選屬性（如 name、width、type）

• 返回 Object - 包含所有可用 method 的建構器物件

// 名稱包含 "cat"
eagle.smartFolder.rule('name').contain('cat');

// 寬度大於 1920
eagle.smartFolder.rule('width')['>']([1920]);

// 類型等於 png
eagle.smartFolder.rule('type').equal('png');

// 評分大於等於 3
eagle.smartFolder.rule('rating')['>=']([3]);

// 名稱為空
eagle.smartFolder.rule('name').empty();

// 搭配 Condition.create 使用
let condition = eagle.smartFolder.Condition.create('AND', [
    eagle.smartFolder.rule('name').contain('cat'),
    eagle.smartFolder.rule('width')['>']([1920]),
]);

---

類：SmartFolder

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

let sf = await eagle.smartFolder.getById('smart_folder_id');

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

sf.name = '新名稱';
console.log(sf.name);

await sf.save();

🦄 最佳實踐： 為了確保數據安全性，請使用 SmartFolder 實例提供的 save() 方法進行數據的存取與修改。

---

實例方法

save()

儲存所有修改

• 返回 Promise<smartFolder: SmartFolder> - 更新後的智慧型資料夾

let sf = await eagle.smartFolder.getById('smart_folder_id');
sf.name = '新的名稱';
sf.iconColor = 'green';

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

---

getItems(options)

取得符合此智慧型資料夾篩選條件的項目。

• options Object (可選)

  • orderBy string (可選) - 排序欄位

  • fields string[] (可選) - 要回傳的欄位

• 返回 Promise<items: Object[]> - 符合條件的項目陣列

let sf = await eagle.smartFolder.getById('smart_folder_id');

// 取得所有符合條件的項目
let items = await sf.getItems();

// 指定回傳欄位
let items2 = await sf.getItems({
    fields: ['id', 'name', 'ext', 'width', 'height']
});

---

實例屬性

SmartFolder 實例包含以下屬性：

id string

唯讀，智慧型資料夾 id。

name string

智慧型資料夾名稱。

conditions Object[]

篩選條件陣列。

description string

智慧型資料夾描述。

icon string

唯讀，智慧型資料夾圖示。

iconColor string

智慧型資料夾圖示顏色。

let sf = await eagle.smartFolder.getById('smart_folder_id');

// 設定圖示顏色為紅色
sf.iconColor = eagle.smartFolder.IconColor.Red;

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

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

modificationTime integer

唯讀，最後修改時間戳記。

children SmartFolder[]

唯讀，子智慧型資料夾陣列。

let children = sf.children;
console.log(children[0].name);

parent string

唯讀，父智慧型資料夾 ID。

imageCount integer

唯讀，符合條件的項目數量。

---

Helper Classes

SmartFolder.Rule

規則物件，用於描述單一篩選規則。

// 透過建構函式建立
let rule = new eagle.smartFolder.Rule('name', 'contain', 'cat');

// 或使用 rule() 流暢建構器（推薦）
let rule2 = eagle.smartFolder.rule('name').contain('cat');

SmartFolder.Condition

條件群組物件，包含多條規則和邏輯運算。

// 使用 Condition.create 建立
let condition = eagle.smartFolder.Condition.create('AND', [
    eagle.smartFolder.rule('name').contain('cat'),
    eagle.smartFolder.rule('width')['>']([1920]),
]);

// 建立排除條件
let excludeCondition = eagle.smartFolder.Condition.create('OR', [
    eagle.smartFolder.rule('type').equal('gif'),
], 'FALSE');

Condition.create(match, rules, boolean)

• match string - 'AND' 或 'OR'

• rules Object[] - 規則陣列

• boolean string (可選) - 'TRUE'（包含，預設）或 'FALSE'（排除）

---

靜態屬性

IconColor Object

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

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

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