Liquidでメタフィールドを出力する
型ごとに正しい方法でメタフィールドをLiquidに出力し、未設定時の表示を制御できる
最終確認: 2026-09
解説
受託の現場でなぜ必要か： この回では、型ごとに正しい書き方でメタフィールドをLiquidに出力し、値が未設定のときの表示を制御できるようになります。
受託では、運用者が値を空にしたときに見出しだけ残る定番バグを、ラッパー要素ごとifで囲む癖で防ぎます。
基本形は.valueで値を取り出す
{{ product.metafields.custom.material.value }}が基本の形です。
`.value`で値を取り出します（公式の例もすべて.valueです。旧型のinteger / json_string / stringだけは値が直接返ります）。
未設定のときはnil（値が無い状態）なので、{% if product.metafields.custom.material != blank %}で囲みます。
空チェックは.valueではなくメタフィールド自体に対して行い、見出しとラッパー要素ごと囲みます。
metafield_tagとmetafield_textの使い分け
{{ product.metafields.custom.care | metafield_tag }}は、型に応じたHTMLを返します。
リッチテキストなら<div class="metafield-rich_text_field">、urlなら<a class="metafield-url">、画像なら<img class="metafield-file_reference">です。
HTMLではなくプレーンテキストが欲しいときは、metafield_textを使います。
リストと参照の展開
リスト型は{% for item in product.metafields.custom.related.value %}のように回します。
参照リストなら、itemに参照先のproductオブジェクトがそのまま入ります。file_referenceは、画像なら.value | image_url、PDFなら.value.urlで取り出します。
発展：単位付きと金額・JSON
weightなどの単位付きの型は、.value.valueと.value.unitに分かれます。money型の.valueはmoneyオブジェクトなので、money_with_currencyなどのmoneyフィルタで整形します。
通貨コードは.value.currency.iso_codeから取ります（amount / currency_codeはGraphQL側の名前です）。json型は.valueがパース済みで、キーでアクセスできます。
※ ShopifyはShopify Inc.の商標です。本サイトは個人が制作した非公式の学習教材であり、同社の承認・提携・後援を受けていません。記載内容は2026-09時点のものです。料金・上限値・管理画面のラベルは変わるため、作業の前に公式ドキュメントで確認してください。