開発ガイドライン

ToolsPanel は、ドロップダウンメニューを含むヘッダーを持つコンテナを作成します。メニューは、ToolsPanelItem コンポーネントタイプに一致するパネルの子要素から自動的に生成されます。各メニュー項目は、対応する子要素の表示をオンまたはオフに切り替えることができます。コントロールの onSelect および onDeselect コールバックが発火し、ブロックサポートコントロールがオフに切り替えられたときにブロック属性をリセットするなど、子要素に対するより大きな制御が可能になります。子コントロールが初めて表示されるかどうかは、以前に値が設定されていたか、isShownByDefault プロパティを通じてデフォルトで表示されるようにフラグが立てられているかに依存します。子要素に値があるかどうかを判断するのは、子のプロパティを通じて提供される hasValue 関数によって行われます。ToolsPanelItem でラップされていないコンポーネントはまだレンダリングされますが、ToolsPanel メニュー内で表現されたり制御されたりすることはありません。この利点があるシナリオの例としては、パネル内に紹介やヘルプテキストを表示することが挙げられます。

ツールパネルレイアウト

ToolsPanel は、2列のグリッドレイアウトを持っています。デフォルトでは、パネル内の ToolsPanelItem コンポーネントは両方の列にまたがるようにスタイリングされており、これは大多数のユースケースに適しています。ヘルプテキストなどのほとんどの非コントロール要素は、関連するコントロールの ToolsPanelItem の子としてレンダリングされ、追加のスタイリングは必要ありません。要素が複数のコントロール（例：コントラストチェッカー）またはパネル自体（例：パネルの説明）に関連している場合、これらはラッピング ToolsPanelItem なしでパネルにレンダリングされます。それらはデフォルトで単一の列にしかまたがりません。これが望ましくない場合、これらの要素には小さなスタイルの調整が必要になる可能性があります。例として grid-column: 1 / -1; を挙げます。以下の使用例では、非-ToolsPanelItem 説明段落、単一行に表示されるべきコントロール、および両方の列にまたがる他のコントロールを示します。

使用法

  1. /**
  2.  * External dependencies
  3.  */
  4. import styled from '@emotion/styled';
  6. /**
  7.  * WordPress dependencies
  8.  */
  9. import {
  10.    BoxControl,
  11.    __experimentalToolsPanel as ToolsPanel,
  12.    __experimentalToolsPanelItem as ToolsPanelItem,
  13.    __experimentalUnitControl as UnitControl,
  14. } from '@wordpress/components';
  15. import { __ } from '@wordpress/i18n';
  17. const PanelDescription = styled.div`
  18.    grid-column: span 2;
  20. const SingleColumnItem = styled( ToolsPanelItem )`
  21.    grid-column: span 1;
  23. export function DimensionPanel() {
  24.    const [ height, setHeight ] = useState();
  25.    const [ width, setWidth ] = useState();
  26.    const [ padding, setPadding ] = useState();
  27.    const [ margin, setMargin ] = useState();
  29.    const resetAll = () => {
  30.    setHeight( undefined );
  31.    setWidth( undefined );
  32.    setPadding( undefined );
  33.    setMargin( undefined );
  34.    };
  36.    return (
  37.    <ToolsPanel label={ __( 'Dimensions' ) } resetAll={ resetAll }>
  38.    <PanelDescription>
  39.    Select dimensions or spacing related settings from the menu for
  40.    additional controls.
  41.    </PanelDescription>
  42.    <SingleColumnItem
  43.    hasValue={ () => !! height }
  44.    label={ __( 'Height' ) }
  45.    onDeselect={ () => setHeight( undefined ) }
  46.    isShownByDefault
  47.    >
  48.    <UnitControl
  49.    label={ __( 'Height' ) }
  50.    onChange={ setHeight }
  51.    value={ height }
  52.    />
  53.    </SingleColumnItem>
  54.    <SingleColumnItem
  55.    hasValue={ () => !! width }
  56.    label={ __( 'Width' ) }
  57.    onDeselect={ () => setWidth( undefined ) }
  58.    isShownByDefault
  59.    >
  60.    <UnitControl
  61.    label={ __( 'Width' ) }
  62.    onChange={ setWidth }
  63.    value={ width }
  64.    />
  65.    </SingleColumnItem>
  66.    <ToolsPanelItem
  67.    hasValue={ () => !! padding }
  68.    label={ __( 'Padding' ) }
  69.    onDeselect={ () => setPadding( undefined ) }
  70.    >
  71.    <BoxControl
  72.    label={ __( 'Padding' ) }
  73.    onChange={ setPadding }
  74.    values={ padding }
  75.    allowReset={ false }
  76.    />
  77.    </ToolsPanelItem>
  78.    <ToolsPanelItem
  79.    hasValue={ () => !! margin }
  80.    label={ __( 'Margin' ) }
  81.    onDeselect={ () => setMargin( undefined ) }
  82.    >
  83.    <BoxControl
  84.    label={ __( 'Margin' ) }
  85.    onChange={ setMargin }
  86.    values={ margin }
  87.    allowReset={ false }
  88.    />
  89.    </ToolsPanelItem>
  90.    </ToolsPanel>
  91.    );
  92. }

プロパティ

hasInnerWrapper: boolean

このツールパネル内のアイテムが内部ラッパー要素内に含まれることを示します。これにより、パネルはそれらを適切にレイアウトできます。

  • 必須: いいえ
  • デフォルト: false

dropdownMenuProps: {}

パネルの DropdownMenu を構成するためのポップオーバープロパティ。

  • タイプ: DropdownMenuProps
  • 必須: いいえ

headingLevel: 1 | 2 | 3 | 4 | 5 | 6 | ‘1’ | ‘2’ | ‘3’ | ‘4’ | ‘5’ | ‘6’

パネルのヘッダーの見出しレベル。

  • 必須: いいえ
  • デフォルト: 2

label: string

パネルのヘッダー内に表示され、パネルのドロップダウンメニューの aria-label として表示されるテキスト。

  • 必須: はい

panelId: string | null

panelId が設定されている場合、それは ToolsPanelContext を通じて渡され、パネルアイテムを制限するために使用されます。panelId が設定されている場合、アイテムは panelId が明示的に null であるか、アイテムの panelId が正確に一致する場合にのみ登録できます。

  • 必須: いいえ

resetAll: ( filters?: ResetAllFilter[] ) => void

Reset all メニューオプションが選択されたときに呼び出される関数。引数として、すべての有効な登録された ToolsPanelItems の resetAllFilter コールバックを含む配列を受け取ります。

  • 必須: はい

shouldRenderPlaceholderItems: boolean

ToolsPanel に対して、すべての ToolsPanelItem 子要素がオフに切り替えられ隠されたときにプレースホルダーコンテンツ（null の代わりに）をレンダリングするべきであることを示します。プレースホルダーアイテムは、ToolsPanelItem を通じて通常表示される className を適用しないことに注意してください。

  • 必須: いいえ
  • デフォルト: false