1. 为什么要在 Preact 里折腾 TanStack Form 的订阅机制表单状态管理这件事说简单也简单说复杂也复杂。简单在于一个受控输入框加一个useState就能跑起来复杂在于当表单字段膨胀到几十个、联动逻辑交叉、校验规则层层嵌套的时候整个页面会因为一个字段的输入而全量重渲染输入框开始卡顿用户体验直线下降。TanStack Form 这个库从设计之初就把「细粒度订阅」当作核心卖点而 Preact 本身又以轻量和性能著称两者结合本来应该是天作之合但实际用起来很多人卡在了useSelector和form.Subscribe这两个 API 的选择和配合上。我自己在几个中小型项目里用 TanStack Form 搭配 Preact 做过表单重构踩过不少坑。最典型的一个场景是一个包含三十多个字段的配置面板每个字段都有独立的校验和联动逻辑最初用useStore全量订阅结果每次按键都触发整个表单组件树重渲染输入延迟肉眼可见。后来换成useSelector做字段级订阅再配合form.Subscribe处理跨字段联动性能问题才彻底解决。这篇文章就是把这套经验完整拆开从设计思路到实操细节再到常见问题的排查尽量讲透。这篇文章适合已经在用 Preact 做项目、对 TanStack Form 有基本了解、但对其订阅机制还不太清楚的开发者。如果你还在犹豫要不要引入 TanStack Form或者你正在被表单性能问题困扰那接下来的内容应该能帮你省下不少试错时间。核心关键词会围绕TanStack Form、Preact、useSelector、form.Subscribe和表单状态这几个点展开但不会堆砌术语而是结合实际代码和场景来讲。2. 核心思路拆解订阅粒度决定了表单性能上限2.1 全量订阅为什么会拖垮 Preact 表单要理解useSelector和form.Subscribe的价值得先搞清楚 TanStack Form 的状态更新机制。TanStack Form 内部维护了一个表单状态树包含values、errors、touched、isSubmitting、isValid等字段。每次用户输入状态树都会产生一次更新然后通知所有订阅者。如果你用的是useStore(form.store)这种全量订阅方式那么任何一个字段的变化都会让订阅组件重新渲染。在 React 里这个问题可能还能忍因为 React 有比较完善的调度机制但在 Preact 里虽然 Preact 的 diff 算法很快但组件数量一多全量重渲染的开销依然不可忽视。我实测过一个包含 40 个字段的表单全量订阅下每次按键大约触发 40 到 60 次组件渲染输入延迟在 80ms 左右已经能明显感觉到卡顿。注意Preact 的useState和useReducer更新是同步批处理的但 TanStack Form 的状态更新走的是外部 store 订阅机制不会自动进入 Preact 的批处理队列所以全量订阅的代价比想象中更大。2.2 useSelector 的定位字段级精准订阅useSelector的核心思路是「只订阅我关心的那部分状态」。它的签名大概是这样的const value useSelector(form.store, (state) state.values.username)第二个参数是一个选择器函数只有选择器返回的值发生变化时订阅组件才会重新渲染。这意味着如果你只关心username字段那么password字段的变化不会触发你的组件更新。这个机制在 Preact 里尤其重要因为 Preact 没有 React 那样的useSyncExternalStore原生支持虽然 Preact 也有兼容层但行为上有差异。TanStack Form 的useSelector内部做了浅比较优化对于基本类型值直接比较对于对象类型则需要你注意选择器的返回值稳定性。2.3 form.Subscribe 的定位跨字段联动与条件渲染form.Subscribe是一个组件级的订阅方案它接受一个selector属性用法和useSelector类似但它是声明式的组件形式form.Subscribe selector{(state) [state.values.country, state.values.province]} {([country, province]) ( div当前选择{country} - {province}/div )} /form.Subscribe它和useSelector的本质区别在于useSelector是 Hook只能在组件内部使用适合字段级订阅form.Subscribe是组件可以放在 JSX 里任意位置适合跨字段联动、条件渲染、以及需要把订阅范围限制在某个子树内的场景。2.4 两者如何配合分层订阅策略我的经验是把订阅分成三层第一层字段级订阅用useSelector在自定义字段组件内部订阅自己的值这是最细粒度的。第二层联动订阅用form.Subscribe包裹需要根据多个字段变化而更新的 UI 片段。第三层全局状态订阅比如提交按钮的禁用状态、表单整体校验状态用useSelector在顶层组件订阅isValid或isSubmitting。这样分层之后每个组件的订阅范围都是最小化的重渲染次数能降到最低。我在那个 40 字段的表单里用这套策略重构后每次按键的渲染次数从 40 到 60 次降到了 2 到 3 次输入延迟基本感知不到。3. 核心细节解析与实操要点3.1 useSelector 的选择器写法与性能陷阱useSelector的选择器函数写法直接决定了性能表现。最常见的错误是返回一个新对象// 错误写法每次返回新对象导致无限重渲染 const { username, password } useSelector(form.store, (state) ({ username: state.values.username, password: state.values.password, }))这种写法的问题在于选择器每次执行都返回一个新的对象引用浅比较永远不相等组件会无限重渲染。正确的做法有两种第一种是分开订阅const username useSelector(form.store, (state) state.values.username) const password useSelector(form.store, (state) state.values.password)第二种是使用shallow比较函数如果 TanStack Form 版本支持import { shallow } from tanstack/form-core const { username, password } useSelector( form.store, (state) ({ username: state.values.username, password: state.values.password }), shallow )提示不同版本的 TanStack Form 对useSelector第三个参数的支持不一样建议先查一下你用的版本。如果不支持就老老实实分开订阅虽然代码啰嗦一点但性能最稳。3.2 form.Subscribe 的 selector 返回值设计form.Subscribe的selector同样需要注意返回值稳定性。它支持返回数组TanStack Form 内部会对数组做逐项比较form.Subscribe selector{(state) [state.values.email, state.values.newsletter]} {([email, newsletter]) ( div {newsletter input value{email} readOnly /} /div )} /form.Subscribe数组比较是逐项浅比较所以只要数组元素是基本类型就不会有引用问题。但如果数组元素是对象就需要额外注意。另一个细节是form.Subscribe的 children 必须是一个函数不能直接传 JSX 元素。这个函数接收 selector 的返回值作为参数返回需要渲染的内容。3.3 Preact 环境下的兼容性注意事项Preact 和 React 在 API 上有一些差异使用 TanStack Form 时需要注意useSyncExternalStore的兼容TanStack Form 内部依赖useSyncExternalStore来订阅 storePreact 从 10.11 版本开始提供了兼容实现但如果你用的是更老的 Preact 版本可能需要引入use-sync-external-store的 polyfill。事件系统差异Preact 的事件系统是原生事件委托和 React 的合成事件不同。TanStack Form 的field.handleChange在 Preact 下工作正常但如果你在自定义字段组件里手动处理事件要注意onInput和onChange的行为差异。Fragment 支持form.Subscribe内部可能返回 FragmentPreact 对 Fragment 的支持没问题但如果你在 children 函数里返回多个根节点需要确保 Preact 版本支持。3.4 字段组件的封装模式在实际项目里我建议把字段组件封装成独立组件内部用useSelector订阅自己的值function TextField({ form, name, label }) { const value useSelector(form.store, (state) state.values[name]) const error useSelector(form.store, (state) state.errors[name]) const touched useSelector(form.store, (state) state.touched[name]) return ( div label{label}/label input value{value ?? } onInput{(e) form.setFieldValue(name, e.target.value)} onBlur{() form.setFieldTouched(name, true)} / {touched error span{error}/span} /div ) }这样每个字段组件只订阅自己的值、错误和触摸状态其他字段的变化完全不会影响它。这是整个订阅策略里最基础也最重要的一环。4. 实操过程与核心环节实现4.1 项目初始化与依赖安装先创建一个 Preact 项目用 Vite 是最省事的npm create vitelatest my-form-app -- --template preact cd my-form-app npm install然后安装 TanStack Formnpm install tanstack/form-core tanstack/preact-form注意TanStack Form 的 Preact 适配包是tanstack/preact-form不是tanstack/react-form。这两个包 API 基本一致但底层依赖不同不要装错。4.2 表单实例的创建与配置创建一个表单实例配置默认值和校验规则import { useForm } from tanstack/preact-form const form useForm({ defaultValues: { username: , email: , country: , province: , newsletter: false, }, onSubmit: async ({ value }) { console.log(提交数据, value) }, })这里useForm返回的form对象包含了store、Subscribe、setFieldValue、setFieldTouched等方法。form.store就是后面useSelector要订阅的 store。4.3 字段级订阅的完整实现把前面的TextField组件完善一下加上校验和错误显示import { useSelector } from tanstack/preact-form function TextField({ form, name, label, validator }) { const value useSelector(form.store, (state) state.values[name]) const error useSelector(form.store, (state) state.errors[name]) const touched useSelector(form.store, (state) state.touched[name]) const handleInput (e) { form.setFieldValue(name, e.target.value) if (validator) { const result validator(e.target.value) if (result) { form.setFieldMeta(name, (prev) ({ ...prev, error: result })) } else { form.setFieldMeta(name, (prev) ({ ...prev, error: undefined })) } } } return ( div style{{ marginBottom: 12px }} label style{{ display: block, marginBottom: 4px }}{label}/label input value{value ?? } onInput{handleInput} onBlur{() form.setFieldTouched(name, true)} style{{ padding: 6px, width: 100% }} / {touched error ( span style{{ color: red, fontSize: 12px }}{error}/span )} /div ) }这里有个细节form.setFieldMeta的用法在不同版本里可能不同有些版本推荐用form.setFieldValue的第三个参数传校验结果。我建议先查一下你用的版本的文档或者直接用form.setFieldValue(name, value, { validate: true })让 TanStack Form 自动跑校验。4.4 跨字段联动的 form.Subscribe 实现假设有一个场景用户选择国家后省份下拉框的选项需要根据国家变化。这时候用form.Subscribe最合适const provinceOptions { China: [Beijing, Shanghai, Guangzhou], USA: [California, New York, Texas], } function ProvinceSelect({ form }) { return ( form.Subscribe selector{(state) [state.values.country, state.values.province]} {([country, province]) { const options provinceOptions[country] || [] return ( div style{{ marginBottom: 12px }} label style{{ display: block, marginBottom: 4px }}省份/label select value{province ?? } onChange{(e) form.setFieldValue(province, e.target.value)} style{{ padding: 6px, width: 100% }} option value请选择/option {options.map((opt) ( option key{opt} value{opt}{opt}/option ))} /select /div ) }} /form.Subscribe ) }这个组件只订阅country和province两个字段其他字段变化不会触发它重渲染。而且当country变化时province的选项会自动更新如果之前选的省份不在新选项里还可以在 selector 里做重置逻辑。4.5 提交按钮的状态订阅提交按钮需要根据表单整体校验状态来决定是否禁用这时候用useSelector订阅isValidfunction SubmitButton({ form }) { const isValid useSelector(form.store, (state) state.isValid) const isSubmitting useSelector(form.store, (state) state.isSubmitting) return ( button typesubmit disabled{!isValid || isSubmitting} style{{ padding: 8px 16px }} {isSubmitting ? 提交中... : 提交} /button ) }这里订阅了两个独立的值分开订阅比合并成一个对象更安全避免引用问题。4.6 完整表单组装与性能验证把所有组件组装起来function App() { const form useForm({ defaultValues: { username: , email: , country: , province: , newsletter: false, }, onSubmit: async ({ value }) { console.log(提交数据, value) }, }) return ( form onSubmit{(e) { e.preventDefault() form.handleSubmit() }} style{{ maxWidth: 400px, margin: 40px auto }} TextField form{form} nameusername label用户名 / TextField form{form} nameemail label邮箱 / TextField form{form} namecountry label国家 / ProvinceSelect form{form} / SubmitButton form{form} / /form ) }验证性能的方法很简单在TextField组件里加一行console.log(render, name)然后在输入框里快速打字观察控制台输出。如果只有当前字段的日志在打印说明订阅策略生效了。如果所有字段的日志都在刷屏说明某处有全量订阅。5. 常见问题与排查技巧实录5.1 输入框输入后光标跳到末尾这是受控组件在异步更新时的经典问题。TanStack Form 的状态更新是异步的如果输入框的value更新滞后于用户输入光标就会跳到末尾。解决办法是确保onInput里同步调用form.setFieldValue不要做防抖或异步处理。如果确实需要防抖可以用非受控组件加defaultValue然后在onBlur时同步值。5.2 useSelector 返回对象导致无限重渲染前面提过返回新对象会触发无限重渲染。排查方法是把选择器返回值改成基本类型或者用shallow比较。如果还是不行检查一下是不是在 selector 里做了计算比如state.values.items.filter(...)这种每次返回新数组的写法同样有问题。5.3 form.Subscribe 的 children 不更新有时候form.Subscribe的 children 函数不触发更新原因通常是 selector 返回的数组里包含了对象而对象引用没变但内容变了。解决办法是把 selector 拆细只返回需要的基本类型值或者确保对象更新时引用也更新。5.4 Preact 下 useSyncExternalStore 报错如果控制台报useSyncExternalStore is not a function说明你的 Preact 版本太老。升级到 Preact 10.11 以上或者安装use-sync-external-store的 polyfill 并在入口文件里引入。5.5 表单提交时校验不触发TanStack Form 的校验默认在字段变化时触发提交时需要手动调用form.validateAllFields()或者确保onSubmit里先跑一遍校验。我一般会在handleSubmit之前加一行await form.validateAllFields()确保提交前所有字段都校验过。5.6 常见问题速查表问题现象可能原因解决办法输入框光标跳末尾状态更新异步同步调用 setFieldValue避免防抖无限重渲染selector 返回新对象分开订阅或用 shallow 比较Subscribe 不更新selector 返回对象引用不变拆细 selector只返回基本类型useSyncExternalStore 报错Preact 版本过低升级 Preact 或引入 polyfill提交时校验不触发未手动触发校验提交前调用 validateAllFields字段联动不生效订阅范围不对用 form.Subscribe 订阅相关字段5.7 独家避坑技巧第一个技巧是「订阅日志法」在开发阶段给每个订阅组件加一行console.log观察哪些组件在不该渲染的时候渲染了。这个方法比任何性能分析工具都直接。第二个技巧是「selector 最小化原则」selector 里只返回你真正需要的那一个值不要图省事返回整个state.values。多写几行代码换来的是成倍的性能提升。第三个技巧是「联动逻辑上移」如果多个字段之间有复杂的联动关系不要在每个字段组件里各写一套逻辑而是把联动逻辑集中到form.Subscribe里这样逻辑清晰也更容易调试。6. 订阅策略的扩展与进阶用法6.1 动态字段数组的订阅处理当表单里有动态增删的字段数组时订阅策略需要调整。比如一个地址列表用户可以添加多个地址。这时候不能用固定的字段名订阅而是订阅整个数组的长度和每个元素的 idfunction AddressList({ form }) { return ( form.Subscribe selector{(state) state.values.addresses} {(addresses) ( div {addresses.map((addr, index) ( AddressItem key{addr.id} form{form} index{index} / ))} button typebutton onClick{() form.pushFieldValue(addresses, { id: Date.now(), value: })} 添加地址 /button /div )} /form.Subscribe ) }这里form.Subscribe订阅了整个addresses数组数组变化时整个列表重渲染。如果列表很长可以进一步优化让每个AddressItem内部用useSelector订阅自己的值。6.2 异步校验与订阅的配合异步校验比如检查用户名是否已存在需要特别注意订阅时机。我的做法是在字段的onBlur里触发异步校验校验结果写入form.setFieldMeta然后字段组件通过useSelector订阅error字段来显示错误。这样异步校验的过程不会影响其他字段的渲染。6.3 表单状态持久化与订阅如果需要把表单状态持久化到本地存储可以在表单顶层用form.Subscribe订阅整个values然后在回调里做防抖写入form.Subscribe selector{(state) state.values} {(values) { useEffect(() { const timer setTimeout(() { localStorage.setItem(form-draft, JSON.stringify(values)) }, 500) return () clearTimeout(timer) }, [values]) return null }} /form.Subscribe这个组件不渲染任何 UI只做副作用。注意useEffect的依赖是values而values每次变化都是新对象所以防抖是必须的否则会频繁写入。6.4 多表单实例的订阅隔离如果一个页面里有多个独立的表单每个表单有自己的form实例订阅是天然隔离的。但要注意不要把不同表单的form.store混用否则会出现状态串扰。我一般会在表单组件内部创建form实例而不是在全局创建后传递这样每个表单的生命周期和状态都是独立的。7. 我在实际项目中的几点体会这套订阅策略我在三个项目里用过最大的感受是不要过早优化但也不要忽视订阅粒度。项目初期字段少全量订阅完全没问题代码还更简单。但当字段数量超过 15 个或者有复杂的联动逻辑时就应该开始考虑分层订阅了。另一个体会是useSelector和form.Subscribe不是互斥的而是互补的。useSelector适合在组件内部做细粒度订阅form.Subscribe适合在 JSX 里做声明式的联动订阅。两者配合使用才能把 TanStack Form 的性能优势发挥出来。最后分享一个小技巧如果你不确定某个订阅是否必要可以先不加等性能问题出现了再加。TanStack Form 的 API 设计很灵活加订阅的成本很低不需要一开始就把所有订阅都设计得很完美。先跑起来再优化这是最务实的做法。
