# tagGroup（標籤群組）

```javascript
// 取得所有標籤群組
const tagGroups = (await eagle.tagGroup.get());
```

## 方法 <a href="#z1a5y" id="z1a5y"></a>

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

取得所有標籤群組。

* 返回 `Promise<tagGroups: Object[]>` - tagGroups 查詢結果。

```javascript
const tagGroups = (await eagle.tagGroup.get());
```

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

取得所有標籤群組。

* 返回 `Promise<tagGroup: Object>` - 新建立的標籤群組

```javascript
await eagle.tagGroup.create({
    name: "new group",
    color: "red",
    tags: ["tag1", "tag2"],
    description: "群組描述"  // Eagle 4.0 build18+
});
```

***

**實例方法**

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

保存標籤群組修改。

* 返回 `Promise<tagGroup: Object>` - 保存結果。

```javascript
const tagGroups = (await eagle.tagGroup.get());
const tagGroup = tagGroups[0];

tagGroup.name = "new name";
tagGroup.color = "red"; // red, orange, yellow, green, aqua, blue, purple, pink
tagGroup.tags = ["tag1", "tag2"];
tagGroup.description = "群組描述";  // Eagle 4.0 build18+

await tagGroup.save();
```

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

刪除標籤群組。

* 返回 `Promise<result: boolean>` - result是否刪除成功

```javascript
const tagGroups = (await eagle.tagGroup.get());
const tagGroup = tagGroups[0];

await tagGroup.remove();
```

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

增量添加標籤到群組，不需要傳入完整的標籤陣列。

* `options` Object - 選項參數
  * `tags` string\[] - 要添加的標籤名稱陣列
  * `removeFromSource` boolean (可選) - 是否從原群組移除標籤，預設 `false`
    * `false`：僅添加標籤（標籤可同時存在多個群組）
    * `true`：移動標籤（從原群組移除）
* 返回 `Promise<tagGroup: Object>` - 更新後的標籤群組

```javascript
const tagGroups = (await eagle.tagGroup.get());
const tagGroup = tagGroups[0];

// 添加標籤（允許同時存在多個群組）
await tagGroup.addTags({
    tags: ['UI', 'UX', 'Typography']
});

// 移動標籤（從原群組移除）
await tagGroup.addTags({
    tags: ['Branding'],
    removeFromSource: true
});
```

{% hint style="info" %}
提示：`addTags()` 方法需要 Eagle 4.0 build18 以上版本支援。
{% endhint %}

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

從群組移除指定標籤。

* `options` Object - 選項參數
  * `tags` string\[] - 要移除的標籤名稱陣列
* 返回 `Promise<tagGroup: Object>` - 更新後的標籤群組

```javascript
const tagGroups = (await eagle.tagGroup.get());
const tagGroup = tagGroups[0];

// 從群組移除標籤
await tagGroup.removeTags({
    tags: ['Outdated', 'Draft']
});
```

{% hint style="info" %}
提示：`removeTags()` 方法需要 Eagle 4.0 build18 以上版本支援。
{% endhint %}

{% hint style="warning" %}
注意：此方法僅從群組移除標籤，不會刪除標籤本身或影響素材上的標籤。
{% 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/zh-tw/api/tag-group.md?ask=<question>
```

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.