アセット
エントリや他のコンテンツタイプと同様に、プロジェクトのメディアと文書ファイル(アセット)を Craft で管理できます。
# ボリューム
すべてのアセットは「ボリューム」にあります。ボリュームは、ストレージコンテナです。ウェブサーバーのディレクトリ、または、Amazon S3 のようなリモートストレージサービスをボリュームにできます。
「設定 > アセット」から、プロジェクトのボリュームを管理できます。
すべてのボリュームは、その中に含まれるアセットがパプリック URL を持つかどうか、持つ場合にベース URL をどうするかを選択できます。
ボリュームのベース URL は環境変数をセットしたり、エイリアスではじめることができます。詳細については、環境設定を参照してください。
# ローカルボリューム
デフォルトで、ボリュームの1つのタイプ「ローカル」を作成できます。ローカルボリュームは、ローカルウェブサーバー上のディレクトリを表します。
ローカルボリュームは、ファイルシステムのパスという1つの設定があります。この設定を利用して、サーバー上のボリュームのルートディレクトリからのパスを定義します。
ボリュームのファイルシステムのパスは環境変数をセットしたり、エイリアスではじめることができます。詳細については、環境設定を参照してください。
Craft もしくは PHP が、作成したディレクトリに書き込み可能でなければならないことに注意してください。
# リモートボリューム
Amazon S3 のようなリモートストレージサービスにアセットを保存したい場合は、インテグレーション機能を提供するプラグインをインストールできます。
- Amazon S3 (opens new window) (first party)
- Google Cloud Storage (opens new window) (first party)
- Rackspace Cloud Files (opens new window) (first party)
- DigitalOcean Spaces (opens new window) (Værsågod)
- fortrabbit Object Storage (opens new window) (fortrabbit)
# アセットのカスタムフィールド
それぞれのアセットボリュームはフィールドレイアウトを持ち、そのボリュームに含まれるアセットが利用可能なフィールドをセットできます。ボリュームの編集中に「フィールドの配置」タブをクリックすることで、ボリュームのフィールドレイアウトを編集できます。
ここで選択したフィールドは、(アセットページまたはアセットフィールドのいずれかにある)アセットをダブルクリックした際に開く、アセットエディタの HUD に表示されます。
# アセットページ
最初のボリュームを作成すると、コントロールパネルのメインナビゲーションに「アセット」項目が追加されます。これをクリックすると、左サイドバーにすべてのボリュームのリスト、メインコンテンツエリアに選択されたボリュームのファイルが表示されたアセットページに移動します。
このページでは、次のことができます。
- 新しいファイルのアップロード
- ファイルのリネーム
- ファイルのタイトルやファイル名の編集
- 選択されたイメージ向けのイメージエディタの起動
- サブフォルダの管理
- (ドラッグアンドドロップによる)別のボリュームやサブフォルダへのファイルの移動
- ファイルの削除
# サブフォルダの管理
左サイドバーのボリュームで右クリックし「新しいサブフォルダー」を選択すると、ボリュームの1つにサブフォルダを作成できます。
サブフォルダを作成すると、その中にファイルをドラックできるようになります。
左サイドバーのサブフォルダで右クリックし「新しいサブフォルダー」を選択すると、サブフォルダの中にネストされたサブフォルダを作成できます。
左サイドバーのサブフォルダを右クリックし「フォルダ名を変更する」を選択すると、サブフォルダをリネームできます。
左サイドバーのサブフォルダを右クリックし「フォルダを削除する」を選択すると、サブフォルダ(および、それに含まれるすべてのアセット)を削除できます。
# アセットインデックスのアップデート
(FTP などの)Craft 外で追加、編集、または、削除されたファイルがある場合、Craft にそのボリュームのインデックスをアップデートするよう伝える必要があります。「ユーティリティ > アセットインデックス」から実行できます。
リモート画像をキャッシュするオプションがあります。(Amazon S3 など)リモートボリュームがない場合は、無視して問題ありません。設定を有効にすると、インデックス処理が完了するまでの時間が長くなりますが、画像変換の生成スピードが向上します。
# 画像変換
Craft はアセットに様々な画像変換を行う手段を提供します。詳細については、画像変換を参照してください。
# イメージエディタ
Craft は画像を変更するための組み込みのイメージエディタを提供します。画像を切り抜いたり、まっすぐにしたり、回転させたり、反転させたり、さらに焦点を選択することもできます。
イメージエディタを起動するには、(アセットページまたはアセットフィールドのいずれかにある)画像をダブルクリックし、HUD の画像プレビューエリアの右上にある「編集」ボタンをクリックします。または、アセットページで任意のアセットを選択し、タスクメニュー(歯車アイコン)から「画像の編集」 を選択することもできます。
# 焦点
画像変換でどのように切り抜くかを決定する際、画像のどの部分を優先させるか Craft が認識するために、画像に焦点をセットします。焦点は、画像変換の「デフォルトの焦点」設定よりも優先されます。
焦点を設定するには、イメージエディタを開き「焦点」ボタンをクリックします。画像の中央に円形のアイコンが表示されます。画像の焦点にしたい場所へ、アイコンをドラッグします。
焦点を削除するには、再度「焦点」ボタンをクリックします。
イメージエディタの他の変更と同様に、画像を保存するまで焦点は有効になりません。
# アセットの照会
アセットクエリを利用して、テンプレートや PHP コード内でアセットを取得できます。
アセットクエリを作成すると、結果を絞り込むためのパラメータをセットできます。さらに、.all()
を呼び出して実行できます。Asset (opens new window) オブジェクトの配列が返されます。
エレメントクエリがどのように機能するかについては、エレメントクエリを参照してください。
# 実例
次の操作を行うことで、「Photos」ボリュームに含まれる画像のサムネイルのリストを表示できます。
craft.assets()
でアセットクエリを作成します。- volume および kind パラメータをセットします。
.all()
でアセットを取得します。- for (opens new window) タグを利用してアセットをループ処理し、サムネイルリストの 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 (opens new window) オブジェクトではなく、データの配列として、マッチしたアセットをクエリが返します。 |
clearCachedResult | キャッシュされた結果をクリアします。 |
dateCreated | アセットの作成日に基づいて、クエリの結果を絞り込みます。 |
dateModified | アセットファイルの最終更新日に基づいて、クエリの結果を絞り込みます。 |
dateUpdated | アセットの最終アップデート日に基づいて、クエリの結果を絞り込みます。 |
filename | アセットのファイル名に基づいて、クエリの結果を絞り込みます。 |
fixedOrder | クエリの結果を id で指定された順序で返します。 |
folderId | フォルダの ID ごとに、アセットが属するフォルダに基づいて、クエリの結果を絞り込みます。 |
height | アセットの画像の高さに基づいて、クエリの結果を絞り込みます。 |
id | アセットの ID に基づいて、クエリの結果を絞り込みます。 |
ignorePlaceholders | craft\services\Elements::setPlaceholderElement() (opens new window) によってセットされたマッチするプレースホルダーエレメントを無視して、データベースに保存されたマッチするアセットをクエリが返します。 |
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 (opens new window) オブジェクトではなく、データの配列として、マッチしたアセットをクエリが返します。
# 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 ではない。 |
特定の順序で結果を返したい場合、fixedOrder と組み合わせることができます。
# ignorePlaceholders
craft\services\Elements::setPlaceholderElement() (opens new window) によってセットされたマッチするプレースホルダーエレメントを無視して、データベースに保存されたマッチするアセットをクエリが返します。
# inReverse
クエリの結果を逆順で返します。
# 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 ではない。 |
# limit
返されるアセットの数を決定します。
# 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() %}
# search
検索クエリにマッチするアセットだけに、クエリの結果を絞り込みます。
このパラメーターがどのように機能するかの詳細については、検索を参照してください。
{# 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 (opens new window) オブジェクト | オブジェクトで表されるサイトから。 |
'*' | すべてのサイトから。 |
複数のサイトを指定した場合、複数のサイトに属するエレメントは複数回返されます。単一のエレメントだけを返したい場合、これと併せて unique を利用してください。
# 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
ソフトデリートされたアセットだけに、クエリの結果を絞り込みます。
# 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 (opens new window) オブジェクト | オブジェクトで表されるユーザーによってアップロードされたもの。 |
{# 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 (opens new window) オブジェクト | オブジェクトで表されるボリューム内。 |
{# 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
)を通常のトランスフォーム定義の後に含めることができます。例えば、
srcset
スタイルのサイズに遭遇すると、トランスフォーム寸法の結果を決定する際、先行する通常のトランスフォーム定義が参照として使用されます。