item
The eagle.item API allows you to easily query the current content of the resource library or add new content to the resource library.
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();
});🦄 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.
Methods
get(options)
Universal search method that can get files with specified conditions.
optionsObject - Query conditionsidstring (optional) - File ididsstring[] (optional) - Array of file idsisSelectedboolean (optional) - Currently selected filesisUntaggedboolean (optional) - Files that have not been taggedisUnfiledboolean (optional) - Files that have not been categorizedkeywordsstring[] (optional) - Contains keywordstagsstring[] (optional) - Contains tagsfoldersstring[] (optional) - Contains foldersextstring (optional) - Formatannotationstring (optional) - AnnotationratingInteger (optional) - Rating, range from0 ~ 5urlstring (optional) - Source URLshapestring (optional) - Shape, options aresquare,portrait,panoramic-portrait,landscape,panoramic-landscapefieldsstring[] (optional) - Specify fields to return, only returning needed data to improve performance
Returns
Promise<items: Item[]>-itemsquery result
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"]
});getAll()
Return all files.
Returns
Promise<items: Item[]>-itemsall files
let items = await eagle.item.getAll();
console.log(items);🦄 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.
getById(itemId)
Return the file with the specified ID.
itemIdstringReturns
Promise<item: Item>-itemthe file with the corresponding ID
let item = await eagle.item.getById('item_id');
console.log(item);getByIds(itemIds)
Return the files with the specified IDs.
itemIdsstring[]Returns
Promise<items: Item[]>-itemsthe files with the corresponding IDs
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: Item[]>-itemsselected files
let selected = await eagle.item.getSelected();
console.log(selected);getIdsWithModifiedAt()
Quickly get IDs and last modified times for all files.
Returns
Promise<items: Object[]>- Array of objects containingidandmodifiedAt
// 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...
}count(options)
Returns the number of files that match the specified query conditions.
optionsObject - Query conditions (same asget()method)idstring (optional) - File ididsstring[] (optional) - Array of file idsisSelectedboolean (optional) - Currently selected filesisUntaggedboolean (optional) - Files that have not been taggedisUnfiledboolean (optional) - Files that have not been categorizedkeywordsstring[] (optional) - Contains keywordstagsstring[] (optional) - Contains tagsfoldersstring[] (optional) - Contains foldersextstring (optional) - Formatannotationstring (optional) - AnnotationratingInteger (optional) - Rating, range from0 ~ 5urlstring (optional) - Source URLshapestring (optional) - Shape, options aresquare,portrait,panoramic-portrait,landscape,panoramic-landscape
Returns
Promise<count: number>-countnumber of files matching the query conditions
// 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}`);countAll()
Returns the total number of files in the resource library.
Returns
Promise<count: number>-counttotal number of files
let totalCount = await eagle.item.countAll();
console.log(`Total files in library: ${totalCount}`);countSelected()
Returns the number of currently selected files in the application.
Returns
Promise<count: number>-countnumber of selected files
let selectedCount = await eagle.item.countSelected();
console.log(`Currently selected files: ${selectedCount}`);
// Equivalent to:
// let selectedCount = await eagle.item.count({ isSelected: true });select(itemIds)
Select specified files
itemIdsstring[] - Array of file IDs to selectReturns
Promise<result: boolean>-resultwhether the selection was successful
// 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([]);addFromURL(url, options)
Add an image link to Eagle.
urlstring - The image link to add, supportshttp,https,base64optionsObjectnamestring (optional) - File namewebsitestring (optional) - Source URLtagsstring[] (optional) - Tagsfoldersstring[] (optional) - Belonging folder IDsannotationstring (optional) - Annotation
Returns
Promise<itemId: string>-itemIdis the successfully created item 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)
Add a base64 image to Eagle.
base64string - Base64 format imageoptionsObjectnamestring (optional) - File namewebsitestring (optional) - Source URLtagsstring[] (optional) - Tagsfoldersstring[] (optional) - Belonging folder IDsannotationstring (optional) - Annotation
Returns
Promise<itemId: string>-itemIdis the successfully created item 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)
Add files to Eagle from a local file path.
pathstring - The file path to addoptionsObjectnamestring (optional) - File namewebsitestring (optional) - Source URLtagsstring[] (optional) - Tagsfoldersstring[] (optional) - Belonging folder IDsannotationstring (optional) - Annotation
Returns
Promise<itemId: string>-itemIdis the successfully created item 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)
Add a bookmark link to Eagle.
urlstring - The bookmark link to addoptionsObjectnamestring (optional) - Bookmark namebase64string (optional) - Custom thumbnail in base64 formattagsstring[] (optional) - Tagsfoldersstring[] (optional) - Belonging folder IDsannotationstring (optional) - Annotation
Returns
Promise<itemId: string>-itemIdis the successfully created item 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, options)
Display the file corresponding to itemId in the full list
itemIdstring - ID of the file to displayoptionsObject (optional) - Open optionswindowboolean (optional) - Whether to open the file in a new window, defaults tofalse
Returns
Promise<result: boolean>
// Open in current window
await eagle.item.open("item_id");
// Open in new window
await eagle.item.open("item_id", { window: true });Class: Item
Object type returned by Eagle API get, provides modification and save features.
🦄 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.
Instance methods
save()
Save all modifications
Returns
Promise<result: boolean>-resultindicates whether the modification was successful
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: boolean>-resultIndicates whether the deletion was successful.
await item.moveToTrash();replaceFile(filePath)
Replace the original file with the specified file, automatically refreshing the thumbnail without needing to call refreshThumbnail() again.
🦄 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.
filePathstring - Path of the file to replaceReturns
Promise<result: boolean>-resultindicates whether the replacement was successful
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: boolean>-resultindicates whether the operation was successful
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.
thumbnailPathstring - Path of the thumbnail to setReturns
Promise<result: boolean>-resultindicates whether the replacement was successful
let item = await eagle.item.getById('item_id');
let result = await item.setCustomThumbnail('thumbnail_path');
console.log(result);open(options)
Display this file in the full list
optionsObject (optional) - Open optionswindowboolean (optional) - Whether to open the file in a new window, defaults tofalse
Returns
Promise<void>
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 });select()
Select this file
Returns
Promise<result: boolean>-resultwhether the selection was successful
let item = await eagle.item.getById('item_id');
await item.select();
// Equivalent to
await eagle.item.select([item.id]);Instance properties
id string
id stringRead-only, file ID.
name string
name stringFile name.
ext string
ext stringRead-only, file extension.
width Interger
width IntergerImage width.
height Interger
height IntergerImage height.
url string
url stringSource link.
isDeleted boolean
isDeleted booleanRead-only, is the file in the trash.
annotation string
annotation stringFile annotation.
tags string[]
tags string[]File tags.
folders string[]
folders string[]Belonging folder ids.
palettes Object[]
palettes Object[]Read-only, color palette information.
size Interger
size IntergerRead-only, file size.
star Interger
star IntergerRating information, 0 ~ 5.
importedAt Interger
importedAt IntergerRead-only, time the file was added.
let date = new Date(item.importedAt);modifiedAt Interger
modifiedAt IntergerRead-only, last modified time.
let modifiedDate = new Date(item.modifiedAt);
console.log(`File was last modified: ${modifiedDate.toLocaleString()}`);noThumbnail boolean
noThumbnail booleanRead-only, the file doesn't have a thumbnail. Files without a thumbnail will be previewed using the original file.
noPreview boolean
noPreview booleanRead-only, the file is not supported for double-click preview.
filePath string
filePath stringRead-only, returns the file path.
fileURL string
fileURL stringRead-only, returns the file URL (file:///).
thumbnailPath string
thumbnailPath stringRead-only, returns the thumbnail path.
thumbnailURL string
thumbnailURL stringRead-only, returns the thumbnail URL (file:///). Use this property if you want to display the file in HTML.
metadataFilePathstring
metadataFilePathstringRead-only, location of the metadata.json file for this file.
🦄 Best Practice: To ensure data security, use the item API provided save() method for data access and modifications. Avoid directly modifying metadata.json.
Last updated