# item（項目）

```javascript
eagle.onPluginCreate(async (plugin) => {
    // 取得 Eagle 應用當前被選中的檔案
    let items = await eagle.item.getSelected();
    let item = items[0];
    
    // 修改屬性
    item.name = 'New Name';
    item.tags = ['tag1', 'tag2'];
    
    // 儲存修改
    await item.save();
});
```

{% hint style="success" %}
**🦄 最佳實踐：** 為了確保數據安全性，請使用 `item` API 提供的 `save()` 方法進行數據的存取與修改，應避免直接修改 Eagle 資源庫底下的 `metadata.json` 或任意檔案。
{% endhint %}

***

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

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

萬用搜尋方法，可取得指定條件的檔案。

* `options` Object - 查詢條件
  * `id` string (可選) - 檔案 id
  * `ids` string\[] (可選) - 檔案 id 陣列
  * `isSelected` boolean (可選) - 正在被選中的檔案
  * `isUntagged` boolean (可選) - 尚未標籤
  * `isUnfiled` boolean (可選) - 尚未分類
  * `keywords` string\[] (可選) - 包含關鍵字
  * `tags` string\[] (可選) - 包含標籤
  * `folders` string\[] (可選) - 包含資料夾
  * `ext` string (可選) - 格式
  * `annotation` string (可選) - 註解
  * `rating` Interger (可選) - 評分，`0 ~ 5`
  * `url` string (可選) - 來源連結
  * `shape` string (可選) - 形狀，`square`、`portrait`、`panoramic-portrait`、`landscape`、`panoramic-landscape`
  * `fields` string\[] (可選) - 指定返回的欄位，僅返回需要的資料以提升效能
* 返回 `Promise<items: Item[]>` - `items` 查詢結果

```javascript
let items = await eagle.item.get({
    ids: [],
    isSelected: true,
    isUnfiled: true,
    isUntagged: true,
    keywords: [""],
    ext: "",
    tags: [],
    folders: [],
    shape: "square",
    rating: 5,
    annotation: "",
    url: ""
});


let selected = await eagle.item.get({
    isSelected: true
});

let jpgs = await eagle.item.get({
    ext: "jpg"
});

// 僅取得特定欄位以提升效能
let itemsWithFields = await eagle.item.get({
    tags: ["Design"],
    fields: ["id", "name", "tags", "modifiedAt"]
});
```

{% hint style="info" %}
提示：使用 `fields` 參數可以顯著提升效能，特別是在處理大量檔案時只需要部分資訊的場景。
{% endhint %}

***

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

返回所有檔案

* 返回 `Promise<items: Item[]>` - `items` 所有檔案

```javascript
let items = await eagle.item.getAll();
console.log(items);
```

{% hint style="success" %}
**🦄 最佳實踐：** 如果資源庫檔案數量非常多（例：20W+），避免無限制的呼叫此方法，避免造成應用效能的降低。
{% endhint %}

***

## getById(itemId) <a href="#katrb" id="katrb"></a>

返回指定 ID 之檔案

* `itemId` string
* 返回 `Promise<item: Item>` - `item` 對應 ID 的檔案

```javascript
let item = await eagle.item.getById('item_id');
console.log(item);
```

## getByIds(itemIds) <a href="#by1ek" id="by1ek"></a>

返回指定 IDs 之檔案

* `itemIds` string\[]
* 返回 `Promise<items: Item[]>` - `items` 對應 IDs 的檔案

```javascript
let items = await eagle.item.getByIds(['item_id_1', 'item_id_2']);
console.log(items);
```

***

## getIdsWithModifiedAt() <a href="#getidsmodified" id="getidsmodified"></a>

快速取得所有檔案的 ID 和最後修改時間

* 返回 `Promise<items: Object[]>` - `items` 包含 `id` 和 `modifiedAt` 的物件陣列

```javascript
let items = await eagle.item.getIdsWithModifiedAt();
console.log(items);
// 輸出：[{id: "item_id_1", modifiedAt: 1234567890}, ...]
```

{% hint style="info" %}
提示：此方法針對效能最佳化，當只需要檔案 ID 和修改時間資訊時，比使用 `get()` 效能更好。
{% endhint %}

