@qin-ui/vant-pro 1.0.1 → 1.0.3

package/AI-CONTEXT.md

@@ -0,0 +1,38 @@
+# @qin-ui/vant-pro
+
+> 基于 Vant v4 的配置驱动表单组件库。
+
+## 安装
+
+```bash
+npm install @qin-ui/vant-pro vant vue
+```
+
+## 核心导出
+
+### 组件
+
+- `ProForm` - 配置驱动表单组件
+- `ProComponentProvider` - 全局配置提供者
+
+### Hooks
+
+- `useForm<D>()` - 创建表单实例
+- `useFields<D>()` - 字段配置管理
+- `useFormRef()` - 表单组件引用
+
+## 字段配置（Field）
+
+每个字段支持：`path`, `label`, `component`, `hidden`, `disabled`, `rules`, `valueFormatter`, `fields`, `grid`, `slots`, `componentStyle`, `componentClass`, `componentContainer`, `formItemStyle`, `formItemClass`, `formItemContainer`, `modelProp`
+
+内置组件：input, textarea, input-search, input-password, input-number, select, cascader, date-picker, range-picker, time-picker, checkbox-group, radio-group, switch, slider, tree-select, transfer, custom
+
+## 类型扩展
+
+```typescript
+declare module '@qin-ui/vant-pro' {
+  interface ComponentMap {
+    'my-custom-component': typeof MyComponent;
+  }
+}
+```

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,8 +1,15 @@
 # @qin-ui/vant-pro
 
-> 基于 Vant 4 和 @qin-ui/core 二次封装的移动端高级表单组件库。
+> 基于 **Vant 4** 和 **@qin-ui/core** 二次封装的移动端高级表单组件库，专门针对移动端 H5 精细化打造，助您极速构建交互流畅、配置驱动的移动端表单应用。
 
-## [📖 使用示例和文档详情](https://dufan3715.github.io/pro-components/)
+<p align="center">
+  <img src="https://img.shields.io/badge/Vant-4.x-blue" alt="Vant 4.x" />
+  <img src="https://img.shields.io/badge/Vue-3.5%2B-brightgreen" alt="Vue 3.5+" />
+  <img src="https://img.shields.io/badge/TypeScript-5.x-blue" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/License-MIT-green" alt="MIT" />
+</p>
+
+## 📝 [使用示例和文档详细内容](https://dufan3715.github.io/pro-components/)
 
 ---
 

package/api.json

