コンテンツにスキップ

useController

制御されたコンポーネントのためのReactフック

useController
(props?: UseControllerProps) => { field: object, fieldState: object, formState: object }

このカスタムフックは Controllerを強化します。さらに、同じpropsとメソッドを共有します。 Controller。再利用可能な制御入力を作成するのに役立ちます。

Props

次の表には、引数に関する情報が含まれています。 useController.

名前型必須説明
nameFieldPath✓入力の一意の名前。
controlControlcontrol useFormを呼び出すことによって提供されるオブジェクト。FormProviderを使用する場合はオプションです。
defaultValueunknown

重要: defaultValueに undefinedを適用したり、 useFormでdefaultValuesを適用することはできません。

  • フィールドレベルでdefaultValueを設定するか、useFormの defaultValuesを設定する必要があります。undefinedは有効な値ではありません。

  • フォームがデフォルト値でresetを呼び出す場合、useFormに以下を提供する必要があります。 defaultValues.

rulesObject

registerと同じ形式の検証ルール。以下が含まれます。

required、min、max、minLength、maxLength、pattern、validate

CodeSandbox TS
rules={{ required: true }}
shouldUnregisterboolean = false

アンマウント後、入力は登録解除され、defaultValuesも削除されます。

注: このpropは、 useFieldArrayと併用する場合は避ける必要があります。unregister関数は、入力のアンマウント/再マウントと並べ替えの後に呼び出されるためです。

disabledboolean = false

disabled propは、`field` propから返されます。制御された入力は無効になり、その値は送信データから省略されます。

戻り値

次の表には、 useControllerが生成するプロパティに関する情報が含まれています。

stringReact.Ref
オブジェクト名名前型説明
fieldonChange(value: any) => void

ライブラリに入力の値を送信する関数。

  • 入力のonChange propに割り当てる必要があり、値は undefinedであってはいけません。.

  • このpropは formState を更新します。手動で setValue またはフィールドの更新に関連する他のAPIを呼び出すことは避ける必要があります。

fieldonBlur() => void

入力のonBlurイベントをライブラリに送信する関数。入力のonBlur propに割り当てる必要があります。

fieldvalueunknown

制御されたコンポーネントの現在の値。

fielddisabledboolean

入力の無効状態。

fieldname

登録されている入力の名前。

fieldref

フックフォームを入力に接続するために使用されるref。エラー入力をフォーカスできるように、 コンポーネントの入力refにrefを割り当てます。

fieldStateinvalidboolean

現在の入力の無効状態。

fieldStateisTouchedboolean

現在の制御された入力のタッチ状態。

fieldStateisDirtyboolean

現在の制御された入力のダーティ状態。

fieldStateerrorobject

この特定の入力のエラー。

formStateisDirtyboolean

ユーザーが入力のいずれかを変更した後、trueに設定されます。

  • 重要: フォームがダーティかどうかを比較するための一意のソースをフックフォームが持つことができるように、すべての入力のdefaultValuesをuseFormで提供してください。

    const {
      formState: { isDirty, dirtyFields },
      setValue,
    } = useForm({ defaultValues: { test: "" } });
    

    // isDirty: true
    setValue('test', 'change')
     
    // isDirty: false because there getValues() === defaultValues
    setValue('test', '')

  • ファイル型の入力は、ファイルの選択をキャンセルする機能と FileList オブジェクトのために、アプリレベルで管理する必要があります。

  • カスタムオブジェクト、クラス、またはファイルオブジェクトはサポートしていません。

formStatedirtyFieldsobject

ユーザーが変更したフィールドを持つオブジェクト。ライブラリがdefaultValuesと比較できるように、useFormを介してすべての入力のdefaultValuesを提供してください。

  • 重要: 各フィールドのダーティさを比較するための一意のソースをフックフォームが持つことができるように、useFormでdefaultValuesを提供してください。

  • ダーティフィールドは、 isDirty formStateとして表されません。これは、ダーティフィールドがフォーム全体ではなく、フィールドレベルでダーティとしてマークされるためです。フォーム全体の状態を判断する場合は、代わりにisDirtyを使用してください。

formStatetouchedFieldsobjectユーザーが操作したすべての入力を含むオブジェクト。
formStatedefaultValuesobject

で設定された値 useFormのdefaultValuesまたは、 reset APIを介して更新されたdefaultValues。

formStateisSubmittedbooleanフォームが送信された後、trueに設定されます。resetメソッドが呼び出されるまで trueのままになります。
formStateisSubmitSuccessfulboolean

フォームがランタイムエラーなしで正常に送信されたことを示します。

formStateisSubmittingbooleanフォームが現在送信中の場合はtrue。 それ以外の場合はfalse。
formStateisLoadingboolean

フォームが現在非同期のデフォルト値をロードしている場合はtrue。

重要: このpropは、非同期のdefaultValuesにのみ適用可能です

const { 
  formState: { isLoading } 
} = useForm({ 
  defaultValues: async () => await fetch('/api') 
});
formStatesubmitCountnumberフォームが送信された回数。
formStateisValidboolean
フォームにエラーがない場合はtrueに設定されます。

setErrorは、isValid formStateには影響を与えません。 isValidは、常にフォーム全体の検証結果から導き出されます。

formStateisValidatingboolean検証中はtrueに設定されます。
formStatevalidatingFieldsboolean非同期検証を取得しているフィールドをキャプチャします。
formStateerrorsobjectフィールドエラーを含むオブジェクト。エラーメッセージを簡単に取得するための ErrorMessage コンポーネントもあります。

例

CodeSandbox JS
import { TextField } from "@material-ui/core";
import { useController, useForm } from "react-hook-form";


function Input({ control, name }) {
  const {
    field,
    fieldState: { invalid, isTouched, isDirty },
    formState: { touchedFields, dirtyFields }
  } = useController({
    name,
    control,
    rules: { required: true },
  });


  return (
    <TextField 
      onChange={field.onChange} // send value to hook form 
      onBlur={field.onBlur} // notify when input is touched/blur
      value={field.value} // input value
      name={field.name} // send down the input name
      inputRef={field.ref} // send input ref, so we can focus on input when error appear
    />
  );
}
CodeSandbox TS
import * as React from "react";
import { useController, useForm } from "react-hook-form";


const Checkboxes = ({ options, control, name }) => {
  const { field } = useController({
    control,
    name
  });
  const [value, setValue] = React.useState(field.value || []);


  return (
    <>
      {options.map((option, index) => (
        <input
          onChange={(e) => {
            const valueCopy = [...value];


            // update checkbox value
            valueCopy[index] = e.target.checked ? e.target.value : null;


            // send data to react hook form
            field.onChange(valueCopy);


            // update local state
            setValue(valueCopy);
          }}
          key={option}
          checked={value.includes(option)}
          type="checkbox"
          value={option}
        />
      ))}
    </>
  );
};


export default function App() {
  const { register, handleSubmit, control } = useForm({
    defaultValues: {
      controlled: [],
      uncontrolled: []
    }
  });
  const onSubmit = (data) => console.log(data);


  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <section>
        <h2>uncontrolled</h2>
        <input {...register("uncontrolled")} type="checkbox" value="A" />
        <input {...register("uncontrolled")} type="checkbox" value="B" />
        <input {...register("uncontrolled")} type="checkbox" value="C" />
      </section>


      <section>
        <h2>controlled</h2>
        <Checkboxes
          options={["a", "b", "c"]}
          control={control}
          name="controlled"
        />
      </section>
      <input type="submit" />
    </form>
  );
}

ヒント

  • MUI、AntD、Chakra UIなどの外部制御コンポーネントを使用する場合は、各propの役割を認識することが重要です。その役割は、入力を監視し、報告し、値を設定することです。

    • onChange: データをフックフォームに送信します

    • onBlur: 入力が操作されたことを報告します（フォーカスとブラー）

    • value: 入力の初期値と更新値を設定します

    • ref: エラーで入力をフォーカスできるようにします

    • name: 入力に一意の名前を付けます

    状態をホストし、 useController.

    CodeSandbox TS
    const { field } = useController();
    const [value, setValue] = useState(field.value);
    

    onChange={(event) => {
      field.onChange(parseInt(event.target.value)) // data send back to hook form
      setValue(event.target.value) // UI state
    }}

  • と組み合わせても問題ありません。入力を再度registerしないでください。このカスタムフックは、登録プロセスを処理するように設計されています。

    const { field } = useController({ name: 'test' })
    

    <input {...field} /> // ✅
    <input {...field} {...register('test')} /> // ❌ double up the registration

  • コンポーネントごとに単一のuseControllerを使用するのが理想的です。複数使用する必要がある場合は、propの名前を変更してください。代わりにControllerの使用を検討することをお勧めします。代わりに。

    const { field: input } = useController({ name: 'test' })
    const { field: checkbox } = useController({ name: 'test1' })
    

    <input {...input} />
    <input {...checkbox} />

ご支援ありがとうございます

もしあなたのプロジェクトでReact Hook Formが役に立つようでしたら、スターを付けてサポートを検討してください。