***

## getSelected() <a href="#ffgvj" id="ffgvj"></a>

返回應用當前選中的檔案

* 返回 `Promise<items: Item[]>` - `items` 選中之檔案

```javascript
let selected = await eagle.item.getSelected();
console.log(selected);
```

***

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

計算符合條件的檔案數量，支援與 `get()` 方法相同的查詢條件。

* `options` Object - 查詢條件（與 `get()` 方法相同）
  * `id` string (可選) - 檔案 id
  * `ids` string\[] (可選) - 檔案 id 陣列
  * `isSelected` boolean (可選) - 正在被選中的檔案
  * `isUntagged` boolean (可選) - 尚未標籤
  * `isUnfiled` boolean (可選) - 尚未分類
  * `keywords` string\[] (可選) - 包含關鍵字
  * `tags` string\[] (可選) - 包含標籤
  * `folders` string\[] (可選) - 包含資料夾
  * `ext` string (可選) - 格式
  * `annotation` string (可選) - 註解
  * `rating` Interger (可選) - 評分，`0 ~ 5`
  * `url` string (可選) - 來源連結
  * `shape` string (可選) - 形狀，`square`、`portrait`、`panoramic-portrait`、`landscape`、`panoramic-landscape`
* 返回 `Promise<count: number>` - `count` 符合條件的檔案數量

```javascript
// 計算 JPG 格式檔案數量
let jpgCount = await eagle.item.count({
    ext: "jpg"
});

// 計算帶有特定標籤的檔案數量
let taggedCount = await eagle.item.count({
    tags: ["Design", "Illustration"]
});

// 計算未分類檔案數量
let unfiledCount = await eagle.item.count({
    isUnfiled: true
});
```

{% hint style="info" %}
提示：當只需要取得檔案數量時，使用 `count()` 比 `get()` 效能更好。
{% endhint %}

***

## countAll() <a href="#countall" id="countall"></a>

快速返回資源庫中所有檔案的總數

* 返回 `Promise<count: number>` - `count` 所有檔案數量

```javascript
let totalCount = await eagle.item.countAll();
console.log(`資源庫共有 ${totalCount} 個檔案`);
```

{% hint style="info" %}
提示：`countAll()` 針對效能進行了最佳化，比 `getAll()` 後計算陣列長度要快得多。
{% endhint %}

***

## countSelected() <a href="#countselected" id="countselected"></a>

返回應用當前選中的檔案數量

* 返回 `Promise<count: number>` - `count` 選中的檔案數量

```javascript
let selectedCount = await eagle.item.countSelected();
console.log(`當前選中了 ${selectedCount} 個檔案`);
```

***

## select(itemIds) <a href="#select" id="select"></a>

選中指定的檔案

* `itemIds` string\[] - 要選中的檔案 ID 陣列
* 返回 `Promise<result: boolean>` - `result` 是否選中成功

```javascript
// 選中單個檔案
await eagle.item.select(['ITEM_ID_1']);

// 選中多個檔案
await eagle.item.select(['ITEM_ID_1', 'ITEM_ID_2', 'ITEM_ID_3']);

// 清空選中
await eagle.item.select([]);
```

{% hint style="info" %}
提示：呼叫此方法會取代當前的選中狀態，而不是追加到現有選中項。
{% endhint %}

{% hint style="info" %}
提示：`select()` 方法需要 Eagle 4.0 build12 以上版本支援。
{% endhint %}

***

## addFromURL(url, options) <a href="#tg9ak" id="tg9ak"></a>

將圖片連結新增至 Eagle

* `url`string - 欲新增圖片連結，支援 `http`、 `https`、 `base64`
* `options` Object
  * `name` string (可選) - 檔案名
  * `website` string (可選) - 來源網址
  * `tags` string\[] (可選) - 標籤
  * `folders` string\[] (可選) - 所屬資料夾 IDs
  * `annotation` string (可選) - 註解
* 返回 `Promise<itemId: string>` - `itemId`成功新增的項目 ID

