# item（項目）

```javascript
eagle.onPluginCreate(async (plugin) => {
    // Eagle アプリで現在選択されているファイルを取得
    let items = await eagle.item.getSelected();
    let item = items[0];
    
    // 属性を変更する
    item.name = 'New Name';
    item.tags = ['tag1', 'tag2'];
    
    // 変更を保存する
    await item.save();
});
```

{% hint style="success" %}
**🦄 ベストプラクティス：** データの安全性を確保するために、`item` APIが提供する `save()` メソッドを使用してデータの取得と変更を行い、Eagle リソースリポジトリの `metadata.json` や任意のファイルを直接変更することを避けてください。
{% endhint %}

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

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

万能検索メソッド。指定条件のファイルを取得できます。

* `options` Object - 検索条件
  * `id` string (オプション) - ファイル id
  * `ids` string\[] (オプション) - ファイル id の配列
  * `isSelected` boolean (オプション) - 現在選択されているファイル
  * `isUntagged` boolean (オプション) - 未タグ付け
  * `isUnfiled` boolean (オプション) - 未分類
  * `keywords` string\[] (オプション) - キーワードを含む
  * `tags` string\[] (オプション) - タグを含む
  * `folders` string\[] (オプション) - フォルダを含む
  * `ext` string (オプション) - 形式
  * `annotation` string (オプション) - 注釈
  * `rating` Integer (オプション) - 評価, `0〜5`
  * `url` string (オプション) - ソースリンク
  * `shape` string (オプション) - 形状, `square`、`portrait`、`panoramic-portrait`、`landscape`、`panoramic-landscape`
  * `fields` string\[] (オプション) - 返すフィールドを指定し、必要なデータのみを返すことでパフォーマンスを向上
* 返り値 `Promise<items: Item[]>` - `items` 検索結果

```javascript
let items = await eagle.item.get({
    ids: [],
    isSelected: true,
    isUnfiled: true,
    isUntagged: true,
    keywords: [""],
    ext: "",
    tags: [],
    folders: [],
    shape: "square",
    rating: 5,
    annotation: "",
    url: ""
});


let selected = await eagle.item.get({
    isSelected: true
});

let jpgs = await eagle.item.get({
    ext: "jpg"
});

// 特定のフィールドのみを取得してパフォーマンスを向上
let itemsWithFields = await eagle.item.get({
    tags: ["Design"],
    fields: ["id", "name", "tags", "modifiedAt"]
});
```

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

全てのファイルを返す

* 返り値 `Promise<items: Item[]>` - `items`全てのファイル

```javascript
let items = await eagle.item.getAll();
console.log(items);
```

{% hint style="success" %}
**🦄 ベストプラクティス：** リソースリポジトリのファイル数が非常に多い場合（例：20万件以上）、無制限にこのメソッドを呼び出さないでください。アプリケーションのパフォーマンスが低下する可能性があります。
{% endhint %}

## getById(itemId) <a href="#katrb" id="katrb"></a>

指定のIDのファイルを返す

* `itemId` string
* 返り値 `Promise<item: Item>` - `item`該当IDのファイル

```javascript
let item = await eagle.item.getById('item_id');
console.log(item);
```

## getByIds(itemIds) <a href="#by1ek" id="by1ek"></a>

指定されたIDのファイルを返す

* `itemIds` string\[]
* 返り値 `Promise<items: Item[]>` - `items` 該当IDのファイル

```javascript
let items = await eagle.item.getByIds(['item_id_1', 'item_id_2']);
console.log(items);
```

## getSelected() <a href="#ffgvj" id="ffgvj"></a>

アプリで現在選択されているファイルを返す

* 返り値 `Promise<items: Item[]>` - `items`選択されたファイル

```javascript
let selected = await eagle.item.getSelected();
console.log(selected);
```

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

指定した検索条件に一致するファイルの数を返す

* `options` Object - 検索条件
  * `id` string (オプション) - ファイル id
  * `ids` string\[] (オプション) - ファイル id の配列
  * `isSelected` boolean (オプション) - 現在選択されているファイル
  * `isUntagged` boolean (オプション) - 未タグ付け
  * `isUnfiled` boolean (オプション) - 未分類
  * `keywords` string\[] (オプション) - キーワードを含む
  * `tags` string\[] (オプション) - タグを含む
  * `folders` string\[] (オプション) - フォルダを含む
  * `ext` string (オプション) - 形式
  * `annotation` string (オプション) - 注釈
  * `rating` Integer (オプション) - 評価, `0〜5`
  * `url` string (オプション) - ソースリンク
  * `shape` string (オプション) - 形状, `square`、`portrait`、`panoramic-portrait`、`landscape`、`panoramic-landscape`
