@ahoo-wang/fetcher-viewer


一个全面的 React 组件库，用于数据可视化和过滤，基于 Ant Design 和 Fetcher 生态系统。提供可重用的 UI 组件，用于构建具有高级过滤功能的数据驱动应用程序。

✨ 特性

- 🔍 高级过滤系统: 完整的过滤面板，支持动态过滤器类型、操作符和状态管理
- 📊 数据组件: 远程搜索选择器、标签输入、数字范围输入
- 🎨 Ant Design 集成: 与 Ant Design 组件无缝集成
- 🔧 TypeScript 优先: 完整的 TypeScript 支持和全面的类型定义
- ⚡ 性能优化: 防抖搜索、高效渲染和优化的状态管理
- 🧪 完善的测试: 使用 Vitest 和 React Testing Library 的全面测试覆盖

📦 安装

``bash


使用 npm

`tsx
import {
RemoteSelect,
TagInput,
NumberRange,
FilterPanel,
} from '@ahoo-wang/fetcher-viewer';
import { useFilterState } from '@ahoo-wang/fetcher-viewer';

// 基本用法
function App() {
const { filters, addFilter, removeFilter, updateFilter } = useFilterState();

return (


`tsx
import { RemoteSelect } from '@ahoo-wang/fetcher-viewer';

search={async (query: string) => {
// 返回选项数组
return [
{ label: '选项 1', value: '1' },
{ label: '选项 2', value: '2' },
];
}}
debounce={{ delay: 300 }}
placeholder="搜索..."
onChange={value => console.log(value)}
/>;
`

属性：

- search: (query: string) => Promise - 搜索函数
- debounce?: UseDebouncedCallbackOptions - 防抖配置
- ...SelectProps - 所有 Ant Design Select 属性

#### TagInput

支持不同值类型序列化的标签输入组件。

`tsx
import { TagInput, StringTagValueItemSerializer, NumberTagValueItemSerializer } from '@ahoo-wang/fetcher-viewer';

// 字符串标签
value={['tag1', 'tag2']}
onChange={(tags) => console.log(tags)}
/>

// 数字标签

value={[1, 2, 3]}
serializer={NumberTagValueItemSerializer}
onChange={(tags) => console.log(tags)}
/>
`

属性：

- value?: ValueItemType[] - 当前标签值
- serializer?: TagValueItemSerializer - 值序列化器
- onChange?: (value: ValueItemType[]) => void - 变更处理器
- ...SelectProps - 其他 Ant Design Select 属性

#### NumberRange

带有最小/最大值验证的数字范围输入组件。

`tsx
import { NumberRange } from '@ahoo-wang/fetcher-viewer';

value={[100, 500]}
min={0}
max={1000}
precision={2}
placeholder={['最小值', '最大值']}
onChange={range => console.log(range)}
/>;
`

属性：

- value?: number | NumberRangeValue - 当前范围值
- min?: number - 允许的最小值
- max?: number - 允许的最大值
- precision?: number - 小数精度
- placeholder?: string[] - 输入占位符
- onChange?: (value: NumberRangeValue) => void - 变更处理器

$3

#### FilterPanel

具有动态过滤器管理的综合过滤面板。

`tsx
import { FilterPanel, useFilterState } from '@ahoo-wang/fetcher-viewer';

function MyFilterComponent() {
const { filters, addFilter, removeFilter, updateFilter } = useFilterState();

return (
filters={filters}
availableFilters={[
{ name: 'name', label: '名称', type: 'text' },
{ name: 'age', label: '年龄', type: 'number' },
{ name: 'status', label: '状态', type: 'select' },
]}
onAddFilter={addFilter}
onRemoveFilter={removeFilter}
onUpdateFilter={updateFilter}
/>
);
}
`

#### useFilterState Hook

过滤器操作的状态管理 hook。

`tsx
import { useFilterState } from '@ahoo-wang/fetcher-viewer';

const {
filters, // 当前过滤器数组
addFilter, // 添加新过滤器
removeFilter, // 移除过滤器
updateFilter, // 更新过滤器
clearFilters, // 清除所有过滤器
getFilterValue, // 获取过滤器值
setFilterValue, // 设置过滤器值
resetFilters, // 重置到初始状态
} = useFilterState(initialFilters);
`

#### 过滤器类型

库提供了几种内置过滤器类型：

- TextFilter: 文本输入，支持各种操作符（=、!=、包含等）
- NumberFilter: 数字输入，支持比较操作符
- SelectFilter: 下拉选择过滤器
- IdFilter: 基于 ID 的过滤器
- AssemblyFilter: 组合多个条件的复合过滤器

#### 自定义过滤器

通过实现 FilterProps 接口创建自定义过滤器组件：

`tsx
import { FilterProps, FilterValue } from '@ahoo-wang/fetcher-viewer';

function CustomFilter({ field, onChange, value }: FilterProps) {
return (


`tsx
import { ConfigProvider } from 'antd';

theme={
{
/ 您的主题配置 /
}
}
>

;
`

🌐 国际化

过滤系统支持多种语言。目前支持的语言环境：

- 英语（默认）
- 中文（zh_CN）

`tsx
import { FilterPanel } from '@ahoo-wang/fetcher-viewer';
import { zh_CN } from '@ahoo-wang/fetcher-viewer/locale';

locale={zh_CN}
// ... 其他属性
/>;
`

🧪 测试

库包含全面的测试。使用以下命令运行测试：

`bash


运行所有测试

`tsx
import React, { useState, useEffect } from 'react';
import {
FilterPanel,
useFilterState,
RemoteSelect,
} from '@ahoo-wang/fetcher-viewer';
import { Table } from 'antd';

function DataTable() {
const [data, setData] = useState([]);
const [loading, setLoading] = useState(false);
const { filters, addFilter, removeFilter, updateFilter } = useFilterState();

useEffect(() => {
fetchData();
}, [filters]);

const fetchData = async () => {
setLoading(true);
try {
const query = buildQueryFromFilters(filters);
const response = await fetch(/api/data?${query});
const result = await response.json();
setData(result);
} finally {
setLoading(false);
}
};

return (