変換

「ブロック変換 (Block Transforms)」API は、あるブロックを別のブロックに変換したり、エンティティからブロックに変換したりします。この API が動作する既存エンティティには、ショートコード、ファイル、正規表現、生の DOM ノードがあります。

変換の方向: to と from

ブロックはブロック構成の transforms オプションキーを使用して、どちらの方向の変換をサポートするかを宣言します。サブキー to と from には、すべての方向に対する利用可能な変換の配列を指定します。

export const settings = {
    title: 'My Block Title',
    description: 'My block description',
    /* ... */
    transforms: {
        from: [ /* サポートする from 変換 */ ],
        to: [ /* サポートする to 変換 */ ],
    }
}

変換タイプ

このセクションではブロックがサポートする既存の変換タイプを説明します。

  • block
  • enter
  • files
  • prefix
  • raw
  • shortcode

block

「block」変換タイプは from と to 双方向の変換をサポートし、あるブロックを異なるブロックに変換できます。ブロックツールバー内には関連する UI コントロールがあります。

block 変換タイプは次のパラメータを取るオブジェクトです。

  • type (string): 文字列 block。
  • blocks (array): 既知のブロックタイプ。ワイルドカード値 ("*") も指定でき、この場合 すべての ブロックタイプで変換可能であることを意味する (例: すべてのブロックは core/group に変換できる)。
  • transform (function): 処理されるブロックの属性とインナーブロックを受け取るコールバック。ブロックオブジェクトまたはブロックオブジェクトの配列を返さなければならない。
  • isMatch (function、オプション): 第1引数にブロックの属性、第2引数にブロックオブジェクトを受け取り、ブール値を返すコールバック。false を返すと可能な変換を行わず、ユーザーにオプションを表示する。
  • isMultiBlock (boolean、オプション): 複数のブロックを選択している場合に変換を適用可能かどうか。true であれば transform 関数の最初のパラメータは選択した各ブロックの属性の配列、2番目のパラメータは選択した各ブロックのインナーブロックの配列になる。デフォルトは false。
  • priority (number、オプション): 変換を適用するプライオリティ。値の小さな方が優先される。この動きは WordPress のフック と同じ。フックと同様に指定されていない場合のデフォルトのプライオリティは 10。

例: 「段落」ブロックから「見出し」ブロックへの変換

この変換を宣言するには「見出し」ブロック構成に以下のコードを追加します。wp-blocks パッケージ から createBlock 関数を使用します。

ESNext

transforms: {
    from: [
        {
            type: 'block',
            blocks: [ 'core/paragraph' ],
            transform: ( { content } ) => {
                return createBlock( 'core/heading', {
                    content,
                } );
            },
        },
    ]
},

ES5

transforms: {
    from: [
        {
            type: 'block',
            blocks: [ 'core/paragraph' ],
            transform: function ( attributes ) {
                return createBlock( 'core/heading', {
                    content: attributes.content,
                } );
            },
        },
    ]
},

例: InnerBlock をもつブロックへの変換

InnerBlock をもつブロックも別の InnerBlock をもつブロックとの間で変換できます。

ESNext

transforms: {
    to: [
        {
            type: 'block',
            blocks: [ 'some/block-with-innerblocks' ],
            transform: ( attributes, innerBlocks ) => {
                return createBlock(
                    'some/other-block-with-innerblocks',
                    attributes,
                    innerBlocks
                );
            },
        },
    ],
},

ES5

transforms: {
    to: [
        {
            type: 'block',
            blocks: [ 'some/block-with-innerblocks' ],
            transform: function( attributes, innerBlocks ) {
                return createBlock(
                    'some/other-block-with-innerblocks',
                    attributes,
                    innerBlocks
                );
            },
        },
    ],
},

enter

「enter」変換タイプは from 方向の変換をサポートし、ユーザーが与えたコンテンツからブロックを作成します。ユーザーが何かコンテンツを入力し Enter キーを押下すると、新しいブロック行に適用されます。

enter 変換タイプは次のパラメータを取るオブジェクトです。

  • type (string): 文字列 enter。
  • regExp (RegExp): パターンマッチに使用する正規表現。マッチすれば変換が適用される。
  • transform (function): 入力された値を受け取るコールバック。ブロックオブジェクトまたはブロックオブジェクトの配列を返さなければならない。
  • priority (number, オプション): 変換を適用するプライオリティ。値の小さな方が優先される。この動きは WordPress のフック と同じ。フックと同様に指定されていない場合のデフォルトのプライオリティは 10。

