item（項目）

透過 eagle.item API 可以方便的查詢當前資源庫內容或新增新的內容到資源庫中。

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();
});

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

---

方法

get(options)

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

• 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

• 返回 Promise<items: Item[]> - items 查詢結果

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"
});

---

getAll()

返回所有檔案

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

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

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

---

getById(itemId)

返回指定 ID 之檔案

• itemId string

• 返回 Promise<item: Item> - item 對應 ID 的檔案

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

getByIds(itemIds)

返回指定 IDs 之檔案

• itemIds string[]

• 返回 Promise<items: Item[]> - items 對應 IDs 的檔案

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

---

getSelected()

返回應用當前選中的檔案

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

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

---

addFromURL(url, options)

將圖片連結新增至 Eagle

• urlstring - 欲新增圖片連結，支援 http、 https、 base64

• options Object

  • name string (可選) - 檔案名

  • website string (可選) - 來源網址

  • tags string[] (可選) - 標籤

  • folders string[] (可選) - 所屬資料夾 IDs

  • annotation string (可選) - 註解

• 返回 Promise<itemId: string> - itemId成功新增的項目 ID

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)

新增 base64 圖片至 Eagle

• base64string - base64 格式圖片

• options Object

  • name string (可選) - 檔案名

  • website string (可選) - 來源網址

  • tags string[] (可選) - 標籤

  • folders string[] (可選) - 所屬資料夾 IDs

  • annotation string (可選) - 註解

• 返回 Promise<itemId: string> - itemId成功新增的項目 ID

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)

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

• pathstring - 欲新增檔案路徑

• options Object

  • name string (可選) - 檔案名

  • website string (可選) - 來源網址

  • tags string[] (可選) - 標籤

  • folders string[] (可選) - 所屬資料夾 IDs

  • annotation string (可選) - 註解

• 返回 Promise<itemId: string> - itemId成功新增的項目 ID

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)

新增書籤連結至 Eagle

• urlstring - 欲新增書籤連結

• options Object

  • name string (可選) - 書籤名

  • base64 string (可選) - 自訂縮圖 base64 格式

  • tags string[] (可選) - 標籤

  • folders string[] (可選) - 所屬資料夾 IDs

  • annotation string (可選) - 註解

• 返回 Promise<itemId: string> - itemId成功新增的項目 ID

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

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)

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

• itemIdstring - 欲顯示檔案 ID

• 返回 Promise<result: boolean>

await eagle.item.open("item_id");

提示：你也可以直接呼叫 item 實例的 open() 方法開啓檔案。

---

類：Item

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

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

---

實例方法

save()

儲存所有修改

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

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是否成功刪除

await item.moveToTrash();

---

replaceFile(filePath)

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

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

• filePathstring - 欲替換檔案之路徑

• 返回 Promise<result: boolean> - result是否替換成功

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

console.log(result);

---

refreshThumbnail()

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

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

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

console.log(result);

---

setCustomThumbnail(thumbnailPath)

為檔案設定自定縮圖。

• thumbnailPathstring - 欲設定縮圖的路徑

• 返回 Promise<result: boolean> - result是否替換成功

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

console.log(result);

---

open()

在全部列表顯示此檔案

• 返回 Promise<void>

提示：你也可以直接呼叫 eagle.item.open(itemId)方法開啓資料夾。

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

// 等價於
await eagle.item.open('item_id');

---

實例屬性

id string

唯讀，檔案 ID。

name string

檔案名。

ext string

唯讀，檔案副檔名。

width Interger

圖片寬度。

height Interger

圖片高度。

url string

來源連結。

isDeleted boolean

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

annotation string

檔案註解。

tags string[]

檔案標籤。

folders string[]

所屬資料夾 ids。

palettes Object[]

唯讀，色票資訊。

size Interger

唯讀，檔案大小。

star Interger

評分資訊，0 ~ 5。

importedAt Interger

唯讀，新增時間。

let date = new Date(item.importedAt);

noThumbnail boolean

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

noPreview boolean

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

filePath string

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

fileURL string

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

thumbnailPath string

唯讀，返回縮圖路徑。

thumbnailURL string

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

metadataFilePathstring

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

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