```javascript
const imgURL = 'https://cdn.dribbble.com/userupload/3885520/file/original-ee68b80a6e10edab6f192e1e542da6ed.jpg';
const itemId = await eagle.item.addFromURL(imgURL, { 
    name: 'Camping', 
    website: 'https://dribbble.com/shots/19744134-Camping-2', 
    tags: ["Dribbble", "Illustration"],
    folders: [],
    annotation: 'add from eagle api',
});
```

***

## addFromBase64(base64, options) <a href="#zmwst" id="zmwst"></a>

新增 base64 圖片至 Eagle

* `base64`string - base64 格式圖片
* `options` Object
  * `name` string (可選) - 檔案名
  * `website` string (可選) - 來源網址
  * `tags` string\[] (可選) - 標籤
  * `folders` string\[] (可選) - 所屬資料夾 IDs
  * `annotation` string (可選) - 註解
* 返回 `Promise<itemId: string>` - `itemId`成功新增的項目 ID

```javascript
const base64 = 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNDAgMjM0IiBlbmFibGUtYmFja2dyb3VuZD0ibmV3IDAgMCAyNDAgMjM0Ij48cGF0aCBmaWxsLXJ1bGU9ImV2ZW5vZGQiIGNsaXAtcnVsZT0iZXZlbm9kZCIgZmlsbD0iIzI2MTMwMCIgZD0iTTEwIDEwaDIyMHYyMTMuOTk5aC0yMjB6Ii8+PHBhdGggZD0iTTAgMHYyMzRoMjQwLjAwMXYtMjM0aC0yNDAuMDAxem0xMCAxMGgyMjAuMDAxdjIxNGgtMjIwLjAwMXYtMjE0em03My4yNTIgMTIyLjUwMWwtNy45MiAyOS45ODJjLS4xNjUuODI0LS40OTUgMS4wMTgtMS40ODUgMS4wMThoLTE0LjY4N2MtLjk4OCAwLTEuMTUyLS4zMy0uOTg4LTEuNDg1bDI4LjM4LTk5LjQ0OGMuNDk1LTEuODE1LjgyNS0zLjM3Ny45OS04LjMyOCAwLS42Ni4zMy0uOTkuODI1LS45OWgyMC45NTVjLjY2IDAgLjk5LjE2NSAxLjE1NS45OWwzMS44NDUgMTA3Ljk0Yy4xNjUuODI0IDAgMS4zMi0uODI1IDEuMzJoLTE2LjVjLS44MjQgMC0xLjMxOS0uMTkzLTEuNDg0LS44NTRsLTguMjUtMzAuMTQ2aC0zMi4wMTF6bTI3Ljg4NS0xNi4yNWMtMi44MDUtMTEuMDU2LTkuNDA1LTM1LjI4Ni0xMS44OC00N2gtLjE2NWMtMi4xNDYgMTEuNzE1LTcuNDI1IDMxLjQ5LTExLjU1IDQ3aDIzLjU5NXptNDQuOTkzLTU1LjU3OGMwLTYuNDM1IDQuNDU1LTEwLjIzIDEwLjIzLTEwLjIzIDYuMTA1IDAgMTAuMjMgNC4xMjUgMTAuMjMgMTAuMjMgMCA2LjYtNC4yOSAxMC4yMy0xMC4zOTUgMTAuMjMtNS45NCAwLTEwLjA2NS0zLjYzLTEwLjA2NS0xMC4yM3ptMS4xMiAyMi43MzJjMC0uODI1LjMzLTEuMTU1IDEuMTU1LTEuMTU1aDE1LjY4OWMuODI1IDAgMS4xNTUuMzMgMS4xNTUgMS4xNTV2NzguOTM5YzAgLjgyNi0uMTY1IDEuMTU2LTEuMTU1IDEuMTU2aC0xNS41MjRjLS45OSAwLTEuMzItLjQ5Ni0xLjMyLTEuMzJ2LTc4Ljc3NXoiIGZpbGwtcnVsZT0iZXZlbm9kZCIgY2xpcC1ydWxlPSJldmVub2RkIiBmaWxsPSIjRkY3QzAwIi8+PC9zdmc+';
const itemId = await eagle.item.addFromBase64(base64, { 
    name: 'Illustation Logo', 
    website: 'https://www.eagle.cool/', 
    tags: ["Adobe", "Logo"],
    folders: [],
    annotation: 'ai logo form api',
});
```

