tag

The eagle.tag API allows easy access to the tags in the current application.

// Get all tags
const tags = await eagle.tag.get();

// Filter tags by name
const designTags = await eagle.tag.get({ name: "design" });

// Get recently used tags
const recents = await eagle.tag.getRecentTags();

// Get starred tags
const starred = await eagle.tag.getStarredTags();

Methods

get(options)

Retrieves tags with optional filtering.

• options Object (optional) - Query conditions

  • name string (optional) - Filter tags by name with fuzzy search, case-insensitive

• Returns Promise<tags: Object[]> - the query result for tags.

// Get all tags
const tags = await eagle.tag.get();

// Filter tags by name
const filteredTags = await eagle.tag.get({
    name: "design"
});

Note: The name parameter requires Eagle 4.0 build12 or higher.

---

getRecentTags()

Retrieves the most recently used tags.

• Returns Promise<tags: Object[]> - the query result for tags.

const recents = await eagle.tag.getRecentTags();

---

getStarredTags()

Retrieves starred tags (user's favorite tags).

• Returns Promise<tags: Object[]> - the query result for tags.

const starred = await eagle.tag.getStarredTags();

Note: The getStarredTags() method requires Eagle 4.0 build18 or higher.

---

merge(options)

Merges tags: renames the source tag to the target tag, automatically updating all items using the source tag.

• options Object - Option parameters

  • source string - Source tag name (will be removed)

  • target string - Target tag name (will be kept after merge)

• Returns Promise<Object> - Merge result

  • affectedItems number - Number of affected items

  • sourceRemoved boolean - Whether the source tag was removed

// Merge all "UI Design" tags into "UI"
const result = await eagle.tag.merge({
    source: 'UI Design',
    target: 'UI'
});

console.log(`Merged tags for ${result.affectedItems} items`);

Note: The merge() method requires Eagle 4.0 build18 or higher.

Warning: The merge operation updates all items, tag groups, starred tags, and history tags that use the source tag. This operation is irreversible.

---

Class: Tag

Object type returned by Eagle API get, providing modification and save functionality.

🦄 Best Practice: To ensure data security, use the save() method provided by the Tag instance to modify data. Avoid directly modifying tag data in the Eagle resource library.

---

Instance Methods

save()

Save tag modifications. Currently only supports modifying tag names.

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

// Get all tags
const tags = await eagle.tag.get();

// Find the tag to modify
const tag = tags.find(t => t.name === 'old-name');

// Modify tag name
tag.name = 'new-name';

// Save changes
await tag.save();

Note: The save() method requires Eagle 4.0 build12 or higher.

Warning: After modifying a tag name, all files using that tag will automatically be updated with the new tag name.

---

Instance Properties

name string

Tag name. This property can be modified and saved through the save() method.

count number

Read-only, number of files using this tag.

color string

Tag color.

groups string[]

Read-only, groups the tag belongs to.

pinyin string

Read-only, pinyin of tag name (for search and sorting).