PostHog 前端表单实战：基于 kea-forms 构建类型安全的自管理表单逻辑

导读

本文面向 PostHog 前端（frontend/）的 React + kea 开发者，系统讲解如何用 kea-forms 这一 kea 插件构建表单：它在一个 builder 中统一管理表单值（values）、校验（validation）、提交状态（submission state）与成功/失败动作（success/failure actions），从而彻底取代手写 reducer + listener 的重复劳动。读完本文，你将掌握 forms builder 的完整 API 与生成物、字段级与跨字段条件校验、基于 submitXxxSuccess/Failure 的动作响应、表单重置、组件侧 <Form>/<Field> 的接入方式，以及一套可直接落地的反模式清单——全部以 PostHog 仓库中 loginLogic.ts 与 LoginForm.tsx 的真实实现为佐证。

为什么用 forms builder，而不是 reducer + listeners

PostHog 前端以 kea 为状态容器，几乎所有非平凡业务逻辑都放在 *Logic.ts / *Logic.tsx 文件中（见 SKILL.md）。表单是其中重复度最高的场景之一：值管理、逐字段校验、提交中的 loading 状态、提交成功/失败后的动作分发，这些逻辑高度同构。手写 reducer + listener 意味着把上述每一条都重新实现一遍，且很容易在各处出现不一致。

kea-forms 的 forms builder 把这一切收敛到一个声明式配置里。在 PostHog 仓库中，kea-forms 通过 catalog 方式引入，版本固定为 ^3.2.0（见 pnpm-workspace.yaml 与 frontend/package.json）。

假设在 logic 中声明了一个名为 foo 的 forms builder，它会自动生成一整套状态、动作与组件，覆盖表单生命周期：

生成物	类型	说明
fooValues	状态	当前表单值对象
fooValidationErrors	状态	按字段组织的校验错误，由 errors 函数计算得出
fooHasErrors	状态	是否存在任何校验错误的布尔值
setFooValues({ a: 1 })	动作	部分更新多个字段
setFooValue('a', 1)	动作	更新单个字段
submitFoo() / submitFooSuccess / submitFooFailure	动作	提交以及成功/失败结果
isFooSubmitting	状态	提交进行中的布尔值
resetFoo(defaults?)	动作	恢复为默认值，可传入部分覆盖
<Form logic={fooLogic} formKey="foo"> + <Field name="...">	组件	组件侧接入

这套生成物在手写 reducer 下无法廉价复刻——这正是 kea-forms 存在的理由。PostHog 的代码约定也明确要求：能用 kea 逻辑承载的状态就不要放进 React hooks（见 SKILL.md 核心原则）。

基础形态：defaults / errors / submit 三要素

一个最简表单逻辑如下（来自 forms.md 的核心示例）：

import { forms } from 'kea-forms'

export interface SignupForm {
    email: string
    organization_name: string
}

forms(() => ({
    signup: {
        defaults: { email: '', organization_name: '' } as SignupForm,
        errors: ({ email, organization_name }) => ({
            email: !email ? 'Please enter your email' : undefined,
            organization_name: !organization_name ? 'Please enter your org' : undefined,
        }),
        submit: async (formValues) => {
            await api.create('api/social_signup/', formValues)
        },
    },
})),

三个配置项各有明确职责：

• defaults——表单初始值。用 as SignupForm 进行类型标注，保证后续 errors、submit 接收到的值对象是有类型的。从源码看，PostHog 的做法是显式声明表单接口（如 export interface LoginForm { email: string; password: string }），再在 defaults 处断言，见 loginLogic.ts。
• errors——从当前值到逐字段错误对象的纯函数。返回 undefined 表示"无错误"，绝不能返回空字符串 ''：kea-forms 会把 errors 映射中任何非 undefined 的值视为"存在错误"，因此 '' 与 'Required' 一样会让字段判为非法（详见下文反模式）。PostHog 的真实写法是 email: !email ? 'Please enter your email to continue' : undefined，见 loginLogic.ts。
• submit——async 函数。抛出的异常会被插件捕获，并以 submitFooFailure 动作的形式浮出水面，同时 isFooSubmitting 会恢复为 false。