* 返り値 `Promise<count: number>` - `count` 検索条件に一致するファイルの数

```javascript
// 特定のタグを持つファイルの数を計算
let tagCount = await eagle.item.count({
    tags: ["design", "ui"]
});

// JPG形式のファイルの数を計算
let jpgCount = await eagle.item.count({
    ext: "jpg"
});

// 選択されたファイルの数を計算
let selectedCount = await eagle.item.count({
    isSelected: true
});

console.log(`選択されたファイル数: ${selectedCount}`);
```

{% hint style="success" %}
**🦄 ベストプラクティス：** このメソッドはパフォーマンスが最適化されており、大量のファイルが含まれるリソースリポジトリでも効率的に動作します。ファイルの実際の内容を読み込まず、数のみを計算するため、高速に結果を取得できます。
{% endhint %}

## countAll() <a href="#countall" id="countall"></a>

リソースリポジトリ内の全ファイル数を返す

* 返り値 `Promise<count: number>` - `count` 全ファイル数

```javascript
let totalCount = await eagle.item.countAll();
console.log(`総ファイル数: ${totalCount}`);
```

{% hint style="success" %}
**🦄 ベストプラクティス：** このメソッドは `getAll()` よりもパフォーマンスが優れており、大量のファイルを含むリソースリポジトリで使用する際に推奨されます。ファイルの内容を読み込まず、数のみを計算するため、メモリ使用量を抑えることができます。
{% endhint %}

## countSelected() <a href="#countselected" id="countselected"></a>

現在選択されているファイルの数を返す

* 返り値 `Promise<count: number>` - `count` 選択されたファイル数

```javascript
let selectedCount = await eagle.item.countSelected();
console.log(`選択されたファイル数: ${selectedCount}`);

// 選択されたファイル数に基づいて処理を分岐
if (selectedCount > 0) {
    console.log(`${selectedCount}個のファイルが選択されています`);
} else {
    console.log("ファイルが選択されていません");
}
```

{% hint style="success" %}
**🦄 ベストプラクティス：** このメソッドは `getSelected()` の軽量版で、選択されたファイルの詳細情報が不要で数のみを知りたい場合に使用することで、パフォーマンスを向上させることができます。
{% endhint %}

`fields` パラメータを使用すると、特に大量のファイルを処理する際に一部の情報のみが必要な場合、パフォーマンスが大幅に向上します。

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

***

## select(itemIds) <a href="#select" id="select"></a>

指定されたファイルを選択する

* `itemIds` string\[] - 選択するファイルIDの配列
* 返り値 `Promise<result: boolean>` - `result` 選択が成功したかどうか

```javascript
// 単一ファイルを選択
await eagle.item.select(['ITEM_ID_1']);

// 複数ファイルを選択
await eagle.item.select(['ITEM_ID_1', 'ITEM_ID_2', 'ITEM_ID_3']);

// 選択をクリア
await eagle.item.select([]);
```

{% hint style="info" %}
ヒント：このメソッドを呼び出すと、現在の選択状態が置き換えられます（既存の選択項目に追加するのではありません）。
{% endhint %}

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

## getIdsWithModifiedAt() <a href="#getidswithmodifiedat" id="getidswithmodifiedat"></a>

すべてのファイルの ID と最終更新時刻を高速に取得

* 返り値 `Promise<items: Object[]>` - `id` と `modifiedAt` を含むオブジェクトの配列

```javascript
// すべてのファイルの ID と更新時刻を取得
let idsWithTimestamps = await eagle.item.getIdsWithModifiedAt();
console.log(idsWithTimestamps);
// [{ id: "item_1", modifiedAt: 1640995200000 }, { id: "item_2", modifiedAt: 1640995300000 }, ...]

// 増分同期用例：最後の同期以降に更新されたファイルを取得
let lastSyncTime = 1640995000000;
let updatedItems = idsWithTimestamps.filter(item => item.modifiedAt > lastSyncTime);
console.log(`${updatedItems.length}個のファイルが更新されました`);

// 更新されたファイルの完全な情報を取得
if (updatedItems.length > 0) {
    let updatedIds = updatedItems.map(item => item.id);
    let fullItems = await eagle.item.getByIds(updatedIds);
    console.log(fullItems);
}
```

