企业官网建设流程全解析

表格筛选这件事，说简单也简单，说麻烦是真麻烦。我见过太多项目，表格数据一多，筛选逻辑就开始打架：全局搜索和列筛选互相覆盖、服务端分页和客户端筛选各算各的、用户点了三下筛选结果页面直接卡死。React Table 本身是个无头（headless）表格库，它把渲染权完全交给你，筛选状态也只是一份可序列化的对象——这既是它的灵活之处，也是很多人踩坑的根源。Next.js 又叠加了服务端组件、路由状态、URL 同步这些维度，一个筛选功能往往要同时考虑客户端交互手感、服务端查询效率、以及刷新后状态能不能还原。这篇内容就是围绕这套组合，把我实际项目里反复验证过的十个筛选技巧拆开讲清楚，从状态设计、列级筛选、全局搜索、防抖节流、服务端模式、URL 同步到性能优化，每个点都给出为什么这么做、怎么做、以及我踩过的坑。适合已经上手过 React Table、正在 Next.js 项目里做数据密集型后台的开发者参考，也适合刚接触无头表格、想搞明白筛选状态到底怎么流转的同学。

1. 先想清楚筛选状态归谁管，再动手写代码

很多人一上来就写useReactTable的配置，结果写到一半发现筛选状态在组件重渲染时丢了，或者两个表格实例互相干扰。问题的根子不在 API，而在状态归属没想明白。React Table 的筛选状态本质上就是一个普通对象，形如{ id: 列标识, value: 筛选值 }的数组，它不关心你把它存在哪。所以第一步不是查文档，而是决定这份状态的生命周期。

1.1 受控与非受控的取舍逻辑

React Table 默认走非受控模式，也就是state里不传columnFilters，库内部自己维护。这种模式写起来最省事，适合筛选逻辑完全封闭在表格组件内部、不需要外部读取或修改的场景。但只要你遇到下面任意一种情况，就必须切到受控模式：需要把筛选状态同步到 URL、需要根据筛选状态触发服务端请求、需要在表格外部放一个"清空筛选"按钮、或者需要把筛选状态存进全局状态管理。

受控模式的写法是把columnFilters和globalFilter放进state，同时提供onColumnFiltersChange和onGlobalFilterChange回调。这里有个容易忽略的细节：onColumnFiltersChange的参数既可能是新值，也可能是一个 updater 函数（当你传函数给 setter 时）。如果你直接setColumnFilters(newValue)而不判断类型，遇到函数式更新就会把函数当成数组存进去，表现为筛选突然失效。稳妥的写法是用 React 的useState的 setter 直接接收，因为useState的 setter 本身就支持函数式更新：

const [columnFilters, setColumnFilters] = useState([]); const [globalFilter, setGlobalFilter] = useState(''); const table = useReactTable({ data, columns, state: { columnFilters, globalFilter }, onColumnFiltersChange: setColumnFilters, onGlobalFilterChange: setGlobalFilter, getCoreRowModel: getCoreRowModel(), getFilteredRowModel: getFilteredRowModel(), });

这样写的好处是 React Table 内部调用onColumnFiltersChange时传什么，useState的 setter 都能正确处理，不用自己写类型判断。

1.2 状态提升到哪一层才不别扭

状态放在表格组件内部，外部想读就得靠回调往上抛，层级一深就变成"回调地狱"。我的经验是按使用范围分三档：只在表格内用，就放组件内；需要在同一页面的工具栏、统计卡片、导出按钮之间共享，就提升到页面级组件；需要跨路由保留（比如从列表进详情再返回），就放进 URL 查询参数或全局 store。URL 方案后面单独讲，这里先说页面级提升的一个坑：如果你把筛选状态提升到父组件，父组件每次 setState 都会导致整个子树重渲染，表格数据量大时会有明显卡顿。解决办法是把筛选状态和表格数据用useMemo隔离，或者干脆把筛选状态放进一个轻量的 context，只让真正消费它的组件订阅。

还有一个隐蔽的问题：受控模式下，如果你在state里传了columnFilters，但忘了传onColumnFiltersChange，表格会变成只读——用户点筛选没反应，控制台也不报错。这个坑我见过不止一个同事踩，排查半天以为是列定义写错了。所以受控三件套（state 值、onChange 回调、对应的 row model）必须成对出现，缺一不可。

