Shopifyのcart.jsの仕組みを初心者向けに解説。数量変更時のローディング表示やAjax更新の流れをわかりやすく把握できます。
Shopifyを触り始めて、気がつけば2年以上が経ちました。
テーマ編集、商品管理、配送設定など、基本的な構築や運用に必要な作業は、だいたい問題なくできるようになったと思います。ですが、どうしても距離を置いてきた分野があります。それが JavaScript（以下、js）です。
「jsって、サイトにちょっとした動きをつけるための言語でしょ？」と思われがちですが、Shopifyではそれだけにとどまりません。
APIを通じてストアのデータベースとやり取りしたり、非同期処理でカート情報をリアルタイム更新したりと、実はテーマの中でもかなり重要な役割を担っております。
その代表例が「cart.js」。正直、js初級レベルの私にとっては“難しさの宝庫”であり、触ろうとしては挫折する‥を繰り返してきた部分でもあります。
そこで今回、私と同じように「cart.jsが難しくて手が止まる」という人に向けて「cart.js」のトリセツ（説明書）をシリーズでまとめていくことにしました。
第1回目の今回は、細かなコード解説に入る前に、まずは「ざっくり全体像」を掴む回です。構文を100%理解しようとするのではなく、「ああ、cart.jsってこういう役割だったのね」と肩の力が少し抜けるようなイメージで読んでもらえたら嬉しいです。
なぜJavaScriptが多用されるの？
Shopifyでテーマを触っていると「Liquidがあるのに、なぜこんなにjsが使われているんだろう？」と感じる場面が多いと思います。
私自身、この疑問をずっと抱えていました。ですが最近ようやく、jsが多用される“理由”が少しずつ見えてきました。
結論から言うと、Shopifyのストアでユーザー体験を高めるには「その場で変化するUI」が欠かせないからです。
たとえば、
・フィルターや絞り込み検索
・並び替えボタンの即時反映
・カート内の数量変更や金額更新
・在庫状況のリアルタイム表示
・非同期通信でのカート追加（ページ遷移なし）
こういった “画面をリロードせずに変化する動き＆データベース更新”はLiquidだけでは実現できません。Liquidは「ページが再読み込みされた時に動く仕組み」なので、ユーザー操作に合わせて瞬時に画面を変えるにはjsが必要になります。
このあたりの詳しい背景は、以下の記事に少し深くまとめています。今回のシリーズと合わせて読むと理解がよりスッキリすると思います。
ShopifyではLiquidがあるのになぜJavaScriptが多用されるの？
なぜ「cart.js」が最重要なのか
Shopify の学習の中でも「cart.js」は避けて通れない存在です。理由はとてもシンプルで「cart.js」は「カートページで起こる挙動」をほぼすべて制御しているからです。
具体的には、カート内の数量調整、合計金額の更新、エラー表示、ドロワーカートとカートページの同期など、“ユーザーが実際に触れる部分”を動かしているのが「cart.js」です。
「え、数量調整のためだけにこんな長いコードが必要なの？」
最初はそう思うかもしれません。私もまったく同じ感想でした。
でも実は、その裏側ではShopifyストア特有の“ユーザー行動に応じたデータ更新”が同時に行われています。
・fetchでAPIにデータ送信
・ストアのDBが更新
・その結果に応じて画面が再描画
・ドロワーカート・ページ・金額・在庫ステータスなどが即時同期
つまり、ユーザーが数量を＋1した瞬間、Shopifyの裏側では「UIの変化＋データベースの更新」が同時に動いています。
これを理解すると「単なる数量変更」ではなく、 Shopifyの非同期処理の全てが凝縮された代表例”が「cart.js」なのだということが見えてきます。
まず「js がどう実装されているか」を押さえよう
「cart.js」のコードを開くと、最初に目に入るのが見慣れない構文だと思います。
class? extends? HTMLElement? customElements?‥
このあたりで手が止まる人も多いはずです。私も最初はそうでした。
Shopifyでは、カート周りの動きを実装する際に「Web Components（ウェブコンポーネント）」がよく使われています。
難しく聞こえますが、ざっくり言うと、
『自分だけの HTMLタグ（カスタムタグ）を作る仕組み』
です。
普段のHTMLに<div>、<p>、<ul>といった「標準タグ」があります。
しかしウェブコンポーネントを使うと、ShopifyはオリジナルのHTMLタグを作ります。
<cart-items></cart-items>このタグは、HTMLの標準仕様には存在しません。Shopifyが“自分たちで作ったタグ”です。
そしてこのタグがページに登場した瞬間「cart.js」で作成した、ウェブコンポーネンで定義した「動き（アクション）」が発動するという仕組みになっています。
①「cart.js」でウェブコンポーネン(クラス)を作成
class CartItems extends HTMLElement {
// ←この中に「カートが読み込まれた時」「数量が変わった時」などの動きを記述
}②このクラスを、HTMLのタグとして登録
customElements.define('cart-items', CartItems);これで、<cart-items></cart-items>というタグがページに置かれた時、Shopifyが上で定義した「CartItems」クラスを実行し、カート更新や情報同期などのアクションが発動する仕組みです。
クラス「CartRemoveButton」について
ここからは「cart.js」がどんな“部品（パーツ）”で構成されているのか、ざっくり全体像を紹介します。
細かいクラスやメソッドの中身まではここでは触れず、役割と仕組みの地図 だけを先に押さえるイメージです。各クラスやメソッドの深掘りは、次回以降の個別記事で丁寧に取り上げていきます。
まず、「CartRemoveButton」について。
class CartRemoveButton extends HTMLElement {
constructor() {
super();
--中略--
});
}
}カートに入っている商品の「削除」を担当する小さなパーツです。ただし、実際には削除 という処理を直接しているわけではなく、実際にやっていることは「数量を0に調整」するだけです。
Shopifyの「cart.js」では、アイテムを削除したい場合でも数量を「0」に変更することで削除扱いにします。
そのため、クラス「CartRemoveButton」は、内部で次の関数を呼び出しています。
updateQuantity(line, quantity, name, variantId)また、この「CartRemoveButton」は、
customElements.define('cart-remove-button', CartRemoveButton);という形で カスタムHTMLタグとして登録 されています。
そのため、テンプレート内に、
<cart-remove-button></cart-remove-button>というタグが登場すると、cart.js で定義した Web コンポーネントが自動的に挿入され、削除ボタンとして機能します。
クラス「CartItems」
次に触れておきたいのが「CartItems」というパーツです。
class CartItems extends HTMLElement {
constructor() {
super();
--以下省略--これは「cart.js」の中でも特にコード量が多く、カート内で行われるさまざまな操作に対する“反応”がまとめられた部分になります。
数量変更、エラーの表示、ドロワーカートとの同期、セクションの再描画など、ユーザーがカート内で行う行動のほとんどに、この「CartItems」が関わっています。そのためコードも長く、最初は圧倒されやすい部分でもあります。
そして、先ほど少しだけ触れた、
updateQuantity(line, quantity, name, variantId)という関数も、この「CartItems」の内部で宣言されています。
では、「CartItems」にはどんな内容が詰められているのか、ざっくり
debouncedOnChange：処理を“わざと遅らせる”ための変数
const debouncedOnChange = debounce((event) => {
this.onChange(event);
--以下、省略--「debouncedOnChange」は、名前のとおり「処理を少し遅らせるための仕組み」。アロー関数で書かれているので難しそうに見えますが、実際には「すぐ実行せず、落ち着いてからまとめて動く」というだけのものです。
なぜ遅らせるかというと、数量ボタンを連打された時などに、サーバーへの通信を毎回行うと負荷が高くなるためです。そこで “少し待ってから1回だけ実行” することで、パフォーマンスを最適化しています。
今回は「処理を遅延させるための変数」と理解しておけば十分です。
connectedCallback():カスタムHTMLが登場した瞬間に動く合図
「connectedCallback()」は、カスタムHTMLタグ（例：<cart-items></cart-items>)が ページ上に出現した瞬間に呼ばれる処理 です。
Webコンポーネントの仕組みのひとつですが「super()」のように必須ではありません。
簡単にいうと「待っていたタグが表示されたよ！これから必要な準備やアクションを始めてね」と指示を出す役割です。
「cart.js」の場合、この中でカートの変動を受け取るための購読（subscribe）を開始し、変化があれば「onCartUpdate（HTMLの再描画）」を実行するように設定しています。
つまり「connectedCallback()」 は「カスタムタグが表示された瞬間、カート更新の準備を整える」ための入口だと覚えておけば十分です。
※なお「disconnectedCallback()」は「connectedCallback()」の“対になる挙動”で、Webコンポーネントが DOMから取り外された（＝関係が断たれた）瞬間 に発火します。つまりWebコンポーネントにおける役割は「DOMとの断絶（＝もうこの要素は不要ですよ）」という合図を出すことです。
onCartUpdate()
「onCartUpdate()」は、カート内で数量変更が行われ、Shopify のデータベースが更新された後に、画面を正しい状態へ差し替えるためのメソッドです。
まず「fetch」を使って最新のカート情報を取得し、その中から変更後のHTMLを取り出します。そのままでは文字列の状態のため、一度「DOMParser」を使ってHTMLとして解析し、置き換え対象の要素に差し替えを行います。
getSectionsToRender()
「getSectionsToRender()」は、「updateQuantity()」の中で使われる「再描画対象パーツの一覧」を用意するメソッドだと考えると分かりやすいです。
カート内で数量が変わったとき「updateQuantity()」は Shopify側のサーバーに接続して最新情報に更新しつつ、ブラウザ側ではどのパーツのHTMLを差し替えるかを決める必要があります。そのときの「このパーツと、このパーツと、このパーツを更新してください」という指示に使われるのが、「getSectionsToRender()」が返す参照キーです。
updateQuantity(line, quantity, name, variantId)
「updateQuantity(line, quantity, name, variantId)」は、「CartItems」クラスの中でも中核となるメソッドです。
カート内で数量が変わったときなどに呼び出され、まずはShopify側に「このラインアイテムが、今こういう数量になりました」と報告し、サーバー上のカート情報を最新の状態に更新することがメインの役割です。その際、返ってきたレスポンスをもとに、カート内の一部パーツを一時的に差し替えて表示を更新する処理もここで行われます（「onCartUpdate()」による最終的な全体更新の“前段階の表示”というイメージです）。
さらに、単に更新するだけでなく、更新時にエラーが起きた場合のエラーメッセージ表示や、カートが空になったときの状態反映なども担当しています。そして、Shopify から返ってきた最新の「cartData」をもとに「publish」を使ってWebコンポーネント側に「カートが更新された」という情報を伝える役割も持っています。
updateLiveRegions(line, message)
「updateLiveRegions(line, message)」は、サーバー側で判定されたエラー情報を受け取り、その内容をユーザーが確認できる形で画面に表示する役割を持っています。数量変更時に在庫が不足していたり、無効な数量が入力された場合など、updateQuantity() が取得したレスポンスの中にエラーメッセージが含まれると、このメソッドが呼び出され、該当するラインアイテムのエリアにエラー内容を反映させます。
getSectionInnerHTML(html, selector)
「getSectionInnerHTML(html, selector) 」は、「updateQuantity()」の中で「とりあえずここだけ先に差し替える」ために使われる補助メソッドです。Shopify から返ってきた html（＝テキストのHTML）を一度「DOMParser」で解釈し、その中から「selector」で指定した要素を探し、その「innerHTML」だけを取り出して返します。
「updateQuantity()」は、この「getSectionInnerHTML()」で取り出した部分的な HTMLを使って、数量が変わった箇所やカートアイコンなど、画面の一部を先に差し替えます。これはあくまでも「onCartUpdate()」が実行される前の「臨時の差し替え処理」で、まずユーザーに素早く画面の変化を見せるための一時的な更新だと考えると分かりやすいです。
enableLoading(line)とdisableLoading(line)
「enableLoading(line)」と「disableLoading(line)」は、「updateQuantity(line, quantity, name, variantId)」の中で呼び出されるメソッドで、どちらも line（カート内の何番目の商品か）を引数として受け取ります。
ここで使われている引数「line」は、「updateQuantity()」が呼び出されるタイミングで「this.dataset.index」によって指定されているインデックスです。つまり「どの行の数量を更新しているのか」を特定するための番号だと考えると分かりやすいです。
「enableLoading(line)」が実行されると、対象の行では一時的に金額表示などが非表示になり、その代わりに、もともとHTML上に用意されていて普段は隠れている「くるくる回るローディングアイコン」が表示されるようになっています。これにより、ユーザーから見ると「いま数量変更の処理中なんだな」ということが視覚的に分かる仕組みになっています。
処理が完了すると「disableLoading(line)」が呼び出されます。これにより、先ほど表示されていたローディングアイコンは非表示に戻され、更新後の新しい金額や小計などが再び表示されます。数量変更のあいだだけローディング表示に切り替え、完了したら新しい情報を見せる、という一連の流れを、この2つのメソッドがうまく分担している形です。
「cart.js」のサイクルまとめ
「cart.js」の各メソッドの役割を個別に見てきましたが、パーツ単体だけでは「全体としてどう動いているのか」が少し分かりにくいところがあります。そこで最後に「cart.js」がどのようなサイクルで動いているのかを、ひとつの流れとして整理しておきます。
「cart.js」のサイクルは、① onChange() → ② updateQuantity() → ③ publish → ④ connectedCallback > onCartUpdate()という順番で動いています。
onChange()
まず「onChange()」は、数量変更などの“変化”が発生したことを感知し、「どの商品がどう変わったか」という情報を「updateQuantity()」に渡す役割を持っています。
updateQuantity()
続いて「updateQuantity()」 が、その情報をもとにfetchでShopifyのサーバーに接続し、カートの内容を更新します。
サーバーから返ってきた最新のHTMLとcartDataを使って、変更された部分の“一次的な差し替え”もこの段階で行われます。「updateQuantity()」は「サーバー更新」と「一次的な画面更新」の両方を担当していると覚えておくと分かりやすいです。
publish → connectedCallback > onCartUpdate()
更新が完了すると、「③ publish」が実行され、変更された「cartData」を含む「cartUpdate」 イベントが発信されます。
これを購読しているのが「 ④ connectedCallback」 で、初回読み込み時に「subscribe」が設定されているため「publish」 が発生すると「onCartUpdate」が呼び出されます。「onCartUpdate」では、サーバーから返ってきたデータを元に、カート画面全体を正しい状態へ整えるための“最終的な差し替え”が行われます。
「onChange」が変化を検知し「updateQuantity」がサーバー更新と一次差し替えを行い、「publish」と「connectedCallback（onCartUpdate」が最終的な画面更新につなげる。この一連の流れを押さえておくと、「cart.js」全体の動きがぐっと理解しやすくなると思います。
***
以上、Shopify「cart.js」のトリセツ第1回目「まずざっくり全体像を掴もう」でした。
各クラスのプロパティやメソッドの役割も多く、コード全体の流れを把握することは決して簡単ではありません。
まずは実際の「cart.js」と見比べながら、「この部分はこういう役割なんだな」という具合に、少しずつ対応関係をつかんでいただければと思います。
