カスタム商品リスト¶

目的¶

ホーム、カート、記事本文などから再利用できる商品リストを、WordPress ではなく Vendure 側で商品バリアント単位に管理する。WordPress は本文中の表示位置だけを shortcode で指定し、価格・可視性・商品カード表示は Storefront が Vendure Shop API 経由で解決する。

正本¶

商品リストの正本は Vendure Settings Store の storefront.customProductLists。
1 リストは handle、表示名、表示位置、社内メモ、商品バリアント ID 配列を持つ。
商品の並び順は Dashboard 上で並べ替えた variantIds の順序を正本にする。
WordPress に商品 ID、商品番号、価格、表示可否の正本を置かない。

Dashboard 運用¶

Vendure Dashboard の カタログ > カスタム商品リスト で一覧から対象リストを選び、詳細画面で編集する。

入力項目:

表示名: Storefront 上のセクション見出し。
呼び出し handle: Storefront / WordPress shortcode から参照する安定キー。
表示位置: 無選択 / ホーム / カート。
社内メモ: 運用者向けのメモ。Storefront へは表示しない。
商品: OrderedSearchSelection で商品名・商品番号から検索し、上下移動で表示順を制御する。

表示位置の扱い:

ホーム: Storefront ホームに表示する。
カート: カート面で使うための予約値。表示面を実装する場合も同じ Shop API 契約を使う。
無選択: shortcode や handle 指定でのみ呼び出す。自動表示面には出さない。
ホーム用リストが複数ある場合は、Dashboard の一覧順で複数セクションとして表示する。重複を禁止するより、運用者が意図した順序をそのまま反映する。

Storefront 表示¶

Storefront は Shop API の storefrontCustomProductListsByPlacement(placement: home) を使い、ホーム用リストを一覧順に表示する。各リストの商品は保存済み variantIds を商品バリアントに解決し、現在の顧客に見える商品だけを商品カードとして描画する。

記事・固定ページ・キャンペーン本文などの WordPress 由来 HTML では、本文内 marker を CmsProductListContent が検出し、storefrontCustomProductListByHandle(handle:) で対象リストを解決して商品カードへ差し込む。

非表示・存在しない商品が含まれても Storefront 側で表示可能な商品だけを出す。空になったリストはセクションごと表示しない。

WordPress shortcode¶

WordPress 本文では次の shortcode を使う。

[ritsubi_product_list handle="home-recommended"]

shortcode は Storefront 用 marker のみを出力する。

<div data-ritsubi-product-list-handle="home-recommended"></div>

handle は小文字化し、英数字・_・- 以外を - に正規化する。空の handle は何も出力しない。

API 契約¶

Shop API:

query {
  storefrontCustomProductListsByPlacement(placement: home) {
    handle
    title
    placement
    variantIds
  }
}

query {
  storefrontCustomProductListByHandle(handle: "home-recommended") {
    handle
    title
    placement
    variantIds
  }
}

Admin API は Dashboard 保存用に同じリスト構造を読み書きする。保存には UpdateCatalog、読み取りには ReadCatalog を要求する。

テスト¶

WordPress unit: apps/wordpress-cms/tests/unit/product-list-shortcode.test.js
Storefront unit: apps/storefront/src/components/cms/cms-product-list-content.test.tsx
Dashboard CT: apps/vendure-server/tests/dashboard-ct/ordered-search-selection.ct.spec.tsx
Admin / Shop API: packages/plugins/src/standard-extensions/admin-extensions/admin-extensions.plugin.spec.ts