コンテンツへスキップ

v7への移行

このガイドでは、Blockstudio 6から7へのアップグレード時に必要な変更について説明します。

ESモジュールのインポート

Blockstudio 7では、ESモジュールのインポートに新しいnpm:プレフィックスが導入され、Denoのnpmspecifier規約に準拠します。

変更前(v6):

JavaScript
import { h, render } from "blockstudio/preact@10.15.1";
import htm from "blockstudio/htm@3.1.1";
import confetti from "blockstudio/canvas-confetti@1.6.0";

変更後(v7):

JavaScript
import { h, render } from "npm:preact@10.15.1";
import htm from "npm:htm@3.1.1";
import confetti from "npm:canvas-confetti@1.6.0";

CSSのインポート

同じ変更がCSSのインポートにも適用されます:

変更前(v6):

JavaScript
import "blockstudio/swiper@11.0.0/swiper.min.css";

変更後(v7):

JavaScript
import "npm:swiper@11.0.0/swiper.min.css";

後方互換性

後方互換性のため、blockstudio/プレフィックスも引き続きサポートされます。既存のコードは変更なしで動作します。ただし、JavaScriptエコシステム全体との一貫性を保つため、新しいnpm:プレフィックスへの移行を推奨します。

npm:プレフィックスには、次の利点があります:

  • エコシステムとの整合性 – Denoで定着している規約に準拠します
  • 明確さ – npmからのインポートであることがすぐに分かります
  • 将来への備え – blockstudio/プレフィックスは、将来のメジャーバージョンで非推奨になる可能性があります

フック名

Blockstudio 7では、すべてのPHPフック名をcamelCaseではなくsnake_caseを使う形式に統一し、WordPressのコア規約に準拠します。

変更されたフック名

旧名(v6) 新名(v7)
blockstudio/blocks/components/useblockprops/render blockstudio/blocks/components/use_block_props/render
blockstudio/blocks/components/innerblocks/render blockstudio/blocks/components/inner_blocks/render
blockstudio/blocks/components/innerblocks/frontend/wrap blockstudio/blocks/components/inner_blocks/frontend/wrap
blockstudio/blocks/components/richtext/render blockstudio/blocks/components/rich_text/render
blockstudio/assets/process/scss/importPaths blockstudio/assets/process/scss/import_paths
blockstudio/settings/assets/process/scssFiles blockstudio/settings/assets/process/scss_files
blockstudio/settings/editor/formatOnSave blockstudio/settings/editor/format_on_save
blockstudio/settings/blockEditor/disableLoading blockstudio/settings/block_editor/disable_loading
blockstudio/settings/blockEditor/cssClasses blockstudio/settings/block_editor/css_classes
blockstudio/settings/blockEditor/cssVariables blockstudio/settings/block_editor/css_variables
blockstudio/settings/ai/enableContextGeneration blockstudio/settings/ai/enable_context_generation

後方互換性

従来のキャメルケースのフック名も、後方互換性のため引き続きサポートされます。既存のコードは変更なしで動作します。ただし、一貫性を保つため、新しいスネークケース名への移行を推奨します。

移行例:

PHP
// Before (v6)
add_filter('blockstudio/settings/blockEditor/cssClasses', function() {
    return ['my-stylesheet'];
});

// After (v7)
add_filter('blockstudio/settings/block_editor/css_classes', function() {
    return ['my-stylesheet'];
});

正規のブロックタグ

Blockstudio 7.6では、プロジェクトのプレフィックスと完全一致するエイリアスを実行時の拡張ポイントとして引き続き使用できますが、例、カタログ出力、レンダー宣言、診断では<bs:namespace-slug>を標準表記として使用します。標準タグには実際に登録されたブロック名が含まれ、ホスト固有のフィルターに依存しません。

brand => ["theme-components"]とui => ["bsui"]を使用するプロジェクトの場合:

HTML
<!-- Legacy project shorthand -->
<brand-card>
  <ui-input />
