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

方法

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 (可選) - 形狀,squareportraitpanoramic-portraitlandscapepanoramic-landscape

    • fields string[] (可選) - 指定返回的欄位,僅返回需要的資料以提升效能

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

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

提示:使用 fields 參數可以顯著提升效能,特別是在處理大量檔案時只需要部分資訊的場景。


getAll()

返回所有檔案

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

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

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

getIdsWithModifiedAt()

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

  • 返回 Promise<items: Object[]> - items 包含 idmodifiedAt 的物件陣列

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

提示:此方法針對效能最佳化,當只需要檔案 ID 和修改時間資訊時,比使用 get() 效能更好。


getSelected()

返回應用當前選中的檔案

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

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

count(options)

計算符合條件的檔案數量,支援與 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 (可選) - 形狀,squareportraitpanoramic-portraitlandscapepanoramic-landscape

  • 返回 Promise<count: number> - count 符合條件的檔案數量

// 計算 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
});

提示:當只需要獲取檔案數量時,使用 count()get() 效能更好。


countAll()

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

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

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

提示:countAll() 針對效能進行了最佳化,比 getAll() 後計算陣列長度要快得多。


countSelected()

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

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

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

select(itemIds)

選中指定的檔案

  • itemIds string[] - 要選中的檔案 ID 陣列

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

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

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

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

提示:呼叫此方法會取代當前的選中狀態,而不是追加到現有選中項。

提示:select() 方法需要 Eagle 4.0 build12 以上版本支援。


addFromURL(url, options)

將圖片連結新增至 Eagle

  • urlstring - 欲新增圖片連結,支援 httphttpsbase64

  • 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,iVBORw0KGgoAAAANSUhEUgAAACUAAAAnCAYAAACIVoEIAAAAAXNSR0IArs4c6QAACUFJREFUWAmlWFlzVMcV/u42Gi0w2pEE1miFIIGRkMoowRCbRErKlUqeU5Uqv+UhD6n4yW8pJ1V5i/9AquynuPLisCUEHNtsdkJYBAGMkWWJAhGMomAWIzSjmbvkO31vX90ZCSMlPdW3u8/e55w+t+8A/2cLAHNZf+MNU4tdhluJPoQZmieeaMBaxt/OuD++b1k/c/MuEElKV9nG/KXLF998e+C137zpvpWzrO7AJb680Vo/gnEKJ2X76zzvd68/Z79jd/ziRG3RMUaNIKiIqcoFlK0LnofNm9Y7M/ng1/dtbDICG4ZItoDqB3kceusPzQ9/Or1QaVqv5opir10mAQiEnk0GmYu7m4oBqfGOXTC8n5t25leBu6iECuGzmhlYaO7dhEeGDT/nwoi8VJm2cX3/u5i363utlrbX53M+DD/yh9BEhmj5asmHjAEN56hcagcwGwKvAGVURC1ET4ur5wVo3VCDup4GzC+60Mlj2BaKMzdx7vQ4XvzJqwiq0wiKrlKoZCWFci5L3ZTXCPAjILdKRkZOuzMm1JOy0WSctgxnsWAyJJ6PgBqFt5rw8388gNquPnQM9WGh4C1tTO8wUprUpUDyYPd9X1GaQRBQ3Op+ruuho6sR6U1NcF0aJLL4sBwbjy6PY+KzOxj5wSjydopwyiROaMQD0mWtxtCGEC/waO3TFk7B8DFUGiqQsqbwhInZ6QoLXTs78IQb4sFQlAETKlXI4fSBP6Fr126GtR0LDJuSLo+QLKRVz8SDuBgt8yj9TPos3JXi1x4LiUMGgTEDiz56+9oQ1K9HIGETej6clIU7p47j3jwwOLYXC54StOQV0iiPrTCKDSU4rqXZgpBkFXcvteRcxRp1tWm0bhcv8ERF6MA0YXx5D+eOncDzYz+C09SAxad4aUl2OIs1cCJzKQmuH4WPIEP7MCYkUdLzAb25eTCLxTRPFPMqRBpIOyYm/3IYyLSh91tDyBWZ3JESFT7KEZl6zmnckrpiby2FTxj5izEidWnt0YjWtgzWd7eiQKXSlFNZAgo3JnHl3FUMvTIGr6qKOSF8oSFJcXGikzeeh2pCes2jpKvw+cp1hC9vBFqmge6dncgZLNeSf0LFrVcEHsYPH0Tj1kG0bNuCXLIEkEToYg9FE7UZ4U8o01PBicHSVO3TngqPceglmUsJyHY3w2ltLCkBpuPg4aWzmL4xh/7du1CwHCqSA7PcS6JHwQWn+wowMUhopZm+t5RTChJhxKiqSgfPDdBLYdSUUJ8lwMnN48rR93gSs7h55iQst8jXpqRmwN1GIaScZadLFOtOZcoQvRb6KNFDTylBkTARTQKPxbGrfxP8zDr4UgIiZoeF8s7Jv+KhW4F9P/wObk7ewv3xM7BsvrtiBWKeyAmNLDE0CQupljYSJzotpqywk0HmHo2oq6tC09Z25FkCpCmFJvNq7i6unPwYW1/eh5bBPnR9cy8uHTkK68nj0FsUsJKHxLCkcUqe3oTIZ49skhwXLwhWVLPJyPzoHuxEPlWhfKwFpCwTnx89xHrUiezQAB7mfWzZM4IFowYzJ45BvKhpVzuWh1BMMHmM1dkQw6RLcrdsrEd1thVFlgBlIx8Gw5Of+gSfX53E9u+NophK813OupTJoP+7o7h6+gy82TsI6E0xqESZ3qseiS83WugZINWWckoYiLDpjexgF3LRpUQpYBI7vE1cP3IITduGUd/bw5oltwuwgnvYOPg80q09mDxyEI5lxAYpwyK5JUYIjL3EcAL8oOSWEHKKl9p7W2A1N6hE14LkFvBw/GN8MfsYm/fuQV4MphCFp2SXYd42NoqpT2/gycRVetWJPSGKtfLkqOYrGEwQpcurWTEGqK5O8f3WhbxLAJso9Q0T1vwjTHz4AczGrNylmYV8j0sJYHmQUSp9XU83NuzYhWt/Zs65BcUXqDIhpSKkS44Kx8wR/rCLGSpwrFOinD8pAR3bsnBrangLkPwKjXL4Orl76ii+LPAiaKUwfewQ7EdzcIp52IU8nKj7XEsh/c/9POb+fhwVflHh7UXSSSddPI9glsCiLnKC/ILKbzkuhpSA+sYa1G5u50tV/BAaZPAWgAdzmL54GVZDrzJ0+pMJfHHhNaSqqtVmxKNx46vIr/8Gzu8/gKrD7ypPxrhnTAw5ICzC0iQW6sKWHejGIj3BIkVlhNFmdSKrMmgceBF3Z2bRv2sHgt1D8B/wlNEz8ReDEiUPfrc0tiNYJM1Xc1yG4YjRXzORO76Rz+PC8bfp0WLBaO+VK24rCyWPuHKg5g5QMB1kR0YwO/V7GAtzaNz3Ci98O2I6Rc5HzCZx52oN9qgImPRH9WIRF37Jc1KVdrBxRy9ycsWVgIQyJdFU8+k5u7YencPD+PT9/RjZuhNeppknoHQDyc3EBuq9yaiBWr7AIh0KHTgo5PKKyty+dzuM+hoWQj88ukJLYqHXyS61qGVgEBZP38z7THTWsiRe0+lRH31FE+nWuBI+4oRW00e1E2amrcmIKkBsRCyADEoIudxUJXpfHsWta58hf+MaL1pMR42PhCf5tKIkbMV5tHlFH364Gia/tQheaoqRy1ihKGYvsoJnuntQt3UoLAvyvSgBj/Ayxjzk51Ktn2acwGOc0MtaX110aSc8bkIgUmOFguG6wD8LOve8hHv3HvOS9zeYfB/GgoVeyGQs69qA5FhOo3hFD5t8RKzYFFGZcLmvV2xoxcYXvo2pD4/BePIVDWF+JehKjEzAkzTlc83Dmi3NMFm99bn4euOIFZ4COTe+MMIr8DrMfsR7lMOCKcoFLyO79ohel4wJuhJ4JIPo8DUjk2c1LUBuoUZNBtm9Y7h57izc2dvxdUXTxCOFKmOTY6Rc4Enj1Tx0EEtcdF14llFJfJFhbOzfjgpeV25/cBA2v3iUt0Sh7gmlGqeN0KMYpnqCR/Tww4F/5/CWa/Kx6s5KGVSk0bnv+/j3jRksTP4T8oUTChJh7HwPGolevtY4gQu9vAECFmQ2w75z/pTdMLiHO5TUErtX1+S6ka60kM724dbJ99BT20AZq+cv1xKwID+YuMid8YX8+F/T/3DT68ZM23H+F6EBt7jgWpi7flm+XMt1rWFt+LlbUx+RwRX3VFZsGW63U04K4c1hDYJYVAsF0qd4+VsTWykx/cO/Ib35a2dvE/H4v9IJhWmtCpMiAAAAAElFTkSuQmCC';
