インストール

モジュールをインストールします 

  1. npm install @wordpress/compose --save

このパッケージは、あなたのコードがES2015+環境で実行されることを前提としています。そのような言語機能やAPIのサポートが限られているか、まったくない環境を使用している場合は、コードに@wordpress/babel-preset-defaultで提供されるポリフィルを含めるべきです。

API

詳細については、各高階コンポーネントのREADMEファイルを参照できます。利用可能なコンポーネントはここにあります。

compose

複数の高階コンポーネントを単一の高階コンポーネントに構成します。右から左への関数合成を行い、各連続呼び出しには前の呼び出しの戻り値が供給されます。

これはlodashのflowRight関数に触発されています。

関連

createHigherOrderComponent

コンポーネントを強化されたコンポーネントと修飾子名にマッピングする関数を与えると、生成されたdisplayNameで強化されたコンポーネントを返します。

パラメータ

  • mapComponent ( Inner: TInner ) => TOuter: コンポーネントを強化されたコンポーネントにマッピングする関数。
  • modifierName string: 生成された表示名の種名。

戻り値

  • 生成された表示名が割り当てられたコンポーネントクラス。

debounce

lodashのdebounceの簡略化された適切な型のバージョンで、常にタイマーを使用し、時々rAFを使用することはありません。 

  2. **注意:** `````leading`````および`````trailing`````オプションが`````true`````の場合、`````func`````は、デバウンス関数が`````wait`````タイムアウト中に1回以上呼び出された場合にのみ、タイムアウトの末尾で呼び出されます。  
  4. `````wait`````が`````0`````で、`````leading`````が`````false`````の場合、`````func`````呼び出しは次のティックまで遅延され、`````setTimeout`````のタイムアウトは`````0`````になります。  
  6. *パラメータ*  
  8. - func `````Function`````: デバウンスする関数。 
  9. - wait `````number`````: 遅延するミリ秒数。 
  10. - options `````Partial< DebounceOptions >`````: オプションオブジェクト。 
  11. - options.leading `````boolean`````: タイムアウトの先頭で呼び出すことを指定します。 
  12. - options.maxWait `````number`````: `````func`````が呼び出される前に遅延される最大時間。 
  13. - options.trailing `````boolean`````: タイムアウトの末尾で呼び出すことを指定します。
  15. *戻り値*  
  17. - 新しいデバウンス関数を返します。
  18.  <a name="ifcondition"></a>
  21. ### ifCondition
  23. 与えられた条件が満たされる場合、または与えられたオプションのprop名でレンダリングする新しいコンポーネントを作成する高階コンポーネントクリエーター。  
  25. *使用法*  
  28. ``````bash
  29. type Props = { foo: string };
  30. const Component = ( props: Props ) => <div>{ props.foo }</div>;
  31. const ConditionalComponent = ifCondition( ( props: Props ) => props.foo.length !== 0 )( Component );
  32. <ConditionalComponent foo="" />; // => null
  33. <ConditionalComponent foo="bar" />; // => <div>bar</div>;
  34. `

パラメータ

  • predicate ( props: Props ) => boolean: 条件をテストする関数。

戻り値

  • 高階コンポーネント。

observableMap

  2. *戻り値*  
  4. - `````ObservableMap< K, V >`````: `````ObservableMap`````型の新しいインスタンス。
  5.  <a name="pipe"></a>
  8. ### pipe
  10. 複数の高階コンポーネントを単一の高階コンポーネントに構成します。左から右への関数合成を行い、各連続呼び出しには前の呼び出しの戻り値が供給されます。  
  12. これは`````lodash`````の`````flow`````関数に触発されています。  
  14. *関連*  
  16. - [https://lodash.com/docs/4#flow](https://lodash.com/docs/4#flow)
  17.  <a name="pure"></a>
  20. ### pure
  23. > **非推奨** `````memo`````または`````PureComponent`````を代わりに使用してください。   
  24. 与えられたコンポーネントは、props/stateが変更されたときのみ再レンダリングされる強化されたコンポーネントを返します  
  25.  <a name="throttle"></a>
  28. ### throttle
  30. lodashの`````throttle`````の簡略化された適切な型のバージョンで、常にタイマーを使用し、時々rAFを使用することはありません。  
  32. `````func`````を最大`````wait`````ミリ秒ごとに1回だけ呼び出すスロットル関数を作成します。スロットル関数には、遅延された`````func`````呼び出しをキャンセルするための`````cancel`````メソッドと、それらを即座に呼び出すための`````flush`````メソッドが付属しています。`````options`````を提供して、`````func`````が`````wait`````タイムアウトの先頭および/または末尾で呼び出されるべきかどうかを示します。`````func`````は、スロットル関数に提供された最後の引数で呼び出されます。スロットル関数への後続の呼び出しは、最後の`````func`````呼び出しの結果を返します。  
  34. **注意:** `````leading`````および`````trailing`````オプションが`````true`````の場合、`````func`````は、スロットル関数が`````wait`````タイムアウト中に1回以上呼び出された場合にのみ、タイムアウトの末尾で呼び出されます。  
  36. `````wait`````が`````0`````で、`````leading`````が`````false`````の場合、`````func`````呼び出しは次のティックまで遅延され、`````setTimeout`````のタイムアウトは`````0`````になります。  
  38. *パラメータ*  
  40. - func `````Function`````: スロットルする関数。 
  41. - wait `````number`````: 呼び出しをスロットルするミリ秒数。 
  42. - options `````Partial< ThrottleOptions >`````: オプションオブジェクト。 
  43. - options.leading `````boolean`````: タイムアウトの先頭で呼び出すことを指定します。 
  44. - options.trailing `````boolean`````: タイムアウトの末尾で呼び出すことを指定します。
  46. *戻り値*  
  48. - 新しいスロットル関数を返します。
  49.  <a name="useasynclist"></a>
  52. ### useAsyncList
  54. Reactフックは、ソース配列から非同期にアイテムを追加する配列を返します。この動作は、パフォーマンス上の理由からアイテムのリストを非同期にレンダリングしたい場合に便利です。  
  56. *パラメータ*  
  58. - list `````T[]`````: ソース配列。 
  59. - config `````AsyncListConfig`````: 設定オブジェクト。
  61. *戻り値*  
  63. - `````T[]`````: 非同期配列。
  64.  <a name="useconstrainedtabbing"></a>
  67. ### useConstrainedTabbing
  69. ダイアログ/モーダルでは、タブ移動はラッパー要素のコンテンツに制約される必要があります。このフックは、返されたrefにその動作を追加します。  
  71. *使用法*  
  74. ``````bash
  75. import { useConstrainedTabbing } from '@wordpress/compose';
  77. const ConstrainedTabbingExample = () => {
  78.    const constrainedTabbingRef = useConstrainedTabbing();
  79.    return (
  80.    <div ref={ constrainedTabbingRef }>
  81.    <Button />
  82.    <Button />
  83.    </div>
  84.    );
  85. };
  86. `