在 PostHog 的 kea 逻辑中，forms 在 builder 顺序上位于 actions 之后、loaders 之前（约定顺序为 props → key → path → connect → actions → forms → loaders → reducers → selectors → …），见 SKILL.md。

提交函数的第二个参数：breakpoint

kea-forms 的 submit 与 kea-loaders 的 handler 一样支持第二个参数 breakpoint，用于在异步流程中取消过期提交。PostHog 在真实提交中调用它：

submit: async ({ email, password }, breakpoint) => {
    breakpoint()
    try {
        return await api.create<any>('api/login', { email, password })
    } catch (e) {
        // ...
    }
},

见 loginLogic.ts。breakpoint() 在用户提交了新值、旧提交已无意义时让流程短路，避免过期请求的结果覆盖新状态。

字段相关与条件校验：errors 是纯函数

errors 函数接收完整的表单值对象，因此天然支持跨字段条件校验。例如，仅当选择了 S3 作为数据源时才要求填写 bucket 与 access key：

errors: ({ source_type, s3_bucket, access_key }) => ({
    source_type: !source_type ? 'Pick a source' : undefined,
    s3_bucket: source_type === 's3' && !s3_bucket ? 'Bucket required' : undefined,
    access_key: source_type === 's3' && !access_key ? 'Access key required' : undefined,
}),

两个关键语义：

1. 每次值变化都会重跑——errors 在每次 setFooValues / setFooValue 之后重新计算，因此"先选 source_type、再要求 s3_bucket"这类依赖关系无需额外监听逻辑，声明即生效。fooValidationErrors、fooHasErrors 以及字段是否显示错误，全部由这一次计算派生。
2. 必须保持纯函数——不能做 I/O，不能调用 Math.random() 之类的不确定操作。因为它在每次击键（keystroke）时都可能执行，任何副作用（日志、埋点、异步请求）都应移到对 setFooValues 的 listener 中。PostHog 的 login 逻辑严格遵守这一点：errors 只做空值判断，见 loginLogic.ts。

另外，登录场景还有一个"错误来自服务端"的常见需求：submit 失败后把服务端返回的 code/detail 展示在表单上。kea-forms 为此提供 setFooManualErrors(errors) 动作，PostHog 在验证码表单中用它把"验证码无效或已过期"这类服务端错误挂到 code 字段下：

actions.setCodeVerificationManualErrors({ code: message })

见 loginLogic.ts。ManualErrors 与 ValidationErrors（来自 errors 函数）是两个独立通道，二者共同决定字段的最终错误显示。

响应提交成功或失败：交给 listener，而非 submit 内部

submit 的职责是"干实际的活"（发请求）；导航、toast、状态重置等"对结果的反应"应该放到 submitFooSuccess / submitFooFailure 的 listener 里。这是 forms.md 反复强调的边界：

listeners(({ actions }) => ({
    submitSignupSuccess: () => {
        router.actions.push(urls.home())
    },
    submitSignupFailure: ({ error }) => {
        lemonToast.error(error.message ?? 'Something went wrong')
    },
})),

PostHog 登录逻辑的实测示例：登录成功后清空待验证邮箱并跳转，而不是在 submit 里做跳转：

listeners(({ values, actions }) => ({
    submitLoginSuccess: () => {
        clearPendingVerificationEmail()
        redirectAfterLogin()
    },
    submitCodeVerificationSuccess: () => {
        clearPendingVerificationEmail()
        redirectAfterLogin()
    },
    // ...
})),

见 loginLogic.ts。

值得注意的是，submitFooFailure 的 listener 参数里不仅携带 error，还携带 errors（服务端/手动错误映射），类型为 (error: Error, errors: Record<string, any>)，见 loginLogic.ts 中 typegen 生成的动作签名。这意味着你可以在失败监听中统一处理错误展示逻辑。

重置表单：resetFoo 的两种形态

resetFoo() 把表单恢复为 defaults；也支持传入部分值做"带初始数据的重置"：