@@ -0,0 +1,163 @@
+{
+  "generatedAt": "2026-05-26T08:14:28.580Z",
+  "name": "@qin-ui/vant-pro",
+  "api": [
+    {
+      "name": "ProComponentProvider",
+      "type": "component",
+      "package": "@qin-ui/vant-pro",
+      "signature": "<ProComponentProvider>",
+      "description": "@qin-ui/vant-pro 全局配置提供者组件\n用于在组件树的顶层配置所有子组件的全局默认属性。",
+      "examples": [
+        "```vue\n<ProComponentProvider\n:componentVars=\"{ 'field': { placeholder: '请输入' } }\"\n>\n<ProForm :form=\"form\" :fields=\"fields\" />\n</ProComponentProvider>\n```"
+      ]
+    },
+    {
+      "name": "ProForm",
+      "type": "component",
+      "package": "@qin-ui/vant-pro",
+      "signature": "<ProForm>",
+      "description": "@qin-ui/vant-pro 配置驱动表单组件（移动端）\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",
+      "package": "@qin-ui/vant-pro",
+      "signature": "<SlotComponent>",
+      "description": "插槽渲染辅助组件。用于在表单或表格的自定义插槽中动态渲染外部传入的 VNode、渲染函数或静态字符串。"
+    },
+    {
+      "name": "ComponentMap",
+      "type": "interface",
+      "package": "@qin-ui/vant-pro",
+      "signature": "export interface ComponentMap {}",
+      "description": "组件映射扩展接口\n通过 TypeScript 声明合并添加自定义组件",
+      "examples": [
+        "```ts\ndeclare module '@qin-ui/vant-pro' {\ninterface ComponentMap {\n'my-custom': typeof MyComponent;\n}\n}\n```"
+      ]
+    },
+    {
+      "name": "ComponentName",
+      "type": "type",
+      "package": "@qin-ui/vant-pro",
+      "signature": "export type ComponentName =\n  | keyof BaseComponentMap\n  | keyof ComponentMap\n  | 'custom';",
+      "description": "组件名称联合类型\n所有支持的组件名称"
+    },
+    {
+      "name": "useFormData",
+      "type": "function",
+      "package": "@qin-ui/vant-pro",
+      "signature": "export const useFormData = <D extends Data = Data>(\n  initFormData?: ExtendWithAny<DeepPartial<D>>\n) =>",
+      "description": "表单数据处理 Hook\n提供响应式表单数据的管理能力，支持：\n- 响应式数据存储（基于 Vue reactive）\n- 深层路径读写（支持点号分隔，如 'address.city'）\n- 类型安全的路径提示（传入泛型 D 后，path 参数可获得类型推导）\n- 父子表单自动注入（非根表单会从注入中获取数据）",
+      "returns": "{Function} .setFormData(path, value) - 设置指定路径的数据",
+      "typeParams": [
+        {
+          "name": "D"
+        }
+      ],
+      "examples": [
+        "```ts\ninterface User { name: string; age: number; address: { city: string } }\n\nconst { formData, getFormData, setFormData } = useFormData<User>({\nname: '张三',\naddress: { city: '北京' }\n})\n\n// 读取\ngetFormData('name')           // '张三'\ngetFormData('address.city')   // '北京'\nformData.name                 // '张三'（响应式）\n\n// 设置\nsetFormData('name', '李四')\nsetFormData('address.city', '上海')\nsetFormData({ name: '王五', age: 30 }) // 批量覆盖\nsetFormData(prev => ({ ...prev, name: '赵六' })) // 函数式更新\n```"
+      ]
+    },
+    {
+      "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",
+      "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```"
+      ]
+    },
+    {
+      "name": "UseFields",
+      "type": "type",
+      "package": "@qin-ui/vant-pro",
+      "signature": "export type UseFields<D extends Data = Data> = ReturnType<typeof useFields<D>>;",
+      "description": "useFields 返回值类型，固定为本地 Fields<D>"
+    },
+    {
+      "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 对象，用于管理弹出层表单",
+      "typeParams": [
+        {
+          "name": "D"
+        },
+        {
+          "name": "F"
+        }
+      ]
+    },
+    {
+      "name": "useForm",
+      "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 用于移动端弹窗表单。",
+      "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```"
+      ]
+    },
+    {
+      "name": "PopupProps",
+      "type": "type",
+      "package": "@qin-ui/vant-pro",
+      "signature": "export type PopupProps = ComponentProps<typeof Popup> &",
+      "description": "Vant Popup 组件属性类型\n用于配置表单弹出层的属性"
+    },
+    {
+      "name": "FormPopup",
+      "type": "type",
+      "package": "@qin-ui/vant-pro",
+      "signature": "export type FormPopup =",
+      "description": "表单弹出层管理对象\nVant 移动端特有的表单弹出层功能"
+    },
+    {
+      "name": "useFormPopup",
+      "type": "function",
+      "package": "@qin-ui/vant-pro",
+      "signature": "export function useFormPopup(root?: boolean): FormPopup;",
+      "description": "用于管理 Vant 移动端的表单弹出层（Popup）。\n在移动端表单中，某些字段（如地址选择、日期选择）需要以弹出层形式展示。",
+      "returns": "{FormPopup} 弹出层管理对象",
+      "examples": [
+        "```ts\nconst formPopup = useFormPopup(true)\nformPopup.open('address') // 打开地址选择弹出层\nformPopup.close()         // 关闭\nformPopup.updateProps({ position: 'top' })\n```"
+      ]
+    },
+    {
+      "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) - 设置表单组件实例",
+      "examples": [
+        "```ts\nconst { formRef, setFormRef } = useFormRef()\nformRef.value?.submit()\n```"
+      ]
+    }
+  ]
+}

package/es/component-provider/index-DC_k4_R3.js

@@ -0,0 +1,121 @@
+import { defineComponent, provide, renderSlot } from "vue";
+import { g as getObject } from "../core/index-B5vvm4Fj.js";
+const INJECT_CONFIG = {
+  "pro-form": {
+    injectionKey: Symbol(""),
+    default: {
+      inputAlign: "right",
+      errorMessageAlign: "right",
+      required: "auto",
+      scrollToError: true,
+      scrollToErrorPosition: "nearest"
+    }
+  },
+  field: {
+    injectionKey: Symbol(""),
+    default: { clearable: true, placeholder: "请输入" }
+  },
+  switch: {
+    injectionKey: Symbol(""),
+    default: {}
+  },
+  stepper: {
+    injectionKey: Symbol(""),
+    default: {}
+  },
+  rate: {
+    injectionKey: Symbol(""),
+    default: {}
+  },
+  slider: {
+    injectionKey: Symbol(""),
+    default: {}
+  },
+  uploader: {
+    injectionKey: Symbol(""),
+    default: {}
+  },
+  "checkbox-group": {
+    injectionKey: Symbol(""),
+    default: {}
+  },
+  "radio-group": {
+    injectionKey: Symbol(""),
+    default: {}
+  },
+  picker: {
+    injectionKey: Symbol(""),
+    default: {}
+  },
+  "date-picker": {
+    injectionKey: Symbol(""),
+    default: {}
+  },
+  "time-picker": {
+    injectionKey: Symbol(""),
+    default: {}
+  },
+  cascader: {
+    injectionKey: Symbol(""),
+    default: {}
+  },
+  area: {
+    injectionKey: Symbol(""),
+    default: {}
+  },
+  signature: {
+    injectionKey: Symbol(""),
+    default: {}
+  },
+  button: {
+    injectionKey: Symbol(""),
+    default: {}
+  }
+};
+const INJECT_COMPONENTS = Symbol("INJECT_COMPONENTS");
+const DYNAMIC_INJECT_CONFIG = /* @__PURE__ */ Object.create(null);
+const getInjectConfig = (key) => {
+  return INJECT_CONFIG[key] || DYNAMIC_INJECT_CONFIG[key];
+};
+const ensureInjectConfig = (key) => {
+  const existing = getInjectConfig(key);
+  if (existing) return existing;
+  const created = {
+    injectionKey: Symbol(`dynamic:${key}`),
+    default: {}
+  };
+  DYNAMIC_INJECT_CONFIG[key] = created;
+  return created;
+};
+const _sfc_main = /* @__PURE__ */ defineComponent({
+  ...{
+    name: "ProComponentProvider",
+    inheritAttrs: false
+  },
+  __name: "index",
+  props: {
+    componentVars: {},
+    componentMap: {}
+  },
+  setup(__props) {
+    const props = __props;
+    if (props.componentMap) {
+      provide(INJECT_COMPONENTS, props.componentMap);
+    }
+    if (props.componentVars) {
+      Object.entries(props.componentVars).forEach(([key, val]) => {
+        const config = ensureInjectConfig(key);
+        provide(config.injectionKey, { ...config.default, ...getObject(val) });
+      });
+    }
+    return (_ctx, _cache) => {
+      return renderSlot(_ctx.$slots, "default");
+    };
+  }
+});
+export {
+  INJECT_COMPONENTS as I,
+  _sfc_main as _,
+  INJECT_CONFIG as a,
+  getInjectConfig as g
+};

package/es/component-provider/index.js

