React Query Builder の概要

Ignite UI for React Query Builder は、指定したデータ セットに対する複雑なデータ フィルタリング クエリを構築できる豊富な UI を提供します。このコンポーネントでは、式ツリーを作成し、各フィールドのデータ型に応じたエディターと条件リストを使用して、式の間に AND / OR 条件を指定できます。作成した式ツリーは、その後バックエンドでサポートされる形式のクエリへ簡単に変換できます。

React Query Builder の使用を開始するには

IgrQueryBuilder の使用を開始するには、まず次のコマンドを実行して Ignite UI for React パッケージをインストールします:

npm install igniteui-react igniteui-react-grids

プロジェクト構成に応じて、対応するスタイルも参照する必要があります。

import 'igniteui-webcomponents-grids/grids/themes/light/bootstrap.css';

React Query Builder の使用

初期の式ツリーが設定されていない場合は、まずエンティティと、クエリが返す対象フィールドを選択します。その後、条件またはサブグループを追加できます。

条件を追加するには、フィールド、フィールドのデータ型に基づく演算子、そして演算子が単項でない場合は値を選択します。In および Not In 演算子を使用すると、単に値を指定する代わりに、別のエンティティに対する条件を持つ内部クエリを作成できます。条件を確定すると、その条件情報を含むチップが表示されます。チップをクリックまたはホバーすると、その条件を編集したり、直後に別の条件やグループを追加したりできます。

各グループの上にある AND または OR ボタンをクリックすると、グループの種類を変更したり、内部の条件をグループ解除したりするためのメニューが開きます。

各条件は特定のエンティティの特定フィールドに関連付けられているため、エンティティを変更すると、事前に設定された条件およびグループはすべてリセットされます。

このコンポーネントは、Entities プロパティに、エンティティ名とそのフィールド配列を記述した配列を設定することで使用できます。各フィールドは、名前とデータ型によって定義されます。フィールドを選択すると、データ型に応じた対応する演算子が自動的に割り当てられます。 また Query Builder には ExpressionTree プロパティがあります。これを使用すると、コントロールの初期状態を設定したり、ユーザーが指定したフィルタリング ロジックにアクセスしたりできます。

const queryBuilderRef = useRef<IgrQueryBuilder>(null);

const ordersFields: Field[] = [
  { field: 'orderId', dataType: 'number' },
  { field: 'customerId', dataType: 'string' },
  { field: 'orderDate', dataType: 'date' }
];

const entities: Entity[] = [
  { name: 'Orders', fields: ordersFields }
];

const onExpressionTreeChange = (newTree: IgrFilteringExpressionsTree) => {
  // Handle expression tree changes
  console.log('Expression tree changed:', newTree);
};

const handleExpressionTreeChange = (event: CustomEvent<IgrFilteringExpressionsTree>) => {
  onExpressionTreeChange(event.detail);
};

useEffect(() => {
  const tree = new IgrFilteringExpressionsTree();
  tree.operator = FilteringLogic.And;
  tree.entity = 'Orders';

  if (queryBuilderRef.current) {
    const queryBuilder = queryBuilderRef.current;
    queryBuilder.entities = entities as any;
    queryBuilder.expressionTree = tree;
    queryBuilder.addEventListener('expressionTreeChange', handleExpressionTreeChange);
  }

  return () => {
    if (queryBuilderRef.current) {
      queryBuilderRef.current.removeEventListener('expressionTreeChange', handleExpressionTreeChange);
    }
  };
}, []);

return (
  <div className="container sample">
    <IgrQueryBuilder ref={queryBuilderRef} id="queryBuilder"></IgrQueryBuilder>
  </div>
);

IgrExpressionTree はバインド可能なプロパティです。つまり、ExpressionTreeChange イベントを購読して、エンドユーザーが条件を作成、編集、削除して UI を変更したときに通知を受け取ることができます。イベント リスナーは useEffect で登録され、返されるティアダウン関数でクリーンアップされます。

const handleExpressionTreeChange = (event: CustomEvent<IgrFilteringExpressionsTree>) => {
  onExpressionTreeChange(event.detail);
};

式のドラッグ

条件チップは、マウスのドラッグ アンド ドロップまたはキーボードによる並べ替えで簡単に位置を変更できます。これにより、ユーザーはクエリ ロジックを動的に調整できます。

• チップをドラッグしても、変更されるのは位置のみであり、条件や内容自体は変更されません。
• チップはグループおよびサブグループ間でもドラッグできます。たとえば、式のグループ化やグループ解除はこのドラッグ機能によって実現できます。 既存の条件をグループ化するには、まず「グループ追加」ボタンで新しいグループを追加します。その後、必要な式をドラッグしてそのグループへ移動できます。グループ解除するには、すべての条件を現在のグループ外へドラッグします。最後の条件が移動されると、そのグループは削除されます。