***

## addFromPath(path, options) <a href="#lnsox" id="lnsox"></a>

從本機檔案路徑新增檔案至 Eagle

* `path`string - 欲新增檔案路徑
* `options` Object
  * `name` string (可選) - 檔案名
  * `website` string (可選) - 來源網址
  * `tags` string\[] (可選) - 標籤
  * `folders` string\[] (可選) - 所屬資料夾 IDs
  * `annotation` string (可選) - 註解
* 返回 `Promise<itemId: string>` - `itemId`成功新增的項目 ID

```javascript
const filePath = 'C:\\Users\\User\\Downloads\\ai.svg';
const itemId = await eagle.item.addFromPath(filePath, { 
    name: 'Illustation Logo', 
    website: 'https://www.eagle.cool/', 
    tags: ["Adobe", "Logo"],
    folders: [],
    annotation: 'ai logo form api',
});
```

***

## addBookmark(url, options) <a href="#atulp" id="atulp"></a>

新增書籤連結至 Eagle

* `url`string - 欲新增書籤連結
* `options` Object
  * `name` string (可選) - 書籤名
  * `base64` string (可選) - 自訂縮圖 base64 格式
  * `tags` string\[] (可選) - 標籤
  * `folders` string\[] (可選) - 所屬資料夾 IDs
  * `annotation` string (可選) - 註解
* 返回 `Promise<itemId: string>` - `itemId`成功新增的項目 ID

```javascript
const bookmarkURL = 'https://www.google.com/';
const itemId = await eagle.item.addBookmark(bookmarkURL, { 
    name: 'Eagle', 
    tags: ["Eagle", "Site"],
    folders: [],
    annotation: 'bookmark form api',
});
```

```javascript
const bookmarkURL = 'https://www.google.com/';
const base64 = 'data:image/png;base64,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';
const itemId = await eagle.item.addBookmark(bookmarkURL, { 
    name: 'Eagle', 
    base64: base64,
    tags: ["Eagle", "Site"],
    folders: [],
    annotation: 'bookmark form api',
});
```

***

## open(itemId, options) <a href="#yxkul" id="yxkul"></a>

在全部列表顯示 `itemId` 對應的檔案

* `itemId`string - 欲顯示檔案 ID
* `options` Object (可選) - 開啟選項
  * `window` boolean (可選) - 是否在新視窗中開啟檔案，預設為 `false`
* 返回 `Promise<result: boolean>`

```javascript
// 在當前視窗開啟
await eagle.item.open("item_id");

// 在新視窗開啟
await eagle.item.open("item_id", { window: true });
```

{% hint style="info" %}
提示：`window` 參數需要 Eagle 4.0 build12 以上版本支援。
{% endhint %}

{% hint style="info" %}
提示：你也可以直接呼叫 item 實例的 `open()` 方法開啓檔案。
{% endhint %}

***

## 類：Item <a href="#uezi0" id="uezi0"></a>

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

{% hint style="success" %}
**🦄 最佳實踐：** 為了確保數據安全性，請使用 Item 實例提供的 `save()` 方法進行數據的存取與修改，應避免直接修改 Eagle 資源庫底下的 `metadata.json` 或任意檔案。
{% endhint %}

***

#### 實例方法 <a href="#sihmc" id="sihmc"></a>

### **save()**

儲存所有修改

* 返回 `Promise<result: boolean>` - `result`是否修改成功

```javascript
let item = await eagle.item.getById('item_id');
item.name = 'New Name';
item.tags = ['tag_1', 'tag_2'];

// 儲存修改
await item.save();
```

***

### **moveToTrash()**

將檔案丟到垃圾桶

* 返回 `Promise<result: boolean>` - `result`是否成功刪除

```javascript
await item.moveToTrash();
```

***

### **replaceFile(filePath)**

使用指定檔案替換原檔案，將自動重新整理縮圖，無須再次呼叫 `refreshThumbnail()`。

