アセット

エントリや他のコンテンツタイプと同様に、プロジェクトのメディアと文書ファイル(アセット)を Craft で管理できます。

# ボリューム

すべてのアセットは「ボリューム」にあります。ボリュームは、ストレージコンテナです。ウェブサーバーのディレクトリ、または、Amazon S3 のようなリモートストレージサービスをボリュームにできます。

「設定 > アセット」から、プロジェクトのボリュームを管理できます。

すべてのボリュームは、その中に含まれるアセットがパプリック URL を持つかどうか、持つ場合にベース URL をどうするかを選択できます。

ボリュームのベース URL は環境変数をセットしたり、エイリアスではじめることができます。詳細については、環境設定を参照してください。

# ローカルボリューム

デフォルトで、ボリュームの1つのタイプ「ローカル」を作成できます。ローカルボリュームは、ローカルウェブサーバー上のディレクトリを表します。

ローカルボリュームは、ファイルシステムのパスという1つの設定があります。この設定を利用して、サーバー上のボリュームのルートディレクトリからのパスを定義します。

ボリュームのファイルシステムのパスは環境変数をセットしたり、エイリアスではじめることができます。詳細については、環境設定を参照してください。

Craft もしくは PHP が、作成したディレクトリに書き込み可能でなければならないことに注意してください。

# リモートボリューム

Amazon S3 のようなリモートストレージサービスにアセットを保存したい場合は、インテグレーション機能を提供するプラグインをインストールできます。

# アセットのカスタムフィールド

それぞれのアセットボリュームはフィールドレイアウトを持ち、そのボリュームに含まれるアセットが利用可能なフィールドをセットできます。ボリュームの編集中に「フィールドの配置」タブをクリックすることで、ボリュームのフィールドレイアウトを編集できます。

ここで選択したフィールドは、(アセットページまたはアセットフィールドのいずれかにある)アセットをダブルクリックした際に開く、アセットエディタの HUD に表示されます。

# アセットページ

最初のボリュームを作成すると、コントロールパネルのメインナビゲーションに「アセット」項目が追加されます。これをクリックすると、左サイドバーにすべてのボリュームのリスト、メインコンテンツエリアに選択されたボリュームのファイルが表示されたアセットページに移動します。

このページでは、次のことができます。

  • 新しいファイルのアップロード
  • ファイルのリネーム
  • ファイルのタイトルやファイル名の編集
  • 選択されたイメージ向けのイメージエディタの起動
  • サブフォルダの管理
  • (ドラッグアンドドロップによる)別のボリュームやサブフォルダへのファイルの移動
  • ファイルの削除

# サブフォルダの管理

左サイドバーのボリュームで右クリックし「新しいサブフォルダー」を選択すると、ボリュームの1つにサブフォルダを作成できます。

サブフォルダを作成すると、その中にファイルをドラックできるようになります。

左サイドバーのサブフォルダで右クリックし「新しいサブフォルダー」を選択すると、サブフォルダの中にネストされたサブフォルダを作成できます。

左サイドバーのサブフォルダを右クリックし「フォルダ名を変更する」を選択すると、サブフォルダをリネームできます。

左サイドバーのサブフォルダを右クリックし「フォルダを削除する」を選択すると、サブフォルダ(および、それに含まれるすべてのアセット)を削除できます。

# アセットインデックスのアップデート

(FTP などの)Craft 外で追加、編集、または、削除されたファイルがある場合、Craft にそのボリュームのインデックスをアップデートするよう伝える必要があります。「ユーティリティ > アセットインデックス」から実行できます。

リモート画像をキャッシュするオプションがあります。(Amazon S3 など)リモートボリュームがない場合は、無視して問題ありません。設定を有効にすると、インデックス処理が完了するまでの時間が長くなりますが、画像変換の生成スピードが向上します。

# 画像変換

Craft はアセットに様々な画像変換を行う手段を提供します。詳細については、画像変換を参照してください。

