WordPressのブロック開発で古いブロックの非推奨(deprecated)を利用して互換性を維持する方法

みなさんこんにちは！エンジニアの高澤です！

今回はWordPressのブロック開発で古いブロックの非推奨(deprecated)を利用して互換性を維持する方法について解説していきたいと思います。

WordPressのブロック開発において、すでに開発したブロックを新規機能追加や修正などをした場合に、既存のデータ構造や出力するブロックのHTMLなどが変更する必要があることがしばしばあります。

このような場合、すでにブロックエディタの本文に追加されている設定済みのブロックは互換性が保たれずに壊れてしまい、表示が崩れてしまいます。

そのため、当記事で解説する非推奨(deprecated)というWordPress側で用意してくれている技術を使い、新規ブロックにアップデートされても既存のブロックは壊れずに維持されるようにする対応が必要になります。

今回は、この非推奨(deprecated)について解説いたしますが、React.jsを使ったブロック開発では必須の知識といっても過言ではありませんので、よろしければぜひ当記事を繰り返しご活用いただけましたら幸いです。

deprecated(非推奨)とは

deprecated(非推奨)とは、ブロックの古いバージョンをサポートしつつ、ブロックの新しいバージョンを導入するための重要な概念です。

ブロックの新規開発によって、ブロックの仕様が変わった場合、古いバージョンのコンテンツが壊れないように、互換性を保ちながら段階的に新しい仕様へ移行する際に使われます。

もしdeprecated対応をしない場合、ブロックに新規機能を追加後のテーマもしくはプラグインを使用した場合、これまで本文に追加していた旧ブロックは下図のように壊れてしまいます。

これを防ぐためにdeprecated対応が必要になります。

deprecated(非推奨)の概要

deprecatedは、ブロックの以前のバージョンの定義を保持するために使用します。

ブロックの構造や属性、エディタでの表示が変更されたとき、古いバージョンで作成されたコンテンツが正しく表示されるように古い仕様を保持し続けるようにします。

例えば、最初のバージョンでattributesにてalignを使っていたが、バージョンアップでalignの名称をtextAlignに変更する場合、既に作成された古いalignを持つブロックが壊れないようにするために、deprecatedを使って古い仕様をサポートします。

なぜdeprecated(非推奨)が重要なのか

それではなぜdeprecatedの対応が重要なのかについて、解説しておきたいと思います。

重要性についてまとめると、以下の3点が言えるかと思います。

• 後方互換性を維持
• エディタとフロントエンドの整合性
• 段階的な更新

それぞれ解説していきます。

後方互換性を維持

WordPress で既に公開されたコンテンツを破壊しないことが重要です。ブロック仕様が変更された場合、古いバージョンのブロックも正しく動作し続ける必要があります。

エディタとフロントエンドの整合性

古いバージョンのブロックは、エディタとフロントエンドの両方で正しく表示される必要があり、そのためのビジュアルやレンダリングの設定も保持します。

段階的な更新

ユーザーがブロックエディタで古いバージョンのブロックを使用している場合、更新を促したり、エディタ上でブロックをアップグレードできるようにします。

WordPress公式ドキュメント

解説する前に、事前に非推奨(deprecated)についてのWordPress公式ドキュメントについてご紹介させていただきます。

当記事の内容と組み合わせて以下にご紹介するドキュメントページを確認しつつ作業を進めていただけますと、仕事に大いにお役立ていただけますと思います。

deprecated(非推奨)のチュートリアル

WordPress公式ドキュメントに続いて、WordPress公式ではdeprecatedのチュートリアルが公開されております。

非常に参考になるチュートリアルなのですが、現状英語版しかありません。そのため、日本語版にとして訳した記事を公開しておりますので、よろしければご活用ください。

チュートリアルと合わせて当記事をご活用いただくと、より一層理解が深まるかと思いますのでお勧めいたします。

deprecated（非推奨）の使い方

WordPressブロックの登録において、deprecatedは、ブロックの新しいバージョンのソースコードをindex.jsなどのJavaScriptファイルに追加し、また別で、修正する前の古いバージョンのソースコードを配列として記述して実装する（もしくは、別ファイルとして作成したdeprecated.jsに追加するパターンが主流です）イメージとなります。

