コンテンツへスキップ

登録

Blockstudioを使った独自ブロックの作成はとても簡単です。プラグインは、現在有効なテーマ内のblockstudioフォルダーを検索します。その中で、blockstudioキーを含むblock.jsonファイルがあるすべてのサブフォルダーが登録されます。

block.json

JSON
{
  "name": "blockstudio/native",
  "title": "Native Block",
  "category": "text",
  "icon": "star-filled",
  "description": "Native Blockstudio block.",
  "blockstudio": true
}

テンプレート

テンプレートがないため、現時点ではカスタムブロックは登録されません。修正するには、block.jsonファイルと同じフォルダーにindex.phpを作成します。ブロックの使用時に、その内容が自動的にレンダリングされます。

PHP
<h1>My first native block.</h1>

条件付きロジック

conditionsキーを使うと、条件に応じてブロックを登録できます。このキーは、属性でも使用できるすべてのグローバル変数をサポートしています。

条件一覧を見る

次の例では、現在の投稿タイプがページの場合にのみブロックが登録されます。

JSON
{
  "blockstudio": {
    "conditions": [
      [
        {
          "type": "postType",
          "operator": "==",
          "value": "page"
        }
      ]
    ]
  }
}

プラグインの依存関係

pluginDependenciesキーを使うと、有効なWordPressプラグインにブロックを依存させられます。一覧にあるプラグインが無効な場合、そのブロックは登録時にスキップされます。

依存関係にはWordPressプラグインのスラッグを使用します。

JSON
{
  "blockstudio": {
    "pluginDependencies": [
      "woocommerce",
      "advanced-custom-fields"
    ]
  }
}

プラグインのバージョンを指定するには、オブジェクト形式を使います。バージョン制約には、PHPのversion_compare()と同じ演算子を使います。演算子を付けないバージョンは>=として扱われます。

JSON
{
  "blockstudio": {
    "pluginDependencies": {
      "woocommerce": {
        "version": ">6"
      }
    }
  }
}

カスタムアイコン

ブロック用のカスタムSVGアイコンは、次のように登録できます。

JSON
{
  "blockstudio": {
    "icon": "<svg></svg>"
  }
}

WordPressでは、独自のblock.jsoniconキーにカスタムSVGアイコンを指定できません。ここで指定できるのはDashiconsIDのみです。

標準WordPressブロック

Blockstudioは、Blockstudioディレクトリにある標準WordPressブロックも自動登録します。blockstudioキーがなく、有効なnameプロパティを持つblock.jsonは、WordPressの標準register_block_type()を通じて登録されます。

つまり、@wordpress/create-blockでひな形を作成したブロックをblockstudio/フォルダーに直接配置すれば、Blockstudioブロックと一緒に自動登録できます。プラグインで個別に登録するコードは必要ありません。

コード
blockstudio/
├── hero/
│   ├── block.json          ← Blockstudio block (has "blockstudio" key)
│   └── index.twig
├── my-js-block/
│   ├── block.json          ← Standard WP block (no "blockstudio" key)
│   ├── index.js            ← Compiled editor script
│   ├── index.css
│   ├── style-index.css
│   └── render.php

npx wp-scripts buildでブロックをビルドし、出力フォルダーをBlockstudioディレクトリに入れます。自動的に登録されます。

WordPress7.0のPHP専用ブロックも同様です。autoRegisterのサポートとrender.phpを備えたblock.jsonなら、スクリプトもビルドも不要で、ここに標準ブロックとして登録されます。Core が対象とするのは、string、integer、boolean、enum の属性を持つシンプルなブロックです。インナーブロック、リッチテキスト、メディア、カスタムコントロールが必要になったら、クライアントサイドブロックをひな形から作成するか、blockstudioキーを指定してPHPを使います。

HTML

Blockstudioはアイコン要素のレンダリングにReact要素パーサーを使うため、アイコン文字列内でHTMLを使用できます。

JSON
{
  "blockstudio": {
    "icon": "<div>:-)</div>"
  }
}

カスタムパス

既定では、Blockstudioは現在のテーマまたは子テーマ内のblockstudioフォルダーを再帰的に検索してブロックを探します。この動作は2つの方法で変更できます。

フィルター

PHP
// Custom path within your theme.
add_filter('blockstudio/path', function () {
    return get_template_directory() . '/blocks';
});

// Custom path within a plugin.
add_filter('blockstudio/path', function () {
    return WP_PLUGIN_DIR . '/my-custom-plugin/blocks';
});

合成ファイルシステムや仮想ファイルシステムでは、親パスとオーバーレイパスを個別に追加するのではなく、論理的な検出ソースを使います。論理ソースは、パスごとのシャドーイング、継承された兄弟ファイル、削除、キャッシュの識別、来歴に対応しています。論理検出ソースを参照してください。

インスタンス

上記の方法で不十分な場合は、任意のフォルダーにBlockstudio\Buildクラスのインスタンスを作成できます。

PHP
add_action('init', function () {
  Blockstudio\Build::init([
    'dir' => get_template_directory() . '/client-blocks'
  ]);
});

フィルターメタデータ

ブロックの登録前に、blockstudio/blocks/metaフィルターを使ってメタデータをフィルタリングできます。

PHP
add_filter('blockstudio/blocks/meta', function ($meta, $block) {
    if (str_starts_with($block['name'], 'marketing')) {
        $meta['icon'] = 'megaphone';
    }
    return $meta;
}, 10, 2);

上記の例は内部で使用され、すべてのBlockstudioライブラリ要素に同じアイコンを設定します。