戻り値

  • import('react').RefCallback<Element>: 要素Ref。

useCopyOnClick

非推奨
要素がクリックされたときにテキストをクリップボードにコピーします。

パラメータ

  • ref import('react').RefObject<string | Element | NodeListOf<Element>>: 要素への参照。
  • text string|Function: コピーするテキスト。
  • timeout [number]: 返された状態をリセットするためのオプションのタイムアウト。デフォルトで4秒。

戻り値

  • boolean: テキストがコピーされたかどうか。タイムアウト後にリセットされます。

useCopyToClipboard

要素がクリックされたときに指定されたテキストをクリップボードにコピーします。

パラメータ

  • text string | (() => string): コピーするテキスト。利用可能でない場合や計算が高価な場合は関数を使用します。
  • onSuccess Function: テキストがコピーされたときに呼び出されます。

戻り値

  • import('react').Ref<TElementType>: 対象要素に割り当てるref。

useDebounce

Lodashのdebounceに似た関数をデバウンスします。新しいデバウンス関数が返され、引数のいずれかが変更された場合は、スケジュールされた呼び出しがキャンセルされます。デバウンスする関数を含め、レンダリング時に作成された関数をuseCallbackでラップしてください。

関連

パラメータ

  • fn TFunc: デバウンスする関数。
  • wait [number]: 遅延するミリ秒数。
  • options [import('../../utils/debounce').DebounceOptions]: オプションオブジェクト。

戻り値

  • import('../../utils/debounce').DebouncedFunc<TFunc>: デバウンス関数。

useDebouncedInput