listeners(({ actions }) => ({
    submitSignupSuccess: () => {
        actions.resetSignup()              // 回到 defaults
        // or: actions.resetSignup({ email: values.signup.email })  // 部分重置，保留邮箱
    },
})),

resetFoo 的动作签名是 (values?: FooForm) => void，即参数可选——PostHog typegen 生成的 resetCodeVerification: (values?: CodeVerificationForm) => ... 与 resetLogin: (values?: LoginForm) => ... 印证了这一点，见 loginLogic.ts。

真实使用：当用户退出"验证码验证"流程时，重置验证码表单：

exitCodeVerification: () => {
    actions.resetCodeVerification()
},

见 loginLogic.ts。

组件侧：

与

逻辑侧配置完成后，组件只需两样东西：<Form> 绑定逻辑与表单 key，<Field> 声明字段名。来自 forms.md 的标准写法：

import { Form, Field } from 'kea-forms'
;<Form logic={signupLogic} formKey="signup" enableFormOnSubmit>
    <Field name="email" label="Email">
        <LemonInput type="email" />
    </Field>
    <Field name="organization_name" label="Org">
        <LemonInput />
    </Field>
    <LemonButton type="primary" htmlType="submit" loading={isSignupSubmitting}>
        Sign up
    </LemonButton>
</Form>

要点：

• <Form logic={signupLogic} formKey="signup"> 把某个 logic 中的某个表单实例绑定到这段 JSX；formKey 必须与 forms 配置中的 key（如 signup）一致。一个 logic 可以挂多个表单（如 PostHog 的 login 与 codeVerification 同时存在于 loginLogic，见 loginLogic.ts），通过不同的 formKey 区分。
• <Field name="email"> 自动接管该字段的 value/onChange/error，不要手动写 value={...} + onChange={...}（详见反模式）。
• <LemonButton htmlType="submit"> 触发 submitFoo()，loading={isFooSubmitting} 在提交期间展示 loading 态。
• enableFormOnSubmit 让 Enter 键提交表单。文档的立场是：除非有明确理由，否则始终开启它（"Use it unless you have a reason not to"）。

PostHog 的 LoginForm.tsx 是 enableFormOnSubmit + noValidate 组合的实测例子：验证码表单用 noValidate 关闭浏览器原生校验，因为隐藏的 \d{6} pattern 输入会在验证码不完整时被浏览器拦截，导致 kea 无法展示自己的错误信息：

<Form
    logic={loginLogic}
    formKey="codeVerification"
    enableFormOnSubmit
    noValidate
    className="flex flex-col gap-4"
>

见 LoginForm.tsx。而普通登录表单则用 <LemonField name="email" label="Email"> 的 render-prop 形式取 value/onChange/error/id，见 LoginForm.tsx。

LemonField 与 Field 的选择

文档示例使用 kea-forms 的 <Field>，而 PostHog 自带的 Lemon 组件体系中更常见的是 lib/lemon-ui/LemonField（内部同样基于 <Field>，额外统一了 label、错误样式与 id 绑定）。两条路线都遵循同一契约：组件声明字段名，变化处理器由框架接线，业务方不再手写 onChange。

反模式清单：表单相关的"convert on sight"

anti-patterns.md 为表单列出了五类应当立即改造的写法，与 kea-forms 的职责一一对应：

1. 在校验放在 submit handler 里

// don't
submit: async (values) => {
    if (!values.email) throw new Error('Email required')
    await api.send(values)
}

校验属于 errors 的职责，submit 只负责"干活"。把校验放进 submit 意味着：校验错误与字段错误展示脱钩、submitFooFailure 会被无关异常触发、UI 无法在提交前给出即时反馈。

2. errors 返回 ''

// don't
errors: ({ email }) => ({ email: email ? '' : 'Required' })
// '' 不是 undefined —— 会被当作"存在错误"

kea-forms 将 errors 映射中任何非 undefined 的值视为"存在错误"，所以 '' 与 'Required' 效果相同，字段始终判为非法。"无错误"必须返回 undefined。

3. errors 内部做副作用

errors 每次击键都会重跑。日志、埋点、异步请求都不该出现在里面；需要响应输入行为时，监听 setFooValues 动作即可。

