@qin-ui/vant-pro 1.0.4 → 1.1.0

package/AI-CONTEXT.md

@@ -1,38 +1,180 @@
-# @qin-ui/vant-pro
+# @qin-ui/vant-pro — AI 上下文
 
-> 基于 Vant v4 的配置驱动表单组件库。
+> Schema-driven高级表单组件库，基于 **vant v4**（Vue 3 移动端UI，`van-` 前缀）。
+> 核心思想：用 JS 对象描述 UI，而非在模板中堆砌组件标签。
 
-## 安装
+---
 
-```bash
-npm install @qin-ui/vant-pro vant vue
+## 1. 三层架构
+
+```
+Field[] 配置层（用户编写的 JS 对象）
+  { path:'city', component:'picker', label:'城市', columns:[...], popup:true }
+        ↓
+@qin-ui/vant-pro（Schema 解析 + 属性分层剥离）
+  van-field 属性 → <van-field> / 其余属性 → 内部输入控件
+        ↓
+vant v4（Vue 3 移动端组件库）
+  van-field / van-picker / van-switch / van-stepper / ...
+```
+
+ProForm 是**渲染引擎**，不是组件库。所有 UI 来自 vant。Field 配置的属性被**逐层剥离**，分发到 `van-field`（容器）和内部控件。
+
+### 组件映射表（componentMap，15 个内置组件）
+
+| Field `component`  | 渲染的 vant 组件 | 备注                                         |
+| :----------------- | :--------------- | :------------------------------------------- |
+| `'field'`          | Field            | **特殊：直接渲染 van-field，无内部控件包裹** |
+| `'switch'`         | Switch           | v-model 绑定 `modelValue`（vant 默认约定）   |
+| `'stepper'`        | Stepper          |                                              |
+| `'rate'`           | Rate             |                                              |
+| `'slider'`         | Slider           |                                              |
+| `'uploader'`       | Uploader         |                                              |
+| `'checkbox-group'` | CheckboxGroup    |                                              |
+| `'radio-group'`    | RadioGroup       |                                              |
+| `'picker'`         | Picker           | 常用 popup 模式（底部弹出）                  |
+| `'date-picker'`    | DatePicker       | 常用 popup 模式                              |
+| `'time-picker'`    | TimePicker       | 常用 popup 模式                              |
+| `'cascader'`       | Cascader         | 常用 popup 模式                              |
+| `'area'`           | Area             | 常用 popup 模式                              |
+| `'signature'`      | Signature        | 常用 popup 模式                              |
+| `'button'`         | Button           |                                              |
+| `'custom'`         | 自定义           | 传入 Vue 组件或 h() 渲染函数                 |
+
+> **编写任何输入控件属性前，必须查阅 [vant v4 官方文档](https://vant-ui.com/) 确认属性名和类型。**
+
+---
+
+## 2. 属性分层传递机制
+
+Field 配置的属性**逐层剥离**，分发到两个目标：
+
+**van-field 容器层（fieldAttrs）：**
+`label`, `rules`, `required`, `clearable`, `inputAlign`, `errorMessageAlign`, `colon`, `readonly`, `clickable`, `isLink`, `labelWidth`, `labelAlign`, `labelClass`, `error`, `center`, `border`, `autosize`, `type`, `maxlength`, `placeholder`, `rows`，以及所有 `on*` 事件回调。`fieldClass`/`fieldStyle` → `class`/`style` 绑定到 van-field。
+
+**内部控件层（bindAttrs）：**
+除上述外的其余属性（`columns`, `options`, `activeValue`, `min`, `max`, `step`, `count`, `size`, `direction`, `disabled` 等）。`componentClass`/`componentStyle` → 内部组件的 `class`/`style`。
+
+**剥离逻辑：**
+
+- 第一阶段（GroupedFieldAttrs）：解构 `path`, `fields`, `hidden`, `extraProps` → 剩余 → `componentProps` → BaseField
+- 第二阶段（BaseField）：解构 `valueFormatter`, `displayFormatter`, `modelProp`, `slots`, `popup` 等 → 匹配 vant Field.props 的属性 + `on*` → `fieldAttrs` → van-field；其余 → `bindAttrs` → 内部控件
+
+**`'field'` 特殊：** `component: 'field'` 直接渲染 van-field，无内部控件包裹，所有属性绑定到 van-field。
+
+### modelProp
+
+默认 `modelProp: 'modelValue'` → `v-model:modelValue`（vant 组件统一使用 `modelValue` 作为 v-model 绑定属性名）。
+
+---
+
+## 3. 渐进式用法
+
+### 3.1 基础渲染
+
+完全依赖 Field 配置，**禁止手写 `<van-field>` 或 `<van-switch>`**。
+
+```ts
+import { ProForm, useForm } from '@qin-ui/vant-pro';
+const form = useForm({ username: '', password: '' }, [
+  {
+    path: 'username',
+    component: 'field',
+    label: '用户名',
+    placeholder: '请输入用户名',
+    rules: [{ required: true }],
+  },
+  {
+    path: 'password',
+    component: 'field',
+    label: '密码',
+    type: 'password',
+    rules: [{ required: true }],
+  },
+]);
+```
+
+```html
+<template><ProForm :form="form" /></template>
 ```
 
-## 核心导出
+### 3.2 字段联动
 
-### 组件
+初始化联动用 `computed()`，运行时联动用 `setField()`，外部状态用 `ref()`。**越简单越好：**
 
-- `ProForm` - 配置驱动表单组件
-- `ProComponentProvider` - 全局配置提供者
+```ts
+// computed() — 初始化时已确定的联动
+disabled: computed(() => !form.formData.enabled);
 
-### Hooks
+// setField() — 事件触发时动态修改
+form.setField('limitCount', { disabled: true });
+```
 
-- `useForm<D>()` - 创建表单实例
-- `useFields<D>()` - 字段配置管理
-- `useFormRef()` - 表单组件引用
+### 3.3 自定义组件
 
-## 字段配置（Field）
+```ts
+// h() 挂载或插槽接管
+component: (p, ctx) => h(CustomPicker, { ...p, ...ctx.attrs }),
+```
 
-每个字段支持：`path`, `label`, `component`, `hidden`, `disabled`, `rules`, `valueFormatter`, `fields`, `grid`, `slots`, `componentStyle`, `componentClass`, `componentContainer`, `formItemStyle`, `formItemClass`, `formItemContainer`, `modelProp`
+```html
+<ProForm :form="form">
+  <template #city="scoped"><CustomPicker v-bind="scoped" /></template>
+</ProForm>
+```
 
-内置组件：field, switch, stepper, rate, slider, uploader, checkbox-group, radio-group, picker, date-picker, time-picker, cascader, area, signature, button, custom
+### 3.4 Popup 弹窗模式
 
-## 类型扩展
+Field 配置 `popup: true` 时：表单项以只读 van-field 展示，点击后底部弹出 Popup，内部控件在 Popup 中渲染。确认提交值，取消丢弃修改。`displayFormatter` 控制只读展示文本。
 
-```typescript
-declare module '@qin-ui/vant-pro' {
-  interface ComponentMap {
-    'my-custom-component': typeof MyComponent;
-  }
-}
+```ts
+{ path: 'city', component: 'picker', label: '城市', columns: ['北京','上海'], popup: true, displayFormatter: (v) => v || '请选择' }
 ```
+
+---
+
+## 4. 反模式
+
+- **禁止手写 van-field**：所有表单项通过 Field 配置驱动，ProForm 自动渲染 van-field
+- **禁止猜测属性名**：编写组件属性前必须查 [vant 文档](https://vant-ui.com/)，vant 不使用 `allowClear`/`mode:'multiple'` 等第三方库命名
+- **联动选简单方式**：初始化联动用 `computed()`，运行时用 `setField()`，避免过度设计
+
+---
+
+## 5. ProComponentProvider 全局默认配置
+
+通过 `ProComponentProvider` 在应用顶层统一配置默认属性，避免重复。属性优先级：Field 级别 > componentVars > INJECT_CONFIG 预设。
+
+### INJECT_CONFIG 预设默认值
+
+| 组件         | 预设默认值                                                                                                                     |
+| :----------- | :----------------------------------------------------------------------------------------------------------------------------- |
+| `pro-form`   | `{ inputAlign: 'right', errorMessageAlign: 'right', required: 'auto', scrollToError: true, scrollToErrorPosition: 'nearest' }` |
+| `field`      | `{ clearable: true, placeholder: '请输入' }`                                                                                   |
+| 其余所有组件 | `{}`（无预设，直接使用 vant 默认值）                                                                                           |
+
+### componentVars 额外配置键
+
+`valueFormatter`, `displayFormatter`, `componentContainer`, `modelProp`, `popup` — 可通过 ProComponentProvider 全局统一配置。
+
+```vue
+<ProComponentProvider
+  :component-vars="{
+    'pro-form': { inputAlign: 'left' },
+    field: { clearable: false, placeholder: '请输入内容' },
+    switch: { activeColor: '#07c160' },
+    stepper: { integer: true, min: 0 },
+  }"
+>
+  <ProForm :form="form" />
+</ProComponentProvider>
+```
+
+---
+
+## 6. 关键参考文件
+
+1. **`node_modules/@qin-ui/vant-pro/api.json`** — 结构化 API 元数据（函数签名、类型定义、JSDoc）
+2. **`node_modules/@qin-ui/vant-pro/README.md`** — 完整使用文档和代码示例
+3. **`https://vant-ui.com/`** — vant v4 官方文档（确认组件属性时必查）
+4. 源码类型定义 — `src/components/form/types/index.ts`（Field 类型）、`src/components/form/constants/index.ts`（componentMap）、`src/components/component-provider/constants/index.ts`（INJECT_CONFIG）

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2023-present pro-components
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @qin-ui/vant-pro
 
-> 基于 **Vant 4** 和 **@qin-ui/core** 二次封装的移动端高级表单组件库，专门针对移动端 H5 精细化打造，助您极速构建交互流畅、配置驱动的移动端表单应用。
+> 基于 **Vant 4** 和 **@qin-ui/pro-components-core** 二次封装的移动端高级表单组件库，专门针对移动端 H5 精细化打造，助您极速构建交互流畅、配置驱动的移动端表单应用。
 
 <p align="center">
   <img src="https://img.shields.io/badge/Vant-4.x-blue" alt="Vant 4.x" />

package/api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-05-26T08:42:45.735Z",
+  "generatedAt": "2026-07-09T04:30:07.554Z",
   "name": "@qin-ui/vant-pro",
   "api": [
     {
@@ -12,25 +12,25 @@
         "```vue\n<ProComponentProvider\n:componentVars=\"{ 'field': { placeholder: '请输入' } }\"\n>\n<ProForm :form=\"form\" :fields=\"fields\" />\n</ProComponentProvider>\n```"
       ]
     },
+    {
+      "name": "ContainerFragment",
+      "type": "component",
+      "package": "@qin-ui/vant-pro",
+      "signature": "<ContainerFragment>",
+      "description": "容器分片渲染组件。用于动态渲染表单行或表单项的外部包裹容器（例如 Grid 行、Col 列等布局容器）。"
+    },
     {
       "name": "ProForm",
       "type": "component",
       "package": "@qin-ui/vant-pro",
       "signature": "<ProForm>",
-      "description": "@qin-ui/vant-pro 配置驱动表单组件（移动端）\n通过配置驱动的方式快速构建移动端表单，支持：\n- 字段联动、嵌套字段、自定义组件\n- 弹出层表单（Popup，适用于移动端选择器场景）",
+      "description": "@qin-ui/vant-pro 配置驱动表单组件（移动端）\n架构设计说明 (Architecture Overview)\n[ 数据层 (Core) ]  =>  [ 绑定层 (ProForm) ]  =>  [ 渲染层 (BaseFormItem / BaseField) ]\n1. 数据隔离：ProForm 本身不负责存储和管理表单状态，所有核心状态（formData, fields, 校验规则）\n均交由底层的 `useForm`（@qin-ui/pro-components-core）驱动。\n2. 上下文透传：通过 `provide` 将核心状态下发给子组件，避免了深层嵌套的 Props 传递。\n3. 递归渲染：具体字段的解析交由 `<BaseFormItem>` 递归完成，实现了 UI 布局与表单逻辑的解耦。\n通过配置驱动的方式快速构建移动端表单，支持：\n- 字段联动、嵌套字段、自定义组件\n- 弹出层表单（Popup，适用于移动端选择器场景）",
       "typeParams": [
         {
           "name": "F"
         }
       ]
     },
-    {
-      "name": "ContainerFragment",
-      "type": "component",
-      "package": "@qin-ui/vant-pro",
-      "signature": "<ContainerFragment>",
-      "description": "容器分片渲染组件。用于动态渲染表单行或表单项的外部包裹容器（例如 Grid 行、Col 列等布局容器）。"
-    },
     {
       "name": "SlotComponent",
       "type": "component",
@@ -59,9 +59,9 @@
       "name": "useFormData",
       "type": "function",
       "package": "@qin-ui/vant-pro",
-      "signature": "export const useFormData = <D extends Data = Data>(\n  initFormData?: ExtendWithAny<DeepPartial<D>>\n) =>",
+      "signature": "export const useFormData = <D extends Data = Data>(\n  initFormData?: ExtendWithAny<DeepPartial<D>>\n): UseFormDataReturn<D> =>",
       "description": "表单数据处理 Hook\n提供响应式表单数据的管理能力，支持：\n- 响应式数据存储（基于 Vue reactive）\n- 深层路径读写（支持点号分隔，如 'address.city'）\n- 类型安全的路径提示（传入泛型 D 后，path 参数可获得类型推导）\n- 父子表单自动注入（非根表单会从注入中获取数据）",
-      "returns": "{Function} .setFormData(path, value) - 设置指定路径的数据",
+      "returns": "{UseFormDataReturn<D>} 表单数据操作对象",
       "typeParams": [
         {
           "name": "D"
@@ -75,15 +75,16 @@
       "name": "useFields",
       "type": "function",
       "package": "@qin-ui/vant-pro",
-      "signature": "export const useFields = _useFields as",
-      "description": "类型安全的 re-export。将 core useFields 的泛型参数绑定为本地类型：\n- 字段类型 F → Field<ComponentName, D>（支持 Vant 组件类型推导）\n- Field 实例 → Vant 的 FieldInstance",
+      "signature": "export function useFields<D extends Data = Data>(\n  initFields?: Fields<D>\n): UseFieldsReturn<D, Field<ComponentName, D>, FieldInstance>;",
+      "description": "字段配置管理 Hook\n基于 `@qin-ui/pro-components-core` 的 `useFields`，将泛型参数绑定为 Vant 的本地类型：\n- 字段类型 F -> `Field<ComponentName, D>`（支持 Vant 组件类型推导）\n- Field 实例 -> Vant 的 `FieldInstance`\n提供对字段配置数组的增删改查操作，支持：\n- 通过路径字符串或查找函数定位字段\n- 深层嵌套字段的遍历和匹配\n- 字段配置的合并/覆盖更新\n- 字段的添加、插入、删除\n- 父级字段查找\n- `fields` - 字段配置数组（响应式 Ref\\<F[]\\>）\n- `getField(path)` - 获取字段配置，支持路径字符串或查找函数\n- `setField(path, field, options?)` - 更新字段配置，默认合并模式\n- `deleteField(path, options?)` - 删除字段配置\n- `appendField(path, field, options?)` - 在指定字段后追加\n- `prependField(path, field, options?)` - 在指定字段前插入\n- `getParentField(path, options?)` - 获取父级字段配置",
+      "returns": "字段操作对象，包含以下属性：",
       "typeParams": [
         {
           "name": "D"
         }
       ],
       "examples": [
-        "```ts\ninterface User { name: string; age: number }\n\nconst { fields, getField, setField } = useFields<User>([\n{ path: 'name', label: '姓名', component: 'field' },\n{ path: 'age', label: '年龄', component: 'stepper' },\n])\n```"
+        "```ts\ninterface User { name: string; age: number }\n\nconst { fields, getField, setField } = useFields<User>([\n{ path: 'name', label: '姓名', component: 'field' },\n{ path: 'age', label: '年龄', component: 'stepper' },\n])\n\n// 通过路径获取\ngetField('name')\n// 通过查找函数获取\ngetField(f => f.label === '姓名')\n// 更新字段（合并模式）\nsetField('name', { label: '用户名', disabled: true })\n```"
       ]
     },
     {
@@ -91,14 +92,14 @@
       "type": "type",
       "package": "@qin-ui/vant-pro",
       "signature": "export type UseFields<D extends Data = Data> = ReturnType<typeof useFields<D>>;",
-      "description": "useFields 返回值类型，固定为本地 Fields<D>"
+      "description": "useFields 返回值类型"
     },
     {
       "name": "Form",
       "type": "type",
       "package": "@qin-ui/vant-pro",
       "signature": "export type Form<\n  D extends Data = Data,\n  F extends Field<ComponentName, D> = Field<ComponentName, D>,\n> = _Form<D, F, FormInstance> & { formPopup: FormPopup };",
-      "description": "在 core Form 类型的基础上：\n1. 将字段类型 F 绑定为本地 Field<ComponentName, D>\n2. 将底层表单实例绑定为 Vant 的 FormInstance\n3. 额外包含 formPopup 对象，用于管理弹出层表单",
+      "description": "表单实例类型\n在 core Form 类型的基础上，将字段类型 F 绑定为本地 Field<ComponentName, D>，\n将底层表单实例 I 绑定为 Vant 的 FormInstance，使 formRef 获得完整的类型提示。\n额外包含 formPopup 对象，用于管理弹出层表单。\n1. `setFormData(path, value)` - 设置指定路径的值<br>\n2. `setFormData(path, prev => newVal)` - 函数式更新<br>\n3. `setFormData({ ... })` - 批量覆盖整个表单",
       "typeParams": [
         {
           "name": "D"
@@ -106,6 +107,9 @@
         {
           "name": "F"
         }
+      ],
+      "examples": [
+        "```ts\ninterface User { name: string; age: number }\nconst form: Form<User> = useForm({ name: '张三', age: 25 })\n\nform.formData.name           // 直接读写响应式数据\nform.getFormData('name')     // 通过路径读取\nform.setFormData('name', '李四')  // 更新数据\nform.formRef.value?.validate()    // 访问底层 Form 实例\nform.formPopup.open('address')    // 打开弹出层表单\n```"
       ]
     },
     {
@@ -113,14 +117,15 @@
       "type": "function",
       "package": "@qin-ui/vant-pro",
       "signature": "export function useForm<D extends Data = Data>(\n  initFormData?: ExtendWithAny<DeepPartial<D>>,\n  initFields?: Field<ComponentName, D>[],\n  root?: boolean\n): Form<D, Field<ComponentName, D>>;",
-      "description": "创建 @qin-ui/vant-pro 表单实例的 Hook\n基于 core useForm 封装，额外提供了 formPopup 用于移动端弹窗表单。",
+      "description": "创建表单实例的 Hook\n基于 `@qin-ui/pro-components-core` 的 `useForm`，将泛型参数绑定为 Vant 的本地类型：\n- 字段类型 F -> `Field<ComponentName, D>`（支持 Vant 组件类型推导）\n- 表单实例 -> Vant 的 `FormInstance`（使 formRef 获得完整的类型提示）\n在 core useForm 基础上额外提供 formPopup，用于移动端弹窗表单场景。\n表单实例组合了四个子模块的能力：\n- **useFormData**：表单数据管理（响应式数据、读写、批量更新）\n- **useFields**：字段配置管理（增删改查字段配置，支持嵌套）\n- **useFormRef**：底层 Form 组件实例引用\n- **useFormPopup**：弹出层表单管理（Vant 专属）",
+      "returns": "{Form<D>} 表单实例，包含数据操作、字段操作、ref 操作和弹出层管理",
       "typeParams": [
         {
           "name": "D"
         }
       ],
       "examples": [
-        "```ts\ninterface User { name: string; age: number }\n\nconst form = useForm<User>(\n{ name: '张三' },\n[\n{ path: 'name', label: '姓名', component: 'field' },\n]\n)\n\n// 打开弹出层表单\nform.formPopup.open('address')\nform.formPopup.close()\n```"
+        "```ts\ninterface User { name: string; age: number }\n\n// 方式一：同时传入初始数据和字段\nconst form = useForm<User>(\n{ name: '张三', age: 25 },\n[\n{ path: 'name', label: '姓名', component: 'field' },\n],\ntrue\n)\n\n// 方式二：仅设置 root 标识\nconst form = useForm<User>(true)\n\n// 使用\nconst { formData, formRef, fields, setFormData, formPopup } = form\nsetFormData('name', '李四')\nformPopup.open('address') // 打开弹出层表单\n```"
       ]
     },
     {
@@ -152,11 +157,11 @@
       "name": "useFormRef",
       "type": "function",
       "package": "@qin-ui/vant-pro",
-      "signature": "export const useFormRef = _useFormRef as",
-      "description": "类型安全的 re-export。将 core useFormRef 的泛型参数绑定为 Vant 的 FormInstance。",
-      "returns": "{Function} .setFormRef(inst) - 设置表单组件实例",
+      "signature": "export function useFormRef(): UseFormRefReturn<FormInstance>",
+      "description": "表单组件实例引用 Hook\n基于 `@qin-ui/pro-components-core` 的 `useFormRef`，将泛型参数绑定为 Vant 的 `FormInstance`，\n使 formRef 获取到完整的 Vant Form 组件 API 类型提示（如 `validate()`、`resetValidation()` 等）。\n`formRef` 由 ProForm 组件内部自动通过 `setFormRef` 绑定，无需手动调用。\n- `formRef` — Vant Form 组件实例的响应式引用（`Ref<FormInstance | undefined>`）\n- `setFormRef(inst)` — 设置 Form 组件实例，由 ProForm 内部自动调用",
+      "returns": "表单组件实例引用管理对象：",
       "examples": [
-        "```ts\nconst { formRef, setFormRef } = useFormRef()\nformRef.value?.submit()\n```"
+        "```ts\nconst { formRef, setFormRef } = useFormRef()\n\n// formRef 由 ProForm 自动绑定，可直接使用\nawait formRef.value?.validate()\nformRef.value?.resetValidation()\nformRef.value?.scrollToField('username')\n```"
       ]
     }
   ]