Fetcher

中文

English

中文

English

Appearance

过滤器与可编辑面板 ​

维护期（已弃用）

@ahoo-wang/fetcher-viewer 已进入维护期（弃用），仅维护现有功能，不再新增功能。数据视图能力的后续演进由 @ahoo-wang/fetcher-view-engine 承担，新项目请使用 View Engine。本页保留供存量项目维护参考；两者模型与 API 不同，迁移需要适配。

Viewer 过滤器目前生成旧 Wow Condition，不生成新 FilterExpression。FilterValue 包装 {condition}；FilterState 保留 UI operator 和原始 value，即使当前值不是有效查询。

组件 / 类型键操作符 / 默认值
TextFilter / text默认 EQ，另有 NE、CONTAINS、STARTS_WITH、ENDS_WITH、IN、NOT_IN。
IdFilter / id默认 ID，另有 IDS，切换时转换单值/数组。
NumberFilter / number默认 EQ，另有 NE、GT、LT、GTE、LTE、BETWEEN、IN、NOT_IN，切换单值/范围/tag 输入。
SelectFilter / select默认 IN，另有 NOT_IN，多选，options 放 value props。
BoolFilter / bool默认 ExtendedOperator.UNDEFINED，另有 TRUE/FALSE，无值输入。
TypedFilter type datetime内置日期实现注册在 datetime；DateTimeFilter 及其转换器不是根导出，使用此分发器。
AssemblyFilter必填 supportedOperators，可被 operator.supportedOperators 覆盖。空列表抛错；合法 defaultValue 优先，否则用首操作符。

FilterProps 要求 field {name,label}；operator/value 可提供 UI 参数/defaultValue，conditionOptions 传旧查询选项，ref 暴露 getValue/getState/reset，onChange 接收 FilterValue 或 undefined。useFilterState 初始化 operator/value，不会每次 prop 变化都变成受控值；setter 先转换/校验/解析再通知。ExtendedOperator.UNDEFINED 不生成条件。默认校验拒绝 null/undefined/空字符串/空数组，对 EMPTY_VALUE_OPERATORS 接受无值，BETWEEN 要求恰好两个非空边界。NumberFilter 使用较宽松的自身数值输入校验。isValidValue 仅拒绝 null/undefined，不校验有限数值；信任边界校验需另行提供。

FilterPanel 收集子 ref，用旧 and(...) 组合有效条件，无有效子项时为 all()。Search 调用 onSearch(condition, conditionMap, stateMap)。Reset 只重置子值，不隐式搜索；Enter 搜索，但 IME 组合期间除外。resetButton 默认显示，false 隐藏。EditableFilterPanel 增删定义、调用 onChange(activeFilters)，filters 引用改变时同步。AvailableFilterSelect 返回新选中可用项，排除已有 active key。Modal open/close 归父级。

datetime 分发器对普通日期使用毫秒，before-today 使用本地 HH:mm:ss 文本，相对天数使用整数。范围末端恰为零点时扩展为当天结束。无效/禁用值会省略，不作为错误条件发送。FallbackFilter 显示不支持类型提示。组件本身不请求数据；定制见 注册表。

定义、输入状态与输出查询 ​

值使用者与含义
AvailableFilter / ActiveFilter可选目录项与选中实例；实例 key 让面板保留/移除正确过滤器。
field.name / field.label查询数据路径 / 展示标题；不会把 label 当作查询路径。
operator.defaultValue / value.defaultValue初始 UI 选项，不是持续受控输入；改变默认值时有意识地使用 reset/remount。
FilterState恢复编辑所需的原始 operator/value，即使尚未完整。
FilterValue.condition有效旧 Condition 或无输出值；下游数据加载消费该查询值。
面板 conditionMap / stateMap合并条件之外的逐过滤器查询 / UI 快照；只保存其中之一可能丢失另一种职责。

面板搜索产出查询，不产出已过滤行。应用 onLoadData 或 FetcherViewer 加载器负责执行。输入验证面向 UI，远端字段授权与查询准入仍由服务端负责。

完整示例 ​