{% hint style="success" %}
**🦄 ベストプラクティス：** このメソッドはファイル ID と更新時刻の取得に特化して最適化されており、`get()` メソッドで完全なデータを取得するよりもはるかに高速です。増分同期やファイル変更の監視に最適です。
{% endhint %}

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

## addFromURL(url, options) <a href="#tg9ak" id="tg9ak"></a>

画像リンクを Eagle に追加する

* `url`string - 追加したい画像リンク。 `http` 、 `https` 、 `base64` に対応。
* `options` Object
  * `name` string (オプション) - ファイル名
  * `website` string (オプション) - 送信元のサイト
  * `tags` string\[] (オプション) - タグ
  * `folders` string\[] (オプション) - 所属フォルダの IDs
  * `annotation` string (オプション) - 注釈
* 返り値 `Promise<itemId: string>` - `itemId`正常に作成されたプロジェクトのID

```javascript
const imgURL = 'https://cdn.dribbble.com/userupload/3885520/file/original-ee68b80a6e10edab6f192e1e542da6ed.jpg';
const itemId = await eagle.item.addFromURL(imgURL, { 
    name: 'Camping', 
    website: 'https://dribbble.com/shots/19744134-Camping-2', 
    tags: ["Dribbble", "Illustration"],
    folders: [],
    annotation: 'add from eagle api',
});
```

## addFromBase64(base64, options) <a href="#zmwst" id="zmwst"></a>

base64 画像を Eagle に追加する

* `base64`string - base64形式の画像
* `options` Object
  * `name` string (オプション) - ファイル名
  * `website` string (オプション) - 送信元のサイト
  * `tags` string\[] (オプション) - タグ
  * `folders` string\[] (オプション) - 所属フォルダの IDs
  * `annotation` string (オプション) - 注釈
* 返り値 `Promise<itemId: string>` - `itemId`正常に作成されたプロジェクトのID

```javascript
const base64 = 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNDAgMjM0IiBlbmFibGUtYmFja2dyb3VuZD0ibmV3IDAgMCAyNDAgMjM0Ij48cGF0aCBmaWxsLXJ1bGU9ImV2ZW5vZGQiIGNsaXAtcnVsZT0iZXZlbm9kZCIgZmlsbD0iIzI2MTMwMCIgZD0iTTEwIDEwaDIyMHYyMTMuOTk5aC0yMjB6Ii8+PHBhdGggZD0iTTAgMHYyMzRoMjQwLjAwMXYtMjM0aC0yNDAuMDAxem0xMCAxMGgyMjAuMDAxdjIxNGgtMjIwLjAwMXYtMjE0em03My4yNTIgMTIyLjUwMWwtNy45MiAyOS45ODJjLS4xNjUuODI0LS40OTUgMS4wMTgtMS40ODUgMS4wMThoLTE0LjY4N2MtLjk4OCAwLTEuMTUyLS4zMy0uOTg4LTEuNDg1bDI4LjM4LTk5LjQ0OGMuNDk1LTEuODE1LjgyNS0zLjM3Ny45OS04LjMyOCAwLS42Ni4zMy0uOTkuODI1LS45OWgyMC45NTVjLjY2IDAgLjk5LjE2NSAxLjE1NS45OWwzMS44NDUgMTA3Ljk0Yy4xNjUuODI0IDAgMS4zMi0uODI1IDEuMzJoLTE2LjVjLS44MjQgMC0xLjMxOS0uMTkzLTEuNDg0LS44NTRsLTguMjUtMzAuMTQ2aC0zMi4wMTF6bTI3Ljg4NS0xNi4yNWMtMi44MDUtMTEuMDU2LTkuNDA1LTM1LjI4Ni0xMS44OC00N2gtLjE2NWMtMi4xNDYgMTEuNzE1LTcuNDI1IDMxLjQ5LTExLjU1IDQ3aDIzLjU5NXptNDQuOTkzLTU1LjU3OGMwLTYuNDM1IDQuNDU1LTEwLjIzIDEwLjIzLTEwLjIzIDYuMTA1IDAgMTAuMjMgNC4xMjUgMTAuMjMgMTAuMjMgMCA2LjYtNC4yOSAxMC4yMy0xMC4zOTUgMTAuMjMtNS45NCAwLTEwLjA2NS0zLjYzLTEwLjA2NS0xMC4yM3ptMS4xMiAyMi43MzJjMC0uODI1LjMzLTEuMTU1IDEuMTU1LTEuMTU1aDE1LjY4OWMuODI1IDAgMS4xNTUuMzMgMS4xNTUgMS4xNTV2NzguOTM5YzAgLjgyNi0uMTY1IDEuMTU2LTEuMTU1IDEuMTU2aC0xNS41MjRjLS45OSAwLTEuMzItLjQ5Ni0xLjMyLTEuMzJ2LTc4Ljc3NXoiIGZpbGwtcnVsZT0iZXZlbm9kZCIgY2xpcC1ydWxlPSJldmVub2RkIiBmaWxsPSIjRkY3QzAwIi8+PC9zdmc+';
const itemId = await eagle.item.addFromBase64(base64, { 
    name: 'Illustation Logo', 
    website: 'https://www.eagle.cool/', 
    tags: ["Adobe", "Logo"],
    folders: [],
    annotation: 'ai logo form api',
});
```