例: — から「区切り」ブロックへの変換

ユーザーが「-」を3回入力し Enter キーを押下した場合に「区切り」ブロックを作成します。

ESNext

transforms = {
    from: [
        {
            type: 'enter',
            regExp: /^-{3,}$/,
            transform: () => createBlock( 'core/separator' ),
        },
    ],
};

ES5

transforms = {
    from: [
        {
            type: 'enter',
            regExp: /^-{3,}$/,
            transform: function ( value ) {
                return createBlock( 'core/separator' );
            },
        },
    ],
};

files

「files」変換タイプは from 方向の変換をサポートし、エディター内にドロップされたファイルからブロックを作成します。

files 変換タイプは次のパラメータを取るオブジェクトです。

  • type (string): 文字列 files。
  • transform (function): 処理するファイルの配列を受け取るコールバック。ブロックオブジェクトまたはブロックオブジェクトの配列を返さなければならない。
  • isMatch (function、オプション): 処理するファイルの配列を受け取り、ブール値を返すコールバック。false を返すと変換を適用しない。
  • priority (number, オプション): 変換を適用するプライオリティ。値の小さな方が優先される。この動きは WordPress のフック と同じ。フックと同様に指定されていない場合のデフォルトのプライオリティは 10。

例: ファイルから「ファイル」ブロックへの変換

ユーザーがエディターにファイルをドロップすると「ファイル」ブロックに変換します。

ESNext

transforms: {
    from: [
        {
            type: 'files',
            isMatch: ( files ) => files.length === 1,
            // デフォルトの 10 よりも低いプライオリティを設定することで
            // 他の変換が見つからない場合のフォールバックとして
            // 「ファイル」ブロックを作成できます。
            priority: 15,
            transform: ( files ) => {
                const file = files[ 0 ];
                const blobURL = createBlobURL( file );
                // ファイルは componentDidMount() でアップロードされます。
                return createBlock( 'core/file', {
                    href: blobURL,
                    fileName: file.name,
                    textLinkHref: blobURL,
                } );
            },
        },
    ];
}

ES5

transforms: {
    from: [
        {
            type: 'files',
            isMatch: function( files ) {
                return files.length === 1;
            },
            // デフォルトの 10 よりも低いプライオリティを設定することで
            // 他の変換が見つからない場合のフォールバックとして
            // 「ファイル」ブロックを作成できます。
            priority: 15,
            transform: function( files ) {
                var file = files[ 0 ];
                var blobURL = createBlobURL( file );
                // ファイルは componentDidMount() でアップロードされます。
                return createBlock( 'core/file', {
                    href: blobURL,
                    fileName: file.name,
                    textLinkHref: blobURL,
                } );
            },
        },
    ];
}

prefix

「prefix」変換タイプは from 方向をサポートし、ユーザーが入力したテキストからブロックを作成します。新しいブロック行でユーザーがテキストを入力し、続けて空白を入力するとこの変換が適用されます。

prefix 変換タイプは次のパラメータを取るオブジェクトです。

  • type (string): 文字列 prefix。
  • prefix (string): この変換にマッチする文字、または文字列。
  • transform (function): 入力したコンテンツを受け取るコールバック。ブロックオブジェクトまたはブロックオブジェクトの配列を返さなければならない。
  • priority (number, オプション): 変換を適用するプライオリティ。値の小さな方が優先される。この動きは WordPress のフック と同じ。フックと同様に指定されていない場合のデフォルトのプライオリティは 10。

例: テキストからカスタムブロックへの変換

ユーザーが疑問符「?」を入力するとカスタムブロックを作成します。

ESNext

transforms: {
    from: [
        {
            type: 'prefix',
            prefix: '?',
            transform( content ) {
                return createBlock( 'my-plugin/question', {
                    content,
                } );
            },
        },
    ];
}

ES5

transforms: {
    from: [
        {
            type: 'prefix',
            prefix: '?',
            transform: function ( content ) {
                return createBlock( 'my-plugin/question', {
                    content,
                } );
            },
        },
    ];
}

raw

「raw」変換タイプは from 方向をサポートし、生の HTML ノードからブロックを生成します。ユーザーがブロック設定 UI メニューで「ブロックへ変換」アクションを実行した場合、またはコンテンツをエディターに貼り付けたり、ドロップした場合にこの変換が適用されます。