2. 列级筛选的配置细节，决定用户能不能筛对

列级筛选是表格筛选的主力，但 React Table 只提供机制，不提供 UI，filterFn选错、enableColumnFilter配错，用户看到的就是"筛了等于没筛"。这一节把列筛选的几个关键配置讲透。

2.1 filterFn 的选择直接决定匹配行为

React Table 内置了一批filterFn，常用的有includesString（不区分大小写的包含匹配）、equalsString（精确匹配）、inNumberRange（数值区间）、arrIncludesSome（数组包含任一）。默认的auto会根据第一行数据的类型自动推断，但自动推断经常不靠谱——比如一列全是数字字符串，它可能推断成字符串匹配，用户输入10却匹配不到100，体验很怪。

我的做法是显式指定，不依赖 auto。文本列用includesString，状态列用equalsString配合下拉选择，数值列用inNumberRange配合两个输入框，标签列用arrIncludesSome。显式指定还有个好处：服务端筛选时你可以根据filterFn的名字映射到对应的查询条件，前后端逻辑对得上。

const columns = [ { accessorKey: 'name', header: '名称', filterFn: 'includesString', }, { accessorKey: 'status', header: '状态', filterFn: 'equalsString', }, { accessorKey: 'price', header: '价格', filterFn: 'inNumberRange', }, ];

2.2 自定义 filterFn 解决业务语义匹配

内置函数覆盖不了业务语义时，就得自己写。自定义filterFn的签名是(row, columnId, filterValue) => boolean，返回 true 表示保留该行。举个实际例子：用户想按"订单状态"筛选，但状态在数据里存的是枚举值pending、paid、shipped，而筛选 UI 上显示的是中文。这时候可以在filterFn里做映射，也可以让筛选值直接存枚举值、UI 层做展示转换——后者更干净，因为筛选状态要序列化进 URL 时，存枚举值比存中文更稳定。

再比如模糊匹配多个关键词：用户输入"北京 手机"，希望名称里同时包含这两个词。内置的includesString只做整串匹配，这时自定义一个按空格拆分、全部命中的filterFn就很必要：

const multiKeywordFilter = (row, columnId, filterValue) => { if (!filterValue) return true; const cellValue = String(row.getValue(columnId)).toLowerCase(); return filterValue .toLowerCase() .split(/\s+/) .filter(Boolean) .every((kw) => cellValue.includes(kw)); };

注意这里对空筛选值返回 true，否则清空筛选后所有行都会消失——这是自定义filterFn最常见的 bug。

2.3 哪些列不该开筛选

不是所有列都适合开筛选。操作列、序号列、纯展示的头像列，开了筛选反而让用户困惑。用enableColumnFilter: false关掉即可。另外，如果某列的值是对象或数组，直接开筛选会得到奇怪的结果，要么先accessorFn转成可读字符串，要么关掉筛选改用其他交互。还有一个细节：enableColumnFilter和enableGlobalFilter是分开的，某列可以参与列筛选但不参与全局搜索，反之亦然。全局搜索默认会扫所有列，如果某些列（比如内部 ID）不该被搜到，记得单独设enableGlobalFilter: false。

3. 全局搜索和列筛选并存时的优先级处理

全局搜索和列筛选同时开启，是后台表格的常见需求，但两者的组合行为经常让人困惑：全局搜索是覆盖列筛选，还是叠加？React Table 的默认行为是叠加——先过全局筛选，再过列筛选，两者是"与"的关系。这个默认值大多数场景下是对的，但有几个边界要处理。

3.1 全局筛选的匹配范围控制

globalFilterFn默认是includesString，会扫所有可筛选的列。如果你的表格有十几列，全局搜索会把一些不该匹配的列也算进去，比如创建时间、内部备注。控制范围有两种方式：一是给不需要参与全局搜索的列设enableGlobalFilter: false；二是自定义globalFilterFn，只对指定列做匹配。后者更灵活，比如只搜名称和描述两列：

const globalFilterFn = (row, columnId, filterValue) => { const searchableColumns = ['name', 'description']; if (!searchableColumns.includes(columnId)) return true; const value = String(row.getValue(columnId)).toLowerCase(); return value.includes(String(filterValue).toLowerCase()); };

注意返回 true 表示"这一列不排除该行"，所以非搜索列直接返回 true，让其他列的判断决定结果。