## addFromPath(path, options) <a href="#lnsox" id="lnsox"></a>

ローカルファイルパスからファイルを Eagle に追加する

* `path`string - 追加したいファイルのパス
* `options` Object
  * `name` string (オプション) - ファイル名
  * `website` string (オプション) - 送信元のサイト
  * `tags` string\[] (オプション) - タグ
  * `folders` string\[] (オプション) - 所属フォルダの IDs
  * `annotation` string (オプション) - 注釈
* 返り値 `Promise<itemId: string>` - `itemId`正常に作成されたプロジェクトのID

```javascript
const filePath = 'C:\\Users\\User\\Downloads\\ai.svg';
const itemId = await eagle.item.addFromPath(filePath, { 
    name: 'Illustation Logo', 
    website: 'https://www.eagle.cool/', 
    tags: ["Adobe", "Logo"],
    folders: [],
    annotation: 'ai logo form api',
});
```

## addBookmark(url, options) <a href="#atulp" id="atulp"></a>

ブックマークリンクを Eagle に追加する

* `url`string - 追加したいブックマークリンク
* `options` Object
  * `name` string (オプション) - ブックマーク名
  * `base64` string (オプション) - カスタムサムネイル base64 形式
  * `tags` string\[] (オプション) - タグ
  * `folders` string\[] (オプション) - 所属フォルダの IDs
  * `annotation` string (オプション) - 注釈
* 返り値 `Promise<itemId: string>` - `itemId`正常に作成されたプロジェクトのID

```javascript
const bookmarkURL = 'https://www.google.com/';
const itemId = await eagle.item.addBookmark(bookmarkURL, { 
    name: 'Eagle', 
    tags: ["Eagle", "Site"],
    folders: [],
    annotation: 'bookmark form api',
});
```

