plugin-form README 的示例键面与 @object-ui/types 的真身不符:`validation` 数组拼法让校验静默失效、`multi-step-form` 全仓未注册、`FormField` 参考块五处漂移

[yinlianghui]

发现于 #5011 的实施(那一单只改导入面 —— 名字存在与否、来自哪个包)。本卡是同文件的键面/形状,不同性质,故未夹带进那个 PR。Filed unassigned, not claiming.

现象

packages/plugin-form/README.md 教的 form 键面有三组与真身不符。真身:@object-ui/types 的 FormField(packages/types/src/form.ts:898)与 FormSchema(:1055)。下面每条读数都是对构建产物 dist/index.d.ts 在 strict 下真编译出来的。

1. validation: 写成数组 —— 规则一条都不跑,且不报错

README 三处这样写(:164 的 FormField 参考块、"Basic Form" 示例、"Form with Validation" 示例):

validation: [
  { type: 'minLength', value: 3, message: '…' },
  { type: 'pattern', value: '^[a-zA-Z0-9_]+$', message: '…' }
]

真身是对象而不是数组:FormField.validation?: FieldValidationRules,FieldValidationRules(form.ts:744)按规则名开键 —— required?、minLength?: { value: number; message: string }、maxLength?、min?、max?、pattern?、validate?。

类型侧(把 "Basic Form" 示例标注成 const schema: FormSchema 后):

error TS2559: Type '{ type: string; message: string; }[]' has no properties in common with type 'FieldValidationRules'.

运行时侧是静默的,这是本卡最要紧的一半:唯一的读点 packages/components/src/renderers/form/form.tsx:1652 写的是 const rules: any = { ...validation }。把数组展开进对象字面量得到 { '0': {…}, '1': {…} } —— react-hook-form 不认这些数字键,于是 README 教出来的 email / minLength / maxLength / pattern 规则全部不生效,而且没有任何报错。照抄的表单看上去有校验,实际没有。

2. type: 'multi-step-form' 全仓未注册

"Multi-Step Form" 整个示例挂在这个 type 上,而 git grep -nw multi-step-form -- packages apps 除该 README 外零命中。本包六个 register 调用 claim 的是 plugin-form:object-form、view:form、plugin-form:embeddable-form、plugin-form:form-analytics、plugin-form:object-master-detail-form、record:line_items(packages/plugin-form/src/index.tsx:100/159/211/232/276/356)。照抄即未知组件红框,#4616 那一族。

示例里的 steps 键同样不在 FormSchema 上;多步表单的真实入口是 WizardForm(本包导出)或 object-form 的 formType: 'wizard'。

类型侧:error TS2322: Type '"multi-step-form"' is not assignable to type '"form"'.

3. FormField 参考块五处漂移

"Schema API → Form Field" 一节现场声明了一个本地 interface FormField。裸声明永远编译通过(它只是个与真类型无关的本地类型),所以按 #5059 的路数对真身做双向 pin,两个方向都红:

参考块	真身	pin 读数
type: string(必填)	type?: string	real 赋给 doc:TS2322 … Types of property 'type' are incompatible … Type 'string | undefined' is not assignable to type 'string'
label: string(必填)	label?: string	同族
validation?: ValidationRule[]	validation?: FieldValidationRules	doc 赋给 real:TS2322 … Type 'ValidationRule[]' has no properties in common with type 'FieldValidationRules'
defaultValue?: any	真身无此键(表单级的是 FormSchema.defaultValues)	—
className?: string	真身无此键	—

ValidationRule 这个类型名本身全仓也不存在 —— #5011 的探针在改前与改后都原样携带 error TS2304: Cannot find name 'ValidationRule'.,那一单如实列了它并指向本卡。

参考块另外只列了真身 23 个键里的 9 个:widget、dependsOn、visibleOn、visibleWhen、readonlyWhen、requiredWhen、options、condition、span、colSpan、hidden、readonly、id、description、field 全部缺席。

为什么不在 #5011 里顺手改

#5011 改的是导入面;本卡是键面,先例上这一类都是分开定级的(plugin-calendar 的 #5045、plugin-gantt 的 #5057、plugin-dashboard 的 #5066)。更实际的理由:这三组是连体的 —— 只改参考块、留着两个示例继续教 validation: [ … ],同一个 README 会自相矛盾;要一次改对就得重写整个 "Schema API" + "Examples" 段落,那是独立的一遍活。

复核方式

# 1
grep -n "validation: \[" packages/plugin-form/README.md
sed -n '744,780p' packages/types/src/form.ts          # FieldValidationRules 是对象
sed -n '1650,1655p' packages/components/src/renderers/form/form.tsx   # { ...validation }

