開発者向け
ストアのために Kyoto を拡張する開発者・制作会社の方と、Kyoto と連携するアプリの開発者の方に向けたページです。コードの変更はサポートの対象外ですが（サポートの範囲）、このページに載せている名前は今後も変えずに維持し、アップデート後も実装が動き続けるようにしています。
コードを編集する前に： テーマを複製し、複製したテーマで作業してください。テーマのファイルへの変更は、ストアが Kyoto をアップデートしたときに新しいバージョンへ引き継がれないため、改めて適用する必要があります。可能な場合は、ファイルを直接編集せずに Custom Liquid のセクションかブロックを使ってください。設定として保存されるので、アップデート後も残ります。
Kyoto の構成
- JSON テンプレート、セクショングループ（ヘッダー、フッター、オーバーレイ）、テーマブロックを使った Online Store 2.0 のテーマです。
- 外部の JavaScript・CSS ライブラリは使っていません。インタラクティブな部分は Web Components で実装し、セクション・ブロック・スニペットはそれぞれ自身の CSS と JavaScript を持っています。
- プログレッシブエンハンスメントを前提にしており、JavaScript なしでも商品の閲覧とカートへの追加ができます。フォームはすべて Shopify 標準のフォームです。
- 色、余白、角丸、動きは、テーマ設定から生成する CSS カスタムプロパティで管理しています。
- アプリとは、27 のセクションで使えるアプリブロック（
@app。一覧はアプリ）とアプリ埋め込みで連携します。テーマのファイルにアプリのコードを書き込む必要はありません。
互換性を保証する名前
以下の名前は Kyoto の公開インターフェースです。マイナー・パッチのアップデートで変更や削除はしません。メジャーバージョンでやむを得ず変更する場合は、その後 2 つのメジャーバージョンの間は旧名称も併用できるようにし、変更内容を更新の履歴に記載します。ここに載っていない内部のクラス名や属性は、バージョンによって変わる可能性があります。
クラスと data 属性
| 名前 | 対象 |
|---|---|
.product-form、[data-product-form] | 商品ページとおすすめ商品セクションの、カートに追加するフォーム |
.price | 価格 |
.product-media | 商品メディアのギャラリー |
.cart-line | カートページとカートドロワーの商品 1 行 |
[data-cart-count] | ヘッダーのカート内商品数 |
[data-cart-form] | カートのフォーム |
[data-cart-native] | 商品フォームに付けると、テーマが送信処理を行わなくなります（ブラウザの通常の送信になります） |
フォームの id
| id | 使い方 |
|---|---|
cart-form | カートページとドロワーのカートフォームです。ページ内のどこに置いても、form="cart-form" を付けた入力欄はカートと一緒に送信されます（独自のカート属性など）。 |
product-form-<section id> | セクションごとの商品フォームです。form="product-form-<section id>" を付けた入力欄は、配置場所に関係なく商品のプロパティ（line item properties）として追加されます。 |
JavaScript のイベント
イベントはすべて document で発火します。
| イベント | detail | 発火するタイミング |
|---|---|---|
variant:change | { variant, previousVariant, sectionId } | お客様が別のバリアントを選んだとき |
cart:updated | { cart, source, item?, items? } | カートが変わったとき。cart は /cart.js のオブジェクト全体で、テーマ自身が発火する場合の source は cart- で始まります。 |
cart:error | { message, status } | 追加や変更に失敗したとき |
cart:refresh（受信側） | なし | 発火するとテーマがカートの表示を再読み込みします。アプリがカートを変更したあとなどに使います |
collection:updated | { url, sectionId } | 絞り込み・並べ替え・もっと見るの操作で商品グリッドが差し替わったとき |
free-shipping:reached | { context } | その訪問中に、送料無料の金額に達したとき |
store:selected | { store } | お客様が店舗セレクターのセクションで店舗を選んだとき |
Shopify 標準のカートイベント（shopify:cart:lines-update、shopify:cart:note-update、shopify:cart:attributes-update、shopify:cart:error、shopify:cart:view）も発火・受信します。アプリがカートを変更してこれらのいずれかを発火すれば、テーマ側でカートの表示を更新します。
window.themeCart
| メソッド | 戻り値 |
|---|---|
add(formData, options?) | Promise<{ ok, cart?, items?, message?, status? }>。商品を追加し、テーマで設定した追加後の動作（ドロワーまたは通知）を行います。 |
change(key, quantity) | 同じ形式。数量を 0 にするとその行を削除します。 |
update(body) | 同じ形式。body は { note?, attributes? } です。 |
refresh() | Promise<{ ok, cart? }>。カートの表示を再読み込みします。 |
どのメソッドも例外を投げません。失敗は ok: false と cart:error イベントで通知します。
CSS カスタムプロパティ
| プロパティ | 値 |
|---|---|
--theme-color-foreground | 本文の文字色 |
--theme-header-height | 固定ヘッダーの高さ。独自の固定要素の位置をずらすときに使います |
--z-header、--z-drawer、--z-modal | テーマが使う重なり順（z-index）の基準値。アプリのレイヤーはこれを基準に配置してください |
多くのセクションとブロックは、サイズの設定を最も外側の要素のカスタムプロパティとしても公開しています（大きさの定規、博物館のラベル、色の面の舞台など）。スタイルシートから見た目を調整でき、詳細は各ファイルのコメントに記載しています。
独自の CSS や JavaScript を追加する
- 小さな追加：Custom Liquid のセクションかブロックを追加し、
<style>や<script>タグを書きます。テンプレートと一緒に保存されるのでアップデート後も残り、テーマエディターから削除できます。 - 大きな変更：複製したテーマで作業し、変更したファイルの一覧を残しておきます。アップデート後に同じ変更を再適用するためです。
Kyoto のすべてのファイルは、先頭のコメントに、そのファイルの役割、読み込む設定、アクセシビリティ上の配慮、JavaScript がない場合の動作を記載しています。