# smartFolder（智慧型資料夾）

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

```javascript
// 使用流暢建構器建立智慧型資料夾
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();
```

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

## 方法 <a href="#methods" id="methods"></a>

## create(options) <a href="#create" id="create"></a>

建立智慧型資料夾

* `options` Object
  * `name` string - 智慧型資料夾名稱
  * `conditions` Object\[] - 篩選條件
  * `description` string (可選) - 描述
  * `iconColor` string (可選) - 圖示顏色
  * `parent` string (可選) - 父智慧型資料夾 ID
* 返回 `Promise<smartFolder: SmartFolder>` - `smartFolder` 成功新增的智慧型資料夾

```javascript
// 使用原始 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) <a href="#get" id="get"></a>

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

* `options` Object - 查詢條件
  * `id` string (可選) - 智慧型資料夾 id
  * `ids` string\[] (可選) - 智慧型資料夾 id 陣列
* 返回 `Promise<smartFolders: SmartFolder[]>` - `smartFolders` 查詢結果

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

***

## getAll() <a href="#getall" id="getall"></a>

取得所有智慧型資料夾。

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

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

***

## getById(smartFolderId) <a href="#getbyid" id="getbyid"></a>

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

* `smartFolderId` string - 智慧型資料夾 id
* 返回 `Promise<smartFolder: SmartFolder>` - `smartFolder` 查詢結果

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

***

## getByIds(smartFolderIds) <a href="#getbyids" id="getbyids"></a>

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

* `smartFolderIds` string\[] - 智慧型資料夾 id 陣列
* 返回 `Promise<smartFolders: SmartFolder[]>` - `smartFolders` 查詢結果

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

***

## remove(smartFolderId) <a href="#remove" id="remove"></a>

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

* `smartFolderId` string - 智慧型資料夾 id
* 返回 `Promise<result: boolean>`

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

***

## getRules() <a href="#getrules" id="getrules"></a>

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

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

```javascript
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: [...] },
//     ...
// }
```

{% hint style="info" %}
提示：先呼叫 `getRules()` 取得可用的 property 和 method，再使用 `rule()` 建構器建構條件，可避免無效的篩選條件。
{% endhint %}

***

## rule(property) <a href="#rule" id="rule"></a>

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

* `property` string - 篩選屬性（如 `name`、`width`、`type`）
* 返回 `Object` - 包含所有可用 method 的建構器物件

```javascript
// 名稱包含 "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 <a href="#class" id="class"></a>

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

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

{% hint style="success" %}
**🦄 最佳實踐：** 為了確保數據安全性，請使用 SmartFolder 實例提供的 `save()` 方法進行數據的存取與修改。
{% endhint %}

***

#### 實例方法 <a href="#instance-methods" id="instance-methods"></a>

### **save()**

儲存所有修改

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

```javascript
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[]>` - 符合條件的項目陣列

```javascript
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']
});
```

***

#### 實例屬性 <a href="#instance-properties" id="instance-properties"></a>

`SmartFolder` 實例包含以下屬性：

### **`id` string**

唯讀，智慧型資料夾 id。

### **`name` string**

智慧型資料夾名稱。

### **`conditions` Object\[]**

篩選條件陣列。

### **`description` string**

智慧型資料夾描述。

### **`icon` string**

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

### **`iconColor` string**

智慧型資料夾圖示顏色。

```javascript
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\[]**

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

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

### **`parent` string**

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

### **`imageCount` integer**

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

***

## Helper Classes <a href="#helpers" id="helpers"></a>

### **SmartFolder.Rule**

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

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

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

### **SmartFolder.Condition**

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

```javascript
// 使用 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'`（排除）

***

## 靜態屬性 <a href="#static-properties" id="static-properties"></a>

### **`IconColor` Object**

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

```javascript
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'
```

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