raw 変換タイプは次のパラメータを取るオブジェクトです。

  • type (string): 文字列 raw。
  • transform (function、オプション): 処理するノードを受け取るコールバック。ブロックオブジェクトまたはブロックオブジェクトの配列を返さなければならない。
  • schema (object|function、オプション): HTML content model に従って貼り付け時に保存される属性とノードの子を定義する。詳細な情報については pasteHandler を参照してください。
  • selector (string、オプション): element.matches メソッドに従って要素が合致するかどうかを決定する CSS セレクター文字列。要素がマッチしない場合、変換は実行されない。isMatch の代替、かつ、短縮形。あれば、isMatch が優先。
  • isMatch (function、オプション): 処理するノードを受け取り、ブール値を返すコールバック。false を返すと変換を適用しない。
  • priority (number, オプション): 変換を適用するプライオリティ。値の小さな方が優先される。この動きは WordPress のフック と同じ。フックと同様に指定されていない場合のデフォルトのプライオリティは 10。

例: URL から「埋め込み」ブロックへの変換

ユーザーがエディターに URL を貼り付けると「埋め込み」ブロックを作成する。

ESNext

transforms: {
    from: [
        {
            type: 'raw',
            isMatch: ( node ) =>
                node.nodeName === 'P' &&
                /^\s*(https?:\/\/\S+)\s*$/i.test( node.textContent ),
            transform: ( node ) => {
                return createBlock( 'core/embed', {
                    url: node.textContent.trim(),
                } );
            },
        },
    ],
}

ES5

transforms: {
    from: [
        {
            type: 'raw',
            isMatch: function( node ) {
                return node.nodeName === 'P' &&
                    /^\s*(https?:\/\/\S+)\s*$/i.test( node.textContent );
            },
            transform: function( node ) {
                return createBlock( 'core/embed', {
                    url: node.textContent.trim(),
                } );
            },
        },
    ],
}

shortcode

「shortcode」変換タイプは from 方向をサポートし、ショートコードからブロックを作成します。raw 変換プロセスの一部として適用されます。

shortcode 変換タイプは次のパラメータを取るオブジェクトです。

  • type (string): 文字列 shortcode。
  • tag (string|array): この変換が動作可能なショートコードタグ、またはショートコードエイリアスのリスト。
  • attributes (object): block 構成オブジェクト で定義された属性の形に従い、ブロック属性がどこを source とするかを表したオブジェクト。特定の属性が shortcode キーを含む場合には関数であり、第1引数にショートコードの属性、第2引数に WPShortcodeMatch を受け取り、ブロックのコメントを source とする属性の値を返さなければならない。
  • isMatch (function、オプション): Shortcode API ごとにショートコード属性を受け取り、ブール値を返すコールバック。false を返すとショートコードのブロックへの変換を適用しない。
  • priority (number, オプション): 変換を適用するプライオリティ。値の小さな方が優先される。この動きは WordPress のフック と同じ。フックと同様に指定されていない場合のデフォルトのプライオリティは 10。

例: ショートコードからブロックへの変換

既存のショートコードをブロックバージョンに変換する。

ESNext

transforms: {
    from: [
        {
            type: 'shortcode',
            tag: 'caption',
            attributes: {
                url: {
                    type: 'string',
                    source: 'attribute',
                    attribute: 'src',
                    selector: 'img',
                },
                align: {
                    type: 'string',
                    // ショートコード関数は
                    // ブロックコメントを source とする形式で
                    // ショートコード属性を取り出す。
                    shortcode: ( { named: { align = 'alignnone' } } ) => {
                        return align.replace( 'align', '' );
                    },
                },
            },
            // 適切な ID をもたない場合、
            // ショートコードからこのブロックへの変換は
            // 行われない。
            isMatch( { named: { id } } ) {
                return id === 'my-id';
            },
        },
    ]
},

ES5

transforms: {
    from: [
        {
            type: 'shortcode',
            tag: 'caption',
            attributes: {
                url: {
                    type: 'string',
                    source: 'attribute',
                    attribute: 'src',
                    selector: 'img',
                },
                align: {
                    type: 'string',
                    // ショートコード関数は
                    // ブロックコメントを source とする形式で
                    // ショートコード属性を取り出す。
                    shortcode: function( attributes ) {
                        var align = attributes.named.align ? attributes.named.align : 'alignnone';
                        return align.replace( 'align', '' );
                    },
                },
            },
            // 適切な ID をもたない場合、
            // ショートコードからこのブロックへの変換は
            // 行われない。
            isMatch: function( attributes ) {
                return attributes.named.id === 'my-id';
            },
        },
    ]
},

原文

最終更新日: