JSON スキーマを使ってFormを生成するライブラリ、React JSON Schema Form (RJSF)

React JSON Schema Form v5は、JSON Schema を使用してフォームを生成するReactライブラリ。カスタマイズの柔軟性を駆使すれば、小規模から大規模まで幅広いプロジェクトに適応可能。ただし、初めて触れる場合は直感的ではなく、扱いにくさを感じることがあるかもしれない。

RJSFによるフォームの基本構成

  return (
    <Form
      schema={schema}
      uiSchema={uiSchema}
      formData={formData}
      onSubmit={handleSubmit}
      onChange={handleChange}
      validate={validate}
      widgets={widgets}
      ErrorList={CustomErrorList}
    />
  );

ドキュメントのトップページ: react-jsonschema-form domument
プレイグラウンド: playground

JSON Schema

フォームの構造を定義するためにこのスキーマを利用する。

// 使用例
const schema = {
  "type": "object",
  "properties": {
    "age": {
      "type": "integer",
      "minimum": 0
    },
    "status": {
      "type": "string",
      "enum": ["student", "employed"]
    }
  },
  "required": ["age"],
  "dependencies": {
    "age": {
      "oneOf": [
        {
          "properties": {
            "age": {"maximum": 18},
            "school": {"type": "string"}
          },
          "required": ["school"]
        },
        {
          "properties": {
            "age": {"minimum": 19},
            "job": {"type": "string"}
          },
          "required": ["job"]
        }
      ]
    }
  }
}

配列 (Arrays)

"type": "array" を使用して配列を定義し、items キーワードで各アイテムのスキーマを指定する

オブジェクト (Objects)

"type": "object" で定義する

依存関係 (Dependencies)

dependencies キーワードを使用して、入力されたデータに基づいてフィールドが動的に変化するスキーマを作成する

oneOf, anyOf, および allOf

oneOf, anyOf, allOf を使用して、複数のスキーマの中から一つまたは全てを満たすデータを許可する。RJSFはこれらのキーワードに対応するカスタムウィジェットをサポートしている

単一フィールド (Single fields)

フィールドの型を"type": "string"、"type": "number"、"type": "integer"、"type": "boolean"、"type": "null"などで指定する

スキーマ定義と参照 (Schema definitions and references)

インラインスキーマ定義の参照を解除することで、スキーマの一部を再利用することができる

ドキュメント: JSON Schema

uiSchema

UI Schemaを使用することで、ウィジェットのカスタマイズ、スタイルの指定、オートコンプリートやオートフォーカスの設定、フィールドの説明やヘルプテキストの追加、フィールドの有効/無効化や読み取り専用の設定、プレースホルダーやサブミットボタンのオプションのカスタマイズなど、フォームのレンダリングを細かくコントロールできる。

//使用例
const uiSchema = {
  firstName: {
    "ui:autofocus": true,
    "ui:placeholder": "Enter your first name",
    "ui:autocomplete": "family-name",
  },
  lastName: {
    "ui:emptyValue": "",
    "ui:autocomplete": "given-name",
  }
};

uiSchemaについての追加的なプロパティや設定方法に関する情報は、ここから探す:
ドキュメント: uiSchema

Widgets

Widgetsは、特定のフィールドをレンダリングするために使用する。uiSchema の ui:widget プロパティを介して設定する。

//使用例
import { RJSFSchema, UiSchema } from '@rjsf/utils';
import Form from '@rjsf/core';

export const MyForm = () => {
    const schema: RJSFSchema = {
      type: 'object',
      properties: {
        done: {
          type: 'boolean',
        },
      },
    };
    const uiSchema: UiSchema = {
      done: {
        'ui:widget': 'radio', // ラジオボタン
      },
    };
    return <Form schema={schema} uiSchema={uiSchema} />
}

ドキュメント: Widgets

Custom Widgets

uiSchemaを使って標準のフォーム要素に加えて、プロジェクト特有のカスタムウィジェットを組み込むことができる。これにより、独自のデザインや機能を持つフォーム要素をフォームに追加し、ユーザーエクスペリエンスを向上させることが可能になる。

// 使用例
import { RJSFSchema, UiSchema } from '@rjsf/utils';
import Form from '@rjsf/core';
import { Checkbox } from 'your-design-system'; // 実際のインポートパスに注意

export const MyForm = () => {
    const schema: RJSFSchema = {
        type: 'object',
        properties: {
            done: {
                type: 'boolean',
            },
        },
    };
    const uiSchema: UiSchema = {
        done: {
            'ui:widget': 'NewCheckbox', // カスタムウィジェット名
        },
    };
    return (<Form
              schema={schema} 
              uiSchema={uiSchema}
              widgets={{    
                NewCheckbox: (props) => ( // 実際のプロップスを使用
                  <Checkbox
                    {...props} // 必要に応じてプロップスを渡す
                  />
                ),
              }}
            />);
}

ドキュメント: Custom Widgets and Fields

formData

formDataは、フォームの初期値を設定し、ユーザーの入力による変更をリアルタイムで追跡する。

//使用例
import Form from '@rjsf/core';

const schema = {
  'type': 'object',
  'properties': {
    'name': {'type': 'string'},
    'age': {'type': 'number'}
  }
};

const formData = { //初期値を設定する
  'name': 'John Smith',
  'age': 40
};

function MyForm() {
  const onSubmit = (formData) => console.log("Data submitted: ", formData);

  return (
    <Form schema={schema} formData={formData} onSubmit={onSubmit} />
  );
}

formDataやその他のFormのプロパティや設定方法に関する情報は、ここから探す:
ドキュメント: <Form /> props

RJSFをさらに活用する場合: 型定義とUIカスタマイズ

RJSFで使う関数、定数、型定義(TypeScript)

@rjsf/utils ライブラリは、React JSON Schema Form (RJSF) をTypeScriptで使用するためのライブラリを提供する。

エクスポートされる主な型は以下の通り:
WidgetProps: カスタムウィジェットやフィールドを作成するのに必要なプロパティの型定義。
RJSFSchema: JSONスキーマやUIスキーマを扱うための型定義。

特定のタスクを実行したいときは、このライブラリの関数から探すとよい:
ドキュメント: RJSF utility functions, constants and types

テーマ(Themes)

API Reference内のthemesセクションには、RJSFでantd、chakra-ui、semantic-uiなどのUIフレームワークのテーマを利用する方法について説明がある。

ドキュメント: Themes
サポートされているテーマ: Thems

この記事の英語への翻訳はこちら: Generate Forms Using JSON Schema: React JSON Schema Form (RJSF)