{% hint style="success" %}
**🦄 最佳實踐：** 直接對要更改的檔案進行操作是具有風險的，若過程中出現錯誤或異常，都有可能造成檔案損毀且無法復原。因此，先將新版本檔案儲存在電腦其它路徑，確定無誤後，再使用 `replaceFile()`方法來替換是更穩健的作法。
{% endhint %}

* `filePath`string - 欲替換檔案之路徑
* 返回 `Promise<result: boolean>` - `result`是否替換成功

```javascript
let item = await eagle.item.getById('item_id');
let result = await item.replaceFile('new_file_path');

console.log(result);
```

***

### **refreshThumbnail()**

重新重新整理檔案縮圖，同時也會重新取得檔案大小、顏色分析、尺寸等屬性。

* 返回 `Promise<result: boolean>` - `result`是否成功

```javascript
let item = await eagle.item.getById('item_id');
let result = await item.refreshThumbnail();

console.log(result);
```

***

### **setCustomThumbnail(thumbnailPath)**

為檔案設定自定縮圖。

* `thumbnailPath`string - 欲設定縮圖的路徑
* 返回 `Promise<result: boolean>` - `result`是否替換成功

```javascript
let item = await eagle.item.getById('item_id');
let result = await item.setCustomThumbnail('thumbnail_path');

console.log(result);
```

***

### **addComment(commentData)** (Eagle 4.0 build22+)

新增一個標註到此項目。支援圖片框選標註和影片時間軸註解。

* `commentData` Object - 標註資料
  * `annotation` string (可選) - 標註文字
  * `x` number (可選) - 框選 X 位置（圖片標註）
  * `y` number (可選) - 框選 Y 位置（圖片標註）
  * `width` number (可選) - 框選寬度，必須 > 0（圖片標註）
  * `height` number (可選) - 框選高度，必須 > 0（圖片標註）
  * `duration` number (可選) - 影片時間戳（秒），必須 >= 0（影片標註）
* 返回 `Promise<comment: Object>` - 新建立的標註物件

```javascript
let item = await eagle.item.getById('item_id');

// 新增圖片框選標註
let comment = await item.addComment({
    x: 350, y: 480, width: 380, height: 400,
    annotation: "臉部區域"
});

// 新增影片時間軸註解
let comment = await item.addComment({
    duration: 65.5,
    annotation: "重要場景"
});
```

{% hint style="info" %}
備註：此方法需要 Eagle 4.0 build22 或更高版本。
{% endhint %}

***

### **updateComment(commentId, updateData)** (Eagle 4.0 build22+)

更新現有的標註。僅更新提供的欄位。

* `commentId` string - 要更新的標註 ID
* `updateData` Object - 要更新的欄位
  * `annotation` string (可選) - 新的標註文字
  * `x` number (可選) - 新的 X 位置（僅圖片標註）
  * `y` number (可選) - 新的 Y 位置（僅圖片標註）
  * `width` number (可選) - 新的寬度（僅圖片標註）
  * `height` number (可選) - 新的高度（僅圖片標註）
  * `duration` number (可選) - 新的時間戳（僅影片標註）
* 返回 `Promise<comment: Object>` - 更新後的標註物件

```javascript
let item = await eagle.item.getById('item_id');
let updated = await item.updateComment('comment_id', {
    annotation: "更新後的文字"
});
```

{% hint style="info" %}
備註：此方法需要 Eagle 4.0 build22 或更高版本。
{% endhint %}

***

### **removeComment(commentId)** (Eagle 4.0 build22+)

從此項目中移除一個標註。

* `commentId` string - 要移除的標註 ID
* 返回 `Promise<result: boolean>` - 是否移除成功

```javascript
let item = await eagle.item.getById('item_id');
await item.removeComment('comment_id');
```

{% hint style="info" %}
備註：此方法需要 Eagle 4.0 build22 或更高版本。
{% endhint %}

***

### **open(options)**

在全部列表顯示此檔案

* `options` Object (可選) - 開啟選項
  * `window` boolean (可選) - 是否在新視窗中開啟檔案，預設為 `false`
* 返回 `Promise<void>`