</brand-card>

<!-- Canonical output -->
<bs:theme-components-card>
  <bs:bsui-input />
</bs:theme-components-card>

単独の移行コマンドで既存のプロジェクトを調査し、短縮表記を標準表記に書き換えます。まずレポートを出力し、未解決のケースがあると処理を停止し、タグ名のみを変更します。コマンド、入力、安全性の動作については、ブロックタグの移行を参照してください。

アセットファイルの命名

Blockstudio 7では、アセットファイルのサフィックスにドット表記を導入し、推奨規約として従来のハイフン表記に置き換えました。

ファイル名の変更

旧名(v6) 新名(v7)
*-inline.(s)css *.inline.(s)css
*-inline.js *.inline.js
*-editor.(s)css *.editor.(s)css
*-editor.js *.editor.js
*-scoped.(s)css *.scoped.(s)css
*-view.js *.view.js

後方互換性

後方互換性のため、従来のハイフン表記も引き続きサポートされます。既存のファイルは名前を変更せずにそのまま動作します。ただし、新しいブロックにはドット表記への移行をおすすめします。

移行例:

コード
my-block/
├── block.json
├── index.php
├── style.css
├── style-inline.css   →  style.inline.css
├── style-scoped.css   →  style.scoped.css
├── style-editor.css   →  style.editor.css
├── script.js
├── script-inline.js   →  script.inline.js
├── script-editor.js   →  script.editor.js
└── script-view.js     →  script.view.js

フィールドスイッチ

switchプロパティのデフォルト値がtrueではなくfalseになりました。v6では、すべてのフィールドの左端に非表示のトグルがあり、デフォルトで有効でした。v7ではスイッチは任意となり、フィールドラベル内の目に見える目のアイコンを使用します。

変更点

  • デフォルトがfalseに変更:"switch": trueを明示的に設定しない限り、フィールドにスイッチは表示されません
  • 目に見える目のアイコン:左側の隠れたクリック領域に代わり、ラベル領域に目のアイコンボタンが表示されます
  • 無効時のオーバーレイ:フィールドを無効にすると、不透明度を下げるだけでなく、「このフィールドは無効です」というテキスト付きのぼかしオーバーレイが表示されます

移行

v6のデフォルトのスイッチ動作に依存していた場合は、明示的に有効にする必要があります:

JSON
{
  "id": "title",
  "type": "text",
  "label": "Title",
  "switch": true
}

以前、トグルを無効にするために"switch": falseを設定していた場合は、falseがデフォルトになったため削除できます。

Tailwind CSS

Blockstudio 7では、v6のTailwind方式を全面的に置き換えます。v6では、エディター内のCDNを介してTailwind CSSがクライアント側でコンパイルされ、投稿の保存時にディスクへ保存されていました。v7では、TailwindPHPを介してフロントエンドのリクエストごとにTailwind CSSがサーバー側でコンパイルされ、ファイルベースのキャッシュが自動的に行われます。

新しいシステムの詳細については、Tailwind CSSドキュメントを参照してください。

常時有効なサーバーサイドコンパイル

tailwind.enabledがtrueの場合、フロントエンドのリクエストごとにサーバー側でコンパイルされます。コンパイルの流れ:

  1. WordPressがページ全体のHTMLを出力バッファにレンダリング
  2. HTMLからCSSのクラス候補を抽出(高速な正規表現。コンパイルなし)
  3. 候補を並べ替え、CSS設定とともにハッシュ化してキャッシュキーを作成
  4. キャッシュヒット時:キャッシュ済みのCSSファイルを読み込んで挿入
  5. キャッシュミス時:TailwindPHPがCSSをコンパイルし、tailwindスコープ内のBlockstudio共有ランタイムキャッシュに書き込んで挿入

コンパイル済みのCSSは、</head>の前にインラインの<style id="blockstudio-tailwind">タグとして挿入されます。これにはTailwindのpreflightと、一致したすべてのユーティリティクラスが含まれます。

