smartFolder（スマートフォルダ）

eagle.smartFolder API を使用すると、スマートフォルダの作成、検索、変更、削除が簡単に行えます。

バージョン要件：この機能には Eagle 4.0 build22 以降が必要です。

// フルエントビルダーを使用してスマートフォルダを作成
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();

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

メソッド

create(options)

スマートフォルダを作成

• options Object

  • name string - スマートフォルダ名

  • conditions Object[] - フィルタ条件

  • description string (任意) - 説明

  • iconColor string (任意) - アイコンの色

  • parent string (任意) - 親スマートフォルダ ID

• 返却 Promise<smartFolder: SmartFolder> - smartFolder 新しく作成されたスマートフォルダ

// 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)

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

• options Object - クエリ条件

  • id string (任意) - スマートフォルダ ID

  • ids string[] (任意) - スマートフォルダ ID の配列

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

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

---

getAll()

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

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

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

---

getById(smartFolderId)

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

• smartFolderId string - スマートフォルダ ID

• 返却 Promise<smartFolder: SmartFolder> - smartFolder クエリ結果

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

---

getByIds(smartFolderIds)

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

• smartFolderIds string[] - スマートフォルダ ID の配列

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

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

---

remove(smartFolderId)

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

• smartFolderId string - スマートフォルダ ID

• 返却 Promise<result: boolean>

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

---

getRules()

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

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

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: [...] },
//     ...
// }

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

---

rule(property)

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

• property string - フィルタプロパティ（例：name、width、type）

• 返却 Object - 利用可能なすべてのメソッドを含むビルダーオブジェクト

// 名前に "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

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

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();

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

---

インスタンスメソッド

save()

すべての変更を保存

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

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[]> - 条件に一致するアイテムの配列

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']
});

---

インスタンスプロパティ

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

id string

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

name string

スマートフォルダ名。

conditions Object[]

フィルタ条件の配列。

description string

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

icon string

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

iconColor string

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

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[]

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

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

parent string

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

imageCount integer

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

---

ヘルパークラス

SmartFolder.Rule

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

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

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

SmartFolder.Condition

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

// 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'（除外）

---

静的プロパティ

IconColor Object

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

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'

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