tsx
import { FilterPanel } from '@ahoo-wang/fetcher-viewer';
import type { ActiveFilter } from '@ahoo-wang/fetcher-viewer';
import { Operator } from '@ahoo-wang/fetcher-wow';
const filters: ActiveFilter[] = [
  {
    key: 'name',
    type: 'text',
    field: { name: 'state.name', label: 'Name' },
    operator: { defaultValue: Operator.CONTAINS },
    value: { defaultValue: 'Ada' },
  },
];
export function SearchPanel() {
  return (
    <FilterPanel
      filters={filters}
      onSearch={condition => console.log(condition)}
    />
  );
}

公开签名与类型 ​

以下签名按当前根入口可达声明核对。? 表示可省略；泛型/接口只约束编译期，继承项与关联类型可从 符号索引 定位。运行时默认值和失败行为以本页上文为准。

OPERATOR_zh_CN ​

ts
declare const OPERATOR_zh_CN: SelectOperatorLocale;

packages/viewer/src/filter/operator/locale/operator.zh_CN.ts:16

ExtendedOperator ​

ts
export enum ExtendedOperator {
  UNDEFINED = 'UNDEFINED',
}

packages/viewer/src/filter/operator/types.ts:16

SelectOperator ​

ts
export type SelectOperator = ExtendedOperator | Operator;

packages/viewer/src/filter/operator/types.ts:20

SelectOperatorLocale ​

ts
export type SelectOperatorLocale = {
  [K in Operator]: string;
} & {
  [K in ExtendedOperator]: string;
};

packages/viewer/src/filter/operator/types.ts:22

AvailableFilterSelect ​

ts
export function AvailableFilterSelect(
  props: AvailableFilterSelectProps,
): import('react').JSX.Element;

packages/viewer/src/filter/panel/AvailableFilterSelect.tsx:57

AvailableFilter ​

ts
export interface AvailableFilter extends AttributesCapable {
  key: Key;
  field: FilterField;
  component: FilterType;
  value?: FilterValueProps;
  operator?: FilterOperatorProps;
  conditionOptions?: ConditionOptions;
}

packages/viewer/src/filter/panel/AvailableFilterSelect.tsx:31

AvailableFilterGroup ​

ts
export interface AvailableFilterGroup {
  label: string;
  filters: AvailableFilter[];
}

packages/viewer/src/filter/panel/AvailableFilterSelect.tsx:40

AvailableFilterSelectRef ​

ts
export interface AvailableFilterSelectRef {
  getValue(): AvailableFilter[];
}

packages/viewer/src/filter/panel/AvailableFilterSelect.tsx:45

AvailableFilterSelectProps ​

ts
export interface AvailableFilterSelectProps
  extends StyleCapable, RefAttributes<AvailableFilterSelectRef> {
  filters: AvailableFilterGroup[];
  activeFilters?: ActiveFilter[];
}

packages/viewer/src/filter/panel/AvailableFilterSelect.tsx:49

AvailableFilterSelectModal ​

ts
export function AvailableFilterSelectModal(
  props: AvailableFiltersModalProps,
): React.JSX.Element;

packages/viewer/src/filter/panel/AvailableFilterSelectModal.tsx:29

AvailableFiltersModalProps ​

ts
export interface AvailableFiltersModalProps extends Omit<ModalProps, 'onOk'> {
  availableFilters: Omit<AvailableFilterSelectProps, 'ref'>;
  onSave?: (filters: AvailableFilter[]) => void;
}

packages/viewer/src/filter/panel/AvailableFilterSelectModal.tsx:24

EditableFilterPanel ​

ts
export function EditableFilterPanel(
  props: EditableFilterPanelProps,
): React.JSX.Element;

packages/viewer/src/filter/panel/EditableFilterPanel.tsx:35

EditableFilterPanelProps ​

ts
export interface EditableFilterPanelProps extends Omit<
  FilterPanelProps,
  'actions'
> {
  availableFilters: AvailableFilterGroup[];
  onChange?: (filters: ActiveFilter[]) => void;
}