@@ -1,122 +1,4 @@
-import { defineComponent, provide, renderSlot } from "vue";
-import { g as getObject } from "../core/index-D-2iAH6o.js";
-const INJECT_CONFIG = {
-  "pro-form": {
-    injectionKey: Symbol(""),
-    default: {
-      inputAlign: "right",
-      errorMessageAlign: "right",
-      required: "auto",
-      scrollToError: true,
-      scrollToErrorPosition: "nearest"
-    }
-  },
-  field: {
-    injectionKey: Symbol(""),
-    default: { clearable: true, placeholder: "请输入" }
-  },
-  switch: {
-    injectionKey: Symbol(""),
-    default: {}
-  },
-  stepper: {
-    injectionKey: Symbol(""),
-    default: {}
-  },
-  rate: {
-    injectionKey: Symbol(""),
-    default: {}
-  },
-  slider: {
-    injectionKey: Symbol(""),
-    default: {}
-  },
-  uploader: {
-    injectionKey: Symbol(""),
-    default: {}
-  },
-  "checkbox-group": {
-    injectionKey: Symbol(""),
-    default: {}
-  },
-  "radio-group": {
-    injectionKey: Symbol(""),
-    default: {}
-  },
-  picker: {
-    injectionKey: Symbol(""),
-    default: {}
-  },
-  "date-picker": {
-    injectionKey: Symbol(""),
-    default: {}
-  },
-  "time-picker": {
-    injectionKey: Symbol(""),
-    default: {}
-  },
-  cascader: {
-    injectionKey: Symbol(""),
-    default: {}
-  },
-  area: {
-    injectionKey: Symbol(""),
-    default: {}
-  },
-  signature: {
-    injectionKey: Symbol(""),
-    default: {}
-  },
-  button: {
-    injectionKey: Symbol(""),
-    default: {}
-  }
-};
-const INJECT_COMPONENTS = Symbol("INJECT_COMPONENTS");
-const DYNAMIC_INJECT_CONFIG = /* @__PURE__ */ Object.create(null);
-const getInjectConfig = (key) => {
-  return INJECT_CONFIG[key] || DYNAMIC_INJECT_CONFIG[key];
-};
-const ensureInjectConfig = (key) => {
-  const existing = getInjectConfig(key);
-  if (existing) return existing;
-  const created = {
-    injectionKey: Symbol(`dynamic:${key}`),
-    default: {}
-  };
-  DYNAMIC_INJECT_CONFIG[key] = created;
-  return created;
-};
-const _sfc_main = /* @__PURE__ */ defineComponent({
-  ...{
-    name: "ProComponentProvider",
-    inheritAttrs: false
-  },
-  __name: "index",
-  props: {
-    componentVars: {},
-    componentMap: {}
-  },
-  setup(__props) {
-    const props = __props;
-    if (props.componentMap) {
-      provide(INJECT_COMPONENTS, props.componentMap);
-    }
-    if (props.componentVars) {
-      Object.entries(props.componentVars).forEach(([key, val]) => {
-        const config = ensureInjectConfig(key);
-        provide(config.injectionKey, { ...config.default, ...getObject(val) });
-      });
-    }
-    return (_ctx, _cache) => {
-      return renderSlot(_ctx.$slots, "default");
-    };
-  }
-});
+import { _ } from "./index-DC_k4_R3.js";
 export {
-  INJECT_COMPONENTS,
-  INJECT_CONFIG,
-  _sfc_main as default,
-  ensureInjectConfig,
-  getInjectConfig
+  _ as default
 };

package/es/core/{index-D-2iAH6o.js → index-B5vvm4Fj.js}

@@ -1,4 +1,4 @@
-import { camelize, inject, reactive, provide, ref } from "vue";
+import { ref, inject, reactive, provide, camelize } from "vue";
 import { i as isPlainObject, s as set, g as get, t as toPath } from "../vendor/utils/lodash-es-DN4QDiDm.js";
 const InjectionFormKey = Symbol("form");
 const InjectionPathKey = Symbol("path");
@@ -109,23 +109,6 @@ const useFields = (initFields) => {
       options
     );
   }
-  function addFields(path, newFields, options, placement) {
-    if (newFields.length === 0) return;
-    if (path) {
-      updaterMatch(
-        path,
-        ({ fieldIndex, parentField }) => {
-          const index = placement === "after" ? fieldIndex + 1 : fieldIndex;
-          parentField.fields.splice(index, 0, ...newFields);
-        },
-        options
-      );
-    } else if (placement === "after") {
-      fields.value.push(...newFields);
-    } else {
-      fields.value.unshift(...newFields);
-    }
-  }
   function appendField(path, field, options) {
     const newFields = Array.isArray(field) ? field : [field];
     addFields(path, newFields, options, "after");
@@ -146,6 +129,23 @@ const useFields = (initFields) => {
     );
     return (options == null ? void 0 : options.all) ? res : res[0];
   }
+  function addFields(path, newFields, options, placement) {
+    if (newFields.length === 0) return;
+    if (path) {
+      updaterMatch(
+        path,
+        ({ fieldIndex, parentField }) => {
+          const index = placement === "after" ? fieldIndex + 1 : fieldIndex;
+          parentField.fields.splice(index, 0, ...newFields);
+        },
+        options
+      );
+    } else if (placement === "after") {
+      fields.value.push(...newFields);
+    } else {
+      fields.value.unshift(...newFields);
+    }
+  }
   return {
     fields,
     getField,
@@ -225,8 +225,8 @@ function useForm(...args) {
   };
 }
 export {
-  InjectionFormKey as I,
-  InjectionPathKey as a,
+  InjectionPathKey as I,
+  InjectionFormKey as a,
   useFields as b,
   camelizeProperties as c,
   useFormRef as d,