値を使用する前にデバウンスする必要がある入力フィールド用のヘルパーフック。

パラメータ

  • defaultValue 使用するデフォルト値。

戻り値

  • [ string, ( value: string ) => void, string ]: 入力値、セッター、およびデバウンスされた入力値。

useDisabled

ブロックプレビューなどの特定の状況では、すべてのフォーカス可能なDOM要素（入力フィールド、リンク、ボタンなど）を無効にする必要があります。このフックは、返されたrefにネストされたDOM要素を無効にする動作を追加します。

可能であれば、inert HTML属性の使用を優先してください。

使用法 

  1. import { useDisabled } from '@wordpress/compose';
  3. const DisabledExample = () => {
  4.    const disabledRef = useDisabled();
  5.    return (
  6.    <div ref={ disabledRef }>
  7.    <a href="#">This link will have tabindex set to -1</a>
  8.    <input
  9.    placeholder="This input will have the disabled attribute added to it."
  10.    type="text"
  11.    />
  12.    </div>
  13.    );
  14. };

パラメータ

  • config Object: 設定オブジェクト。
  • config.isDisabled boolean=: 要素を無効にするかどうか。

戻り値

  • import('react').RefCallback<HTMLElement>: 要素Ref。

useEvent

最新の状態にアクセスできる安定したコールバック関数を作成し、イベントハンドラーやエフェクトコールバック内で使用できます。レンダーフェーズで使用するとエラーが発生します。

使用法 

  1. function Component( props ) {
  2.    const onClick = useEvent( props.onClick );
  3.    useEffect( () => {
  4.    onClick();
  5.    // Won't trigger the effect again when props.onClick is updated.
  6.    }, [ onClick ] );
  7.    // Won't re-render Button when props.onClick is updated (if `Button` is
  8.    // wrapped in `React.memo`).
  9.    return <Button onClick={ onClick } />;
  10. }

パラメータ

  • callback T: ラップするコールバック関数。

useFocusableIframe

iframeがフォーカスを受け取るときにバブリングフォーカスイベントを発生させます。通常通りonFocusをiframeまたは親要素で使用します。

戻り値

  • RefCallback< HTMLIFrameElement >: iframeに渡すref。

useFocusOnMount

マウント時に最初のタブ可能な要素にフォーカスを当てるために使用されるフック。

使用法 

  1. import { useFocusOnMount } from '@wordpress/compose';
  3. const WithFocusOnMount = () => {
  4.    const ref = useFocusOnMount();
  5.    return (
  6.    <div ref={ ref }>
  7.    <Button />
  8.    <Button />
  9.    </div>
  10.    );
  11. };

パラメータ

  • focusOnMount boolean | 'firstElement': マウントモードでフォーカスを当てる。

戻り値

  • import('react').RefCallback<HTMLElement>: Refコールバック。

useFocusReturn

メニューやダイアログのような役割に期待されるように、以前にフォーカスを持っていた要素にフォーカスを戻すアンマウント動作を追加します。

使用法 

  1. import { useFocusReturn } from '@wordpress/compose';
  3. const WithFocusReturn = () => {
  4.    const ref = useFocusReturn();
  5.    return (
  6.    <div ref={ ref }>
  7.    <Button />
  8.    <Button />
  9.    </div>
  10.    );
  11. };

パラメータ

  • onFocusReturn [() => void]: デフォルトの戻り動作をオーバーライドします。

戻り値

  • import('react').RefCallback<HTMLElement>: 要素Ref。

useInstanceId

ユニークなインスタンスIDを提供します。

パラメータ

  • object object: IDを作成するためのオブジェクト参照。
  • prefix [string]: ユニークIDのプレフィックス。
  • preferredId [string | number]: 使用するデフォルトID。

戻り値

  • string | number: ユニークなインスタンスID。

