このドキュメントは、カートブロックとチェックアウトブロックを拡張するために必要な可動部の高レベルの概要です。

まずは WordPress のブロック開発環境のドキュメントを読み、チュートリアルに従うことをお勧めします：最初のブロックを作るを参照してください。

ブロックテンプレート・パッケージの例

WooCommerce リポジトリにブロックテンプレートの例があります。このドキュメントを読みながらこのテンプレートをセットアップしておくと、説明されているコンセプトの一部を理解するのに役立つかもしれません。サンプルブロックのインストールと実行方法は @woocommerce/extend-cart-checkout-block パッケージドキュメントを参照してください。

(注意: 上記のリンク先のリポジトリにあるコードは、それだけではあまり役に立ちません; そこにあるコードはテンプレートコードです。README の指示に従うと、通常の JS や PHP に変換されます)。

フロントエンドの拡張性

ブロックのフロントエンドを拡張するには、JavaScript を使用しなければなりません。JavaScript ファイルは、それらが効果を発揮する前にキューに入れられ、ページに読み込まれなければなりません。

ビルドシステム

ある拡張モジュールは非常にシンプルで、JavaScript ファイルを1つだけ含むかもしれませんし、他の拡張モジュールは複雑で、コードが複数のファイルに分割されるかもしれません。いずれにせよ、ファイルはバンドルされ、単一の出力ファイルにミニファイされることが推奨されます。拡張モジュールが特定のページでのみ読み込まれるような複数の異なる部分を持つ場合は、バンドル分割を推奨しますが、このドキュメントの範囲外です。

ビルドシステムをセットアップするには、WordPress に合わせ、@wordpress/scriptsと呼ばれる JavaScript パッケージを使用することをお勧めします。このパッケージには build というスクリプトが含まれています。デフォルトでは、wp_enqueue_script を使ってスクリプトを1つの出力ファイルにビルドし、それをキューに入れることができます。

@wordpress/scripts の build スクリプトの基本設定は、プラグインのルートに webpack.config.js ファイルを作成することで上書きすることができます。例のブロックは、基本設定をどのように拡張できるかを示しています。

WooCommerceDependencyExtractionWebpackPlugin

WordPress Dependency Extraction Webpack Pluginおよび
WooCommerce Dependency Extraction Webpack Plugin.

この Webpack プラグインは、以下の目的で使用されます：

• WordPress サイトの共有スクリプトやモジュールとして利用可能な依存関係を外部化します。
  • つまり、@woocommerce/blocks-checkout から何かをインポートすると、コードを変更しなくてもそのパスが window.wc.wcBlocksCheckout に解決されます。これによってコードが読みやすくなり、パッケージがページに一度だけ読み込まれるようになります。
• 各エントリーポイントにアセットファイルを追加し、エントリーポイントの WordPress スクリプトやモジュールの依存リストを含むオブジェクトを宣言します。アセットファイルには、現在のソースコードに対して計算された現在のバージョンも含まれます。

このプラグインが出力する PHP の「アセットファイル」には、依存関係やパスなど、スクリプトが自身を登録するために必要な情報が含まれています。

WooCommerce Dependency Extraction Webpack Plugin を使用して Webpack でビルドされるコードを記述した場合、各エントリーポイントにアセットファイルが出力されます。このアセットファイルはスクリプトに関する情報、特に依存関係やバージョンを含む PHP ファイルです：

<?php
return array(
  'dependencies' => array(
    'react',
    'wc-settings',
    'wp-block-editor',
    'wp-blocks',
    'wp-components',
    'wp-element',
    'wp-i18n',
    'wp-primitives'
  ),
  'version' => '455da4f55e1ac73b6d34'
);

スクリプトをエンキューするときにこのアセットファイルを使用すると、依存関係が正しく読み込まれ、クライアントがスクリプトの最新バージョンを取得できるようになります (バージョンは、スクリプトがキャッシュからではなく、新鮮な状態で取得されるようにするために使用されます)。

<?php
$script_path = '/build/index.js';
$script_url  = plugins_url( $script_path, __FILE__ );

$script_asset_path = dirname( __FILE__ ) . '/build/index.asset.php';
$script_asset      = file_exists( $script_asset_path )
  ? require $script_asset_path
  : [
    'dependencies' => [],
    'version'      => $this->get_file_version( $script_path ),
  ];

wp_register_script(
  'example-blocks-integration-handle',
  $script_url,
  $script_asset['dependencies'],
  $script_asset['version'],
  true
);

IntegrationInterface を使用してスクリプトを正しく登録する方法については、カートとチェックアウト – スクリプト、スタイル、およびデータの処理 ドキュメントを参照してください。

ブロックの作成

サンプルブロックの中には、Checkout にインナーブロックを登録するために必要なファイルを含む「checkout-newsletter-subscription-block」ディレクトリがあります。サンプルのブロックテンプレートは、単一のブロックをインポートしてビルドするように設定されているだけですが、Webpack の設定を変更することで、複数のブロックをビルドすることができます。このドキュメントはサポートしていませんので、代わりに Webpack ドキュメント を参照してください。

チュートリアルで扱われている原則：最初のブロックを作るで説明した原則がここにも当てはまります。

フロントエンドで既存の値を変更する

たとえば、拡張機能がフィルターを通して既存のコンテンツを変更するだけの場合、拡張機能を思い通りに動作させるためにブロックを作成する必要はないかもしれません。

この場合、サンプルブロックからブロックフォルダを削除し、そのディレクトリから読み込まなくなるように Webpack の設定ファイルを修正し、エントリの JavaScript ファイルに必要なコードを含めることができます。

フィルタの使い方の詳細は、Filter RegistryとAvailable Filtersのドキュメントを参照してください。

WooCommerce コンポーネントをエクステンションにインポートする

コンポーネントは @woocommerce/blocks-components からインポートできます（@woocommerce/dependency-extraction-webpack-plugin によって window.wc.blocksComponents に外部化されます）。利用可能なコンポーネントのリストはWooCommerce Storybookの “WooCommerce Blocks -> External components” で確認できます。

Button コンポーネントのインポート例は以下の通り：

import { Button } from '@woocommerce/blocks-components';

const MyComponent = () => {
  return <div class="my-wrapper">
    <Button type="button" />
  </div>
}

WooCommerce ユーティリティと React フックのインポート

一部のチェックアウト・ユーティリティと React フックは、@woocommerce/blocks-checkout から外部で使用できます。利用可能なユーティリティについては、Checkout Utilities ドキュメントを参照してください。

店舗データへのアクセスには、useStoreCart のような内部フックをインポートするよりも、wc/store/...データストアを使用する方が好ましい。

バックエンドの拡張性

チェックアウトプロセス中の情報の変更

カートとチェックアウトブロックのサーバーサイド部分を PHP を使って変更することが可能です。ショートコードのカート/チェックアウト体験からいくつかのアクションやフィルターも動作しますが、すべてではありません。私たちは、どのフックがサポートされているか、また代替フックの概要をまとめたドキュメント（フック代替ドキュメント ）を用意しています。

店舗 API の拡張

Store API の動作方法を変更したり、レスポンス内のデータを拡張したりする必要がある場合は、Store API の拡張を参照してください。