# folder（資料夾）
```javascript
// 取得 Eagle 應用當前被選中的資料夾
let folder = (await eagle.folder.getSelected())[0];
// 修改屬性
folder.name = 'New Folder Name';
folder.description = 'New description...';
// 儲存修改
await folder.save();
```
{% hint style="success" %}
**🦄 最佳實踐：** 為了確保數據安全性，請使用 API 提供的 `save()` 方法進行數據的存取與修改，應避免直接修改 Eagle 資源庫底下的 `metadata.json` 或任意檔案。
{% endhint %}
## 方法
## create(options)
建立資料夾
* `options` Object
* `name` string - 資料夾名
* `description` string (可選) - 資料夾描述
* `parent` string (可選) - 父資料夾 ID，帶此參數等同 `createSubfolder(parentId, options)`
* 返回 `Promise` - `folder` 成功新增的資料夾
```javascript
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` 成功新增的資料夾
```javascript
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` 查詢結果
```javascript
// 取得指定 id 對應的資料夾
let folders = await eagle.folder.get({
ids: ['folder_id1', 'folder_id2']
});
// 取得應用當前被選中的資料夾
let folders = await eagle.folder.get({
isSelected: true
});
```
***
## getAll()
取得所有資料夾。
* 返回 `Promise` - `folders` 查詢結果
```javascript
let folders = await eagle.folder.getAll();
```
***
## getById(folderId)
取得對應 `folderId` 的資料夾。
* `folderId` string - 資料夾 id
* 返回 `Promise` - `folder` 查詢結果
```javascript
let folder = await eagle.folder.getById('folder_id');
```
***
## getByIds(folderIds)
取得對應 `folderIds` 的資料夾陣列。
* `folderIds` string\[] - 資料夾 id 陣列
* 返回 `Promise` - `folders` 查詢結果
```javascript
let folders = await eagle.folder.getByIds(['folder_id1', 'folder_id2']);
```
***
## getSelected()
取得目前應用選中的資料夾
* 返回 `Promise` - `folders`
```javascript
let folders = await eagle.folder.getSelected();
```
***
## getRecents()
取得最近使用的資料夾
* 返回 `Promise` - `folders`
```javascript
let folders = await eagle.folder.getRecents();
```
***
## open(folderId)
Eagle 將開啓對應 `folderId`資料夾。
* 返回 `Promise`
```javascript
await eagle.folder.open('folder_id');
// 等價於
let folder = await eagle.folder.getById('folder_id');
await folder.open();
```
{% hint style="info" %}
提示：你也可以直接呼叫 folder 實例的 `open()` 方法開啓資料夾。
{% endhint %}
***
## 類：Folder
由 Folder API `get`返回的 Object 類型，提供修改、儲存功能。
```javascript
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();
```
{% hint style="success" %}
**🦄 最佳實踐：** 為了確保數據安全性，請使用 Folder 實例提供的 `save()` 方法進行數據的存取與修改，應避免直接修改 Eagle 資源庫底下的 `metadata.json` 或任意檔案。
{% endhint %}
***
#### 實例方法
### **save()**
儲存所有修改
* 返回 `Promise`
```javascript
let folder = await eagle.folder.getById('folder_id');
folder.name = 'New Fodler Name';
// 儲存修改
await folder.save();
```
***
### **open()**
Eagle 將開啓此資料夾。
* 返回 `Promise`
```javascript
let folder = await eagle.folder.getById('folder_id');
await folder.open();
// 等價於
await eagle.folder.open('folder_id');
```
{% hint style="info" %}
提示：你也可以直接呼叫 `eagle.folder.open(folderId)`方法開啓資料夾。
{% endhint %}
***
#### 實例屬性
`Folder` 實例包含以下屬性：
### **`id` string**
唯讀，資料夾 id。
### **`name` string**
資料夾名稱。
### **`description` string**
資料夾描述、介紹。
### **`icon` string**
唯讀，資料夾圖示。
### **`iconColor` string**
資料夾圖示顏色。
```javascript
let folder = await eagle.folder.getById('folder_id');
// 設定資料夾顏色為紅色
folder.iconColor = eagle.folder.IconColor.Red;
// 或直接使用字串值
folder.iconColor = 'red';
// 儲存修改
await folder.save();
```
{% hint style="info" %}
提示：在 Eagle 4.0 build12 版本之前，此屬性為唯讀狀態，不支援修改。從 Eagle 4.0 build12 版本開始，支援修改此屬性。
{% endhint %}
### **`createdAt` Interger**
唯讀，資料夾新增時間(timestamp)。
```javascript
let date = new Date(folder.createdAt);
```
### **`parent` string**
父資料夾 ID。
```javascript
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();
```
{% hint style="info" %}
提示：在 Eagle 4.0 build12 版本之前，此屬性為唯讀狀態，不支援修改。從 Eagle 4.0 build12 版本開始，支援修改此屬性，可以通過更改此屬性來移動資料夾到不同的父資料夾下。
{% endhint %}
### **`children` Folder\[]**
唯讀，子資料夾陣列。
```javascript
let children = folder.children;
console.log(children[0]);
await children[0].open();
```
***
## 靜態屬性
### **`IconColor` Object**
提供預定義的資料夾圖示顏色常數，用於設定資料夾的 `iconColor` 屬性。
```javascript
// 可用的顏色常數
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'
```
**使用範例：**
```javascript
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();
}
```
{% hint style="success" %}
**🦄 最佳實踐：** 建議使用 `eagle.folder.IconColor` 常數而非直接使用字串值，這樣可以獲得更好的程式碼提示和型別安全。
{% endhint %}
###