ここまで文字だけでイメージわかなかった方は以下で解説するソースコードを見ていただくとお分かりになるかと思います。

基本的なソースコード

ブロックを作成する際、registerBlockType関数の中でdeprecatedプロパティを使用して、古いバージョンの定義を追加します。

以下のコードをご確認ください。以下のコードは、ブロックを構成するindex.js（edit.jsとsave.jsに分けてない形）を想定したコードの一部になります。

// 必要なモジュールを@wordpress/blocksからインポート
import { registerBlockType } from '@wordpress/blocks';

registerBlockType('my-plugin/my-block', {
  title: 'My Block',
  category: 'widgets',
  attributes: {
    textAlign: {
      type: 'string',
    },
  },
  edit({ attributes, setAttributes }) {
    return (
      <div style={{ textAlign: attributes.textAlign }}>
        <p>編集画面</p>
      </div>
    );
  },
  save({ attributes }) {
    return (
      <div style={{ textAlign: attributes.textAlign }}>
        <p>保存されたコンテンツ</p>
      </div>
    );
  },

  // 古いバージョンの定義
  deprecated: [
    {
      attributes: {
        align: {
          type: 'string',
        },
      },
      save({ attributes }) {
        return (
          <div style={{ textAlign: attributes.align }}>
            <p>古いバージョンの保存されたコンテンツ</p>
          </div>
        );
      },
    },
  ],
});

上記コードについて解説いたします。

attributesには、新しいバージョンの属性が定義されています。この例ではtextAlignを新しい属性として使います。

deprecatedの配列には、配列内には、古いバージョンの属性や保存方法が含まれます。この例では、古いバージョンではalign属性を使っていたことがわかります。

save関数には、ブロックがフロントエンドで表示されるときの HTMLを定義します。
新しいバージョンと古いバージョンで異なるレンダリングが必要な場合は、通常のsave関数とdeprecatedでのsave関数とそれぞれのsave関数の内容が出力されます。

deprecatedのより実践的な使い方

deprecatedには複数のバージョンを指定することができます。

これにより、複数回のバージョンアップをサポートできます。つまり、各バージョンで異なる属性や保存方法を使用することが可能です。

以下のコードをご確認ください。

deprecated: [
  {
    attributes: {
      align: {
        type: 'string',
      },
    },
    save({ attributes }) {
      return <div style={{ textAlign: attributes.align }}>Old Content 1</div>;
    },
  },
  {
    attributes: {
      float: {
        type: 'string',
      },
    },
    save({ attributes }) {
      return <div style={{ float: attributes.float }}>Old Content 2</div>;
    },
  },
],

このように、複数の非推奨バージョンを順に指定することで、後方互換性を確保しながらブロックの進化に対応できます。

上記コードのdeprecated配列の処理は、上から順番にチェックされる仕組みになっています。

つまり、deprecated配列の最初の要素が最新の「古いバージョン」 として扱われ、そこから順番に過去のバージョンが処理されていきます。

基本的には、deprecatedを追加するたびにどんどん一番上に追加されて直近の古い配列がその直下にくる形になるかと思います。処理される順番となっておりますので、配列の順番はしっかり考えた上で決めましょう。

isEligible関数で適用するdeprecatedを条件指定する(条件分岐)

isEligible関数とは、ブロックの旧バージョンのデータを新バージョンの形式に変換できるかを判定する関数のことを言います。

ブロックのデータ構造が変わったときに、古いデータを正しく変換できるかを判断する役割を持っています。

具体的には、以下のコードのように古いバージョンのブロックを読み込む際に、条件に合致するかどうかをチェックし、該当するdeprecatedバージョンが適用されるかを判断します。

deprecated: [
  {
    attributes: {
      align: { type: 'string' },
    },
    save({ attributes }) {
      return <div style={{ textAlign: attributes.align }}>Old Content</div>;
    },
    isEligible(attributes) {
      return attributes.align !== undefined;
    },
  },
],

isEligible関数の役割と用途

isEligible関数は、特定のバージョンのブロックが適用されるべきかどうかを判定するためのカスタムロジックを定義できます。