CDNスクリプトはライブプレビュー専用としてエディター内で引き続き動作します。フロントエンドに配信されることはありません。

config形式の変更

configプロパティは、JSONオブジェクト(Tailwind v3)からCSS文字列(Tailwind v4のCSS優先構文)に変更されました。

変更前(v6):

JSON
{
  "tailwind": {
    "config": {
      "theme": {
        "extend": {
          "colors": {
            "primary": "pink"
          }
        }
      }
    }
  }
}

変更後(v7):

JSON
{
  "tailwind": {
    "config": "@theme { --color-primary: pink; }"
  }
}

customClasses設定の削除

customClasses配列設定は削除されました。Tailwind v4のCSS優先方式では、config文字列内で@layer utilitiesを使ってカスタムユーティリティクラスを直接定義します。

変更前(v6):

JSON
{
  "tailwind": {
    "customClasses": [
      { "className": "btn", "value": "px-4 py-2 rounded-lg font-medium" },
      { "className": "card", "value": "bg-white rounded-xl shadow-lg p-6" }
    ]
  }
}

変更後(v7):

JSON
{
  "tailwind": {
    "config": "@layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .card { @apply bg-white rounded-xl shadow-lg p-6; } }"
  }
}

または、複数行の設定ではフィルターを使用します:

PHP
add_filter('blockstudio/settings/tailwind/config', function () {
    return <<<CSS
@layer utilities {
    .btn { @apply px-4 py-2 rounded-lg font-medium; }
    .card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});

blockstudio/settings/tailwind/custom_classesフィルターも削除されました。代わりにblockstudio/tailwind/cssフィルターを使ってカスタムCSSルールを追加してください。

RESTエンドポイントの削除

POST /blockstudio/v1/editor/tailwind/saveエンドポイントは削除されました。コンパイル済みのCSSはエディターから保存されなくなりました。このエンドポイントを呼び出すカスタムコードがある場合は、安全に削除できます。

キャッシュ

Blockstudioは候補ベースのキャッシュ戦略を採用しています。ページのHTML全体をハッシュ化すると、nonceやタイムスタンプによってリクエストごとにキャッシュが無効になるため、CSSクラスの候補のみをハッシュ化します。これにより:

  • CSSクラスが同じ2つのページは、同じキャッシュファイルを共有します
  • 動的コンテンツ(nonce、管理バー、タイムスタンプ)によってキャッシュが無効になりません
  • CSSクラスのセットまたは設定が変更された場合にのみキャッシュが無効になります

キャッシュファイルは、設定されたBlockstudioランタイムルートのsites/{network-blog}/{runtime-identity}/tailwind/以下に保存されます。 強制的に再コンパイルするにはBlockstudio\Runtime_Cache::purge('tailwind')を呼び出してください。

フィルターの変更

旧名(v6) 新名(v7)
blockstudio/tailwind/on_demand/css blockstudio/tailwind/css
blockstudio/tailwind/assets/dir 削除
blockstudio/settings/tailwind/custom_classes 削除

ファイルとエンキュー処理の削除

v6では、Tailwind CSSは外部スタイルシート(blockstudio-tailwind、blockstudio-tailwind-preflight)としてエンキューされていました。v7では、すべてのCSSが出力バッファを介してインラインで挿入されます。フロントエンドでTailwind用のlinkタグやエンキューされたスタイルシートはありません。

ブロックライブラリ

組み込みの「Blockstudio Elements」ライブラリは削除されました。blockstudio.json内のlibrary設定とblockstudio/settings/libraryフィルターは、どちらも効果がなくなりました。

ライブラリのブロック(Gallery、Slider、Image Comparison、Code、Icon)を使用していた場合は、v6インストールのincludes/library/blockstudio-element/ディレクトリからブロックフォルダーをテーマのblockstudioディレクトリにコピーし、block.jsonファイルを新しい名前とカテゴリーに更新してください。