```javascript
const bookmarkURL = 'https://www.google.com/';
const base64 = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACUAAAAnCAYAAACIVoEIAAAAAXNSR0IArs4c6QAACUFJREFUWAmlWFlzVMcV/u42Gi0w2pEE1miFIIGRkMoowRCbRErKlUqeU5Uqv+UhD6n4yW8pJ1V5i/9AquynuPLisCUEHNtsdkJYBAGMkWWJAhGMomAWIzSjmbvkO31vX90ZCSMlPdW3u8/e55w+t+8A/2cLAHNZf+MNU4tdhluJPoQZmieeaMBaxt/OuD++b1k/c/MuEElKV9nG/KXLF998e+C137zpvpWzrO7AJb680Vo/gnEKJ2X76zzvd68/Z79jd/ziRG3RMUaNIKiIqcoFlK0LnofNm9Y7M/ng1/dtbDICG4ZItoDqB3kceusPzQ9/Or1QaVqv5opir10mAQiEnk0GmYu7m4oBqfGOXTC8n5t25leBu6iECuGzmhlYaO7dhEeGDT/nwoi8VJm2cX3/u5i363utlrbX53M+DD/yh9BEhmj5asmHjAEN56hcagcwGwKvAGVURC1ET4ur5wVo3VCDup4GzC+60Mlj2BaKMzdx7vQ4XvzJqwiq0wiKrlKoZCWFci5L3ZTXCPAjILdKRkZOuzMm1JOy0WSctgxnsWAyJJ6PgBqFt5rw8388gNquPnQM9WGh4C1tTO8wUprUpUDyYPd9X1GaQRBQ3Op+ruuho6sR6U1NcF0aJLL4sBwbjy6PY+KzOxj5wSjydopwyiROaMQD0mWtxtCGEC/waO3TFk7B8DFUGiqQsqbwhInZ6QoLXTs78IQb4sFQlAETKlXI4fSBP6Fr126GtR0LDJuSLo+QLKRVz8SDuBgt8yj9TPos3JXi1x4LiUMGgTEDiz56+9oQ1K9HIGETej6clIU7p47j3jwwOLYXC54StOQV0iiPrTCKDSU4rqXZgpBkFXcvteRcxRp1tWm0bhcv8ERF6MA0YXx5D+eOncDzYz+C09SAxad4aUl2OIs1cCJzKQmuH4WPIEP7MCYkUdLzAb25eTCLxTRPFPMqRBpIOyYm/3IYyLSh91tDyBWZ3JESFT7KEZl6zmnckrpiby2FTxj5izEidWnt0YjWtgzWd7eiQKXSlFNZAgo3JnHl3FUMvTIGr6qKOSF8oSFJcXGikzeeh2pCes2jpKvw+cp1hC9vBFqmge6dncgZLNeSf0LFrVcEHsYPH0Tj1kG0bNuCXLIEkEToYg9FE7UZ4U8o01PBicHSVO3TngqPceglmUsJyHY3w2ltLCkBpuPg4aWzmL4xh/7du1CwHCqSA7PcS6JHwQWn+wowMUhopZm+t5RTChJhxKiqSgfPDdBLYdSUUJ8lwMnN48rR93gSs7h55iQst8jXpqRmwN1GIaScZadLFOtOZcoQvRb6KNFDTylBkTARTQKPxbGrfxP8zDr4UgIiZoeF8s7Jv+KhW4F9P/wObk7ewv3xM7BsvrtiBWKeyAmNLDE0CQupljYSJzotpqywk0HmHo2oq6tC09Z25FkCpCmFJvNq7i6unPwYW1/eh5bBPnR9cy8uHTkK68nj0FsUsJKHxLCkcUqe3oTIZ49skhwXLwhWVLPJyPzoHuxEPlWhfKwFpCwTnx89xHrUiezQAB7mfWzZM4IFowYzJ45BvKhpVzuWh1BMMHmM1dkQw6RLcrdsrEd1thVFlgBlIx8Gw5Of+gSfX53E9u+NophK813OupTJoP+7o7h6+gy82TsI6E0xqESZ3qseiS83WugZINWWckoYiLDpjexgF3LRpUQpYBI7vE1cP3IITduGUd/bw5oltwuwgnvYOPg80q09mDxyEI5lxAYpwyK5JUYIjL3EcAL8oOSWEHKKl9p7W2A1N6hE14LkFvBw/GN8MfsYm/fuQV4MphCFp2SXYd42NoqpT2/gycRVetWJPSGKtfLkqOYrGEwQpcurWTEGqK5O8f3WhbxLAJso9Q0T1vwjTHz4AczGrNylmYV8j0sJYHmQUSp9XU83NuzYhWt/Zs65BcUXqDIhpSKkS44Kx8wR/rCLGSpwrFOinD8pAR3bsnBrangLkPwKjXL4Orl76ii+LPAiaKUwfewQ7EdzcIp52IU8nKj7XEsh/c/9POb+fhwVflHh7UXSSSddPI9glsCiLnKC/ILKbzkuhpSA+sYa1G5u50tV/BAaZPAWgAdzmL54GVZDrzJ0+pMJfHHhNaSqqtVmxKNx46vIr/8Gzu8/gKrD7ypPxrhnTAw5ICzC0iQW6sKWHejGIj3BIkVlhNFmdSKrMmgceBF3Z2bRv2sHgt1D8B/wlNEz8ReDEiUPfrc0tiNYJM1Xc1yG4YjRXzORO76Rz+PC8bfp0WLBaO+VK24rCyWPuHKg5g5QMB1kR0YwO/V7GAtzaNz3Ci98O2I6Rc5HzCZx52oN9qgImPRH9WIRF37Jc1KVdrBxRy9ycsWVgIQyJdFU8+k5u7YencPD+PT9/RjZuhNeppknoHQDyc3EBuq9yaiBWr7AIh0KHTgo5PKKyty+dzuM+hoWQj88ukJLYqHXyS61qGVgEBZP38z7THTWsiRe0+lRH31FE+nWuBI+4oRW00e1E2amrcmIKkBsRCyADEoIudxUJXpfHsWta58hf+MaL1pMR42PhCf5tKIkbMV5tHlFH364Gia/tQheaoqRy1ihKGYvsoJnuntQt3UoLAvyvSgBj/Ayxjzk51Ktn2acwGOc0MtaX110aSc8bkIgUmOFguG6wD8LOve8hHv3HvOS9zeYfB/GgoVeyGQs69qA5FhOo3hFD5t8RKzYFFGZcLmvV2xoxcYXvo2pD4/BePIVDWF+JehKjEzAkzTlc83Dmi3NMFm99bn4euOIFZ4COTe+MMIr8DrMfsR7lMOCKcoFLyO79ohel4wJuhJ4JIPo8DUjk2c1LUBuoUZNBtm9Y7h57izc2dvxdUXTxCOFKmOTY6Rc4Enj1Tx0EEtcdF14llFJfJFhbOzfjgpeV25/cBA2v3iUt0Sh7gmlGqeN0KMYpnqCR/Tww4F/5/CWa/Kx6s5KGVSk0bnv+/j3jRksTP4T8oUTChJh7HwPGolevtY4gQu9vAECFmQ2w75z/pTdMLiHO5TUErtX1+S6ka60kM724dbJ99BT20AZq+cv1xKwID+YuMid8YX8+F/T/3DT68ZM23H+F6EBt7jgWpi7flm+XMt1rWFt+LlbUx+RwRX3VFZsGW63U04K4c1hDYJYVAsF0qd4+VsTWykx/cO/Ib35a2dvE/H4v9IJhWmtCpMiAAAAAElFTkSuQmCC';
const itemId = await eagle.item.addBookmark(bookmarkURL, { 
    name: 'Eagle', 
    base64: base64,
    tags: ["Eagle", "Site"],
    folders: [],
    annotation: 'bookmark form api',
});
```

