ブロックAPIリファレンス - 変換（Transforms） - 《WordPress開発者リソース》日本語

変換方向: からとへ
変換タイプ
ブロックのグループ解除

変換方向: からとへ

ブロックは、ブロック設定のオプションの transforms キーを介してサポートする変換を宣言し、そのサブキー to と from は、各方向の利用可能な変換の配列を保持します。例:

export const settings = {
   title: 'My Block Title',
   description: 'My block description',
   /* ... */
   transforms: {
   from: [
   /* supported from transforms */
   ],
   to: [
   /* supported to transforms */
   ],
   },
};

変換タイプ

このセクションでは、ブロックがサポートする既存の変換タイプについて説明します:

ブロック
エンター
ファイル
プレフィックス
生
ショートコード

ブロック

このタイプの変換は、からとへの両方の方向をサポートし、ブロックを別のものに変換できるようにします。ブロックツールバー内に対応するUIコントロールがあります。

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

type (文字列): 値 block。
blocks (配列): 知られているブロックタイプのリスト。ワイルドカード値 ("*") も受け入れ、すべてのブロックタイプに対して変換が利用可能であることを意味します (例: すべてのブロックは core/group に変換できます)。
transform (関数): 処理中のブロックの属性と内部ブロックを受け取るコールバックです。ブロックオブジェクトまたはブロックオブジェクトの配列を返す必要があります。
isMatch (関数, オプション): 最初の引数としてブロック属性を、2番目の引数としてブロックオブジェクトを受け取り、ブール値を返すコールバックです。この関数から false を返すと、変換が利用可能であることを防ぎ、ユーザーにオプションとして表示されなくなります。
isMultiBlock (ブール値, オプション): 複数のブロックが選択されているときに変換を適用できるかどうか。true の場合、transform 関数の最初のパラメータは、各選択されたブロックの属性を含む配列になり、2番目は各選択されたブロックの内部ブロックの配列になります。デフォルトは false です。
priority (数値, オプション): 変換が適用される優先度を制御し、低い値が高い値よりも優先されます。これは WordPress フックのように動作します。フックと同様に、デフォルトの優先度は 10 です。

例: 段落ブロックから見出しブロックへ

この変換を宣言するには、createBlock 関数を使用する見出しブロック設定に次のコードを追加します。wp-blocks パッケージから。

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

例: InnerBlocks を持つブロック

InnerBlocks を持つブロックは、別の InnerBlocks を持つブロックに変換することもできます。

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

エンター

このタイプの変換は、からの方向をサポートし、ユーザーが入力したコンテンツからブロックを作成できるようにします。ユーザーがコンテンツを入力し、エンターキーを押した後に新しいブロック行に適用されます。

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

type (文字列): 値 enter。
regExp (RegExp): マッチャーとして使用する正規表現。値が一致する場合、変換が適用されます。
transform (関数): 入力された値を含む content フィールドを持つオブジェクトを受け取るコールバックです。ブロックオブジェクトまたはブロックオブジェクトの配列を返す必要があります。
priority (数値, オプション): 変換が適用される優先度を制御し、低い値が高い値よりも優先されます。これは WordPress フックのように動作します。フックと同様に、デフォルトの優先度は 10 です。

例: — からセパレータブロックへ

ユーザーがハイフンを3回入力し、エンターキーを押したときにセパレータブロックを作成するには、次のコードを使用できます:

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

ファイル

このタイプの変換は、からの方向をサポートし、エディタにドロップされたファイルからブロックを作成できるようにします。

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

type (文字列): 値 files。
transform (関数): 処理中のファイルの配列を受け取るコールバックです。ブロックオブジェクトまたはブロックオブジェクトの配列を返す必要があります。
isMatch (関数, オプション): 処理中のファイルの配列を受け取り、ブール値を返すコールバックです。この関数から false を返すと、変換が適用されなくなります。
priority (数値, オプション): 変換が適用される優先度を制御し、低い値が高い値よりも優先されます。これは WordPress フックのように動作します。フックと同様に、デフォルトの優先度は 10 です。

例: ファイルからファイルブロックへ

ユーザーがファイルをエディタにドロップしたときにファイルブロックを作成するには、次のコードを使用できます:

transforms: {
   from: [
   {
   type: 'files',
   isMatch: ( files ) => files.length === 1,
   // By defining a lower priority than the default of 10,
   // we make that the File block to be created as a fallback,
   // if no other transform is found.
   priority: 15,
   transform: ( files ) => {
   const file = files[ 0 ];
   const blobURL = createBlobURL( file );
   // File will be uploaded in componentDidMount()
   return createBlock( 'core/file', {
   href: blobURL,
   fileName: file.name,
   textLinkHref: blobURL,
   } );
   },
   },
   ];
}

プレフィックス

このタイプの変換は、からの方向をサポートし、ユーザーが入力したテキストからブロックを作成できるようにします。新しいブロック行で、ユーザーがテキストを入力し、後にスペースを追加したときに適用されます。

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

type (文字列): 値 prefix。
prefix (文字列): この変換に一致する文字または文字のシーケンス。
transform (関数): 入力されたコンテンツを受け取るコールバックです。ブロックオブジェクトまたはブロックオブジェクトの配列を返す必要があります。
priority (数値, オプション): 変換が適用される優先度を制御し、低い値が高い値よりも優先されます。これは WordPress フックのように動作します。フックと同様に、デフォルトの優先度は 10 です。

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

ユーザーが疑問符を入力したときにカスタムブロックを作成したい場合、次のコードを使用できます:

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

生

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

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

type (文字列): 値 raw。
transform (関数, オプション): 処理中のノードを受け取るコールバックです。ブロックオブジェクトまたはブロックオブジェクトの配列を返す必要があります。
schema (オブジェクト|関数, オプション): 貼り付けられたコンテンツを検出し処理するために使用される HTML コンテンツモデルを定義します。以下を参照してください。
selector (文字列, オプション): 要素が element.matches メソッドに従って一致するかどうかを判断するためのCSSセレクタ文字列です。要素が一致しない場合、変換は実行されません。これは isMatch を使用するための短縮形であり、存在する場合は優先されます。
isMatch (関数, オプション): 処理中のノードを受け取り、ブール値を返すコールバックです。この関数から false を返すと、変換が適用されなくなります。
priority (数値, オプション): 変換が適用される優先度を制御し、低い値が高い値よりも優先されます。これは WordPress フックのように動作します。フックと同様に、デフォルトの優先度は 10 です。

例: URL から埋め込みブロックへ

ユーザーがエディタにURLを貼り付けたときに埋め込みブロックを作成したい場合、次のコードを使用できます:

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(),
   } );
   },
   },
   ],
}

スキーマとコンテンツモデル

コンテンツを貼り付けるとき、貼り付けられたコンテンツを検証し処理するために使用されるコンテンツモデルを定義することが可能です。エディタに貼り付けられたHTMLは、転送すべき 要素と 転送すべきでない 要素の混合を含むことがよくあります。例えば、<span class="time">12:04 pm</span> をエディタに貼り付けることを考えてみてください。12:04 pm をコピーし、<span> とその class 属性を省略したいと考えています。なぜなら、それらは元のコピー元と同じ意味や構造を持たないからです。

raw 変換を書くとき、許可されるコンテンツを説明する schema を提供することでこれを制御できます。これは、ブロックと一致させる前に貼り付けられたコンテンツをクリーンアップするために適用されます。スキーマは cleanNodeList から @wordpress/dom に渡されます; スキーマの完全な説明を確認してください。

schema = { span: { children: { '#text': {} } } };

例: カスタムコンテンツモデル

次のHTMLスニペットと一致させて、何らかのカスタム投稿プレビューのブロックに変換したいとします。

<div data-post-id="13">
   <h2>The Post Title</h2>
   <p>Some <em>great</em> content.</p>
</div>

エディタに inner h2 と p 要素を許可するように指示したいです。これを行うために、次のスキーマを提供します。この例では、関数形式を使用しており、phrasingContentSchema を提供する引数を受け取ります (変換操作がテキストの貼り付けで始まったかどうかを示すブール値 isPaste も含まれます)。phrasingContentSchema は、<strong> や <sup>、<kbd> などのHTMLフレージング要素と一致するように事前定義されています。<RichText /> コンポーネントが期待される場所は、フレージングコンテンツを許可する良い場所です。そうしないと、変換時にすべてのテキストフォーマットが失われます。

schema = ({ phrasingContentSchema }) => {
   div: {
   required: true,
   attributes: [ 'data-post-id' ],
   children: {
   h2: { children: phrasingContentSchema },
   p: { children: phrasingContentSchema }
   }
   }
}