例えば、複数の非推奨バージョンがある場合、ブロックの属性や状態によって適用するバージョンを自動的に選びたいときに役立ちます。

なぜisEligible関数が必要なのか？

deprecatedプロパティに複数のバージョンが指定されているとき、WordPressは古いバージョンのブロックを読み込んだ際に、順番にisEligibleの条件を評価して最初に該当するものを適用します。

これにより、複数のバージョンが混在しても、最適なバージョンが適切に選択されます。

例として、以下のようなケースが考えられます。

1. あるバージョンのブロックではattributesでalignを定義。
2. その次のバージョンではattributesでfloat属性を定義。
3. 現在のバージョンではattributesでtextAlign属性を定義。

ここで、「align」や「float」が設定されたブロックを更新すると、正しいdeprecated定義が適用されるように、isEligible関数で条件を設定します。

isEligible関数の書き方

isEligibleは、ブロックの属性にアクセスして、特定の条件に一致するかをチェックします。true を返すとそのバージョンが適用され、false を返すと次のバージョンに進みます。

deprecated: [
  {
    attributes: {
      align: { type: 'string' },
    },
    save({ attributes }) {
      return <div style={{ textAlign: attributes.align }}>Old Content 1</div>;
    },
    isEligible(attributes) {
      return attributes.align !== undefined;
    },
  },
  {
    attributes: {
      float: { type: 'string' },
    },
    save({ attributes }) {
      return <div style={{ float: attributes.float }}>Old Content 2</div>;
    },
    isEligible(attributes) {
      return attributes.float !== undefined;
    },
  },
],

上記コードについて解説いたします。

上記コード中のattributesは、古いバージョンで使われていた属性を受け取り、条件に合うかどうかを判断します。
各isEligible関数では、ブロックごとのその時々のバージョンごとにattributesに定義された属性が存在するかどうかを確認することで、適用するバージョンを選びます。

上記コードの例では、以下のように機能します。

1. 最初のdeprecatedブロックでは、attributesに「align」が存在すれば適用されます。
2. 次に、attributesに「align」が無い場合、「float」があれば次のバージョンが適用されます。

このように、順番に処理が行われていき、条件がtrueになった古いブロックが適切に処理されるようになります。

isEligible関数の応用的な使い方

それでisEligibleの応用的な使い方について解説いたします。

特定の値を判定する

isEligible関数を使って、単に属性が存在するかどうかだけでなく、特定の値に一致するかを条件にすることもできます。

isEligible(attributes) {
  return attributes.align === 'left';
}

これにより、たとえば「align」が「left」の場合にだけこのバージョンを適用する、というように、より細かい条件指定が可能です。

複数の条件を組み合わせる

isEligible関数では複数の属性を組み合わせて条件を指定することもできます。例えば、以下のように「align」と「color」の両方を条件にできます。

isEligible(attributes) {
  return attributes.align === 'center' && attributes.color === 'blue';
}

isEligible関数の実践的な使い方

次の例では、ブロックがattributesにて「align」を「center」、「color」を「red」と定義しているか、また、特定の「textAlign」が「undefined」でない場合にだけ特定の非推奨バージョンが適用されるようにしています。

deprecated: [
  {
    attributes: {
      align: { type: 'string' },
      color: { type: 'string' },
    },
    save({ attributes }) {
      return (
        <div style={{ textAlign: attributes.align, color: attributes.color }}>
          Deprecated Version 1
        </div>
      );
    },
    isEligible(attributes) {
      return attributes.align === 'center' && attributes.color === 'red';
    },
  },
  {
    attributes: {
      textAlign: { type: 'string' },
    },
    save({ attributes }) {
      return <div style={{ textAlign: attributes.textAlign }}>Deprecated Version 2</div>;
    },
    isEligible(attributes) {
      return attributes.textAlign !== undefined;
    },
  },
],

このように、ご自身で細かい条件を指定して処理することができます。

isEligible関数の注意点

それでは最後に、isEligibleの注意点を解説いたします。
注意点としては、以下があります。

• 順番が重要
• シンプルでわかりやすい条件を指定するようにする

それぞれ解説いたします。

順番が重要

deprecatedの配列の順序は、優先度に影響します。

