> For the complete documentation index, see [llms.txt](https://developer.eagle.cool/plugin-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.eagle.cool/plugin-api/ja-jp/api/tag.md).

# tag（タグ）

```javascript
// すべてのタグを取得
const tags = await eagle.tag.get();

// 名前でタグをフィルタリング
const designTags = await eagle.tag.get({ name: "design" });

// 最近使用されたタグを取得
const recents = await eagle.tag.getRecentTags();

// お気に入りタグを取得
const starred = await eagle.tag.getStarredTags();
```

## メソッド <a href="#z1a5y" id="z1a5y"></a>

## get(options) <a href="#x9nu2" id="x9nu2"></a>

タグを取得します。オプションでフィルタリングが可能です。

* `options` Object (オプション) - クエリ条件
  * `name` string (オプション) - タグ名で曖昧検索、大文字小文字を区別しない
* 戻り値 `Promise<tags: Object[]>` - タグのクエリ結果。

```javascript
// すべてのタグを取得
const tags = await eagle.tag.get();

// 名前でタグをフィルタリング
const filteredTags = await eagle.tag.get({
    name: "design"
});
```

{% hint style="info" %}
ヒント：`name` パラメータは Eagle 4.0 build12 以上のバージョンが必要です。
{% endhint %}

***

## getRecentTags() <a href="#dwsxw" id="dwsxw"></a>

最近使用されたタグを取得します。

* 戻り値 `Promise<tags: Object[]>` - タグのクエリ結果。

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

***

## getStarredTags() <a href="#starred" id="starred"></a>

お気に入りタグ（ユーザーがスターを付けたタグ）を取得します。

* 戻り値 `Promise<tags: Object[]>` - タグのクエリ結果。

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

{% hint style="info" %}
ヒント：`getStarredTags()` メソッドは Eagle 4.0 build18 以上のバージョンが必要です。
{% endhint %}

***

## merge(options) <a href="#merge" id="merge"></a>

タグをマージします：ソースタグをターゲットタグに名前変更し、ソースタグを使用しているすべてのアイテムを自動的に更新します。

* `options` Object - オプションパラメータ
  * `source` string - ソースタグ名（削除されます）
  * `target` string - ターゲットタグ名（マージ後に保持されます）
* 戻り値 `Promise<Object>` - マージ結果
  * `affectedItems` number - 影響を受けたアイテム数
  * `sourceRemoved` boolean - ソースタグが削除されたかどうか

```javascript
// すべての "UI Design" タグを "UI" にマージ
const result = await eagle.tag.merge({
    source: 'UI Design',
    target: 'UI'
});

console.log(`${result.affectedItems} 個のアイテムのタグをマージしました`);
```

{% hint style="info" %}
ヒント：`merge()` メソッドは Eagle 4.0 build18 以上のバージョンが必要です。
{% endhint %}

{% hint style="warning" %}
注意：マージ操作は、ソースタグを使用しているすべてのアイテム、タググループ、お気に入りタグ、履歴タグを更新します。この操作は元に戻せません。
{% endhint %}

***

## クラス：Tag <a href="#tag-class" id="tag-class"></a>

Eagle API `get` によって返されるオブジェクトタイプで、変更・保存機能を提供します。

{% hint style="success" %}
**🦄 ベストプラクティス：** データの安全性を確保するため、Tag インスタンスが提供する `save()` メソッドを使用してデータを変更してください。Eagle リソースライブラリ内のタグデータを直接変更することは避けてください。
{% endhint %}

***

### インスタンスメソッド <a href="#instance-methods" id="instance-methods"></a>

#### **save()**

タグの変更を保存します。現在はタグ名の変更のみサポートしています。

* 戻り値 `Promise<result: boolean>` - `result` 変更が成功したかどうか

```javascript
// すべてのタグを取得
const tags = await eagle.tag.get();

// 変更するタグを見つける
const tag = tags.find(t => t.name === 'old-name');

// タグ名を変更
tag.name = 'new-name';

// 変更を保存
await tag.save();
```

{% hint style="info" %}
ヒント：`save()` メソッドは Eagle 4.0 build12 以上のバージョンが必要です。
{% endhint %}

{% hint style="warning" %}
注意：タグ名を変更すると、そのタグを使用しているすべてのファイルが自動的に新しいタグ名に更新されます。
{% endhint %}

***

### インスタンスプロパティ <a href="#instance-properties" id="instance-properties"></a>

#### **`name` string**

タグ名。このプロパティを変更して `save()` メソッドで保存できます。

#### **`count` number**

読み取り専用、このタグを使用しているファイルの数。

#### **`color` string**

タグの色。

#### **`groups` string\[]**

読み取り専用、タグが属するグループ。

#### **`pinyin` string**

読み取り専用、タグ名のピンイン（検索とソート用）。