## open(itemId, options) <a href="#yxkul" id="yxkul"></a>

すべてのリストに `itemId` に対応するファイルを表示する

* `itemId`string - 表示するファイルID
* `options` Object (オプション) - 開くオプション
  * `window` boolean (オプション) - 新しいウィンドウでファイルを開くかどうか、デフォルトは `false`
* 戻り値 `Promise<result：boolean>`

```javascript
// 現在のウィンドウで開く
await eagle.item.open("item_id");

// 新しいウィンドウで開く
await eagle.item.open("item_id", { window: true });
```

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

{% hint style="info" %}
ヒント：ファイルを開くために、itemインスタンスの `open()` メソッドを直接呼び出すこともできます。
{% endhint %}

## クラス：Item <a href="#uezi0" id="uezi0"></a>

Eagle API `get`によって返されるObjectタイプで、変更および保存機能を提供します。

{% hint style="success" %}
**🦄 ベストプラクティス：** データの安全性を確保するために、Itemインスタンスが提供する `save()` メソッドを使用してデータの読み書きと変更を行ってください。Eagle リソースリポジトリの下の `metadata.json` や任意のファイルを直接変更しないでください。
{% endhint %}

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

### **save()**

すべての変更を保存

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

```javascript
let item = await eagle.item.getById('item_id');
item.name = 'New Name';
item.tags = ['tag_1', 'tag_2'];

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

### **moveToTrash()**

ファイルをゴミ箱に移動します。

* 戻り値 `Promise<result：boolean>` - `result`削除が成功したかどうかを示します。

```javascript
await item.moveToTrash();
```

### **replaceFile(filePath)**

指定されたファイルで元のファイルを置き換えます。サムネイルが自動的に更新されるため、`refreshThumbnail()`を再度呼び出す必要はありません。

{% hint style="success" %}
**🦄 ベストプラクティス：** 直接変更するファイルに対して操作を行うことはリスクが伴います。エラーや例外が発生した場合、ファイルが破損して復元不可能になる可能性があります。したがって、新しいバージョンのファイルをコンピュータの他のパスに保存し、確認が取れた後で `replaceFile()` メソッドを使用して置き換えることが、より確実な方法です。
{% endhint %}

* `filePath`string - 履歴置換ファイルのパス
* 戻り値 `Promise<result：boolean>` - `result`置換が成功したかどうか

```javascript
let item = await eagle.item.getById('item_id');
let result = await item.replaceFile('new_file_path');

