# 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 %}
###
---
# 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/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.