3.2 筛选冲突时的用户预期管理

叠加逻辑有个副作用：用户先在列筛选里选了"状态=已支付"，再用全局搜索搜一个不存在的词，结果为空。用户可能以为是全局搜索坏了，其实是两个条件同时生效。我的处理方式是在 UI 上明确展示当前生效的筛选条件，比如在表格上方放一排"筛选标签"，每个标签可单独移除，让用户一眼看到有几个条件在起作用。这个交互成本很低，但能省掉大量"为什么搜不到"的疑问。

还有一种情况是全局搜索和列筛选作用在同一列上，比如名称列既有列筛选输入框，又被全局搜索覆盖。这时两个条件会同时约束该列，结果可能比用户预期更严格。如果业务上不允许这种双重约束，可以在全局搜索激活时临时禁用列筛选 UI，或者反过来。这个取舍没有标准答案，关键是和产品对齐预期，别让用户猜。

4. 防抖不是可选项，是筛选体验的生死线

筛选输入框每敲一个字符就触发一次筛选，数据量小的时候看不出问题，数据上千行、或者筛选触发服务端请求时，卡顿和请求风暴立刻显现。防抖（debounce）在这里不是锦上添花，是必须做的基础设施。

4.1 客户端筛选的防抖策略

客户端筛选虽然不涉及网络，但每次筛选都要遍历全量数据做匹配，几千行乘以十几列，主线程照样会卡。防抖的思路是让输入框的值先"稳定"下来再更新筛选状态。实现上有两种：一种是在输入框的onChange里做防抖，延迟更新columnFilters；另一种是输入框维护自己的本地 state，防抖后再同步给表格。后者更推荐，因为输入框的即时反馈不能丢——用户打字时字符要立刻出现，只是筛选结果延迟生效。

function DebouncedFilterInput({ column }) { const [value, setValue] = useState(''); const timerRef = useRef(null); const handleChange = (e) => { const next = e.target.value; setValue(next); clearTimeout(timerRef.current); timerRef.current = setTimeout(() => { column.setFilterValue(next); }, 300); }; return <input value={value} onChange={handleChange} placeholder="筛选..." />; }

300 毫秒是个经验值，打字快的人基本感觉不到延迟，又能把连续输入合并成一次筛选。如果数据量特别大，可以调到 500 毫秒，但再长用户就会觉得"卡"。

4.2 服务端筛选的请求取消与竞态处理

服务端筛选的坑比客户端深得多。用户快速输入"abc"，会依次发出 a、ab、abc 三个请求，如果 ab 的响应比 abc 晚回来，界面就会显示 ab 的结果，这就是竞态。防抖能减少请求数量，但不能完全避免竞态，必须配合请求取消或结果校验。

用AbortController取消上一个请求是最直接的办法：每次发请求前 abort 掉前一个，只保留最新请求的结果。如果用的是 fetch，把 signal 传进去即可；如果用 axios，用它的 CancelToken 或 AbortController 支持。另一种办法是给每个请求打上序号，响应回来时比对序号，不是最新的就丢弃。两种方案可以叠加使用，双保险。

const abortRef = useRef(null); const fetchData = async (filters) => { abortRef.current?.abort(); const controller = new AbortController(); abortRef.current = controller; try { const res = await fetch(`/api/items?${buildQuery(filters)}`, { signal: controller.signal, }); const data = await res.json(); setRows(data); } catch (err) { if (err.name !== 'AbortError') throw err; } };

这里有个细节：abort 触发的错误 name 是AbortError，要单独判断并忽略，否则控制台会刷一堆红色报错，干扰真正的错误排查。

5. 服务端筛选模式下，manualFiltering 只是起点

数据量大到客户端扛不住时，筛选必须挪到服务端。React Table 提供了manualFiltering: true，告诉它"筛选我自己处理，你别在客户端过滤了"。但开了这个开关只是起点，真正的工作量在状态到查询参数的映射、分页与筛选的联动、以及加载态的处理上。

5.1 筛选状态到查询参数的映射

columnFilters是一个数组，每个元素是{ id, value }，服务端需要把它转成查询字符串或请求体。简单的等值筛选直接拼id=value，但区间筛选（inNumberRange）的 value 是[min, max]数组，需要拆成priceMin和priceMax两个参数。全局搜索单独一个q参数。这个映射逻辑建议抽成一个纯函数，前后端共用同一套字段命名，避免"前端叫 status、后端叫 state"这种低级错位。