キーボード操作

キー操作

• Tab / Shift + Tab - 次 / 前のチップ、ドラッグ インジケーター、削除ボタン、「式を追加」ボタンへ移動します。
• Arrow Down/Arrow Up - チップのドラッグ インジケーターにフォーカスがある場合、チップを上下に移動できます。
• Space / Enter - フォーカスされた式が編集モードに入ります。チップの移動中であれば、新しい位置を確定します。
• Esc - チップの並べ替えをキャンセルし、元の位置に戻します。

テンプレート

Ignite UI for React Query Builder では、コンポーネントのヘッダーおよび検索値に対してテンプレートを定義できます:

ヘッダー テンプレート

既定では、IgrQueryBuilder のヘッダーは表示されません。ヘッダーを定義するには、IgrQueryBuilderHeader コンポーネントを Query Builder 内に追加する必要があります。

検索値テンプレート

条件の検索値は、SearchValueTemplate プロパティに lit-html テンプレートを返す関数を設定することでテンプレート化できます。

<IgrQueryBuilder 
  ref={queryBuilderRef} 
  id="queryBuilder"
  searchValueTemplate={buildSearchValueTemplate}>
  <IgrQueryBuilderHeader title="Query Builder Template Sample"></IgrQueryBuilderHeader>
</IgrQueryBuilder>

useEffect(() => {
  if (queryBuilderRef.current) {
    const queryBuilder = queryBuilderRef.current;
    queryBuilder.entities = entities as any;
    queryBuilder.expressionTree = tree;
  }
}, []);

const buildSearchValueTemplate = (ctx: QueryBuilderSearchValueContext) => {
  const field = ctx.selectedField?.field;
  const condition = ctx.selectedCondition;
  const matchesEqualityCondition = condition === 'equals' || condition === 'doesNotEqual';

  if (!ctx.implicit) {
    ctx.implicit = { value: null };
  }

  if (field === 'Region' && matchesEqualityCondition) {
    return buildRegionSelect(ctx);
  }

  if (field === 'OrderStatus' && matchesEqualityCondition) {
    return buildStatusRadios(ctx);
  }

  if (ctx.selectedField?.dataType === 'date') {
    return buildDatePicker(ctx);
  }

  if (ctx.selectedField?.dataType === 'time') {
    return buildTimeInput(ctx);
  }

  return buildDefaultInput(ctx, matchesEqualityCondition);
};

以下は、各エディター タイプごとに 1 つのテンプレート例を示したものです:

Region Select の例:

// Field definition
{ field: 'Region', dataType: 'string' }

// Template
const buildRegionSelect = (ctx: QueryBuilderSearchValueContext) => {
  const currentValue = ctx?.implicit?.value?.value ?? '';
  const key = `region-select-${currentValue}`;

  return (
    <IgrSelect
      className="qb-select"
      key={key}
      value={currentValue}
      onChange={(sender: any) => {
        const value = sender.detail.value;
        const currentKey = ctx?.implicit?.value?.value ?? '';

        if (!value || value === currentKey) return;

        setTimeout(() => {
          ctx.implicit.value = regionOptions.find(option => option.value === value) ?? null;
        });
      }}>
      {regionOptions.map(option => (
        <IgrSelectItem key={option.value} value={option.value}>
          <span>{option.text}</span>
        </IgrSelectItem>
      ))}
    </IgrSelect>
  );
};

Status Radio Group の例:

// Field definition
{ field: 'OrderStatus', dataType: 'number' }

// Template
const buildStatusRadios = (ctx: QueryBuilderSearchValueContext) => {
  const implicitValue = ctx.implicit?.value;
  const currentValue = implicitValue === null ? '' : implicitValue.toString();
  const key = `status-radio-${currentValue}`;

  return (
    <IgrRadioGroup
      key={key}
      style={{ gap: '5px' }}
      alignment="horizontal"
      value={currentValue}
      onChange={(sender: any) => {
        const value = sender.detail;
        if (value === undefined) return;

        const numericValue = Number(value);
        if (ctx.implicit.value === numericValue) return;

        setTimeout(() => {
          ctx.implicit.value = numericValue;
        });
      }}>
      {statusOptions.map(option => (
        <IgrRadio
          key={option.value}
          name="status"
          value={option.value.toString()}
          checked={option.value.toString() === currentValue}
          labelText={option.text}>
        </IgrRadio>
      ))}
    </IgrRadioGroup>
  );
};

Date Picker の例:

// Field definition
{ field: 'OrderDate', dataType: 'date' }