# イメージエディタ

Craft は画像を変更するための組み込みのイメージエディタを提供します。画像を切り抜いたり、まっすぐにしたり、回転させたり、反転させたり、さらに焦点を選択することもできます。

イメージエディタを起動するには、(アセットページまたはアセットフィールドのいずれかにある)画像をダブルクリックし、HUD の画像プレビューエリアの右上にある「編集」ボタンをクリックします。または、アセットページで任意のアセットを選択し、タスクメニュー(歯車アイコン)から「画像の編集」 を選択することもできます。

# 焦点

画像変換でどのように切り抜くかを決定する際、画像のどの部分を優先させるか Craft が認識するために、画像に焦点をセットします。焦点は、画像変換の「デフォルトの焦点」設定よりも優先されます。

焦点を設定するには、イメージエディタを開き「焦点」ボタンをクリックします。画像の中央に円形のアイコンが表示されます。画像の焦点にしたい場所へ、アイコンをドラッグします。

焦点を削除するには、再度「焦点」ボタンをクリックします。

イメージエディタの他の変更と同様に、画像を保存するまで焦点は有効になりません。

# アセットの照会

アセットクエリを利用して、テンプレートや PHP コード内でアセットを取得できます。

{# Create a new asset query #}
{% set myAssetQuery = craft.assets() %}

アセットクエリを作成すると、結果を絞り込むためのパラメータをセットできます。さらに、.all() を呼び出して実行できます。Asset オブジェクトの配列が返されます。

エレメントクエリがどのように機能するかについては、エレメントクエリを参照してください。

# 実例

次の操作を行うことで、「Photos」ボリュームに含まれる画像のサムネイルのリストを表示できます。

  1. craft.assets() でアセットクエリを作成します。
  2. volume および kind パラメータをセットします。
  3. .all() でアセットを取得します。
  4. for タグを利用してアセットをループ処理し、サムネイルリストの HTML を作成します。
{# Create an asset query with the 'volume' and 'kind' parameters #}
{% set myAssetQuery = craft.assets()
    .volume('photos')
    .kind('image') %}

{# Fetch the assets #}
{% set images = myAssetQuery.all() %}

{# Display the thumbnail list #}
<ul>
    {% for image in images %}
        <li><img src="{{ image.getUrl('thumb') }}" alt="{{ image.title }}"></li>
    {% endfor %}
</ul>

asset.url または asset.getUrl() を使用する場合、そのアセットのソースボリュームは「このボリュームのアセットにはパブリック URL が含まれます」が有効で、「ベース URL」がセットされていなければなりません。さもなければ、結果は常に空になります。

# パラメータ

アセットクエリは、次のパラメータをサポートしています。

パラメータ 説明
anyStatus ステータスに基づくエレメントのフィルタを削除します。
asArray Asset オブジェクトではなく、データの配列として、マッチしたアセットをクエリが返します。
clearCachedResult キャッシュされた結果をクリアします。
dateCreated アセットの作成日に基づいて、クエリの結果を絞り込みます。
dateModified アセットファイルの最終更新日に基づいて、クエリの結果を絞り込みます。
dateUpdated アセットの最終アップデート日に基づいて、クエリの結果を絞り込みます。
filename アセットのファイル名に基づいて、クエリの結果を絞り込みます。
fixedOrder クエリの結果を id で指定された順序で返します。
folderId フォルダの ID ごとに、アセットが属するフォルダに基づいて、クエリの結果を絞り込みます。
height アセットの画像の高さに基づいて、クエリの結果を絞り込みます。
id アセットの ID に基づいて、クエリの結果を絞り込みます。
ignorePlaceholders craft\services\Elements::setPlaceholderElement() によってセットされたマッチするプレースホルダーエレメントを無視して、データベースに保存されたマッチするアセットをクエリが返します。
inReverse クエリの結果を逆順で返します。
includeSubfolders folderId で指定されたフォルダのすべてのサブフォルダにあるアセットを含むよう、クエリの結果を拡張します。
kind アセットのファイルの種類に基づいて、クエリの結果を絞り込みます。
limit 返されるアセットの数を決定します。
offset 結果からスキップされるアセットの数を決定します。
orderBy 返されるアセットの順序を決定します。(空の場合、デフォルトは dateCreated DESC
preferSites unique がセットされている場合、マルチサイトでエレメント照会する際に選択されるべきサイトを決定します
relatedTo 特定の他のエレメントと関連付けられたアセットだけに、クエリの結果を絞り込みます。
search 検索クエリにマッチするアセットだけに、クエリの結果を絞り込みます。
site アセットを照会するサイトを決定します。
siteId サイトの ID ごとに、アセットを照会するサイトを決定します。
size アセットのファイルサイズ(バイト単位)に基づいて、クエリの結果を絞り込みます。
title アセットのタイトルに基づいて、クエリの結果を絞り込みます。
trashed ソフトデリートされたアセットだけに、クエリの結果を絞り込みます。
uid アセットの UID に基づいて、クエリの結果を絞り込みます。
unique クエリによってユニークな ID のエレメントだけが返されるかを決定します。
uploader ユーザーの ID ごとに、アセットをアップロードしたユーザーに基づいて、クエリの結果を絞り込みます。
volume アセットが属するボリュームに基づいて、クエリの結果を絞り込みます。
volumeId ボリュームの ID ごとに、アセットが属するボリュームに基づいて、クエリの結果を絞り込みます。
width アセットの画像の幅に基づいて、クエリの結果を絞り込みます。
with 関連付けられたエレメントを eager-loaded した状態で、マッチしたアセットをクエリが返します。
withTransforms 画像変換インデックスを eager-loaded した状態で、マッチしたアセットをクエリが返します。

# anyStatus

ステータスに基づくエレメントのフィルタを削除します。

{# Fetch all assets, regardless of status #}
{% set assets = craft.assets()
    .anyStatus()
    .all() %}

# asArray

Asset オブジェクトではなく、データの配列として、マッチしたアセットをクエリが返します。

{# Fetch assets as arrays #}
{% set assets = craft.assets()
    .asArray()
    .all() %}

# clearCachedResult

キャッシュされた結果をクリアします。

# dateCreated

アセットの作成日に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するアセット
'>= 2018-04-01' 2018-04-01 以降に作成されたもの。
'< 2018-05-01' 2018-05-01 より前に作成されたもの。
['and', '>= 2018-04-04', '< 2018-05-01'] 2018-04-01 から 2018-05-01 の間に作成されたもの。
{# Fetch assets created last month #}
{% set start = date('first day of last month')|atom %}
{% set end = date('first day of this month')|atom %}

{% set assets = craft.assets()
    .dateCreated(['and', ">= #{start}", "< #{end}"])
    .all() %}

# dateModified

アセットファイルの最終更新日に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するアセット
'>= 2018-04-01' 2018-04-01 以降に更新されたもの。
'< 2018-05-01' 2018-05-01 より前に更新されたもの。
['and', '>= 2018-04-04', '< 2018-05-01'] 2018-04-01 から 2018-05-01 の間に更新されたもの。
{# Fetch assets modified in the last month #}
{% set start = date('30 days ago')|atom %}

{% set assets = craft.assets()
    .dateModified(">= #{start}")
    .all() %}

# dateUpdated

アセットの最終アップデート日に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するアセット
'>= 2018-04-01' 2018-04-01 以降にアップデートされたもの。
'< 2018-05-01' 2018-05-01 より前にアップデートされたもの。
['and', '>= 2018-04-04', '< 2018-05-01'] 2018-04-01 から 2018-05-01 の間にアップデートされたもの。
{# Fetch assets updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}

{% set assets = craft.assets()
    .dateUpdated(">= #{lastWeek}")
    .all() %}

# filename

アセットのファイル名に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するアセット
'foo.jpg' ファイル名が foo.jpg
'foo*' ファイル名が foo ではじまる。
'*.jpg' ファイル名が .jpg で終わる。
'*foo*' ファイル名に foo を含む。
'not *foo*' ファイル名に foo を含まない。
['*foo*', '*bar*'] ファイル名に foo または bar を含む。
['not', '*foo*', '*bar*'] ファイル名に foo または bar を含まない。
{# Fetch all the hi-res images #}
{% set assets = craft.assets()
    .filename('*@2x*')
    .all() %}

# fixedOrder

クエリの結果を id で指定された順序で返します。

{# Fetch assets in a specific order #}
{% set assets = craft.assets()
    .id([1, 2, 3, 4, 5])
    .fixedOrder()
    .all() %}

# folderId

フォルダの ID ごとに、アセットが属するフォルダに基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するアセット
1 ID が 1 のフォルダ内。
'not 1' ID が 1 のフォルダ内ではない。
[1, 2] ID が 1 または 2 のフォルダ内。
['not', 1, 2] ID が 1 または 2 のフォルダ内ではない。
{# Fetch assets in the folder with an ID of 1 #}
{% set assets = craft.assets()
    .folderId(1)
    .all() %}

特定のフォルダのすべてのサブフォルダのアセットを含めたい場合、includeSubfolders と組み合わせることができます。

# height

アセットの画像の高さに基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するアセット
100 高さ 100px。
'>= 100' 少なくとも、高さ 100px。
['>= 100', '<= 1000'] 高さ 100px から 1,000px の間。
{# Fetch XL images #}
{% set assets = craft.assets()
    .kind('image')
    .height('>= 1000')
    .all() %}

# id

アセットの ID に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するアセット
1 ID が 1。
'not 1' ID が 1ではない。
[1, 2] ID が 1 または 2。
['not', 1, 2] ID が 1 または 2 ではない。
{# Fetch the asset by its ID #}
{% set asset = craft.assets()
    .id(1)
    .one() %}

特定の順序で結果を返したい場合、fixedOrder と組み合わせることができます。

# ignorePlaceholders

craft\services\Elements::setPlaceholderElement() によってセットされたマッチするプレースホルダーエレメントを無視して、データベースに保存されたマッチするアセットをクエリが返します。

# inReverse

クエリの結果を逆順で返します。

{# Fetch assets in reverse #}
{% set assets = craft.assets()
    .inReverse()
    .all() %}

# includeSubfolders

folderId で指定されたフォルダのすべてのサブフォルダにあるアセットを含むよう、クエリの結果を拡張します。

{# Fetch assets in the folder with an ID of 1 (including its subfolders) #}
{% set assets = craft.assets()
    .folderId(1)
    .includeSubfolders()
    .all() %}

これは folderId に単一のフォルダ ID がセットされているときだけ、動作します。

# kind

アセットのファイルの種類に基づいて、クエリの結果を絞り込みます。

サポートされるファイルの種類:

  • access
  • audio
  • compressed
  • excel
  • flash
  • html
  • illustrator
  • image
  • javascript
  • json
  • pdf
  • photoshop
  • php
  • powerpoint
  • text
  • video
  • word
  • xml
  • unknown

利用可能な値には、次のものが含まれます。

取得するアセット
'image' ファイルの種類が image
'not image' ファイルの種類が image ではない。
['image', 'pdf'] ファイルの種類が image または pdf
['not', 'image', 'pdf'] ファイルの種類が image または pdf ではない。
{# Fetch all the images #}
{% set assets = craft.assets()
    .kind('image')
    .all() %}

# limit

返されるアセットの数を決定します。

{# Fetch up to 10 assets  #}
{% set assets = craft.assets()
    .limit(10)
    .all() %}

# offset

結果からスキップされるアセットの数を決定します。

{# Fetch all assets except for the first 3 #}
{% set assets = craft.assets()
    .offset(3)
    .all() %}

# orderBy

返されるアセットの順序を決定します。(空の場合、デフォルトは dateCreated DESC

{# Fetch all assets in order of date created #}
{% set assets = craft.assets()
    .orderBy('dateCreated asc')
    .all() %}

# preferSites

unique がセットされている場合、マルチサイトでエレメント照会する際に選択されるべきサイトを決定します

例えば、エレメント “Foo” がサイト A とサイト B に存在し、エレメント “Bar” がサイト B とサイト C に存在し、ここに ['c', 'b', 'a'] がセットされている場合、Foo will はサイト C に対して返され、Bar はサイト B に対して返されます。

これがセットされていない場合、現在のサイトが優先されます。

{# Fetch unique assets from Site A, or Site B if they don’t exist in Site A #}
{% set assets = craft.assets()
    .site('*')
    .unique()
    .preferSites(['a', 'b'])
    .all() %}

# relatedTo

特定の他のエレメントと関連付けられたアセットだけに、クエリの結果を絞り込みます。

このパラメーターがどのように機能するかの詳細については、リレーションを参照してください。

{# Fetch all assets that are related to myCategory #}
{% set assets = craft.assets()
    .relatedTo(myCategory)
    .all() %}

検索クエリにマッチするアセットだけに、クエリの結果を絞り込みます。

このパラメーターがどのように機能するかの詳細については、検索を参照してください。

{# Get the search query from the 'q' query string param #}
{% set searchQuery = craft.app.request.getQueryParam('q') %}

{# Fetch all assets that match the search query #}
{% set assets = craft.assets()
    .search(searchQuery)
    .all() %}

# site

アセットを照会するサイトを決定します。

デフォルトでは、現在のサイトが使用されます。

利用可能な値には、次のものが含まれます。

取得するアセット
'foo' ハンドルが foo のサイトから。
['foo', 'bar'] ハンドルが foo または bar のサイトから。
['not', 'foo', 'bar'] ハンドルが foo または bar のサイトではない。
craft\models\Site オブジェクト オブジェクトで表されるサイトから。
'*' すべてのサイトから。

複数のサイトを指定した場合、複数のサイトに属するエレメントは複数回返されます。単一のエレメントだけを返したい場合、これと併せて unique を利用してください。

{# Fetch assets from the Foo site #}
{% set assets = craft.assets()
    .site('foo')
    .all() %}

# siteId

サイトの ID ごとに、アセットを照会するサイトを決定します。

デフォルトでは、現在のサイトが使用されます。

利用可能な値には、次のものが含まれます。

取得するアセット
1 ID が 1 のサイトから。
[1, 2] ID が 1 または 2 のサイトから。
['not', 1, 2] ID が 1 または 2 のサイトではない。
'*' すべてのサイトから。
{# Fetch assets from the site with an ID of 1 #}
{% set assets = craft.assets()
    .siteId(1)
    .all() %}

# size

アセットのファイルサイズ(バイト単位)に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するアセット
1000 サイズが 1,000 bytes(1KB)。
'< 1000000' サイズが 1,000,000 bytes(1MB)よりも小さい。
['>= 1000', '< 1000000'] サイズが 1KB から 1MB の間。
{# Fetch assets that are smaller than 1KB #}
{% set assets = craft.assets()
    .size('< 1000')
    .all() %}

# title

アセットのタイトルに基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するアセット
'Foo' タイトルが Foo
'Foo*' タイトルが Foo ではじまる。
'*Foo' タイトルが Foo で終わる。
'*Foo*' タイトルが Foo を含む。
'not *Foo*' タイトルが Foo を含まない。
['*Foo*', '*Bar*'] タイトルが Foo または Bar を含む。
['not', '*Foo*', '*Bar*'] タイトルが Foo または Bar を含まない。
{# Fetch assets with a title that contains "Foo" #}
{% set assets = craft.assets()
    .title('*Foo*')
    .all() %}

# trashed

ソフトデリートされたアセットだけに、クエリの結果を絞り込みます。

{# Fetch trashed assets #}
{% set assets = craft.assets()
    .trashed()
    .all() %}

# uid

アセットの UID に基づいて、クエリの結果を絞り込みます。

{# Fetch the asset by its UID #}
{% set asset = craft.assets()
    .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    .one() %}

# unique

クエリによってユニークな ID のエレメントだけが返されるかを決定します。

一度に複数のサイトからエレメントを照会する際、「重複する」結果を望まない場合に使用します。

{# Fetch unique assets across all sites #}
{% set assets = craft.assets()
    .site('*')
    .unique()
    .all() %}

# uploader

ユーザーの ID ごとに、アセットをアップロードしたユーザーに基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するアセット
1 ID が 1 のユーザーによってアップロードされたもの。
craft\elements\User オブジェクト オブジェクトで表されるユーザーによってアップロードされたもの。
{# Fetch assets uploaded by the user with an ID of 1 #}
{% set assets = craft.assets()
    .uploader(1)
    .all() %}

# volume

アセットが属するボリュームに基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するアセット
'foo' ハンドルが foo のボリューム内。
'not foo' ハンドルが foo のボリューム内ではない。
['foo', 'bar'] ハンドルが foo または bar のボリューム内。
['not', 'foo', 'bar'] ハンドルが foo または bar のボリューム内ではない。
volume オブジェクト オブジェクトで表されるボリューム内。
{# Fetch assets in the Foo volume #}
{% set assets = craft.assets()
    .volume('foo')
    .all() %}

# volumeId

ボリュームの ID ごとに、アセットが属するボリュームに基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するアセット
1 ID が 1 のボリューム内。
'not 1' ID が 1 のボリューム内ではない。
[1, 2] ID が 1 または 2 のボリューム内。
['not', 1, 2] ID が 1 または 2 のボリューム内ではない。
':empty:' ボリューム内にまだ何も保管されていない。
{# Fetch assets in the volume with an ID of 1 #}
{% set assets = craft.assets()
    .volumeId(1)
    .all() %}

# width

アセットの画像の幅に基づいて、クエリの結果を絞り込みます。

利用可能な値には、次のものが含まれます。

取得するアセット
100 幅 100px。
'>= 100' 少なくとも、幅 100px。
['>= 100', '<= 1000'] 幅 100px から 1,000px の間。
{# Fetch XL images #}
{% set assets = craft.assets()
    .kind('image')
    .width('>= 1000')
    .all() %}

# with

関連付けられたエレメントを eager-loaded した状態で、マッチしたアセットをクエリが返します。

このパラメーターがどのように機能するかの詳細については、エレメントの Eager-Loading を参照してください。

{# Fetch assets eager-loaded with the "Related" field’s relations #}
{% set assets = craft.assets()
    .with(['related'])
    .all() %}

# withTransforms

画像変換インデックスを eager-loaded した状態で、マッチしたアセットをクエリが返します。

トランスフォームがすでに生成されている場合、一度に複数の変換された画像を表示する際のパフォーマンスが向上します。

トランスフォームは、ハンドルや width、および / または、height プロパティを含むオブジェクトとして指定できます。

srcset スタイルのサイズ(例:100w または 2x)を通常のトランスフォーム定義の後に含めることができます。例えば、

[{width: 1000, height: 600}, '1.5x', '2x', '3x']

srcset スタイルのサイズに遭遇すると、トランスフォーム寸法の結果を決定する際、先行する通常のトランスフォーム定義が参照として使用されます。

{# Fetch assets with the 'thumbnail' and 'hiResThumbnail' transform data preloaded #}
{% set assets = craft.assets()
    .kind('image')
    .withTransforms(['thumbnail', 'hiResThumbnail'])
    .all() %}