react-query-builder查询构建器中文文档

简介

react-query-builder是一个React组件库，用于构建可配置的查询构建器。

使用react-query-builder，您可以轻松地构建复杂的查询表单，使用户能够以直观的方式构建和执行查询。

以下是一些常见的用例：

• 构建高级搜索表单，允许用户根据不同的条件搜索数据。
• 在数据可视化应用程序中使用，以允许用户筛选和过滤数据。
• 作为电子商务应用程序中的筛选器，允许用户根据价格范围、品牌、颜色等条件筛选商品。

react-query-builder的主要特点包括：

• 可配置性：react-query-builder允许您自定义每个查询条件的行为、外观和验证逻辑。
• 易于使用：react-query-builder提供了一个简单的API，使您能够轻松地构建和管理查询构建器。
• 可扩展性：react-query-builder是一个可扩展的库，允许您自定义和扩展其功能。

安装

您可以使用npm或yarn安装react-query-builder：

npm install react-query-builder

或者

yarn add react-query-builder

示例

下面是一个简单的示例，演示如何使用react-query-builder构建一个简单的查询表单：

import React from 'react';

import QueryBuilder from 'react-query-builder';

const fields = [

 { name: 'firstName', label: 'First Name', type: 'string' },

 { name: 'lastName', label: 'Last Name', type: 'string' },

 { name: 'age', label: 'Age', type: 'number' },

 { name: 'gender', label: 'Gender', type: 'select', options: ['Male', 'Female'] },

];

 const operators = [

 { name: '=', label: '=' },

 { name: '!=', label: '!=' },

 { name: '<', label: '<' },

 { name: '>', label: '>' },

];

const QueryBuilderExample = () => {

 const [query, setQuery] = React.useState(null);

 const onQueryChange = (query) => {

  setQuery(query);

 };

 return (

  <QueryBuilder

   fields={fields}

   operators={operators}

   onQueryChange={onQueryChange}

  />

 );

}; 

export default QueryBuilderExample;

在这个示例中，我们定义了四个字段：firstName、lastName、age和gender。每个字段都有一个名称、一个标签和一个类型。我们还定义了四个运算符：=、!=、<和>。

基本用法

QueryBuilder组件接受三个必需的属性：fields、operators和onQueryChange。

• fields：一个数组，包含所有可用的字段。每个字段应该有一个名称、一个标签和一个类型。
• operators：一个数组，包含所有可用的运算符。
• onQueryChange：一个回调函数，每当查询发生变化时都会被调用。这个函数应该接受一个查询对象作为参数。

在上面这个示例中，我们将onQueryChange函数定义为一个状态更新函数，以便我们能够在组件中跟踪查询状态。在实际应用程序中，您可能会将查询对象传递给API调用或其他组件等。

扩展用法

react-query-builder提供了许多选项和属性，以便您自定义和扩展其功能

属性

以下是QueryBuilder组件的可用属性：

• fields：一个包含所有可用字段的数组。每个字段应该是一个对象，包含以下属性：

  • name（必需）：字段名称，用于标识该字段。
  • label（必需）：字段标签，用于显示给用户。
  • type（必需）：字段类型。可以是文本（text）、数字（number）、日期（date）、时间（time）、日期时间（datetime）、下拉选项（select）等。支持的类型包括：string、number、date、time、datetime和select。
  • options（可选）：如果字段类型为select，则提供可用选项的数组。如果字段类型为下拉选项，则可以提供选项列表。这应该是一个字符串数组或对象数组，每个对象包含value和label属性。
  • operators：字段支持的运算符数组。如果省略，则使用默认运算符。
  • defaultValue：字段的默认值。
  • valueSources：字段支持的值来源。默认为['value']，即手动输入值。
  • fieldSettings：一个对象，包含用于自定义字段行为和外观的属性。有关更多信息，请参见下面的“自定义字段行为和外观”部分。

• operators：一个包含所有可用运算符的数组。每个运算符应该是一个对象，包含以下属性：

  • name（必需）：运算符名称；操作符名称，用于标识该操作符。

  • label（必需）：运算符标签。操作符标签，用于显示给用户。

  • valueTypes（必需）：操作符可以接受的值类型，应该是一个字符串数组，包含text、number、date、time、datetime和select。

  • defaultValue：运算符的默认值。

  • textSeparators：如果运算符需要两个文本输入值，则

以下是可用的组合器：

• combinators：一个包含所有可用组合器的数组。每个组合器应该是一个对象，包含以下属性：
  • name（必需）：组合器名称，用于标识该组合器。
  • label（必需）：组合器标签，用于显示给用户。
  • clause（必需）：组合器可以包含的子句数量，可以是single（单个子句）或multiple（多个子句）。

其他属性：

• onQueryChange：当查询更改时调用的回调函数。它接收当前查询作为参数。

• controlElements：一个对象，用于定义自定义控件元素。键应该是控件名称，值应该是一个包含以下属性的对象：

  • type（必需）：控件类型，可以是text、number、date、time、datetime和select。

  • props（可选）：控件属性，可以是任何传递给控件的属性，比如options（如果控件类型为下拉选项）。

  • allowEmpty：是否允许空查询，默认为false。

  • showCombinatorsBetweenRows：是否在行之间显示组合器，默认为false。

  • showNotToggle：是否显示否定切换按钮，默认为false。

  • enableDragAndDrop：是否启用拖放支持，默认为false。

  • enableCollapse：是否启用折叠支持，默认为false。

  • enableInvert：是否启用反转支持，默认为false。

  • enableDelete：是否启用删除支持，默认为false。

QueryBuilder组件具有许多可用的属性，以便您可以自定义和控制查询构建器的行为和外观。以下是QueryBuilder组件的可用属性：

• fields：一个数组，包含所有可用的字段。每个字段应该有一个名称、一个标签和一个类型。默认值为[]。
• operators：一个数组，包含所有可用的运算符。默认值为[]。
• combinators：一个数组，包含所有可用的组合器。默认值为[]。
• controlClassnames：一个对象，用于自定义控件的类名。可以使用这个属性来自定义控件的样式。默认值为{}。
• translations：一个对象，用于自定义组件的翻译。可以使用这个属性来自定义组件的语言。默认值为{}。
• getOperators：一个函数，用于获取特定字段的可用运算符。默认值为一个返回所有运算符的函数。
• getCombinaors：一个函数，用于获取特定条件的可用组合器。默认值为一个返回所有组合器的函数。
• onQueryChange：一个回调函数，每当查询发生变化时都会被调用。这个函数应该接受一个查询对象作为参数。默认值为一个空函数。
• controlElements：一个对象，用于自定义每个控件的外观和行为。默认值为一个包含所有默认控件元素的对象。
• enableMountQueryChange：一个布尔值，控制是否在组件挂载时调用onQueryChange函数。默认值为false。

上述属性中，fields、operators和combinators是QueryBuilder组件最基本的属性。它们定义了查询构建器中所有可用的字段、运算符和组合器。

controlClassnames和translations允许您自定义查询构建器中每个控件的样式和语言。

getOperators和getCombinators允许您自定义每个字段和条件的可用运算符和组合器。

onQueryChange是一个回调函数，每当查询发生变化时都会被调用。您可以使用这个函数来处理查询结果，例如将查询结果传递给API调用或其他组件。

controlElements允许您自定义每个控件的外观和行为。

enableMountQueryChange允许您在组件挂载时调用onQueryChange函数。默认情况下，只有在用户交互后才会调用onQueryChange函数。

这些属性使QueryBuilder组件非常灵活和可配置，允许您自定义和控制查询构建器的每个方面。