# 2
git grep -nw multi-step-form -- packages apps          # 只有该 README
git grep -nE "ComponentRegistry\.register\(" -- packages/plugin-form/src

# 3
sed -n '898,1050p' packages/types/src/form.ts          # 真身 FormField,23 个键

分级

交 PM 分诊,未打 finding 标签:三组都是今天的读者会撞上的,而第 1 组还是静默失效(拿到一个没有校验的表单,零报错),严重度可能高于纯文档级。

今天没有门禁看得见这一类:check-doc-links 只解析链接,check-doc-component-types 只扫 content/docs,包内 README 的键面断言无人核对 —— 根因与门禁提案见 #5043。

[yinlianghui]

立卡人补记(正文末尾 footer 被 issues 端点剥掉,改用评论补):本卡由 #5011 的 os-dev 席在实施中扫出并如实分离 —— 那一单的 PR 只动导入面,键面这三组一行未碰,其编译探针改前改后都原样携带 TS2304: Cannot find name 'ValidationRule',指向本卡。未认领。

---

Generated by Claude Code

[yinlianghui]

认领(objectui 分片 PM 直辖,批次 22 补席)—— session session_01GTRjn8xBqp75dk7kFupVRt,分支 claude/issue-5075-form-readme-keys。os-dev 席位实施,PM 只读验收。前置 PR #5079(#5011 导入面半)已落 main;与在飞 #5066(dashboard README)、#5062+#5063(app-shell)零交集。

范围按卡面三组连体一次改对(整段重写 Schema API + Examples,#5002 家族形):① validation 全部改真身对象形(FieldValidationRules 按规则名开键),静默失效机制(form.tsx:1652 { ...validation } 展开数组成数字键)写进 PR 作前提复现;② multi-step-form 示例改教真实入口(WizardForm 导出或 object-form 的 formType: 'wizard' —— 以 register 调用现场与真身键为准,steps 键处置随真形);③ FormField 参考块按真身 23 键重写(双向 pin 承载键面事实,#5059 路数)。前提门:三组读数逐条复测,键面证据 cast 感知读取点口径({ ...validation } 这类展开形也算读点形态,留意);探针只用于可编译面,不冒充键面证据(索引签名致盲三席已证 —— FormField 若无索引签名则 pin 有牙,先实测确认再声称)。⛔ 不加渲染器能力、⛔ 不动 components/form.tsx 的容忍支路(观察归 #5043 族)。

---

Generated by Claude Code

[yinlianghui]

实施完成,draft PR #5100(分支 claude/issue-5075-form-readme-keys,基线 origin/main = 9fbb9b52ffa92432019a9a5ebfdd6a671d891f77)。三组一次改对,只动 packages/plugin-form/README.md + 一个 changeset。

前提门:卡面读数逐条复测通过,两处计数如实修正

• 缺席的真键是 16 个,不是 15 —— 卡面清单漏了 inputType,而本 README 自己的示例一直在用它;相应地「列了 9 个」实为列了 7 个真键(defaultValue / className 本就不是真键,不该数进「列了」)。
• steps 一条比卡面更强:不只是「不在 FormSchema 上」,而是 packages/types/src 零声明,全仓 .steps 读点全部是 flow 执行日志,与表单无关。

探针口径(先实测再声称):FormField 与 BaseSchema 都带 [key: string]: any(form.ts:1034 / base.ts:318),所以探针对「键不存在」这一类没有牙 —— 实测确认 steps / defaultValue / className 三条挂上去都不报错。这三条只由「声明缺席 + 读点 grep」证明,PR 与 README 都按这个分层写。有牙的部分照卡面读数复现:validation 数组 TS2559 ×3、type: 'multi-step-form' TS2322、双向 pin 的 TS2322。反面对照:WizardFormSchema 没有索引签名,所以标注它的示例里发明一个键是真编译错误。

静默失效已作前提复现写进 PR:{ ...validation } 把数组展开成 { '0': …, '1': … },而 react-hook-form 的字段校验器只解构 required/maxLength/minLength/min/max/pattern/validate/valueAsNumber —— 规则一条不跑、零报错。⛔ 未动 form.tsx 的读点。

实施中扫出、未夹带的两条已另立卡:#5098(同文件 ## Integration with Data Sources 把 dataSource / resource 写在 form schema 上,两键零读取点)、#5099(手写 FieldValidationRules 既不校验也不归一:pattern.value 写 string 被 RHF 静默忽略;含两方案与推荐,需维护者定)。

---

Generated by Claude Code