# smartFolder（スマートフォルダ）

{% hint style="danger" %}
**バージョン要件**：この機能には Eagle 4.0 build22 以降が必要です。
{% endhint %}

```javascript
// フルエントビルダーを使用してスマートフォルダを作成
const sf = await eagle.smartFolder.create({
    name: '大きな PNG',
    conditions: [
        eagle.smartFolder.Condition.create('AND', [
            eagle.smartFolder.rule('width')['>']([1920]),
            eagle.smartFolder.rule('type').equal('png'),
        ])
    ]
});

// プロパティを変更
sf.name = '超大型 PNG';
sf.iconColor = 'blue';

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

{% hint style="success" %}
**🦄 ベストプラクティス：** `getRules()` メソッドで利用可能なフィルタルールスキーマを取得し、`rule()` フルエントビルダーと `Condition.create()` ヘルパーを組み合わせることで、より安全に条件を構築できます。
{% endhint %}

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

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

スマートフォルダを作成

* `options` Object
  * `name` string - スマートフォルダ名
  * `conditions` Object\[] - フィルタ条件
  * `description` string (任意) - 説明
  * `iconColor` string (任意) - アイコンの色
  * `parent` string (任意) - 親スマートフォルダ ID
* 返却 `Promise<smartFolder: SmartFolder>` - `smartFolder` 新しく作成されたスマートフォルダ

```javascript
// JSON 形式で作成
let sf = await eagle.smartFolder.create({
    name: '猫の画像',
    conditions: [
        {
            rules: [
                { property: 'name', method: 'contain', value: 'cat' }
            ],
            match: 'AND'
        }
    ]
});

// フルエントビルダーを使用
let sf2 = await eagle.smartFolder.create({
    name: '大きな画像',
    conditions: [
        eagle.smartFolder.Condition.create('AND', [
            eagle.smartFolder.rule('width')['>']([1920]),
            eagle.smartFolder.rule('height')['>']([1080]),
        ])
    ],
    iconColor: 'blue'
});
```

***

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

指定した条件のスマートフォルダを取得します。

* `options` Object - クエリ条件
  * `id` string (任意) - スマートフォルダ ID
  * `ids` string\[] (任意) - スマートフォルダ ID の配列
* 返却 `Promise<smartFolders: SmartFolder[]>` - `smartFolders` クエリ結果

```javascript
let smartFolders = await eagle.smartFolder.get({
    ids: ['sf_id1', 'sf_id2']
});
```

***

## getAll() <a href="#getall" id="getall"></a>

すべてのスマートフォルダを取得します。

* 返却 `Promise<smartFolders: SmartFolder[]>` - `smartFolders` クエリ結果

```javascript
let smartFolders = await eagle.smartFolder.getAll();
```

***

## getById(smartFolderId) <a href="#getbyid" id="getbyid"></a>

指定した `smartFolderId` のスマートフォルダを取得します。

* `smartFolderId` string - スマートフォルダ ID
* 返却 `Promise<smartFolder: SmartFolder>` - `smartFolder` クエリ結果

```javascript
let sf = await eagle.smartFolder.getById('smart_folder_id');
```

***

## getByIds(smartFolderIds) <a href="#getbyids" id="getbyids"></a>

指定した `smartFolderIds` のスマートフォルダ配列を取得します。

* `smartFolderIds` string\[] - スマートフォルダ ID の配列
* 返却 `Promise<smartFolders: SmartFolder[]>` - `smartFolders` クエリ結果

```javascript
let smartFolders = await eagle.smartFolder.getByIds(['sf_id1', 'sf_id2']);
```

***

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

指定したスマートフォルダを削除します。

* `smartFolderId` string - スマートフォルダ ID
* 返却 `Promise<result: boolean>`

```javascript
await eagle.smartFolder.remove('smart_folder_id');
```

***

## getRules() <a href="#getrules" id="getrules"></a>

利用可能なフィルタルールスキーマを取得します。各プロパティでサポートされている methods、valueType、options などの情報を返却します。

* 返却 `Promise<rules: Object>` - ルールスキーマオブジェクト

```javascript
const rules = await eagle.smartFolder.getRules();
console.log(rules);
// {
//     name: { methods: ['contain', 'equal', ...], valueType: 'string' },
//     width: { methods: ['=', '>=', '>', ...], valueType: 'number' },
//     type: { methods: ['equal', 'unequal'], valueType: 'string', options: [...] },
//     ...
// }
```

{% hint style="info" %}
ヒント：まず `getRules()` で利用可能なプロパティとメソッドを取得し、`rule()` ビルダーで条件を構築すると、無効なフィルタ条件を回避できます。
{% endhint %}

***

## rule(property) <a href="#rule" id="rule"></a>

単一のフィルタルールを構築するフルエントビルダー。利用可能なすべてのメソッドを含むオブジェクトを返却し、メソッドを呼び出すと対応する Rule オブジェクトが生成されます。

* `property` string - フィルタプロパティ（例：`name`、`width`、`type`）
* 返却 `Object` - 利用可能なすべてのメソッドを含むビルダーオブジェクト

```javascript
// 名前に "cat" を含む
eagle.smartFolder.rule('name').contain('cat');

// 幅が 1920 より大きい
eagle.smartFolder.rule('width')['>']([1920]);