console.log(result);
```

### **refreshThumbnail()**

ファイルのサムネイルを更新し、ファイルサイズ、色分析、寸法などの属性も再取得します。

* 戻り値 `Promise<result：boolean>` - `result`成功したかどうか

```javascript
let item = await eagle.item.getById('item_id');
let result = await item.refreshThumbnail();

console.log(result);
```

### **setCustomThumbnail(thumbnailPath)**

ファイルにカスタムサムネイルを設定します。

* `thumbnailPath`string - サムネイルのパスを設定します。
* 戻り値 `Promise<result：boolean>` - `result`置換が成功したかどうか

```javascript
let item = await eagle.item.getById('item_id');
let result = await item.setCustomThumbnail('thumbnail_path');

console.log(result);
```

***

### **addComment(commentData)** (Eagle 4.0 build22+)

このアイテムにコメントを追加します。画像矩形コメントと動画タイムスタンプコメントに対応。

* `commentData` Object - コメントデータ
  * `annotation` string (オプション) - コメントテキスト
  * `x` number (オプション) - 矩形の X 位置（画像コメント）
  * `y` number (オプション) - 矩形の Y 位置（画像コメント）
  * `width` number (オプション) - 矩形の幅、0 より大きい必要あり（画像コメント）
  * `height` number (オプション) - 矩形の高さ、0 より大きい必要あり（画像コメント）
  * `duration` number (オプション) - 動画タイムスタンプ（秒）、0 以上である必要あり（動画コメント）
* 戻り値 `Promise<comment: Object>` - 新しく作成されたコメントオブジェクト

```javascript
let item = await eagle.item.getById('item_id');

// 画像矩形コメントを追加
let comment = await item.addComment({
    x: 350, y: 480, width: 380, height: 400,
    annotation: "顔の領域"
});

// 動画タイムスタンプコメントを追加
let comment = await item.addComment({
    duration: 65.5,
    annotation: "重要なシーン"
});
```

{% hint style="info" %}
注意：このメソッドは Eagle 4.0 build22 以降が必要です。
{% endhint %}

***

### **updateComment(commentId, updateData)** (Eagle 4.0 build22+)

既存のコメントを更新します。指定されたフィールドのみ更新されます。

* `commentId` string - 更新するコメント ID
* `updateData` Object - 更新するフィールド
  * `annotation` string (オプション) - 新しいコメントテキスト
  * `x` number (オプション) - 新しい X 位置（画像コメントのみ）
  * `y` number (オプション) - 新しい Y 位置（画像コメントのみ）
  * `width` number (オプション) - 新しい幅（画像コメントのみ）
  * `height` number (オプション) - 新しい高さ（画像コメントのみ）
  * `duration` number (オプション) - 新しいタイムスタンプ（動画コメントのみ）
* 戻り値 `Promise<comment: Object>` - 更新されたコメントオブジェクト

```javascript
let item = await eagle.item.getById('item_id');
let updated = await item.updateComment('comment_id', {
    annotation: "更新されたテキスト"
});
```

{% hint style="info" %}
注意：このメソッドは Eagle 4.0 build22 以降が必要です。
{% endhint %}

***

### **removeComment(commentId)** (Eagle 4.0 build22+)

このアイテムからコメントを削除します。

* `commentId` string - 削除するコメント ID
* 戻り値 `Promise<result: boolean>` - 削除が成功したかどうか

```javascript
let item = await eagle.item.getById('item_id');
await item.removeComment('comment_id');
```

{% hint style="info" %}
注意：このメソッドは Eagle 4.0 build22 以降が必要です。
{% endhint %}

***

### **open(options)**

このファイルをすべてのリストに表示する

* `options` Object (オプション) - 開くオプション
  * `window` boolean (オプション) - 新しいウィンドウでファイルを開くかどうか、デフォルトは `false`
* 戻り値 `Promise<void>`

{% hint style="info" %}
ヒント：ファイルを開くために、`eagle.item.open(itemId, options)` メソッドを直接呼び出すこともできます。
{% endhint %}

```javascript
let item = await eagle.item.getById('item_id');
// 現在のウィンドウで開く
await item.open();

