# 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 %}
## 方法
## create(options)
建立智慧型資料夾
* `options` Object
* `name` string - 智慧型資料夾名稱
* `conditions` Object\[] - 篩選條件
* `description` string (可選) - 描述
* `iconColor` string (可選) - 圖示顏色
* `parent` string (可選) - 父智慧型資料夾 ID
* 返回 `Promise` - `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)
取得指定條件的智慧型資料夾。
* `options` Object - 查詢條件
* `id` string (可選) - 智慧型資料夾 id
* `ids` string\[] (可選) - 智慧型資料夾 id 陣列
* 返回 `Promise` - `smartFolders` 查詢結果
```javascript
// 取得指定 id 對應的智慧型資料夾
let smartFolders = await eagle.smartFolder.get({
ids: ['sf_id1', 'sf_id2']
});
```
***
## getAll()
取得所有智慧型資料夾。
* 返回 `Promise` - `smartFolders` 查詢結果
```javascript
let smartFolders = await eagle.smartFolder.getAll();
```
***
## getById(smartFolderId)
取得對應 `smartFolderId` 的智慧型資料夾。
* `smartFolderId` string - 智慧型資料夾 id
* 返回 `Promise` - `smartFolder` 查詢結果
```javascript
let sf = await eagle.smartFolder.getById('smart_folder_id');
```
***
## getByIds(smartFolderIds)
取得對應 `smartFolderIds` 的智慧型資料夾陣列。
* `smartFolderIds` string\[] - 智慧型資料夾 id 陣列
* 返回 `Promise` - `smartFolders` 查詢結果
```javascript
let smartFolders = await eagle.smartFolder.getByIds(['sf_id1', 'sf_id2']);
```
***
## remove(smartFolderId)
刪除指定的智慧型資料夾。
* `smartFolderId` string - 智慧型資料夾 id
* 返回 `Promise`
```javascript
await eagle.smartFolder.remove('smart_folder_id');
```
***
## getRules()
取得可用的篩選規則 schema。回傳每個 property 支援的 methods、valueType、options 等資訊。
* 返回 `Promise` - 規則 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)
流暢建構器，用於建構單一篩選規則。回傳一個包含所有可用 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
由 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 %}
***
#### 實例方法
### **save()**
儲存所有修改
* 返回 `Promise` - 更新後的智慧型資料夾
```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` - 符合條件的項目陣列
```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']
});
```
***
#### 實例屬性
`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
### **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'`（排除）
***
## 靜態屬性
### **`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 %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.eagle.cool/plugin-api/zh-tw/api/smart-folder.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.