{% hint style="info" %}
提示：你也可以直接呼叫 `eagle.item.open(itemId, options)`方法開啓資料夾。
{% endhint %}

```javascript
let item = await eagle.item.getById('item_id');
// 在當前視窗開啟
await item.open();

// 在新視窗開啟
await item.open({ window: true });

// 等價於
await eagle.item.open('item_id');
await eagle.item.open('item_id', { window: true });
```

{% hint style="info" %}
提示：`window` 參數需要 Eagle 4.0 build12 以上版本支援。
{% endhint %}

***

### **select()**

選中此檔案

* 返回 `Promise<result: boolean>` - `result` 是否選中成功

```javascript
let item = await eagle.item.getById('item_id');
await item.select();

// 等價於
await eagle.item.select([item.id]);
```

{% hint style="info" %}
提示：呼叫實例方法 `select()` 會清空當前選中並僅選中此檔案。如需批量選中多個檔案，請使用靜態方法 `eagle.item.select(itemIds)`。
{% endhint %}

{% hint style="info" %}
提示：`select()` 方法需要 Eagle 4.0 build12 以上版本支援。
{% endhint %}

***

#### 實例屬性 <a href="#woenk" id="woenk"></a>

### **`id` string**

唯讀，檔案 ID。

### **`name` string**

檔案名。

### **`ext` string**

唯讀，檔案副檔名。

### **`width` Interger**

圖片寬度。

### **`height` Interger**

圖片高度。

### **`url` string**

來源連結。

### **`isDeleted` boolean**

唯讀，檔案是否在垃圾桶。

### **`annotation` string**

檔案註解。

### **`tags` string\[]**

檔案標籤。

### **`folders` string\[]**

所屬資料夾 ids。

### **`palettes` Object\[]**

唯讀，色票資訊。

### **`comments` Object\[]** (Eagle 4.0 build22+)

唯讀，項目標註。使用 `addComment()`、`updateComment()`、`removeComment()` 方法來修改。

```javascript
let item = await eagle.item.getById('item_id');

// 讀取標註
console.log(item.comments);
// [{ id: "abc", x: 324, y: 810, width: 194, height: 208, annotation: "臉部", lastModified: 1774282485915 }]
```

{% hint style="info" %}
備註：此屬性需要 Eagle 4.0 build22 或更高版本。
{% endhint %}

### **`size` Interger**

唯讀，檔案大小。

### **`star` Interger**

評分資訊，`0 ~ 5`。

### **`importedAt` Interger**

導入時間（時間戳記）。可讀寫，修改後需呼叫 `save()` 儲存。

```javascript
// 讀取導入時間
let date = new Date(item.importedAt);

// 修改導入時間（需要 Eagle 4.0 build18+）
item.importedAt = Date.now();
item.importedAt = new Date('2024-01-01').getTime();
await item.save();
```

{% hint style="info" %}
備註：設定值必須為正整數時間戳記，無效值將被忽略。此功能需要 Eagle 4.0 build18 或更高版本。
{% endhint %}

### **`modifiedAt` Interger**

唯讀，最後修改時間。

```javascript
let modifiedDate = new Date(item.modifiedAt);
```

### **`noThumbnail` boolean**

唯讀，檔案是否有縮圖，無縮圖檔案將以原始檔案進行預覽。

### **`noPreview` boolean**

唯讀，檔案是否支援雙擊預覽。

### **`filePath` string**

唯讀，返回檔案所在路徑。

### **`fileURL` string**

唯讀，返回檔案所在路徑之連結（`file:///`）。

### **`thumbnailPath` string**

唯讀，返回縮圖路徑。

### **`thumbnailURL` string**

唯讀，返回縮圖連結（`file:///`），如需在 HTML 顯示該檔案，可以使用這個屬性。

### **`metadataFilePath`string**

唯讀，該檔案 `metadata.json` 所在位置。

{% hint style="success" %}
**🦄 最佳實踐：** 為了確保數據安全性，請使用 `item` API 提供的 `save()` 方法進行數據的存取與修改，應避免直接 `metadata.json`。
{% endhint %}

### &#x20;<a href="#nptwx" id="nptwx"></a>