高质量vue表单控件库的核心是精准约束、清晰分层与恰当语义：控件置于web/src/lib/forms/，不依赖业务逻辑，仅通过props/emits通信；采用headless设计，透传原生事件，支持v-model与ref；统一用variant/size/state三元状态驱动；配合ox/oformx两级容器实现表单协作；并通过vitest、playwright和storybook保障可测试性与一致性。
高质量的 Vue 自定义表单控件库，核心不在“写得多”，而在“约束得准、分层得清、语义得当”。它不是把所有输入框堆在一起，而是建立一套可预测、可组合、可测试的契约体系。
明确职责边界：lib/ 与 components/ 不混用
这是复用性的根基。所有通用表单控件（如 OInput、OSelect、OFormInput）必须放在 web/src/lib/forms/ 下，且严格遵守：
- 不访问 store、router、i18n 或任何业务 service
- 只通过
props接收数据，通过emits（如update:modelValue、validate）向外通信 - 不直接操作 DOM 或依赖全局状态
- 同一组组件（如 OInput + OInputPassword + OInputSearch）应共用基础逻辑，通过 variant / size 等语义化 prop 区分行为
采用 headless 优先设计，暴露底层能力
高质量控件不绑定视觉样式，而是提供无样式的“行为骨架”。例如：
Vue Composition Analyzer
下载
分析 Vue 3 Composition API 使用情况——审计响应式模式、可组合函数设计、ref 与 reactive 的选择、计算属性、watcher 使用及组件……
-
OInput 内部使用
<input>原生元素，但把 focus、blur、input、change 等原生事件全部透传为emits - 支持
v-model（即modelValueprop +update:modelValueevent），也支持手动绑定:value+@input - 提供
ref暴露原生 input 元素，便于父组件调用.focus()或.select() - 校验逻辑分离：控件本身不执行规则，只提供
validate()方法供外部触发，并返回 Promise
统一 API 语义：variant / size / state 三元驱动
避免用一堆布尔 prop（isDisabled, isSmall, hasError）拼凑状态。推荐标准化命名：
-
size: 'sm' | 'md' | 'lg'—— 控制高度、内边距、字体大小 -
variant: 'default' | 'outline' | 'filled'—— 控制边框、背景、焦点样式 -
state: 'idle' | 'success' | 'error' | 'warning'—— 控制图标、边框色、辅助文本 - 所有状态组合都应在设计令牌（Design Tokens）中定义，如
--input-border-color-error，确保跨组件一致
配套表单容器：OX + OFormX 模式
单个控件再好，没有协作机制也无法形成表单系统。O2 库采用两级封装：
-
OX 组件（如
OForm、OFormItem）：负责布局、标签对齐、响应式断点、错误提示位置等 UI 结构 -
OFormX 组件（如
OFormInput、OFormSelect）：是 OX 容器与 headless 控件（如 OInput）的胶水层，自动注入 label、help-text、error-message，并绑定校验状态 - 这种分层让业务页只需写：
<oform><oforminput v-model="user.name" label="姓名"></oforminput></oform>，无需关心字段级渲染细节
构建与测试闭环：Vitest + Playwright 验证真实行为
可复用 ≠ 可运行。每个新控件需包含：
- Vitest 单元测试：覆盖 props 变化、事件触发、v-model 同步、禁用态交互等边界场景
- Playwright E2E 快照测试：在真实浏览器中验证 focus 流程、键盘导航（Tab/Enter）、AR 属性（aria-*）是否正确生成
- Storybook 示例：提供最小可用案例（minimal usage）、尺寸变体、错误状态、禁用组合等，作为文档和协作依据
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