isEligible関数の条件にマッチするものがあった時点でそのバージョンが適用され、次のバージョンには進まないため、順番に気をつけて条件を設定することが必要です。

シンプルでわかりやすい条件を指定するようにする

複雑な条件を設定しすぎると、後で理解しづらくなることがあるため、シンプルでわかりやすい条件を心がけましょう。

isEligible関数についてまとめると、isEligible関数は、WordPressのブロック開発において、過去の複数バージョンに対応するための柔軟な条件指定を可能にする機能です。

適切な条件でバージョンを判別することで、既存のブロックデータを安全に扱いながら、新しい仕様へとスムーズに移行できます。

migrate関数を使用したブロック属性の移行方法（マイグレーション）

WordPressブロックの仕様が変更されることはよくあります。

例えば、ブロックのあるバージョンでattributesにて「text」という属性を使っていたものの、後のバージョンで「content」という属性に変更したい場合があるかと思います。

そんな時にmigrate関数を活用すると、旧バージョンの属性を新しいバージョンの属性へ自動的に変換できるため、ブロックエディタを使用するサイト運営者に影響なくアップデートを行えます。

migrate関数とは

migrate関数とは、WordPressブロックのバージョン更新時に古いバージョンの属性データを新しいバージョンの属性へ変換するための関数です。

これにより、ブロックの属性名や構造が変わっても、過去のデータが失われずに新しい形式で利用できるようになります。たとえば、あるバージョンのブロックがattributesにて「text」という属性を持っていたが、新バージョンでは「content」という名前に変更した場合、この変換を自動化できます。

使い方の概要として、isEligible関数と同様にmigrate関数はブロックのdeprecated配列の一部として設定されます。

const deprecated = [
  {
    attributes: {
      align: { type: 'string' },
    },
    migrate(attributes) {
      return {
        textAlign: attributes.align, // align を textAlign に変換
      };
    },
    save({ attributes }) {
      return <div style={{ textAlign: attributes.align }}>Old Content</div>;
    },
  },
];

deprecated配列に過去のバージョンのブロック定義をそのまま追加し、各バージョンにmigrate関数を定義することで、ブロックエディタ上で旧バージョンのブロックが新しいデータ形式へ自動変換されます。

ただし、migrate関数は新しいブロックをロードする際に適用されるものであり、保存済みのデータ自体を変更するわけではありません。

つまり、既存の投稿データにあるブロックの状態はそのままですが、投稿編集のブロックエディタでブロックが再読み込みされたときに、新しい構造へ自動的に変換されます。

migrate関数の使い方

それではmigrate関数の使い方について解説いたします。

ここでの説明としては、解説用の場面として、古いバージョンのブロックがattributesにて「text」属性を持っていたが、新しいバージョンで「content」属性を使用するように変更したい場合を想定します。このとき、migrate関数で「text」のデータを「content」に移行します。

ここでの説明では、以下のようにブロックを構成するファイルはindex.jsファイルひとつでまとめているのではなく、index.jsとedit.js、save.jsという形でファイルを分けていることを前提に解説いたします。

非推奨バージョン（deprecated）を設定する

まず、ブロックのバージョンアップを行なっても古いバージョンのブロック（バージョンアップ前に設定済みのブロック）が壊れないように、を非推奨としてdeprecated.jsに古いバージョンのブロックのattributesやsave関数をそのまま保存し、migrate関数を追加してマイグレーションの処理を記述します。

定数としている「v2」という定数名は適当ですので、ご自身の任意の定数名としてください。

// deprecated.js
import { RichText } from '@wordpress/block-editor';

const v2 = {
  attributes: {
    text: { type: 'string' },
  },
  save({ attributes }) {
    return <RichText.Content tagName="p" value={attributes.text} />;
  },
  migrate(attributes) {
    const { text } = attributes;
    return {
      content: text, // `text` の値を `content` に移行
    };
  },
};

export default [ v2 ];

上記のコードのポイントは以下になります。

• attributes定義：「text」属性が古いバージョンで使用されていたことを明示します。
• save関数：「text」の内容を表示するための旧表示方法を定義します。
• migrate関数：「text」から「content」へデータを変換します。「attributes.text」の値を取得し、新しい「content」属性にセットして返します。