useIsomorphicLayoutEffect

  1.  <a name="usekeyboardshortcut"></a>
  4. ### useKeyboardShortcut
  6. キーボードショートカットハンドラーを追加します。  
  8. *関連*  
  10. - [https://craig.is/killing/mice#api.bind](https://craig.is/killing/mice#api.bind)は、`````callback`````パラメータに関する情報です。
  12. *パラメータ*  
  14. - shortcuts `````string[]|string`````: キーボードショートカット。 
  15. - callback `````(e: import('mousetrap').ExtendedKeyboardEvent, combo: string) => void`````: ショートカットコールバック。 
  16. - options `````WPKeyboardShortcutConfig`````: ショートカットオプション。
  17.  <a name="usemediaquery"></a>
  20. ### useMediaQuery
  22. メディアクエリを実行し、変更時にその値を返します。  
  24. *パラメータ*  
  26. - query `````[string]`````: メディアクエリ。
  28. *戻り値*  
  30. - `````boolean`````: メディアクエリの戻り値。
  31.  <a name="usemergerefs"></a>
  34. ### useMergeRefs
  36. refsを1つのrefコールバックにマージします。  
  38. マージされたrefコールバックは、変更されたとき（`````useCallback`````依存関係の更新の結果）またはref値が変更されたときにのみ呼び出されることを保証します。  
  40. 予想通り、毎回新しい関数を渡すと、refコールバックは毎回のレンダリング後に呼び出されます。  
  42. 毎回のレンダリング後にrefコールバックが呼び出されないようにするには、`````useCallback( callback, dependencies )`````でラップします。依存関係が変更されると、古いrefコールバックは`````null`````で呼び出され、新しいrefコールバックは同じ値で呼び出されます。  
  44. refコールバックを使いやすくするために、`````useRefEffect`````の結果を渡すこともできます。これにより、`````null`````を処理する代わりにクリーンアップ関数を返すことができます。  
  46. ref（およびその動作）を*無効にする*ことも、単にrefを渡さないことで可能です。  
  49. ``````bash
  50. const ref = useRefEffect( ( node ) => {
  51.   node.addEventListener( ... );
  52.   return () => {
  53.    node.removeEventListener( ... );
  54.   };
  55. }, [ ...dependencies ] );
  56. const otherRef = useRef();
  57. const mergedRefs useMergeRefs( [
  58.   enabled && ref,
  59.   otherRef,
  60. ] );
  61. return <div ref={ mergedRefs } />;
  62. `

パラメータ

  • refs Array<TRef>: マージするrefs。

戻り値

  • import('react').RefCallback<TypeFromRef<TRef>>: マージされたrefコールバック。

useObservableValue

Reactフックは、ObservableMapのエントリを観察できます。このフックは、キーに対応する現在の値を返します。値が保存されていない場合はundefinedを返します。また、値の変更を観察し、値が変更された場合に呼び出しコンポーネントの更新をトリガーします。

パラメータ

  • map ObservableMap< K, V >: 観察するObservableMap。
  • name K: 観察するマップキー。

戻り値

  • V | undefined: 要求されたマップキーに対応する値。

usePrevious

前のレンダリングからの値を使用します。https://usehooks.com/usePrevious/に基づいています。

パラメータ

  • value T: トラッキングする値。

戻り値

  • T | undefined: 前のレンダリングからの値。

useReducedMotion

ユーザーが動きの軽減を好むかどうかを返すフック。

戻り値

  • boolean: 動きの軽減の好みの値。

useRefEffect

エフェクトのようなrefコールバック。useEffectと同様に、refが変更された場合や依存関係の1つが変更された場合に実行されるクリーンアップ関数を返すことができます。refはコールバック関数の引数として提供されます。このuseEffectとの主な違いは、useEffectコールバックがrefが変更されたときに呼び出されないことですが、これは呼び出されます。返されたrefコールバックをコンポーネントのrefとして渡し、useMergeRefsで複数のrefsをマージします。

依存関係の配列が空の場合、例えばイベントハンドラーをクリーンアップする必要は厳密にはありません。ノードが削除されるためです。依存関係を追加すると、同じノードに対してrefコールバックが複数回呼び出されるため、クリーンアップが必要です。

パラメータ

  • callback ( node: TElement ) => ( () => void ) | void: 引数としてrefを持つコールバック。
  • dependencies DependencyList: コールバックの依存関係。

戻り値

  • RefCallback< TElement | null >: Refコールバック。

useResizeObserver

HTMLまたはSVG要素のためのResizeObserverを設定します。

返されたセッターを観察したいReact要素にコールバックrefとして渡すか、高度な使用ケースのためにレイアウトエフェクトで使用します。

使用法 

  1. const setElement = useResizeObserver(
  2.    ( resizeObserverEntries ) => console.log( resizeObserverEntries ),
  3.    { box: 'border-box' }
  4. );
  5. <div ref={ setElement } />;
  7. // The setter can be used in other ways, for example:
  8. useLayoutEffect( () => {
  9.    setElement( document.querySelector( `data-element-id="${ elementId }"` ) );
  10. }, [ elementId ] );

パラメータ

  • callback ResizeObserverCallback: ResizeObserverコールバック – MDNドキュメント。
  • options ResizeObserverOptions: 呼び出し時にResizeObserver.observeに渡されるオプション – MDNドキュメント。 変更は無視されます。

useStateWithHistory

undo/redo履歴を持つuseState。

パラメータ

  • initialValue T: 初期値。

戻り値

  • 値、setValue、hasUndo、hasRedo、undo、redo。

useThrottle

Lodashのthrottleに似た関数をスロットルします。新しいスロットル関数が返され、引数のいずれかが変更された場合は、スケジュールされた呼び出しがキャンセルされます。スロットルする関数を含め、レンダリング時に作成された関数をuseCallbackでラップしてください。

関連

パラメータ

  • fn TFunc: スロットルする関数。
  • wait [number]: 呼び出しをスロットルするミリ秒数。
  • options [import('../../utils/throttle').ThrottleOptions]: オプションオブジェクト。詳細についてはリンクされたドキュメントを参照してください。

戻り値

  • import('../../utils/debounce').DebouncedFunc<TFunc>: スロットル関数。

useViewportMatch

ビューポートが指定されたクエリに一致する場合はtrueを返し、そうでない場合はfalseを返します。

使用法 

  1. useViewportMatch( 'huge', '<' );
  2. useViewportMatch( 'medium' );

パラメータ

  • breakpoint WPBreakpoint: ブレークポイントサイズ名。
  • operator [WPViewportOperator]: ビューポートオペレーター。

戻り値

  • boolean: ビューポートがクエリに一致するかどうか。

useWarnOnChange

オブジェクトのプレビュー値と新しい値の間で浅い比較を行うフック。違いがある場合、それをコンソールに印刷します。これは、コンポーネントが再レンダリングされる理由を確認するために、パフォーマンス関連の作業で便利です。

使用法 

  1. function MyComponent( props ) {
  2.    useWarnOnChange( props );
  4.    return 'Something';
  5. }

パラメータ

  • object object: 比較する変更のあるオブジェクト。
  • prefix string: コンソールログに表示するためのプレフィックス。

withGlobalEvents

非推奨
DOMイベントタイプとコンポーネントのコールバック関数名に対応する値のオブジェクトを与えると、イベントが発生したときにコールバックを呼び出すウィンドウイベントハンドラーを作成または更新する高階コンポーネントクリエーター。消費者開発者に代わって、高階コンポーネントは、コンポーネントがアンマウントされるときにアンバインドを管理し、アプリケーション全体で最大1つのイベントハンドラーをバインドします。

パラメータ

  • eventTypesToHandlers Record<keyof GlobalEventHandlersEventMap, string>: DOMイベントタイプのキーを持つオブジェクトで、値はイベントを処理する元のコンポーネントのインスタンス上の関数の名前です。

戻り値

  • any: 高階コンポーネント。

withInstanceId

コンポーネントごとにユニークなインスタンスIDを提供するために使用される高階コンポーネント。

withSafeTimeout

コンポーネントのライフサイクルにバインドされるべき遅延関数呼び出しを提供および管理するために使用される高階コンポーネント。

withState

非推奨 useStateを代わりに使用してください。
内部コンポーネント状態をpropsを介して提供および管理するために使用される高階コンポーネント。

パラメータ

  • initialState any: コンポーネントのオプションの初期状態。

戻り値

  • any: 状態props + 自身のprops + setStateを受け入れるコンポーネントの高階コンポーネントラッパーで、自己のpropsのみを受け入れるコンポーネントを返します。

このパッケージへの貢献

これはGutenbergプロジェクトの一部である個別のパッケージです。このプロジェクトはモノレポとして整理されています。特定の目的を持つ複数の自己完結型ソフトウェアパッケージで構成されています。このモノレポ内のパッケージはnpmに公開され、WordPressや他のソフトウェアプロジェクトで使用されています。

このパッケージやGutenberg全体への貢献について詳しく知りたい場合は、プロジェクトの主要な貢献者ガイドをお読みください。