packages/viewer/src/filter/panel/EditableFilterPanel.tsx:27

FilterPanel ​

ts
export function FilterPanel(props: FilterPanelProps): React.JSX.Element;

packages/viewer/src/filter/panel/FilterPanel.tsx:92

ActiveFilter ​

ts
export interface ActiveFilter extends Omit<
  TypedFilterProps,
  'onChange' | 'ref'
> {
  key: Key;
  onRemove?: () => void;
}

packages/viewer/src/filter/panel/FilterPanel.tsx:29

FilterPanelConditionCapableRef ​

ts
export interface FilterPanelConditionCapableRef {
  getCondition(): Condition | undefined;
}

packages/viewer/src/filter/panel/FilterPanel.tsx:37

FilterPanelRef ​

ts
export interface FilterPanelRef extends FilterPanelConditionCapableRef {
  search(): void;
  reset(): void;
}

packages/viewer/src/filter/panel/FilterPanel.tsx:47

FilterPanelProps ​

ts
export interface FilterPanelProps extends RefAttributes<FilterPanelRef> {
  row?: RowProps;
  col?: ColProps;
  actionsCol?: ColProps;
  filters: ActiveFilter[];
  actions?: React.ReactNode;
  onSearch?: (
    finalCondition: Condition,
    activeFilterValues: Map<Key, Condition>,
    filterStates: Map<Key, FilterState>,
  ) => void;
  resetButton?: boolean | Omit<ButtonProps, 'onClick'>;
  searchButton?: Omit<ButtonProps, 'onClick'>;
}

packages/viewer/src/filter/panel/FilterPanel.tsx:61

RemovableTypedFilter ​

ts
export function RemovableTypedFilter(
  props: RemovableTypedFilterProps,
): React.JSX.Element;

packages/viewer/src/filter/panel/RemovableTypedFilter.tsx:26

RemovableTypedFilterProps ​

ts
export interface RemovableTypedFilterProps extends TypedFilterProps {
  onRemove?: () => void;
}

packages/viewer/src/filter/panel/RemovableTypedFilter.tsx:22

AssemblyFilter ​

ts
export function AssemblyFilter(
  options: AssemblyFilterProps,
): import('react').JSX.Element;

packages/viewer/src/filter/AssemblyFilter.tsx:45

ValueInputRender ​

ts
export type ValueInputRender = (
  filterState: UseFilterStateReturn,
) => ReactNode | null;

packages/viewer/src/filter/AssemblyFilter.tsx:30

AssemblyFilterProps ​

ts
export interface AssemblyFilterProps<
  ValuePropsType extends FilterValueProps = FilterValueProps,
> extends FilterProps<ValuePropsType> {
  supportedOperators: SelectOperator[];
  onOperatorChangeValueConverter?: OnOperatorChangeValueConverter;
  validate?: ValidateValue;
  conditionValueParser?: ConditionValueParser;
  filterValueConverter?: FilterValueConverter;
  valueInputRender?: ValueInputRender;
}

packages/viewer/src/filter/AssemblyFilter.tsx:34

BoolFilter ​

ts
export function BoolFilter(props: FilterProps): import('react').JSX.Element;

packages/viewer/src/filter/BoolFilter.tsx:28

ts
BoolFilter;

packages/viewer/src/filter/BoolFilter.tsx:42

BOOL_FILTER ​

ts
declare const BOOL_FILTER: 'bool';

packages/viewer/src/filter/BoolFilter.tsx:22

FallbackFilter ​

ts
export function FallbackFilter(options: TypedFilterProps): React.JSX.Element;

packages/viewer/src/filter/FallbackFilter.tsx:20

ts
FallbackFilter;

packages/viewer/src/filter/FallbackFilter.tsx:44

filterRegistry ​

ts
declare const filterRegistry: TypedComponentRegistry<
  string,
  FilterProps<import('./types').FilterValueProps>
>;

packages/viewer/src/filter/filterRegistry.ts:73

IdFilter ​

ts
export function IdFilter(props: FilterProps): import('react').JSX.Element;