4. 用 useState 管理表单值

// don't
const [email, setEmail] = useState('')
const [name, setName] = useState('')

这就是一个等待被改写成 forms builder 的表单——校验、提交态、成功/失败动作全部缺失，最终会在组件里逐一手写。

5. 手动 setFooValue 链替代 <Field>

// don't
<LemonInput value={values.signup.email} onChange={(v) => actions.setSignupValue('email', v)} />

<Field name="email"> 已经接好了变化处理器，手动接线只会让组件膨胀、并容易漏掉错误展示。PostHog 约定：业务逻辑进 logic、组件退化为视图（见 SKILL.md）。

此外，anti-patterns.md 中"表单"之外的通用规则同样适用于 forms 场景：例如不要用 subscriptions 响应由动作设置的值（应直接监听该动作），不要在组件里用 useEffect 响应 logic 值变化（应移入 listener）。

从源码看完整生命周期：login 表单的端到端流程

将上述知识点拼起来，PostHog 登录表单的完整数据流如下（涉及 loginLogic.ts 与 LoginForm.tsx）：

1. 声明：forms 中定义 login（defaults: { email: '', password: '' }）与 codeVerification（defaults: { code: '' }）两个表单。codeVerification 故意不写 errors，因为其唯一的内联错误来自服务端拒绝，通过 setCodeVerificationManualErrors 注入，见 loginLogic.ts。
2. 渲染：LoginForm.tsx 根据 codeVerificationRequired 状态在两个 <Form> 之间切换，均开启 enableFormOnSubmit；LemonButton htmlType="submit" 驱动 submitLogin() / submitCodeVerification()，loading={isLoginSubmitting} 由插件维护。
3. 提交：submit 内部 breakpoint() 后调用 api.create('api/login', ...)；按服务端错误码（2fa_required、verify_email_pending、code_based_verification_required 等）分流处理，最终统一 throw e 让插件发出 submitLoginFailure。
4. 响应：listener 监听 submitLoginSuccess 完成跳转；监听 setCodeVerificationValue 在用户重新输入时清空手动错误，见 loginLogic.ts。
5. 重置：exitCodeVerification listener 调用 resetCodeVerification() 让表单回到 { code: '' } 的默认态。

这个流程展示了 kea-forms 的核心价值：值、校验、提交态、结果动作、重置全由插件管理，业务代码只需要声明式描述表单本身，再把"对结果的反应"放进 listener。

何时改用 loader / selector：先做容器决策

forms 不是表单场景的唯一选择。在动手写任何 kea 逻辑前，SKILL.md 建议先做容器决策：

• 数据来自 HTTP 调用 → 用 loader；
• 可由其他状态计算得出 → 用 selector；
• 由动作改变且 UI 需要响应重渲染 → 用 reducer；
• 定时器/监听器等需要清理的资源 → 用 cache.disposables。

表单天然包含"被动作改变且 UI 需要响应"的值（字段值）、"由值计算"的派生量（校验错误）、"HTTP 调用 + 提交态"（submit），因此 kea-forms 恰好是上述几者的组合封装。但反过来，如果某个"表单"根本没有提交动作、没有校验，只是几个同步值，那么它可能只是 reducer/selector 的职责，不应为了套用 builder 而引入完整的提交状态机。

小结

在 PostHog 前端，任何表单都应优先使用 kea-forms 的 forms builder：defaults + 纯函数 errors + async submit 三要素声明表单本体，生成的 fooValues / fooValidationErrors / fooHasErrors / isFooSubmitting / submitFooSuccess / submitFooFailure / resetFoo 等 API 覆盖完整生命周期，组件侧以 <Form formKey> + <Field> 零成本接入。记住三条铁律：errors 返回 undefined 而非 '' 表示无错误、errors 保持纯净、提交后的反应交给 submitXxxSuccess/Failure 的 listener。若想在具体代码中观察这套模式，PostHog 仓库的 loginLogic.ts（逻辑侧）与 LoginForm.tsx（组件侧）是最完整的一对参考实现。