エディター内のブロック

Topics

ブロックエディターは React シングルページアプリケーション (SPA) です。エディター内のすべてのブロックは、クライアントでのブロック登録に使用される settings オブジェクトの edit プロパティで定義された、React コンポーネント経由で表示されます。

ブロックの Edit React コンポーネントが受け取る props オブジェクトは以下を含みます。

  • attributes: ブロックスのすべての属性オブジェクト
  • setAttributes: 属性オブジェクトを更新するメソッド
  • isSelected: ブロックが現在選択されているかどうかを示すブール値

WordPress にはエディター内のブロックのインターフェイスを定義する、多くの組み込み標準コンポーネントがあります。これらの組み込みコンポーネントは、@wordpress/components や @wordpress/block-editor などのパッケージから利用できます。

WordPress Gutenberg プロジェクトでは、WordPress パッケージで利用可能なユーザーインターフェイスコンポーネントのドキュメントに、Storybook を使用しています。

ブロックツールバーや設定サイドバーのブロックのカスタム設定コントロールもまた、次のような組み込みコンポーネントを介して、Edit React コンポーネント経由で定義できます。

組み込みコンポーネント

パッケージ @wordpress/components には、ブロックエディターと WordPress ダッシュボード用の共通 UI 要素を作成する、汎用 WordPress コンポーネントのライブラリが含まれています。このパッケージでよく使用されるコンポーネントです。

パッケージ @wordpress/block-editor にはブロックエディター用のコンポーネントとフックのライブラリが含まれ、そこにはブロックのカスタム設定コントロールを定義するものもあります。このパッケージでよく使用されるコンポーネントです。

パッケージ @wordpress/block-editor にはまた、スタンドアロンブロックエディターを作成し、使用するためのツールも含まれます。

ブロックエディター用のコンポーネントを使用する際の、良いワークフローは、

  • WordPress のパッケージからコンポーネントをインポートする。
  • コンポーネントに対応するコードを JSX 形式でプロジェクトに追加する。
  • ほとんどの組み込みコンポーネントは、ブロック属性の設定に使用される。このため、block.json で必要な属性を定義し、コンポーネントの setAttributes でその属性を更新するイベントハンドラを作成する。
  • 必要であれば、コードをシリアライズして、データベースに格納できるようにする。

Top ↑

ブロックコントロール: ブロックツールバーと設定サイドバー

ブロックのカスタマイズを簡素化し、一貫したユーザー体験を保証するため、ブロックのエディタープレビュー生成を支援するいくつかの組み込み UI パターンがあります。

下図は、選択した段落ブロックのブロックツールバーと設定サイドバーの詳細です。

段落ブロック選択時のブロックツールバーと設定サイドバーの図解

Top ↑

ブロックツールバー

ユーザーがブロックを選択すると、選択されたブロックの上のツールバーに、多くのコントロールボタンが表示されます。このうちブロックレベルのコントロールのいくつかは自動的に表示されますが、ツールバーをカスタマイズしてブロックタイプに固有のコントロールを挿入できます。ブロックタイプの edit 関数の戻り値に BlockControls 要素を含めると、選択したブロックのツールバーにそのコントロールが表示されます。

export default function Edit( { className, attributes: attr, setAttributes } ) {

	const onChangeContent = ( newContent ) => {
		setAttributes( { content: newContent } );
	};

	const onChangeAlignment = ( newAlignment ) => {
		setAttributes( {
			alignment: newAlignment === undefined ? 'none' : newAlignment,
		} );
	};

	return (
		<div { ...useBlockProps() }>
			<BlockControls>
				<ToolbarGroup>
					<AlignmentToolbar
						value={ attr.alignment }
						onChange={ onChangeAlignment }
					/>
				</ToolbarGroup>
			</BlockControls>

			<RichText
				className={ className }
				style={ { textAlign: attr.alignment } }
				tagName="p"
				onChange={ onChangeContent }
				value={ attr.content }
			/>
		</div>
	);
}

上のコードを含む、完全なブロックのサンプルプログラムを参照してください。

なお、BlockControls はブロックが選択されていて、ビジュアル編集モードのときのみ表示されます。HTML 編集モードでブロックを編集しているときは BlockControls は表示されません。

Top ↑

設定サイドバー

設定サイドバーは、使用頻度の低い設定や、大きな画面領域を必要とする設定の表示に使用されます。設定サイドバーは、ブロックレベルの設定のみに使用し、ブロックを選択すると表示されます。

ブロック内の選択したコンテンツにのみ影響する設定、たとえばテキストの「太字」などは、設定サイドバー内に配置しないでください。代わりにツールバーを使用してください。設定サイドバーは HTML モードでブロックを編集しているときにも表示されます。このため、ブロックレベルの設定のみを配置してください。

ツールバーのレンダリングと同様に、ブロックタイプの edit 関数の戻り値に InspectorControls 要素を含めると、コントロールが設定サイドバー領域に表示されます。

export default function Edit( { attributes, setAttributes } ) {
	const onChangeBGColor = ( hexColor ) => {
		setAttributes( { bg_color: hexColor } );
	};

	const onChangeTextColor = ( hexColor ) => {
		setAttributes( { text_color: hexColor } );
	};

	return (
		<div { ...useBlockProps() }>
			<InspectorControls key="setting">
				<div>
					<fieldset>
						<legend className="blocks-base-control__label">
							{ __( 'Background color', 'block-development-examples' ) }
						</legend>
						<ColorPalette // Element Tag for Gutenberg standard colour selector
							onChange={ onChangeBGColor } // onChange event callback
						/>
					</fieldset>
					<fieldset>
						<legend className="blocks-base-control__label">
							{ __( 'Text color', 'block-development-examples' ) }
						</legend>
						<ColorPalette
							onChange={ onChangeTextColor }
						/>
					</fieldset>
				</div>
			</InspectorControls>
			<TextControl
				value={ attributes.message }
				onChange={ ( val ) => setAttributes( { message: val } ) }
				style={ {
					backgroundColor: attributes.bg_color,
					color: attributes.text_color,
				} }
			/>
		</div>
	);
}

上のコードを含む、完全なブロックのサンプルプログラムを参照してください。

ツールバーとサイドバーの両方でレンダーされるブロックコントロールは、同じタイプの複数のブロックが選択されている場合にも利用できます。

色、ボーダー、スペースのカスタマイズなどを含む、一般的なカスタマイズ設定については、ブロックサポートを使用すると、より効率的な方法で、同じ機能を提供できます。

Top ↑

その他の情報

原文

最終更新日: