⚠️ ATTENTION ⚠️

Проект перемещён в главный репозиторий компонентов.

@n3/react-filters

Установка

npm install @n3/react-filters

или

yarn add @n3/react-filters

API

Использование

import Filters from '@n3/react-filters';


...

<Filters
  isAdaptive={isAdaptive}
  filters={filters}
  filterData={filterData}
  values={values}
  errors={errors}
  appliedFilters={appliedFilters}
  canReset={canReset}
  setValues={setValues}
  applyFilters={applyFilters}
  handleReset={handleReset}
  typeKey={typeKey}
  labelKey={labelKey}
  filtersBlockComponent={filtersBlockComponent}
/>

Props

• isAdaptive: Boolean - необязательное, включить ли адаптивное поведение фильтров, по умолчанию true

• values: Object - необязательное, текущие значения фильтров, по умолчанию {}

• errors: Object - необязательное, текущие ошибки фильтров, по умолчанию {}

• appliedFilters: Object - необязательное, значения применённых фильтров, по умолчанию {}

• canReset: Boolean - необязательное, возможен ли сброс фильтров, по умолчанию false

• setFiltersValues: Function - обязательное, хэндлер, срабатывающий при изменении значений фильтров. Принимает объект изменённых фильтров

• setAndApplyFilters: Function - обязательное, аналогично, setFiltersValues, но должно сразу применить фильтры с новыми значениями

• applyFilters: Function - обязательное, функция применения фильтров

• handleReset: Function - необязательное, функция сброса фильтров

• filters: Object - обязательное, объект описаний используемых фильтров. Ключ - тип фильтра, значение - описание фильтра

• filterData: Array - обязательное, массив используемых фильтров

  • name - обязательное, название фильтра
  • label - обязательное, заголовок фильтра, ключ может быть изменён с помощью свойства labelKey
  • type - обязательное, тип фильтра, ключ может быть изменён с помощью свойства typeKey
  • required - необязательное, признак обязательности фильтра - отображается звёздочка вместе с заголовком, пустые фильтры с признаком required блокируют кнопку Найти, ключ может быть изменён с помощью свойства requiredKey

• typeKey: String - необязательное, ключ для получения типа фильтра, по умолчанию type

• labelKey: String - необязательное, ключ для получения заголовка фильтра, по умолчанию label

• requiredKey: String - необязательное, ключ для получения признака обязательности фильтра, по умолчанию required

• fastFiltersNumber - Number, необязательное, количество быстрых фильтров, по умолчанию 0

• collapsibleButtonText: Function | String - необязательное, текст или функция, возвращающая текст, для кнопки раскрытия/скрытия блока с фильтрами, по умолчанию Все фильтры, в качестве аргумента функции передаётся внутреннее состояние блока { opened: boolean }

• resetButtonText: String - необязательное, текст для кнопки сброса всех фильтров, по умолчанию Сбросить

• actionsBlock: Element - необязательное, группа кнопок, расположенных в верхнем-правом углу блока с фильтрами

• filtersBlockComponent: Function - необязательное, кастомный компонент блока фильтров. Принимает props:

  • isAdaptive - из компонента Filters
  • filters - из компонента Filters
  • filterData - из компонента Filters
  • labelKey - из компонента Filters
  • typeKey - из компонента Filters
  • values - из компонента Filters
  • errors - из компонента Filters
  • setValues - из компонента Filters
  • applyFilters - асинхронная функция, сначала вызывает applyFilters из компонента Filters, затем в случае успеха закрывает блок фильтров. Для обозначения ошибки применения фильтров нужно бросить исключение ApplyFiltersError.

• styles: Object - необязательное, принимает объект, ключи которого представляют различные внутренние компоненты, составляющих блок с фильтрами

  • filtersBlock: Function, возвращает новые стили для элемента, содержащего фильтры
  • filterBlock: Function, возвращает новые стили для фильтра
  • actionsBlock: Function, возвращает новые стили для группы кнопок, расположенных в верхнем-правом углу блока с фильтрами
  • appliedIndicator: Function, возвращает новые стили для индикатора применения фильтра

import { ApplyFiltersError } from '@n3/react-filters';