// Template
const buildDatePicker = (ctx: QueryBuilderSearchValueContext) => {
  const implicitValue = ctx.implicit?.value;
  const currentValue = implicitValue instanceof Date
    ? implicitValue
    : implicitValue
      ? new Date(implicitValue)
      : null;

  const allowedConditions = ['equals', 'doesNotEqual', 'before', 'after'];
  const isEnabled = allowedConditions.indexOf(ctx.selectedCondition ?? '') !== -1;
  const key = `date-picker-${currentValue}`;

  return (
    <IgrDatePicker
      key={key}
      value={currentValue}
      disabled={!isEnabled}
      onChange={(sender: any) => {
        setTimeout(() => {
          ctx.implicit.value = sender.detail;
        });
      }}>
    </IgrDatePicker>
  );
};

Time Input の例:

// Field definition
{ field: 'RequiredTime', dataType: 'time' }

// Template
const buildTimeInput = (ctx: QueryBuilderSearchValueContext) => {
  const currentValue = normalizeTimeValue(ctx.implicit?.value);
  const allowedConditions = ['at', 'not_at', 'at_before', 'at_after', 'before', 'after'];
  const isDisabled = ctx.selectedField == null || allowedConditions.indexOf(ctx.selectedCondition ?? '') === -1;
  const key = `time-input-${currentValue}`;

  return (
    <IgrDateTimeInput
      key={key}
      inputFormat="hh:mm tt"
      value={currentValue}
      disabled={isDisabled}
      onChange={(sender: any) => {
        setTimeout(() => {
          ctx.implicit.value = sender.detail;
        });
      }}>
      <div slot="prefix">
        <IgrIcon name="clock" collection="material" />
      </div>
    </IgrDateTimeInput>
  );
};

Default Input テンプレートの例:

// Field definitions for string, number, and boolean types
{ field: 'ShipCountry', dataType: 'string' }
{ field: 'OrderID', dataType: 'number' }
{ field: 'IsRushOrder', dataType: 'boolean' }

// Template that handles all these types
const buildDefaultInput = (ctx: QueryBuilderSearchValueContext, matchesEqualityCondition: boolean) => {
  const selectedField = ctx.selectedField;
  const dataType = selectedField?.dataType;
  const isNumber = dataType === 'number';
  const isBoolean = dataType === 'boolean';

  const placeholder = ctx.selectedCondition === 'inQuery' || ctx.selectedCondition === 'notInQuery'
    ? 'Sub-query results'
    : 'Value';

  const currentImplicitValue = ctx && ctx.implicit ? ctx.implicit.value : null;
  const currentValue = typeof currentImplicitValue === 'object' && currentImplicitValue && 'text' in currentImplicitValue
      ? equalityCondition ? currentImplicitValue.text : ''
      : currentImplicitValue;

  const inputValue = currentValue == null ? '' : currentValue;
  const disabledConditions = ['empty', 'notEmpty', 'null', 'notNull', 'inQuery', 'notInQuery'];
  const isDisabled = isBoolean || selectedField == null || disabledConditions.indexOf(ctx.selectedCondition ?? '') !== -1;
  const key = `default-input-${inputValue}`;

  return (
    <IgrInput 
      key={key}
      value={inputValue?.toString() || ''}
      disabled={isDisabled}
      placeholder={placeholder}
      type={isNumber ? 'number' : 'text'}
      onInput={(sender: any) => {
        const value = sender.detail;
        setTimeout(() => {
          ctx.implicit.value = isNumber
            ? value === '' ? null : Number(value)
            : value;
        });
      }}>
    </IgrInput>
  );
};

フォーマッター

条件が編集モードではないときにチップ内へ表示される検索値の見た目を変更するには、fields 配列に formatter 関数を設定します。検索値には次のように value 引数からアクセスできます:

const ordersFields = [
  { field: 'OrderID', dataType: 'number' },
  { field: 'ShipCountry', dataType: 'string' },
  {
    field: 'OrderDate',
    dataType: 'date',
    formatter: (value: any) => value.toLocaleDateString(queryBuilderRef.current?.locale, { 
      month: 'short', 
      day: 'numeric', 
      year: 'numeric' 
    })
  },
  {
    field: 'Region',
    dataType: 'string',
    formatter: (value: any) => value?.text ?? value?.value ?? value
  }
];

デモ

この例では、React Query Builder コンポーネントのヘッダーおよび検索値に対するテンプレート機能と formatter 機能を確認できます。

API リファレンス

その他のリソース

コミュニティは活発で、新しいアイデアをいつでも歓迎しています。

• Ignite UI for React Forums
• Ignite UI for React GitHub