packages/viewer/src/filter/IdFilter.tsx:48

ts
IdFilter;

packages/viewer/src/filter/IdFilter.tsx:73

ID_FILTER ​

ts
declare const ID_FILTER: 'id';

packages/viewer/src/filter/IdFilter.tsx:25

IdOnOperatorChangeValueConverter ​

ts
declare const IdOnOperatorChangeValueConverter: OnOperatorChangeValueConverter;

packages/viewer/src/filter/IdFilter.tsx:27

NumberFilter ​

ts
export function NumberFilter(props: FilterProps): import('react').JSX.Element;

packages/viewer/src/filter/NumberFilter.tsx:67

ts
NumberFilter;

packages/viewer/src/filter/NumberFilter.tsx:141

NUMBER_FILTER ​

ts
declare const NUMBER_FILTER: 'number';

packages/viewer/src/filter/NumberFilter.tsx:26

NumberOnOperatorChangeValueConverter ​

ts
declare const NumberOnOperatorChangeValueConverter: OnOperatorChangeValueConverter;

packages/viewer/src/filter/NumberFilter.tsx:49

SelectFilter ​

ts
export function SelectFilter(
  props: FilterProps<SelectFilterValueProps>,
): import('react').JSX.Element;

packages/viewer/src/filter/SelectFilter.tsx:48

ts
SelectFilter;

packages/viewer/src/filter/SelectFilter.tsx:69

SELECT_FILTER ​

ts
declare const SELECT_FILTER: 'select';

packages/viewer/src/filter/SelectFilter.tsx:25

SelectFilterValueProps ​

ts
export interface SelectFilterValueProps
  extends
    FilterValueProps,
    Omit<
      SelectProps,
      | 'defaultValue'
      | 'mode'
      | 'value'
      | 'allowClear'
      | 'onChange'
      | 'placeholder'
    > {}

packages/viewer/src/filter/SelectFilter.tsx:27

SelectOnOperatorChangeValueConverter ​

ts
declare const SelectOnOperatorChangeValueConverter: OnOperatorChangeValueConverter;

packages/viewer/src/filter/SelectFilter.tsx:40

TextFilter ​

ts
export function TextFilter(props: FilterProps): import('react').JSX.Element;

packages/viewer/src/filter/TextFilter.tsx:53

ts
TextFilter;

packages/viewer/src/filter/TextFilter.tsx:97

TEXT_FILTER ​

ts
declare const TEXT_FILTER: 'text';

packages/viewer/src/filter/TextFilter.tsx:25

TextOnOperatorChangeValueConverter ​

ts
declare const TextOnOperatorChangeValueConverter: OnOperatorChangeValueConverter;

packages/viewer/src/filter/TextFilter.tsx:27

TypedFilter ​

ts
export function TypedFilter(
  props: TypedFilterProps,
): React.FunctionComponentElement<TypedFilterProps>;

packages/viewer/src/filter/TypedFilter.tsx:30

ts
TypedFilter;

packages/viewer/src/filter/TypedFilter.tsx:45

FilterType ​

ts
export type FilterType = string;

packages/viewer/src/filter/TypedFilter.tsx:20

TypedFilterProps ​

ts
export interface TypedFilterProps
  extends FilterProps, TypeCapable<FilterType> {}

packages/viewer/src/filter/TypedFilter.tsx:22

FilterField ​

ts
export interface FilterField extends NamedCapable {
  label: string;
  type?: string;
  format?: string;
}

packages/viewer/src/filter/types.ts:28

FilterRef ​

ts
export interface FilterRef {
  getValue(): FilterValue | undefined;
  getState(): FilterState;
  reset(): void;
}

packages/viewer/src/filter/types.ts:34

FilterState ​

ts
export interface FilterState {
  operator: SelectOperator;
  value: Optional;
}

packages/viewer/src/filter/types.ts:42

FilterLabelProps ​

ts
export interface FilterLabelProps extends StyleCapable {}

packages/viewer/src/filter/types.ts:47

FilterOperatorProps ​