// 新しいウィンドウで開く
await item.open({ window: true });

// 等価
await eagle.item.open('item_id');
await eagle.item.open('item_id', { window: true });
```

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

***

### **select()**

このファイルを選択する

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

```javascript
let item = await eagle.item.getById('item_id');
await item.select();

// 等価
await eagle.item.select([item.id]);
```

{% hint style="info" %}
ヒント：インスタンスメソッド `select()` を呼び出すと、現在の選択がクリアされ、このファイルのみが選択されます。複数のファイルを一括選択する場合は、静的メソッド `eagle.item.select(itemIds)` を使用してください。
{% endhint %}

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

#### インスタンス属性 <a href="#woenk" id="woenk"></a>

### **`id` string**

読み取り専用、ファイルID。

### **`name` string**

ファイル名。

### **`ext` string**

読み取り専用、ファイル拡張子。

### **`width` Interger**

画像の幅。

### **`height` Interger**

画像の高さ。

### **`url` string**

出典リンク。

### **`isDeleted` boolean**

読み取り専用、ファイルがゴミ箱に入っているかどうか。

### **`annotation` string**

ファイルの注釈。

### **`tags` string\[]**

ファイルのタグ。

### **`folders` string\[]**

所属フォルダの ids。

### **`palettes` Object\[]**

読み取り専用、カラーパレット情報。

### **`comments` Object\[]** (Eagle 4.0 build22+)

読み取り専用、アイテムのコメント/アノテーション。変更するには `addComment()`、`updateComment()`、`removeComment()` メソッドを使用してください。

```javascript
let item = await eagle.item.getById('item_id');

// コメントを読み取る
console.log(item.comments);
// [{ id: "abc", x: 324, y: 810, width: 194, height: 208, annotation: "顔", lastModified: 1774282485915 }]
```

{% hint style="info" %}
注意：このプロパティは Eagle 4.0 build22 以降が必要です。
{% endhint %}

### **`size` Interger**

読み取り専用、ファイルサイズ。

### **`star` Interger**

評価情報、`0 ~ 5`。

### **`importedAt` Interger**

インポート時間（タイムスタンプ）。読み書き可能、変更後は `save()` を呼び出して保存。

```javascript
// インポート時間を読み取る
let date = new Date(item.importedAt);

// インポート時間を変更する（Eagle 4.0 build18+ が必要）
item.importedAt = Date.now();
item.importedAt = new Date('2024-01-01').getTime();
await item.save();
```

{% hint style="info" %}
注意：値は正の整数タイムスタンプである必要があり、無効な値は無視されます。この機能には Eagle 4.0 build18 以降が必要です。
{% endhint %}

### **`modifiedAt` Interger**

読み取り専用、最終更新時刻。

```javascript
let modifiedDate = new Date(item.modifiedAt);
console.log(`ファイルは ${modifiedDate.toLocaleString()} に更新されました`);

// ファイルが最近更新されたかチェック
let hourAgo = Date.now() - (60 * 60 * 1000);
if (item.modifiedAt > hourAgo) {
    console.log("このファイルは1時間以内に更新されました");
}
```

### **`noThumbnail` boolean**

読み取り専用、ファイルにサムネイルがないかどうか。サムネイルがないファイルは、元のファイルでのプレビューになります。

### **`noPreview` boolean**

読み取り専用、ファイルがダブルクリックでプレビューに対応しているかどうか。

### **`filePath` string**

読み取り専用、ファイルのパスを返します。

### **`fileURL` string**

読み取り専用、ファイルのパスのリンク（`file:///`）を返します。

### **`thumbnailPath` string**

読み取り専用、サムネイルのパスを返します。

### **`thumbnailURL` string**

読み取り専用、サムネイルのリンク（`file:///`）を返します。HTMLでこのファイルを表示するには、この属性を使用します。

### **`metadataFilePath`string**

読み取り専用、このファイルの `metadata.json` の場所。

{% hint style="success" %}
**🦄 ベストプラクティス：** データの安全性を確保するために、`item` APIが提供する `save()` メソッドを使用してデータの読み書きと変更を行ってください。`metadata.json`を直接変更しないでください。
{% endhint %}

### &#x20;<a href="#nptwx" id="nptwx"></a>


---

# 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/ja-jp/api/item.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.