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.

  • 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

  • Returns Promise<items: Item[]> - items query 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"
});

getAll()

Return all files.

  • Returns Promise<items: Item[]> - items all 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.

  • itemId string

  • Returns Promise<item: Item> - item the 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.

  • itemIds string[]

  • Returns Promise<items: Item[]> - items the 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[]> - items selected files

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

addFromURL(url, options)

Add an image link to Eagle.

  • urlstring - 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: string> - itemId is 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 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: string> - itemId is 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 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: string> - itemId is 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 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: string> - itemId is 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)

Display the file corresponding to itemId in the full list

  • itemId string - ID of the file to display

  • Returns Promise<result: boolean>

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

Hint: You can also directly call the open() method of the item instance to open the file.

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> - result indicates 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> - result Indicates 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.

  • filePath string - Path of the file to replace

  • Returns Promise<result: boolean> - result indicates 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> - result indicates 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.

  • thumbnailPath string - Path of the thumbnail to set

  • Returns Promise<result: boolean> - result indicates whether the replacement was successful

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

console.log(result);

open()

Display this file in the full list

  • Returns Promise<void>

Hint: You can also directly call the eagle.item.open(itemId) method to open the file.

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

// Equivalent to
await eagle.item.open('item_id');

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.

size Interger

Read-only, file size.

star Interger

Rating information, 0 ~ 5.

importedAt Interger

Read-only, time the file was added.

let date = new Date(item.importedAt);

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.

metadataFilePathstring

Read-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.

PreviouseventNextfolder

Last updated