ts
export interface FilterOperatorProps extends Omit<
  SelectProps<SelectOperator>,
  'value' | 'options' | 'mode'
> {
  locale?: SelectOperatorLocale;
  supportedOperators?: SelectOperator[];
}

packages/viewer/src/filter/types.ts:49

FilterValueProps ​

ts
export interface FilterValueProps extends StyleCapable {
  defaultValue?: any;
  placeholder?: string;
  [key: string]: any;
}

packages/viewer/src/filter/types.ts:57

FilterValue ​

ts
export interface FilterValue extends ConditionCapable {}

packages/viewer/src/filter/types.ts:64

FilterProps ​

ts
export interface FilterProps<
  ValuePropsType extends FilterValueProps = FilterValueProps,
>
  extends AttributesCapable, RefAttributes<FilterRef>, StyleCapable {
  field: FilterField;
  label?: FilterLabelProps;
  operator?: FilterOperatorProps | null;
  value?: ValuePropsType | null;
  onChange?: (value?: FilterValue) => void;
  conditionOptions?: ConditionOptions;
}

packages/viewer/src/filter/types.ts:66

FilterComponent ​

ts
export type FilterComponent = React.FunctionComponent<FilterProps>;

packages/viewer/src/filter/types.ts:78

useFilterState ​

ts
export function useFilterState(
  options: UseFilterStateOptions,
): UseFilterStateReturn;

packages/viewer/src/filter/useFilterState.ts:101

OnOperatorChangeValueConverter ​

ts
export type OnOperatorChangeValueConverter = (
  beforeOperator: SelectOperator,
  afterOperator: SelectOperator,
  value: Optional,
) => Optional;

packages/viewer/src/filter/useFilterState.ts:24

OnChange ​

ts
export type OnChange = (condition: Optional<FilterValue>) => void;

packages/viewer/src/filter/useFilterState.ts:29

ValidateValue ​

ts
export type ValidateValue = (operator: Operator, value: Optional) => boolean;

packages/viewer/src/filter/useFilterState.ts:30

ConditionValueParser ​

ts
export type ConditionValueParser = (
  operator: Operator,
  value: Optional,
) => Optional;

packages/viewer/src/filter/useFilterState.ts:31

FilterValueConverter ​

ts
export type FilterValueConverter = (
  filterValue: FilterValue,
) => Optional<FilterValue>;

packages/viewer/src/filter/useFilterState.ts:35

TrueValidateValue ​

ts
declare const TrueValidateValue: ValidateValue;

packages/viewer/src/filter/useFilterState.ts:38

UseFilterStateOptions ​

ts
export interface UseFilterStateOptions extends RefAttributes<FilterRef> {
  field?: string;
  operator: SelectOperator;
  value: Optional;
  conditionOptions?: ConditionOptions;
  onOperatorChangeValueConverter?: OnOperatorChangeValueConverter;
  validate?: ValidateValue;
  conditionValueParser?: ConditionValueParser;
  filterValueConverter?: FilterValueConverter;
  onChange?: OnChange;
}

packages/viewer/src/filter/useFilterState.ts:42

UseFilterStateReturn ​

ts
export interface UseFilterStateReturn {
  operator: SelectOperator;
  value: Optional;
  setOperator: (operator: SelectOperator) => void;
  setValue: (value: Optional) => void;
  reset: () => void;
}

packages/viewer/src/filter/useFilterState.ts:54

isValidBetweenValue ​

ts
export function isValidBetweenValue(value: any): boolean;

packages/viewer/src/filter/utils.ts:29

isValidValue ​

ts
export function isValidValue(value: any): boolean;

packages/viewer/src/filter/utils.ts:57

currentTimeZone ​

ts
export function currentTimeZone(): string;

packages/viewer/src/filter/utils.ts:78

相关专题 ​

模型与状态所有权 · View 与 Viewer 组合 · 已保存视图面板与持久化回调 · FetcherViewer 远端集成 · 表格、列与单元格 · 注册表、输入与全屏按钮 · 工具栏、刷新与本地化

基于 Apache License 2.0 发布。

Copyright 2024-present Ahoo Wang