Gutenbergブロックの非推奨化: コンテンツを壊さずに更新する

概要

Gutenbergブロックを更新すると、古いバージョンを使用している既存の投稿が壊れることがよくあります。この記事では、block.jsonのdeprecatedプロパティを使用して後方互換性を維持する方法を説明します。現在のブロックマークアップをキャプチャし、1つ以上の非推奨バージョンを定義し、属性を正しくマッピングする正確な手順を学びます。静的ブロックと動的ブロックの両方を、実用的な例とともに解説します。また、非推奨化が常に最善のアプローチであるという前提に疑問を投げかけ、クリーンブレークが適切な場合についても議論します。最後には、ユーザーのコンテンツを壊さずにブロックを自信を持って更新できるようになります。

変更による破壊的シナリオ

6か月前にカスタムのテスティモニアルブロックをリリースしたとします。これは引用文と著者名を含む単純な<div>を出力します。今、クライアントは新しいデザインを希望しています。著者を引用文の上に配置し、異なるCSSクラスを使用するように。ブロックのsave関数とrender_callbackを更新します。新しい投稿でテストすると、見栄えは良好です。ところが、そのブロックを使用している古い投稿に移動すると、問題が発生します。引用文のテキストが消え、著者の位置が間違っていて、スタイルも崩れています。ブロックを使用しているすべてのページが壊れてしまいました。

これがGutenbergブロック開発における典型的な「破壊的変更」の問題です。ブロックは基本的にデータ構造とマークアップの組み合わせです。マークアップを変更すると、エディタは古いコンテンツを新しい構造に自動的にマッピングできません。結果として、検証エラー（ブロックが無効になる）か、さらに悪いことに、ブロックが正しくレンダリングされないサイレントな破損が発生します。

ブロックの非推奨化とは？

ブロックの非推奨化は、Gutenbergに組み込まれたバージョン変更を処理するためのメカニズムです。ブロックのblock.jsonにdeprecated配列を定義することで、エディタに「これらの古いバージョンのいずれかに一致するブロックが見つかったら、現在のバージョンに変換してください」と指示します。各非推奨エントリは、以前のattributes、supports、save関数（またはrender_callback）を指定します。エディタが古いブロックを読み込むと、非推奨配列を順に調べ、最初に一致する変換を適用します。

この機能は、開発者がブロックのマークアップを変更する必要があるとは考えないため、あまり使用されていません。しかし、実際のプロジェクトでは要件が変化します。非推奨化をスキップすると、ユーザーにブロックの削除と再挿入を強制するか（使い勝手が悪い）、2つの別々のブロックバージョンを管理することになります（煩雑）。公式のWordPress開発者ハンドブックでは、ブロックエディターハンドブックでカバーされていますが、実践的なウォークスルーは不足しています。

ステップ1: 現在の状態をキャプチャする

変更を加える前に、現在のsaveの出力（動的ブロックの場合はrender_callback）と、ブロックが現在使用しているattributesを正確に記録します。スナップショットを撮るようなものです。静的ブロックの場合は、save関数が返すJSXを保存します。動的ブロックの場合は、render_callbackが生成するPHPマークアップを保存します。

プラグイン内にdeprecated.js（または同様の）ファイルを作成し、そこに古いsave関数を保存します。あるいは、非推奨バージョンをブロックのメインJavaScriptファイルに直接保持することもできます。重要なのは、ブロックが最初にデプロイされたときのコードをそのまま保存することです。

ステップ2: 非推奨バージョンを定義する

block.jsonにdeprecated配列を追加します。各エントリは、次のものを含むことができるオブジェクトです：

• attributes（オブジェクト）：以前の属性定義。
• supports（オブジェクト）：変更された以前のサポート設定。
• save（関数または文字列）：以前のsave関数。JavaScriptのみのブロックの場合は、古い関数をインポートします。PHPでレンダリングされる動的ブロックの場合は、代わりにmigrateとrender_callbackを使用できます。
• migrate（関数）：古い属性を新しいものにマッピングする関数（オプション）。

例：

"deprecated": [
  {
    "attributes": {
      "quote": { "type": "string", "source": "html", "selector": ".quote" },
      "author": { "type": "string", "source": "html", "selector": ".author" }
    },
    "supports": {},
    "save": "() => <div className="testimonial-legacy"><p className="quote">{attributes.quote}</p><p className="author">{attributes.author}</p></div>"
  }
]