async function applyFilters() {

  ...

  throw new ApplyFiltersError();

}

Описания фильтров

Каждое описание фильтра иммет формат @n3/filters-utils, и представляется объектом вида:

• component - react-компонент фильтра. Принимает следующие props:

  • isFastFilter: Boolean - отрендерен ли фильтр в блоке быстрых фильтров
  • label: String - лейбл поля
  • payload: Object - объект, переданный в filtersData
  • values: Object - текущие значения фильтров
  • errors: Object - текущие ошибки фильтров
  • filters: Object - объект, переданный в Filters
  • setFiltersValues: Function - из родительского компонента
  • setAndApplyFilters: Function - из родительского компонента
  • setValues: Function - хэндлер, который нужно вызывать при изменении значения фильтра. Первым аргументом принимает объект, ключами которого являются имена изменённых фильтров, а значениями - значения фильтров. Для быстрых фильтров принимает setAndApplyFilters, а для обычных - setFiltersValues

• checkForApplied: Function - необязательная, функция проверки, применён ли фильтр. Первым аргументом принимает payload (объект, переданный в filtersData), а вторым - appliedFilters главного компонента. Должна возвращать массив булево значение. По умолчанию, берёт значение из appliedFilters по ключу payload.name и проверяет его на истинность

• getNames: Function - необязательная, смотри @n3/filters-utils

• serializeValues: Function - необязательная, смотри @n3/filters-utils

• checkCanReset: Function - необязательная, смотри @n3/filters-utils

• parseValues: Function - необязательная, смотри @n3/filters-utils

Интеграция c react-filterlist

Рекомендуемый способ использования. Инкапсулирует сериализацию, парсинг, изменения, отслеживание возможности сброса фильтров, передачу параметров values, errors и appliedFilters.

Filterlist нужно установить отдельно.

yarn add @vtaits/filterlist @vtaits/react-filterlist

Импорт

// commonjs
import { Filterlist, Filters } from '@n3/react-filters/lib/filterlist';

// es modules
import { Filterlist, Filters } from '@n3/react-filters/es/filterlist';

Использование

<Filterlist
  filters={filters}
  filterData={filterData}
  labelKey={labelKey}
  typeKey={typeKey}
  loadItems={loadItems}
  parseFiltersAndSort={parseFiltersAndSort}
  onChangeLoadParams={onChangeLoadParams}
  {...otherFilterlistProps}
>
  {({
    isListInited,
    listState,
    listActions,
  }) => (
    <div>
      <Filters
        isAdaptive={isAdaptive}
        filtersBlockComponent={filtersBlockComponent}
      />

      {otherJsx}
    </div>
  )}
</Filterlist>

• filters - смотри выше;

• filterData - смотри выше;

• labelKey - смотри выше;

• typeKey - смотри выше;

• isAdaptive - смотри выше;

• filtersBlockComponent - смотри выше;

• loadItems - аналогично функции loadItems из filterlist, но принимает вторым аргументом объект { serializedValues: {...} }, где serializedValues - сериализованные значения фильтров;

• onChangeLoadParams - аналогично функции onChangeLoadParams из react-filterlist, но принимает вторым аргументом объект { serializedValues: {...} }, где serializedValues - сериализованные значения фильтров;

• parseFiltersAndSort - аналогично функции parseFiltersAndSort из react-filterlist, но принимает вторым аргументом объект { parseValues }, где parseValues - асинхронная функция парсинга значений, принимающая только один аргумент - объект значений;

• otherFilterlistProps - остальные параметры react-filterlist за исключением isRecountAsync, оно всегда true;

• isListInited - смотри react-filterlist;

• listState - смотри react-filterlist;

• listActions - смотри react-filterlist;

Стили

Готовые стили

import '@n3/react-filters/dist/n3-react-filters.css';

Исходные postcss-стили

import '@n3/react-filters/postcss/n3-react-filters.css';

Для сборки необходим плагин precss, а также настроен импорт из директории node_modules.

Исходные postcss-стили без определения css-переменных

import '@n3/react-filters/postcss/without-variables.css';

Для сборки необходим плагин precss, а также настроен импорт из директории node_modules.