# item ```javascript eagle.onPluginCreate(async (plugin) => { // Get the currently selected file in the Eagle app let items = await eagle.item.getSelected(); let item = items[0]; // Modify attributes item.name = 'New Name'; item.tags = ['tag1', 'tag2']; // Save modifications await item.save(); }); ``` {% hint style="success" %} **🦄 Best Practice:** To ensure data security, use the `item` API provided `save()` method for data access and modification, and avoid directly modifying the `metadata.json` or any files under the Eagle resource library. {% endhint %} *** ## Methods ## get(options) Universal search method that can get files with specified conditions. * `options` Object - Query conditions * `id` string (optional) - File id * `ids` string\[] (optional) - Array of file ids * `isSelected` boolean (optional) - Currently selected files * `isUntagged` boolean (optional) - Files that have not been tagged * `isUnfiled` boolean (optional) - Files that have not been categorized * `keywords` string\[] (optional) - Contains keywords * `tags` string\[] (optional) - Contains tags * `folders` string\[] (optional) - Contains folders * `ext` string (optional) - Format * `annotation` string (optional) - Annotation * `rating` Integer (optional) - Rating, range from `0 ~ 5` * `url` string (optional) - Source URL * `shape` string (optional) - Shape, options are `square`, `portrait`, `panoramic-portrait`, `landscape`, `panoramic-landscape` * `fields` string\[] (optional) - Specify fields to return, only returning needed data to improve performance * Returns `Promise` - `items` query result ```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" }); // Get only specific fields to improve performance let itemsWithFields = await eagle.item.get({ tags: ["Design"], fields: ["id", "name", "tags", "modifiedAt"] }); ``` {% hint style="info" %} **Performance Tip:** Using the `fields` parameter can significantly improve performance, especially when handling large numbers of files and only partial information is needed. {% endhint %} *** ## getAll() Return all files. * Returns `Promise` - `items` all files ```javascript let items = await eagle.item.getAll(); console.log(items); ``` {% hint style="success" %} **🦄 Best Practice:** If the resource library has a large number of files (e.g., 20W+), avoid calling this method without restrictions to avoid reducing application performance. {% endhint %} *** ## getById(itemId) Return the file with the specified ID. * `itemId` string * Returns `Promise` - `item` the file with the corresponding ID ```javascript let item = await eagle.item.getById('item_id'); console.log(item); ``` ## getByIds(itemIds) Return the files with the specified IDs. * `itemIds` string\[] * Returns `Promise` - `items` the files with the corresponding IDs ```javascript let items = await eagle.item.getByIds(['item_id_1', 'item_id_2']); console.log(items); ``` *** ## getSelected() Return the currently selected files in the application. * Returns `Promise` - `items` selected files ```javascript let selected = await eagle.item.getSelected(); console.log(selected); ``` *** ## getIdsWithModifiedAt() Quickly get IDs and last modified times for all files. * Returns `Promise` - Array of objects containing `id` and `modifiedAt` ```javascript // Get all file IDs and modification times for incremental sync let fileInfo = await eagle.item.getIdsWithModifiedAt(); console.log(fileInfo); // Output: [{ id: "item_id_1", modifiedAt: 1234567890 }, ...] // Example: Incremental sync use case let lastSyncTime = getLastSyncTimestamp(); let allFiles = await eagle.item.getIdsWithModifiedAt(); let modifiedFiles = allFiles.filter(file => file.modifiedAt > lastSyncTime); // Only fetch full data for files that have been modified if (modifiedFiles.length > 0) { let modifiedIds = modifiedFiles.map(file => file.id); let fullData = await eagle.item.getByIds(modifiedIds); // Process modified files... } ``` {% hint style="info" %} **Performance Tip:** This method is specifically optimized for retrieving file IDs and modification times, and is much faster than using the `get()` method to retrieve complete data. {% endhint %} *** ## count(options) Returns the number of files that match the specified query conditions. * `options` Object - Query conditions (same as `get()` method) * `id` string (optional) - File id * `ids` string\[] (optional) - Array of file ids * `isSelected` boolean (optional) - Currently selected files * `isUntagged` boolean (optional) - Files that have not been tagged * `isUnfiled` boolean (optional) - Files that have not been categorized * `keywords` string\[] (optional) - Contains keywords * `tags` string\[] (optional) - Contains tags * `folders` string\[] (optional) - Contains folders * `ext` string (optional) - Format * `annotation` string (optional) - Annotation * `rating` Integer (optional) - Rating, range from `0 ~ 5` * `url` string (optional) - Source URL * `shape` string (optional) - Shape, options are `square`, `portrait`, `panoramic-portrait`, `landscape`, `panoramic-landscape` * Returns `Promise` - `count` number of files matching the query conditions ```javascript // Count all selected files let selectedCount = await eagle.item.count({ isSelected: true }); // Count JPG files let jpgCount = await eagle.item.count({ ext: "jpg" }); // Count files with specific tags let taggedCount = await eagle.item.count({ tags: ["design", "inspiration"] }); console.log(`Selected: ${selectedCount}, JPG: ${jpgCount}, Tagged: ${taggedCount}`); ``` {% hint style="info" %} **Performance Tip:** The `count()` method is optimized for performance and is more efficient than calling `get()` and checking the array length when you only need the number of files. {% endhint %} *** ## countAll() Returns the total number of files in the resource library. * Returns `Promise` - `count` total number of files ```javascript let totalCount = await eagle.item.countAll(); console.log(`Total files in library: ${totalCount}`); ``` {% hint style="info" %} **Performance Tip:** This method is highly optimized and provides a fast way to get the total file count without loading all file data into memory. {% endhint %} *** ## countSelected() Returns the number of currently selected files in the application. * Returns `Promise` - `count` number of selected files ```javascript let selectedCount = await eagle.item.countSelected(); console.log(`Currently selected files: ${selectedCount}`); // Equivalent to: // let selectedCount = await eagle.item.count({ isSelected: true }); ``` {% hint style="info" %} **Performance Tip:** This is a convenience method that provides a faster way to count selected files compared to using `getSelected().length`. {% endhint %} *** ## select(itemIds) Select specified files * `itemIds` string\[] - Array of file IDs to select * Returns `Promise` - `result` whether the selection was successful ```javascript // Select a single file await eagle.item.select(['ITEM_ID_1']); // Select multiple files await eagle.item.select(['ITEM_ID_1', 'ITEM_ID_2', 'ITEM_ID_3']); // Clear selection await eagle.item.select([]); ``` {% hint style="info" %} Note: Calling this method will replace the current selection state, rather than appending to existing selected items. {% endhint %} {% hint style="info" %} Note: The `select()` method requires Eagle 4.0 build12 or higher. {% endhint %} *** ## addFromURL(url, options) Add an image link to Eagle. * `url`string - The image link to add, supports `http`, `https`, `base64` * `options` Object * `name` string (optional) - File name * `website` string (optional) - Source URL * `tags` string\[] (optional) - Tags * `folders` string\[] (optional) - Belonging folder IDs * `annotation` string (optional) - Annotation * Returns `Promise` - `itemId` is the successfully created item 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) Add a base64 image to Eagle. * `base64`string - Base64 format image * `options` Object * `name` string (optional) - File name * `website` string (optional) - Source URL * `tags` string\[] (optional) - Tags * `folders` string\[] (optional) - Belonging folder IDs * `annotation` string (optional) - Annotation * Returns `Promise` - `itemId` is the successfully created item 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) Add files to Eagle from a local file path. * `path`string - The file path to add * `options` Object * `name` string (optional) - File name * `website` string (optional) - Source URL * `tags` string\[] (optional) - Tags * `folders` string\[] (optional) - Belonging folder IDs * `annotation` string (optional) - Annotation * Returns `Promise` - `itemId` is the successfully created item 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) Add a bookmark link to Eagle. * `url`string - The bookmark link to add * `options` Object * `name` string (optional) - Bookmark name * `base64` string (optional) - Custom thumbnail in base64 format * `tags` string\[] (optional) - Tags * `folders` string\[] (optional) - Belonging folder IDs * `annotation` string (optional) - Annotation * Returns `Promise` - `itemId` is the successfully created item 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) Display the file corresponding to `itemId` in the full list * `itemId` string - ID of the file to display * `options` Object (optional) - Open options * `window` boolean (optional) - Whether to open the file in a new window, defaults to `false` * Returns `Promise` ```javascript // Open in current window await eagle.item.open("item_id"); // Open in new window await eagle.item.open("item_id", { window: true }); ``` {% hint style="info" %} Note: The `window` parameter requires Eagle 4.0 build12 or higher. {% endhint %} {% hint style="info" %} Hint: You can also directly call the `open()` method of the item instance to open the file. {% endhint %} *** ## Class: Item Object type returned by Eagle API `get`, provides modification and save features. {% hint style="success" %} **🦄 Best Practice:** To ensure data security, use `save()` method provided by the Item instance for data access and modification. Avoid directly modifying `metadata.json` or any files in the Eagle repository. {% endhint %} *** #### Instance methods ### **save()** Save all modifications * Returns `Promise` - `result` indicates whether the modification was successful ```javascript let item = await eagle.item.getById('item_id'); item.name = 'New Name'; item.tags = ['tag_1', 'tag_2']; // Save changes await item.save(); ``` *** ### **moveToTrash()** Move the file to the trash. * Returns `Promise` - `result` Indicates whether the deletion was successful. ```javascript await item.moveToTrash(); ``` *** ### **replaceFile(filePath)** Replace the original file with the specified file, automatically refreshing the thumbnail without needing to call `refreshThumbnail()` again. {% hint style="success" %} **🦄 Best Practice:** Directly modifying the file you want to change can be risky. Errors or exceptions during the process may cause file corruption and be irreversible. Therefore, to ensure a more robust operation, first save the new version of the file in another location on your computer. After verifying it's correct, use the `replaceFile()` method to replace it. {% endhint %} * `filePath` string - Path of the file to replace * Returns `Promise` - `result` indicates whether the replacement was successful ```javascript let item = await eagle.item.getById('item_id'); let result = await item.replaceFile('new_file_path'); console.log(result); ``` *** ### **refreshThumbnail()** Refreshes the file thumbnail, and updates the properties like file size, color analysis, dimensions, etc. * Returns `Promise` - `result` indicates whether the operation was successful ```javascript let item = await eagle.item.getById('item_id'); let result = await item.refreshThumbnail(); console.log(result); ``` *** ### **setCustomThumbnail(thumbnailPath)** Set a custom thumbnail for the file. * `thumbnailPath` string - Path of the thumbnail to set * Returns `Promise` - `result` indicates whether the replacement was successful ```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+) Add a comment to this item. Supports image rect comments and video timestamp comments. * `commentData` Object - Comment data * `annotation` string (optional) - Comment text * `x` number (optional) - Rect X position (image comment) * `y` number (optional) - Rect Y position (image comment) * `width` number (optional) - Rect width, must > 0 (image comment) * `height` number (optional) - Rect height, must > 0 (image comment) * `duration` number (optional) - Video timestamp in seconds, must >= 0 (video comment) * Returns `Promise` - The newly created comment object ```javascript let item = await eagle.item.getById('item_id'); // Add image rect comment let comment = await item.addComment({ x: 350, y: 480, width: 380, height: 400, annotation: "Face area" }); // Add video timestamp comment let comment = await item.addComment({ duration: 65.5, annotation: "Important scene" }); ``` {% hint style="info" %} Note: This method requires Eagle 4.0 build22 or later. {% endhint %} *** ### **updateComment(commentId, updateData)** (Eagle 4.0 build22+) Update an existing comment. Only the provided fields are updated. * `commentId` string - The comment ID to update * `updateData` Object - Fields to update * `annotation` string (optional) - New comment text * `x` number (optional) - New X position (image comment only) * `y` number (optional) - New Y position (image comment only) * `width` number (optional) - New width (image comment only) * `height` number (optional) - New height (image comment only) * `duration` number (optional) - New timestamp (video comment only) * Returns `Promise` - The updated comment object ```javascript let item = await eagle.item.getById('item_id'); let updated = await item.updateComment('comment_id', { annotation: "Updated text" }); ``` {% hint style="info" %} Note: This method requires Eagle 4.0 build22 or later. {% endhint %} *** ### **removeComment(commentId)** (Eagle 4.0 build22+) Remove a comment from this item. * `commentId` string - The comment ID to remove * Returns `Promise` - Whether the removal was successful ```javascript let item = await eagle.item.getById('item_id'); await item.removeComment('comment_id'); ``` {% hint style="info" %} Note: This method requires Eagle 4.0 build22 or later. {% endhint %} *** ### **open(options)** Display this file in the full list * `options` Object (optional) - Open options * `window` boolean (optional) - Whether to open the file in a new window, defaults to `false` * Returns `Promise` {% hint style="info" %} Hint: You can also directly call the `eagle.item.open(itemId, options)` method to open the file. {% endhint %} ```javascript let item = await eagle.item.getById('item_id'); // Open in current window await item.open(); // Open in new window await item.open({ window: true }); // Equivalent to await eagle.item.open('item_id'); await eagle.item.open('item_id', { window: true }); ``` {% hint style="info" %} Note: The `window` parameter requires Eagle 4.0 build12 or higher. {% endhint %} *** ### **select()** Select this file * Returns `Promise` - `result` whether the selection was successful ```javascript let item = await eagle.item.getById('item_id'); await item.select(); // Equivalent to await eagle.item.select([item.id]); ``` {% hint style="info" %} Note: Calling the instance method `select()` will clear the current selection and select only this file. To batch select multiple files, use the static method `eagle.item.select(itemIds)`. {% endhint %} {% hint style="info" %} Note: The `select()` method requires Eagle 4.0 build12 or higher. {% endhint %} *** #### Instance properties ### **`id` string** Read-only, file ID. ### **`name` string** File name. ### **`ext` string** Read-only, file extension. ### **`width` Interger** Image width. ### **`height` Interger** Image height. ### **`url` string** Source link. ### **`isDeleted` boolean** Read-only, is the file in the trash. ### **`annotation` string** File annotation. ### **`tags` string\[]** File tags. ### **`folders` string\[]** Belonging folder ids. ### **`palettes` Object\[]** Read-only, color palette information. ### **`comments` Object\[]** (Eagle 4.0 build22+) Read-only, item comments/annotations. Use `addComment()`, `updateComment()`, `removeComment()` methods to modify. ```javascript let item = await eagle.item.getById('item_id'); // Read comments console.log(item.comments); // [{ id: "abc", x: 324, y: 810, width: 194, height: 208, annotation: "Face", lastModified: 1774282485915 }] ``` {% hint style="info" %} Note: This property requires Eagle 4.0 build22 or later. {% endhint %} ### **`size` Interger** Read-only, file size. ### **`star` Interger** Rating information, `0 ~ 5`. ### **`importedAt` Interger** Import time (timestamp). Readable and writable, call `save()` after modification. ```javascript // Read import time let date = new Date(item.importedAt); // Modify import time (requires Eagle 4.0 build18+) item.importedAt = Date.now(); item.importedAt = new Date('2024-01-01').getTime(); await item.save(); ``` {% hint style="info" %} Note: Value must be a positive integer timestamp, invalid values will be ignored. This feature requires Eagle 4.0 build18 or later. {% endhint %} ### **`modifiedAt` Interger** Read-only, last modified time. ```javascript let modifiedDate = new Date(item.modifiedAt); console.log(`File was last modified: ${modifiedDate.toLocaleString()}`); ``` ### **`noThumbnail` boolean** Read-only, the file doesn't have a thumbnail. Files without a thumbnail will be previewed using the original file. ### **`noPreview` boolean** Read-only, the file is not supported for double-click preview. ### **`filePath` string** Read-only, returns the file path. ### **`fileURL` string** Read-only, returns the file URL (`file:///`). ### **`thumbnailPath` string** Read-only, returns the thumbnail path. ### **`thumbnailURL` string** Read-only, returns the thumbnail URL (`file:///`). Use this property if you want to display the file in HTML. ### **`metadataFilePath`string** Read-only, location of the `metadata.json` file for this file. {% hint style="success" %} **🦄 Best Practice:** To ensure data security, use the `item` API provided `save()` method for data access and modifications. Avoid directly modifying `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/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.