const itemId = await eagle.item.addBookmark(bookmarkURL, { 
    name: 'Eagle', 
    base64: base64,
    tags: ["Eagle", "Site"],
    folders: [],
    annotation: 'bookmark form api',
});

open(itemId, options)

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

  • itemIdstring - 欲顯示檔案 ID

  • options Object (可選) - 開啟選項

    • window boolean (可選) - 是否在新視窗中開啟檔案,預設為 false

  • 返回 Promise<result: boolean>

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

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

提示:window 參數需要 Eagle 4.0 build12 以上版本支援。

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


類:Item

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


實例方法

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

  • 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(options)

在全部列表顯示此檔案

  • options Object (可選) - 開啟選項

    • window boolean (可選) - 是否在新視窗中開啟檔案,預設為 false

  • 返回 Promise<void>

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

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

提示:window 參數需要 Eagle 4.0 build12 以上版本支援。


select()

選中此檔案

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

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

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

提示:呼叫實例方法 select() 會清空當前選中並僅選中此檔案。如需批量選中多個檔案,請使用靜態方法 eagle.item.select(itemIds)

提示:select() 方法需要 Eagle 4.0 build12 以上版本支援。


實例屬性

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

modifiedAt Interger

唯讀,最後修改時間。

let modifiedDate = new Date(item.modifiedAt);

noThumbnail boolean

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

noPreview boolean

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

filePath string

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

fileURL string

唯讀,返回檔案所在路徑之連結(file:///)。

thumbnailPath string

唯讀,返回縮圖路徑。

thumbnailURL string

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

metadataFilePathstring

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

Last updated