このコンテンツと一致することに成功すると、data-post-id を除いてすべてのHTML属性が削除され、div 内に他のHTMLの配置がある場合、それは私たちのトランスフォーマーと一致しません。同様に、<h3> の代わりに <h2> が見つかった場合、一致しません。

スキーマは、<details> と <summary> のような非フレージングコンテンツを含むHTMLスニペットと一致させたいときに最も重要です。カスタムスキーマを宣言しないと、エディタは他の構造をスキップし、ブロック変換を実行しようとします。

ショートコード

このタイプの変換は、からの方向をサポートし、ショートコードからブロックを作成できるようにします。raw 変換プロセスの一部として適用されます。

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

type (文字列): 値 shortcode。
tag (文字列|配列): この変換が機能するショートコードタグまたはショートコードエイリアスのリスト。
transform (関数, オプション): 最初の引数としてショートコード属性を、2番目として WPShortcodeMatch を受け取るコールバックです。ブロックオブジェクトまたはブロックオブジェクトの配列を返す必要があります。このパラメータが定義されている場合、attributes パラメータよりも優先されます。
attributes (オブジェクト, オプション): ブロック属性がどこから取得されるべきかを表すオブジェクトで、ブロック設定オブジェクトによって定義された属性の形状に従います。特定の属性が shortcode キーを含む場合、それはショートコード属性を最初の引数として受け取り、WPShortcodeMatch を2番目として受け取り、ブロックのコメントでソースされる属性の値を返す関数であるべきです。
isMatch (関数, オプション): ショートコードAPI に従ってショートコード属性を受け取り、ブール値を返すコールバックです。この関数から false を返すと、ショートコードがこのブロックに変換されるのを防ぎます。
priority (数値, オプション): 変換が適用される優先度を制御し、低い値が高い値よりも優先されます。これは WordPress フックのように動作します。フックと同様に、デフォルトの優先度は 10 です。

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

既存のショートコードは、transform メソッドを使用してそのブロックの対応物に変換できます。

transforms: {
   from: [
   {
   type: 'shortcode',
   tag: 'video',
   transform( { named: { src } } ) {
   return createBlock( 'core/video', { src } );
   },
   // Prevent the shortcode to be converted
   // into this block when it doesn't
   // have the proper ID.
   isMatch( { named: { id } } ) {
   return id === 'my-id';
   },
   },
   ],
},

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

既存のショートコードは、attributes パラメータを使用してそのブロックの対応物に変換できます。

transforms: {
   from: [
   {
   type: 'shortcode',
   tag: 'youtube',
   attributes: {
   url: {
   type: 'string',
   source: 'attribute',
   attribute: 'src',
   selector: 'img',
   },
   align: {
   type: 'string',
   // The shortcode function will extract
   // the shortcode atts into a value
   // to be sourced in the block's comment.
   shortcode: ( { named: { align = 'alignnone' } } ) => {
   return align.replace( 'align', '' );
   },
   },
   },
   // Prevent the shortcode to be converted
   // into this block when it doesn't
   // have the proper ID.
   isMatch( { named: { id } } ) {
   return id === 'my-id';
   },
   },
   ]
},

ブロックのグループ解除

ブロック設定のオプションの transforms キーを介して、ブロックは ungroup サブキーを使用して、処理中のブロックを置き換えるブロックを定義できます。これらの新しいブロックは通常、既存の内部ブロックのサブセットですが、新しいブロックを含むこともできます。

ブロックに ungroup 変換がある場合、デフォルトのグループ化ブロックである必要はなく、グループ解除の対象となります。このAPIを使用してブロックをグループ解除するためのUIは、デフォルトのグループ化ブロックに使用されるものと同じです。グループ解除ボタンを表示するには、単一のグループ化ブロックが選択されている必要があり、内部ブロックも含まれている必要があります。

ungroup は、処理中のブロックの属性と内部ブロックを受け取るコールバック関数です。ブロックオブジェクトの配列を返す必要があります。

例:

export const settings = {
   title: 'My grouping Block Title',
   description: 'My grouping block description',
   /* ... */
   transforms: {
   ungroup: ( attributes, innerBlocks ) =>
   innerBlocks.flatMap( ( innerBlock ) => innerBlock.innerBlocks ),
   },
};