# 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 %} *** ## 方法 ## 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` * `fields` string\[] (可選) - 指定返回的欄位，僅返回需要的資料以提升效能 * 返回 `Promise` - `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() 返回所有檔案 * 返回 `Promise` - `items` 所有檔案 ```javascript let items = await eagle.item.getAll(); console.log(items); ``` {% hint style="success" %} **🦄 最佳實踐：** 如果資源庫檔案數量非常多（例：20W+），避免無限制的呼叫此方法，避免造成應用效能的降低。 {% endhint %} *** ## getById(itemId) 返回指定 ID 之檔案 * `itemId` string * 返回 `Promise` - `item` 對應 ID 的檔案 ```javascript let item = await eagle.item.getById('item_id'); console.log(item); ``` ## getByIds(itemIds) 返回指定 IDs 之檔案 * `itemIds` string\[] * 返回 `Promise` - `items` 對應 IDs 的檔案 ```javascript let items = await eagle.item.getByIds(['item_id_1', 'item_id_2']); console.log(items); ``` *** ## getIdsWithModifiedAt() 快速取得所有檔案的 ID 和最後修改時間 * 返回 `Promise` - `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() 返回應用當前選中的檔案 * 返回 `Promise` - `items` 選中之檔案 ```javascript 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 (可選) - 形狀，`square`、`portrait`、`panoramic-portrait`、`landscape`、`panoramic-landscape` * 返回 `Promise` - `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() 快速返回資源庫中所有檔案的總數 * 返回 `Promise` - `count` 所有檔案數量 ```javascript let totalCount = await eagle.item.countAll(); console.log(`資源庫共有 ${totalCount} 個檔案`); ``` {% hint style="info" %} 提示：`countAll()` 針對效能進行了最佳化，比 `getAll()` 後計算陣列長度要快得多。 {% endhint %} *** ## countSelected() 返回應用當前選中的檔案數量 * 返回 `Promise` - `count` 選中的檔案數量 ```javascript let selectedCount = await eagle.item.countSelected(); console.log(`當前選中了 ${selectedCount} 個檔案`); ``` *** ## select(itemIds) 選中指定的檔案 * `itemIds` string\[] - 要選中的檔案 ID 陣列 * 返回 `Promise` - `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) 將圖片連結新增至 Eagle * `url`string - 欲新增圖片連結，支援 `http`、 `https`、 `base64` * `options` Object * `name` string (可選) - 檔案名 * `website` string (可選) - 來源網址 * `tags` string\[] (可選) - 標籤 * `folders` string\[] (可選) - 所屬資料夾 IDs * `annotation` string (可選) - 註解 * 返回 `Promise` - `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) 新增 base64 圖片至 Eagle * `base64`string - base64 格式圖片 * `options` Object * `name` string (可選) - 檔案名 * `website` string (可選) - 來源網址 * `tags` string\[] (可選) - 標籤 * `folders` string\[] (可選) - 所屬資料夾 IDs * `annotation` string (可選) - 註解 * 返回 `Promise` - `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) 從本機檔案路徑新增檔案至 Eagle * `path`string - 欲新增檔案路徑 * `options` Object * `name` string (可選) - 檔案名 * `website` string (可選) - 來源網址 * `tags` string\[] (可選) - 標籤 * `folders` string\[] (可選) - 所屬資料夾 IDs * `annotation` string (可選) - 註解 * 返回 `Promise` - `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) 新增書籤連結至 Eagle * `url`string - 欲新增書籤連結 * `options` Object * `name` string (可選) - 書籤名 * `base64` string (可選) - 自訂縮圖 base64 格式 * `tags` string\[] (可選) - 標籤 * `folders` string\[] (可選) - 所屬資料夾 IDs * `annotation` string (可選) - 註解 * 返回 `Promise` - `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,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` 對應的檔案 * `itemId`string - 欲顯示檔案 ID * `options` Object (可選) - 開啟選項 * `window` boolean (可選) - 是否在新視窗中開啟檔案，預設為 `false` * 返回 `Promise` ```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 由 Eagle API `get`返回的 Object 類型，提供修改、儲存功能。 {% hint style="success" %} **🦄 最佳實踐：** 為了確保數據安全性，請使用 Item 實例提供的 `save()` 方法進行數據的存取與修改，應避免直接修改 Eagle 資源庫底下的 `metadata.json` 或任意檔案。 {% endhint %} *** #### 實例方法 ### **save()** 儲存所有修改 * 返回 `Promise` - `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`是否成功刪除 ```javascript await item.moveToTrash(); ``` *** ### **replaceFile(filePath)** 使用指定檔案替換原檔案，將自動重新整理縮圖，無須再次呼叫 `refreshThumbnail()`。 {% hint style="success" %} **🦄 最佳實踐：** 直接對要更改的檔案進行操作是具有風險的，若過程中出現錯誤或異常，都有可能造成檔案損毀且無法復原。因此，先將新版本檔案儲存在電腦其它路徑，確定無誤後，再使用 `replaceFile()`方法來替換是更穩健的作法。 {% endhint %} * `filePath`string - 欲替換檔案之路徑 * 返回 `Promise` - `result`是否替換成功 ```javascript let item = await eagle.item.getById('item_id'); let result = await item.replaceFile('new_file_path'); console.log(result); ``` *** ### **refreshThumbnail()** 重新重新整理檔案縮圖，同時也會重新取得檔案大小、顏色分析、尺寸等屬性。 * 返回 `Promise` - `result`是否成功 ```javascript let item = await eagle.item.getById('item_id'); let result = await item.refreshThumbnail(); console.log(result); ``` *** ### **setCustomThumbnail(thumbnailPath)** 為檔案設定自定縮圖。 * `thumbnailPath`string - 欲設定縮圖的路徑 * 返回 `Promise` - `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` - 新建立的標註物件 ```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` - 更新後的標註物件 ```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` - 是否移除成功 ```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` {% 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` 是否選中成功 ```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 %} *** #### 實例屬性 ### **`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 %} ### --- # 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/item.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.