migrate関数の引数attributesは、旧バージョンのブロックの属性を持つオブジェクトです。その中から旧属性（この例では「text」）を取り出し、新しい属性「content」に割り当てます。

また、migrate関数の戻り値として、新しい属性のオブジェクトを返します。

また、ここではdeprecated.jsとしてファイルを分けて配列を定義して作成しておりますが、こちらに関して以下の記事で触れておりますので、よろしければご確認ください。

block.jsonの属性名を新しいものに変更

次は、block.jsonの属性名を新しいものに変更します。
ここでは、block.json内でattributesの属性「text」を「content」に変更します。

◾️ block.json内のattributesの属性「text」になっている部分を…

{
  "apiVersion": 2,
  "name": "my-plugin/my-block",
  "title": "My Block",
  "attributes": {
    "text": {
      "type": "string"
    }
  }
}

◾️ block.json内のattributesの属性「content」へ変更します。

{
  "apiVersion": 2,
  "name": "my-plugin/my-block",
  "title": "My Block",
  "attributes": {
    "content": {
      "type": "string"
    }
  }
}

これで、ブロックのJSON設定ファイル（block.json）を更新して新しい属性名「content」を反映させます。「text」属性をcontent属性に置き換え、これが新しいブロックの仕様であることを明確にします。

edit.jsやsave.js（index.jsを分けている場合）内の参照も更新

最後に、新しい「content」属性を使うようにedit.jsやsave.jsのコードを更新します。

新しい「content」属性を使用するように、編集（edit.js）および保存（save.js）の各コンポーネントも修正します。特に、setAttributesメソッドで新しい属性にデータをセットするようにします。

以下ではEditコンポーネントでユーザーが入力した値を新しい「content」属性に保存するようにします。

// edit.js

import { RichText } from '@wordpress/block-editor';

export default function Edit({ attributes, setAttributes }) {
  const { content } = attributes;

  return (
    <RichText
      tagName="p"
      value={content}
      onChange={(newContent) => setAttributes({ content: newContent })}
    />
  );
}

そしてsave関数では、保存された「content」属性の値が適切に表示されるように設定します。

// save.js

import { RichText } from '@wordpress/block-editor';

export default function save({ attributes }) {
  const { content } = attributes;

  return <RichText.Content tagName="p" value={content} />;
}

ここで注意点やポイントとして以下が考えられます。

• migrate関数はdeprecated配列内のオブジェクトに追加し、変換の順序が正しく処理されるようにします。
• migrate関数は複数の属性やinnerBlocksの変換もサポートしているため、複雑な変換が必要な場合にも活用できます。

上記の例に手順に従ってmigrate関数を利用することで、ブロックの互換性を維持しつつ新しい属性へのデータ移行を実現できます。

index.jsにて各ファイルを読み込む

最後に、index.jsにて各ファイルを読み込みます。

基本的に以下のコードのイメージになるかと思います。

// index.js

import { registerBlockType } from '@wordpress/blocks';
import metadata from './block.json';
import Edit from './edit';
import save from './save';
import deprecated from './deprecated';

registerBlockType(metadata.name, {
  ...metadata, // block.json の内容を適用
  edit: Edit,
  save,
  deprecated, // 旧バージョンのブロック定義を適用
});

registerBlockType関数の引数として読み込んでいる順番にお気をつけください。

これにより、旧バージョンのブロックもデータを失わずにアップデートされるため、ユーザー体験が損なわれません。また、複雑な変換が必要な場合でもmigrate関数で柔軟に対応できます。

まとめ

WordPressのブロック開発で古いブロックの非推奨(deprecated)を利用して互換性を維持する方法について解説は以上になります。

WordPress のブロック開発における deprecatedは、後方互換性を保ちながら、ブロックの機能を拡張していくための重要な機能です。

既存のコンテンツを壊さないようにするために、過去のバージョンのサポートを追加し、段階的に新しいバージョンに移行できます。

当記事で扱った非推奨(deprecated)は、React.jsを使ったブロック開発では必須の知識といっても過言ではありませんので、よろしければぜひ当記事を繰り返しご活用いただけましたら幸いです。