// タイプが png と等しい
eagle.smartFolder.rule('type').equal('png');

// レーティングが 3 以上
eagle.smartFolder.rule('rating')['>=']([3]);

// 名前が空
eagle.smartFolder.rule('name').empty();

// Condition.create と組み合わせて使用
let condition = eagle.smartFolder.Condition.create('AND', [
    eagle.smartFolder.rule('name').contain('cat'),
    eagle.smartFolder.rule('width')['>']([1920]),
]);
```

***

## クラス：SmartFolder <a href="#class" id="class"></a>

SmartFolder API の `get` メソッドから返却されるオブジェクト型で、変更と保存の機能を提供します。

```javascript
let sf = await eagle.smartFolder.getById('smart_folder_id');

console.log(sf.id);
console.log(sf.name);

sf.name = '新しい名前';
console.log(sf.name);

await sf.save();
```

{% hint style="success" %}
**🦄 ベストプラクティス：** データの安全性を確保するため、SmartFolder インスタンスの `save()` メソッドを使用して変更を保存してください。
{% endhint %}

***

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

### **save()**

すべての変更を保存

* 返却 `Promise<smartFolder: SmartFolder>` - 更新されたスマートフォルダ

```javascript
let sf = await eagle.smartFolder.getById('smart_folder_id');
sf.name = '新しい名前';
sf.iconColor = 'green';

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

***

### **getItems(options)**

このスマートフォルダのフィルタ条件に一致するアイテムを取得します。

* `options` Object (任意)
  * `orderBy` string (任意) - ソートフィールド
  * `fields` string\[] (任意) - 返却するフィールド
* 返却 `Promise<items: Object[]>` - 条件に一致するアイテムの配列

```javascript
let sf = await eagle.smartFolder.getById('smart_folder_id');

// 条件に一致するすべてのアイテムを取得
let items = await sf.getItems();

// 返却フィールドを指定
let items2 = await sf.getItems({
    fields: ['id', 'name', 'ext', 'width', 'height']
});
```

***

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

`SmartFolder` インスタンスには以下のプロパティが含まれます：

### **`id` string**

読み取り専用。スマートフォルダ ID。

### **`name` string**

スマートフォルダ名。

### **`conditions` Object\[]**

フィルタ条件の配列。

### **`description` string**

スマートフォルダの説明。

### **`icon` string**

読み取り専用。スマートフォルダのアイコン。

### **`iconColor` string**

スマートフォルダのアイコンの色。

```javascript
let sf = await eagle.smartFolder.getById('smart_folder_id');

// アイコンの色を赤に設定
sf.iconColor = eagle.smartFolder.IconColor.Red;

// または文字列値を直接使用
sf.iconColor = 'red';

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

### **`modificationTime` integer**

読み取り専用。最終更新タイムスタンプ。

### **`children` SmartFolder\[]**

読み取り専用。子スマートフォルダの配列。

```javascript
let children = sf.children;
console.log(children[0].name);
```

### **`parent` string**

読み取り専用。親スマートフォルダ ID。

### **`imageCount` integer**

読み取り専用。条件に一致するアイテム数。

***

## ヘルパークラス <a href="#helpers" id="helpers"></a>

### **SmartFolder.Rule**

単一のフィルタルールを記述するルールオブジェクト。

```javascript
// コンストラクタで作成
let rule = new eagle.smartFolder.Rule('name', 'contain', 'cat');

// または rule() フルエントビルダーを使用（推奨）
let rule2 = eagle.smartFolder.rule('name').contain('cat');
```

### **SmartFolder.Condition**

複数のルールと論理演算子を含む条件グループオブジェクト。

```javascript
// Condition.create を使用して作成
let condition = eagle.smartFolder.Condition.create('AND', [
    eagle.smartFolder.rule('name').contain('cat'),
    eagle.smartFolder.rule('width')['>']([1920]),
]);

// 除外条件を作成
let excludeCondition = eagle.smartFolder.Condition.create('OR', [
    eagle.smartFolder.rule('type').equal('gif'),
], 'FALSE');
```

**Condition.create(match, rules, boolean)**

* `match` string - `'AND'` または `'OR'`
* `rules` Object\[] - ルールの配列
* `boolean` string (任意) - `'TRUE'`（包含、デフォルト）または `'FALSE'`（除外）

***

## 静的プロパティ <a href="#static-properties" id="static-properties"></a>

### **`IconColor` Object**

`iconColor` プロパティを設定するための定義済みアイコン色定数を提供します。

```javascript
eagle.smartFolder.IconColor.Red      // 'red'
eagle.smartFolder.IconColor.Orange   // 'orange'
eagle.smartFolder.IconColor.Yellow   // 'yellow'
eagle.smartFolder.IconColor.Green    // 'green'
eagle.smartFolder.IconColor.Aqua     // 'aqua'
eagle.smartFolder.IconColor.Blue     // 'blue'
eagle.smartFolder.IconColor.Purple   // 'purple'
eagle.smartFolder.IconColor.Pink     // 'pink'
```

{% hint style="success" %}
**🦄 ベストプラクティス：** 文字列値を直接使用するのではなく、`eagle.smartFolder.IconColor` 定数を使用することで、より良いコードヒントと型安全性を得られます。
{% endhint %}