function buildQueryParams(columnFilters, globalFilter, pagination) { const params = new URLSearchParams(); columnFilters.forEach(({ id, value }) => { if (Array.isArray(value)) { if (value[0] != null) params.set(`${id}Min`, value[0]); if (value[1] != null) params.set(`${id}Max`, value[1]); } else if (value != null && value !== '') { params.set(id, value); } }); if (globalFilter) params.set('q', globalFilter); params.set('page', pagination.pageIndex + 1); params.set('size', pagination.pageSize); return params.toString(); }

注意空值和空字符串要跳过，否则会拼出status=这种无意义参数，服务端还得额外处理。

5.2 筛选变化时重置分页

这是个高频 bug：用户在第三页做筛选，筛选后结果只有一页，但分页状态还停在第三页，界面显示空白。原因是筛选变化没有重置pageIndex。正确做法是在筛选状态变化的副作用里把分页重置到第一页。用useEffect监听columnFilters和globalFilter，变化时setPagination(prev => ({ ...prev, pageIndex: 0 }))。注意别把pagination本身放进依赖，否则会无限循环。

服务端模式下还有个联动细节：筛选和分页的请求应该合并成一次，而不是筛选发一个、分页发一个。把筛选状态和分页状态一起作为请求参数，用一个useEffect统一触发请求，依赖数组里放这两组状态。这样既减少请求数，又保证结果一致。

6. 把筛选状态写进 URL，刷新和分享都不丢

后台系统里，用户筛选好数据后刷新页面、或者把链接发给同事，结果筛选条件全没了，这种体验很糟。把筛选状态同步到 URL 查询参数，是解决这个问题的标准方案，Next.js 的useRouter和useSearchParams正好配套。

6.1 初始化时从 URL 还原状态

页面加载时，先从searchParams读出筛选参数，反序列化成columnFilters和globalFilter的初始值。这里要注意类型转换：URL 里全是字符串，数值区间要转回数字，布尔值要转回布尔。反序列化函数和前面的序列化函数要成对维护，字段命名保持一致。

function parseFiltersFromParams(searchParams) { const columnFilters = []; searchParams.forEach((value, key) => { if (key.endsWith('Min') || key.endsWith('Max')) return; if (key === 'q' || key === 'page' || key === 'size') return; columnFilters.push({ id: key, value }); }); return { columnFilters, globalFilter: searchParams.get('q') || '', }; }

区间参数的处理要单独合并：遍历时遇到xxxMin和xxxMax，配对成一个数组塞进对应的id。这段逻辑稍微绕，建议写单元测试覆盖，否则很容易出现"刷新后区间筛选只剩一半"的问题。

6.2 状态变化时用 replace 而非 push

筛选状态每次变化都往历史记录里 push 一条，用户点浏览器后退键会一步步退回之前的筛选状态，体验很怪。正确做法是用router.replace，只更新当前历史记录，不新增条目。Next.js 的useRouter里，replace的第二个参数可以传{ scroll: false }，避免更新 URL 时页面跳动。

const router = useRouter(); const pathname = usePathname(); useEffect(() => { const query = buildQueryParams(columnFilters, globalFilter, pagination); router.replace(`${pathname}?${query}`, { scroll: false }); }, [columnFilters, globalFilter, pagination]);

这个副作用要小心死循环：router.replace会触发路由变化，如果路由变化又反过来更新筛选状态，就转起来了。解决办法是初始化时只读一次 URL，后续的 URL 更新只由筛选状态单向驱动，不再从 URL 反向同步。单向数据流是这里的关键原则。

7. 筛选 UI 的组件化，别把表格组件写成意大利面

筛选输入框、下拉选择、区间输入，如果全塞在表格组件里，代码很快就会失控。把筛选 UI 抽成独立组件，通过column实例操作筛选值，是保持可维护性的关键。

7.1 用 column 实例驱动筛选控件

React Table 给每个列对象提供了getFilterValue()和setFilterValue()方法，筛选控件只需要拿到column就能工作，不需要知道表格的其他细节。这样文本输入、下拉、区间三种控件可以各自封装，按filterFn类型自动选择渲染哪个控件。