注意：block.json内のsave関数は通常JavaScriptで定義されます。外部スクリプトを使用している場合は、それをエンキューして関数名を参照する必要があります。または、関数を文字列としてインライン化することもできますが（複雑なブロックには推奨されません）。

ステップ3: 属性をマッピングする

多くの場合、マークアップだけでなく属性名やソースも変更します。例えば、著者をプレーンな文字列として保存していたのをリッチテキストフィールドに変更する場合などです。そのような場合、migrateプロパティを使用して古い属性を新しいものに変換します。

migrate: (attributes) => {
  return {
    quote: attributes.quote,
    author: { content: attributes.author, level: 2 }
  };
}

migrate関数を提供しない場合、エディタは古い属性をそのまま新しいブロックに渡します。属性名が変更されているとエラーが発生する可能性があります。

ステップ4: 実際のコンテンツでテストする

非推奨バージョンを定義したら、徹底的にテストします。新しい投稿を作成し、古いブロックを挿入して（既存の投稿からシリアライズされたブロックコードを貼り付けることでシミュレーション）、検証エラーなしに新しいバージョンに変換されることを確認します。また、変換されたブロックの編集と保存もテストします。複数の非推奨バージョンがある場合は、それぞれテストします。

動的ブロックの場合、プロセスは似ていますが、ひねりがあります：動的ブロックのsave関数は通常nullを返します（ブロックはPHPでレンダリングされます）。非推奨エントリでは、動的レンダリングに切り替える前に使用されていた以前の静的マークアップをsaveに設定するか、古い属性構造と新しい属性構造の両方を処理するPHPのrender_callbackを使用できます。これはより複雑ですが、可能です。

注意点とトレードオフ

非推奨化は強力ですが、欠点もあります。非推奨バージョンごとにコードがプラグインに追加されます。時間が経つと、ほとんど使用されないが維持しなければならない5〜6個のレガシーバージョンの連鎖ができる可能性があります。WordPressコアチームは少なくとも2バージョン前までを維持することを推奨していますが、それを超える場合は、影響を受ける投稿数が少なければクリーンブレークを検討してもよいでしょう。

もう一つの微妙な点：非推奨エントリの順序が重要です。エディタは配列をインデックス0から順に調べ、最初に一致したものを使用します。2つの非推奨バージョンが類似している場合、間違った方が適用される可能性があります。常に最も新しい非推奨バージョン（現在のバージョンの直前に位置するもの）を最初にリストしてください。

最後に、非推奨化はサイト全体のスタイル変更（例：theme.json経由）で編集されたコンテンツを処理しません。ブロックの外観が変更されたグローバルスタイルに依存していた場合、非推奨化はそれを調整しません。保存時またはプラグイン更新フックを介して実行される移行スクリプトを追加する必要があるかもしれません。

非推奨化が答えでない場合

ほとんどのチュートリアルでは、非推奨化を必須と位置づけています。実際には、クリーンブレークの方が適切な状況もあります。ブロックが新しく、少数の投稿でしか使用されていない場合、それらのインスタンスを手動で更新する方が、非推奨コードを書いてテストするよりも速いかもしれません。同様に、ブロックの基礎となるデータモデルが根本的に異なる場合（例：2つのブロックを1つに統合するなど）、非推奨化では柔軟性が不十分かもしれません。その場合は、プラグイン更新時に実行される1回限りの移行スクリプトを作成し、古いブロックを新しい形式に変換します。

もう一つの異論：非推奨化は優れた設計の代わりになるべきではありません。頻繁な変更を見込んでいるなら、最初からバージョニングを考慮したブロックを設計してください。例えば、version属性を保存し、条件付きレンダリングを使用する方法です。このアプローチは、基本を超えたブロックで説明されていますが、非推奨化より軽量ですが、先見性が必要です。

結論

ブロックの非推奨化は、本格的なGutenberg開発者にとって不可欠なツールです。これにより、ユーザーのコンテンツを壊さずにブロックを進化させることができます。重要な手順は、現在の状態をキャプチャし、block.jsonで非推奨バージョンを定義し、必要に応じて属性をマッピングし、実際のコンテンツでテストすることです。ただし、非推奨化にはメンテナンスコストが伴うことを覚えておいてください。時にはクリーンブレークやバージョン管理されたブロック設計の方が実用的です。非推奨化を戦略的に使用し、自動的に使用しないことで、ブロックは多くの更新を通じて堅牢性を維持します。

保守可能なプラグインを構築するための広い視点については、堅牢なWordPressプラグインの構築を参照してください。また、ブロック開発が初めての方は、基本を超えたブロックが始めるのに役立ちます。