function FilterControl({ column }) { const filterFnName = column.columnDef.filterFn; if (filterFnName === 'inNumberRange') { return <RangeFilter column={column} />; } if (filterFnName === 'equalsString') { return <SelectFilter column={column} />; } return <TextFilter column={column} />; }

这种按filterFn分发的写法，让列定义和 UI 解耦：新增一列只要声明filterFn，UI 自动匹配，不用改表格组件。

7.2 筛选控件的受控值同步问题

自定义筛选控件内部如果用本地 state 做防抖，要处理一个同步问题：外部清空筛选（比如点"重置"按钮）时，控件内部的本地 state 不会自动清空，表现为筛选实际已清空但输入框里还留着旧文字。解决办法是监听column.getFilterValue()的变化，用useEffect把本地 state 同步过去。这个细节很小，但不处理就是明显的 bug。

8. 大数据量下的筛选性能，别让主线程背锅

数据量到几千行以上，客户端筛选的耗时开始显现。每次筛选都要对全量数据跑一遍filterFn，如果filterFn里还有字符串拼接、正则、对象访问，耗时会成倍增加。性能优化要抓几个关键点。

8.1 减少不必要的重渲染

React Table 的getFilteredRowModel在筛选状态变化时会重新计算，这个计算本身有缓存，但如果你在列定义里用了内联函数（比如cell渲染器每次渲染都新建），会导致列定义引用变化，进而触发全表重算。解决办法是把列定义用useMemo包起来，依赖只放真正会变的东西。同理，data也要保持引用稳定，不要在渲染时用map生成新数组传给表格。

8.2 筛选函数的性能陷阱

自定义filterFn里避免做重操作。比如每次比较都JSON.stringify整个对象、或者用复杂的正则，几千行跑下来就是灾难。能预计算的字段提前算好存进数据里，filterFn里只做简单比较。字符串匹配统一转小写后再比，避免每次比较都调用toLowerCase——可以在数据预处理阶段就把搜索字段转成小写存一份。

如果数据量真的很大（上万行），客户端筛选就该让位给服务端筛选了。判断标准不是行数绝对值，而是"筛选一次是否超过 100 毫秒"，超过就该考虑挪到服务端。这个阈值可以用performance.now()在开发环境测一下，心里有数。

9. 几个我踩过的具体坑和对应解法

前面讲的偏系统性，这一节列几个具体到代码层面的坑，都是实际项目里踩出来的。

9.1 筛选后选中状态错乱

表格带行选择时，筛选会改变可见行，但选中状态如果按行索引存，筛选后索引错位，选中的行就变了。正确做法是按行的唯一 ID 存选中状态，React Table 的getRowId可以指定用哪个字段作为行 ID。筛选只影响可见性，不影响选中集合，这样才符合用户预期。

9.2 空筛选值导致的边界问题

前面提过自定义filterFn要对空值返回 true，这里再强调一个相关坑：inNumberRange的 value 是[undefined, undefined]时，内置函数能正确处理，但如果你自己解析 URL 参数时把空字符串转成了0，区间就变成了[0, 0]，结果全空。解析时务必区分"没有值"和"值为 0"，用null或undefined表示前者。

9.3 服务端筛选的加载态闪烁

服务端筛选每次请求都有延迟，如果请求期间不清空旧数据，用户会看到旧结果停留；如果清空，又会闪一下空白。折中方案是保留旧数据但加一层半透明遮罩或顶部进度条，让用户知道"正在筛"，而不是"筛完了没结果"。这个交互细节对感知性能影响很大。

10. 筛选功能的测试与验收清单

筛选逻辑写完了不算完，得有办法验证它真的对。我习惯维护一份验收清单，每次改动筛选相关代码都过一遍。

这份清单不用每次全跑，但改动筛选核心逻辑时至少过一遍关键项。尤其是"刷新还原"和"竞态"这两项，出问题最隐蔽，用户反馈时往往描述成"有时候筛不对"，排查成本很高。

筛选这块东西，API 本身不复杂，复杂的是状态在组件、URL、服务端之间的流转，以及各种边界条件的处理。我个人的体会是，先把状态归属和单向数据流定死，再往上叠防抖、URL 同步、服务端模式，顺序反了就会反复返工。另外，筛选 UI 的即时反馈和筛选结果的延迟生效要分开处理，输入框永远要跟手，结果可以慢半拍，这个分寸感是体验好坏的分水岭。