@vue-ui-kit/ant 1.7.4 → 1.8.0

package/README.zh.md

@@ -108,373 +108,516 @@ export const setupKit = () => {
 
 ## 组件
 
+### PGrid
+
+增强的数据表格组件，集成了查询表单、分页和工具栏功能。
+
+#### 基础示例
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue';
+import { PGridProps, labelColDict } from '@vue-ui-kit/ant';
+
+const gridSetting = computed<PGridProps<Student, { keyword?: string }>>(() => ({
+  columns: [
+    { field: 'name', title: '姓名', width: 200 },
+    { field: 'email', title: '邮箱', width: 200 },
+    { field: 'age', title: '年龄', width: 100 },
+  ],
+  formConfig: {
+    items: [
+      {
+        field: 'keyword',
+        title: '关键字',
+        labelCol: labelColDict[3],
+        itemRender: {
+          name: '$input',
+          props: { placeholder: '请输入关键字...' },
+        },
+      },
+    ],
+  },
+  proxyConfig: {
+    ajax: {
+      query: ({ form, page }) => api.getStudents({ ...form, ...page }),
+    },
+  },
+}));
+</script>
+
+<template>
+  <p-grid v-bind="gridSetting" />
+</template>
+```
+
 ### PForm
 
 增强的表单组件，具有简化的配置和动态字段功能。
 
 #### 属性
 
-| 属性        | 类型               | 说明                            |
-| ----------- | ------------------ | ------------------------------- |
-| items       | `PFormItemProps[]` | 表单项配置数组                  |
-| customReset | `() => void`       | 自定义重置函数                  |
-| 其他        | `FormProps`        | 所有 ant-design-vue Form 的属性 |
+| 属性 | 类型 | 说明 | 默认值 |
+| --- | --- | --- | --- |
+| items | `PFormItemProps[]` | 表单项配置数组 | - |
+| data | `T` | 表单数据对象 | - |
+| customReset | `() => void` | 自定义重置函数 | - |
+| labelCol | `ColProps` | 标签列布局 | `{ span: 6 }` |
+| wrapperCol | `ColProps` | 包装列布局 | `{ span: 16 }` |
+| ...其他 | `FormProps` | 所有 ant-design-vue Form 的属性 | - |
+
+#### 事件
+
+| 事件 | 说明 | 参数 |
+| --- | --- | --- |
+| apply | 表单提交时触发 | `(formData: T) => void` |
+| reset | 表单重置时触发 | `() => void` |
 
 #### PFormItemProps
 
-| 属性          | 类型                            | 说明                       | 默认值 |
-| ------------- | ------------------------------- | -------------------------- | ------ |
-| field         | `string`                        | 表单字段名                 | -      |
-| title         | `string`                        | 字段标签                   | -      |
-| span          | `number`                        | 栅格跨度                   | -      |
-| colon         | `boolean`                       | 是否显示冒号               | true   |
-| forceRequired | `boolean`                       | 显示必填标记（不进行验证） | false  |
-| align         | `'left' \| 'right' \| 'center'` | 文本对齐方式               | 'left' |
-| col           | `ColProps`                      | 栅格列属性                 | -      |
-| rule          | `Rule[]`                        | 验证规则                   | -      |
-| tooltipConfig | `TooltipConfig`                 | 提示配置                   | -      |
+| 属性 | 类型 | 说明 | 默认值 |
+| --- | --- | --- | --- |
+| field | `string` | 表单字段名 | - |
+| title | `string` | 字段标签 | - |
+| span | `number` | 栅格跨度 (1-24) | - |
+| colon | `boolean` | 标签后显示冒号 | `true` |
+| labelCol | `ColProps` | 标签列布局 | - |
+| wrapperCol | `ColProps` | 包装列布局 | - |
+| forceRequired | `boolean` | 显示必填标记（仅视觉效果） | `false` |
+| align | `'left' \| 'right' \| 'center'` | 文本对齐方式 | `'left'` |
+| col | `ColProps` | 栅格列属性 | - |
+| rule | `Rule[]` | 验证规则 | - |
+| itemRender | `ItemRender` | 字段渲染器配置 | - |
+| tooltipConfig | `TooltipConfig` | 提示配置 | - |
+| slots | `object` | 自定义插槽渲染器 | - |
+
+#### 内置渲染器
+
+- `$input`: 输入框
+- `$textarea`: 文本域
+- `$number`: 数字输入框
+- `$select`: 下拉选择
+- `$date`: 日期选择器
+- `$range`: 日期范围选择器
+- `$time`: 时间选择器
+- `ASwitch`: 开关组件
+- `ACheckbox`: 复选框
+- `ARate`: 评分组件
+- `ASlider`: 滑动输入条
+
+#### 基础示例
 
-#### 示例
+```vue
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { PFormProps } from '@vue-ui-kit/ant';
+
+interface UserForm {
+  name: string;
+  email: string;
+  age?: number;
+  gender: string;
+  skills: string[];
+}
+
+const formData = ref<UserForm>({
+  name: '',
+  email: '',
+  age: undefined,
+  gender: '',
+  skills: [],
+});
+
+const formSetting = computed<PFormProps<UserForm>>(() => ({
+  items: [
+    {
+      field: 'name',
+      title: '姓名',
+      span: 12,
+      rule: [{ required: true, message: '请输入姓名' }],
+      itemRender: {
+        name: '$input',
+        props: { placeholder: '请输入姓名' },
+      },
+    },
+    {
+      field: 'email',
+      title: '邮箱',
+      span: 12,
+      rule: [
+        { required: true, message: '请输入邮箱' },
+        { type: 'email', message: '邮箱格式不正确' },
+      ],
+      itemRender: {
+        name: '$input',
+        props: { placeholder: '请输入邮箱' },
+      },
+    },
+    {
+      field: 'gender',
+      title: '性别',
+      span: 12,
+      rule: [{ required: true, message: '请选择性别' }],
+      itemRender: {
+        name: '$select',
+        props: {
+          placeholder: '请选择性别',
+          options: [
+            { label: '男', value: 'male' },
+            { label: '女', value: 'female' },
+          ],
+        },
+      },
+    },
+    {
+      field: 'skills',
+      title: '技能',
+      span: 24,
+      itemRender: {
+        name: '$select',
+        props: {
+          mode: 'multiple',
+          placeholder: '请选择技能',
+          options: [
+            { label: 'Vue.js', value: 'vue' },
+            { label: 'React', value: 'react' },
+            { label: 'Angular', value: 'angular' },
+          ],
+        },
+      },
+    },
+  ],
+}));
+
+const handleSubmit = (data: UserForm) => {
+  console.log('表单提交:', data);
+};
+</script>
+
+<template>
+  <p-form 
+    v-bind="formSetting" 
+    :data="formData"
+    @apply="handleSubmit"
+  />
+</template>
+```
+
+#### 自定义插槽示例
 
 ```vue
 <script setup lang="tsx">
-  import { computed, ref } from 'vue';
-  import { TextAdAccount } from '...somewhere';
-  import { PFormProps } from '@vue-ui-kit/ant';
-
-  const createFormData = ref<TextAdAccount>({
-    account_code: '',
-    key_id: '',
-    org_id: '',
-    secret_key: '',
-  });
-  const createFormSetting = computed<PFormProps<TestAdAccount>>(() => ({
-    rules: {
-      account_code: [{ required: true, message: '请选择Test账户', trigger: 'change' }],
-      org_id: [{ required: true, message: '请选择授权组织', trigger: 'change' }],
-      secret_key: [{ required: true, message: '请输入Secret Key', trigger: 'change' }],
-      key_id: [{ required: true, message: '请输入Key ID', trigger: 'change' }],
+import { ref, computed } from 'vue';
+
+const formData = ref({
+  name: '',
+  isActive: false,
+});
+
+const formSetting = computed(() => ({
+  items: [
+    {
+      field: 'isActive',
+      title: '状态',
+      span: 24,
+      slots: {
+        default: ({ data }) => (
+          <a-switch
+            v-model:checked={data.isActive}
+            checkedChildren="启用"
+            unCheckedChildren="禁用"
+          />
+        ),
+      },
     },
+  ],
+}));
+</script>
+```
+
+### PFormGroup
+
+动态表单组组件，用于管理多个表单实例，支持添加/删除功能。
+
+#### 属性
+
+| 属性 | 类型 | 说明 | 默认值 |
+| --- | --- | --- | --- |
+| v-model | `Array<T & { __index: number }>` | 表单组数据数组 | `[]` |
+| getFormSetting | `(data: T) => PFormProps<T>` | 获取表单配置的函数 | - |
+| title | `string` | 组标题 | - |
+| tabLabel | `string` | 自定义标签页标签模板 | - |
+| editAble | `boolean` | 标签页是否可编辑 | `true` |
+| showAdd | `boolean` | 显示添加按钮 | `true` |
+| lazyErrorMark | `boolean` | 延迟错误标记 | `false` |
+| forceRender | `boolean` | 强制渲染所有标签页 | `false` |
+| keepSerial | `boolean` | 保持连续编号 | `false` |
+| loading | `boolean` | 加载状态 | `false` |
+| max | `number` | 最大项目数量 | `Infinity` |
+| itemMenus | `GroupMenuItem[]` | 自定义菜单项 | 默认复制/删除 |
+| createItem | `(opts: { list: T[] }) => Promise<T>` | 自定义项目创建器 | - |
+| menuHandler | `GroupMenuItemHandler<T>` | 自定义菜单处理器 | - |
+
+#### 暴露的方法
+
+| 方法 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| validateAll | 验证所有表单实例 | - | `Promise<void>` |
+| validate | 验证特定表单实例 | `__index: number` | `Promise<void>` |
+| setActiveKey | 设置活动标签页 | `key: number` | `void` |
+
+#### 基础示例
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { PFormGroupProps } from '@vue-ui-kit/ant';
+
+interface Project {
+  __index: number;
+  name: string;
+  startDate: string;
+  endDate: string;
+  budget?: number;
+}
+
+const projects = ref<Project[]>([
+  {
+    __index: 0,
+    name: '项目A',
+    startDate: '',
+    endDate: '',
+    budget: undefined,
+  }
+]);
+
+const groupSetting = computed<PFormGroupProps<Project>>(() => ({
+  title: '项目管理',
+  showAdd: true,
+  max: 10,
+  getFormSetting: (data) => ({
     items: [
       {
-        title: '渠道',
+        field: 'name',
+        title: '项目名称',
         span: 24,
+        rule: [{ required: true, message: '请输入项目名称' }],
         itemRender: {
-          name: 'readonly',
-          props: {
-            getText: () => 'Test',
-          },
+          name: '$input',
+          props: { placeholder: '请输入项目名称' },
         },
       },
       {
-        field: 'account_code',
-        title: '账户',
-        span: 24,
+        field: 'startDate',
+        title: '开始日期',
+        span: 12,
+        rule: [{ required: true, message: '请选择开始日期' }],
         itemRender: {
-          name: '$select',
-          props: {
-            options: [
-              { label: 'Test账户1', value: '1' },
-              { label: 'Test账户2', value: '2' },
-            ],
-          },
-          events: {
-            change: ({ data }) => {
-              data.org_id = '';
-            },
-          },
-        },
-        tooltipConfig: {
-          title: '账号是指登录Test后台的邮箱',
+          name: '$date',
+          props: { placeholder: '请选择开始日期' },
         },
       },
       {
-        field: 'org_id',
-        title: '授权组织',
-        span: 24,
-        slots: {
-          default: ({ data }) => <my-custom-input v-model={data.org_id}></my-custom-input>,
-        },
-        tooltipConfig: {
-          title: '对应账号下的组织名称、组织ID、组织核心ID（Org Core ID）',
-        },
-      },
-      {
-        field: 'secret_key',
-        title: 'Secret Key',
-        span: 24,
+        field: 'endDate',
+        title: '结束日期',
+        span: 12,
+        rule: [{ required: true, message: '请选择结束日期' }],
         itemRender: {
-          name: '$input',
-        },
-        tooltipConfig: {
-          title: '我是tooltip',
+          name: '$date',
+          props: { placeholder: '请选择结束日期' },
         },
       },
       {
-        field: 'key_id',
-        title: 'Key ID',
+        field: 'budget',
+        title: '预算',
         span: 24,
         itemRender: {
-          name: '$input',
-        },
-        tooltipConfig: {
-          title: '我是tooltip',
+          name: '$number',
+          props: {
+            min: 0,
+            placeholder: '请输入预算',
+            formatter: (value) => `￥ ${value}`.replace(/\B(?=(\d{3})+(?!\d))/g, ','),
+            parser: (value) => value.replace(/￥\s?|(,*)/g, ''),
+          },
         },
       },
     ],
-  }));
+  }),
+}));
+
+const handleSave = async () => {
+  try {
+    await groupRef.value?.validateAll();
+    console.log('所有项目已保存:', projects.value);
+  } catch (error) {
+    console.error('验证失败:', error);
+  }
+};
+
+const groupRef = ref();
 </script>
+
 <template>
-  <p-form ref="cf" :data="createFormData" v-bind="createFormSetting" />
+  <div>
+    <p-form-group 
+      ref="groupRef"
+      v-model="projects"
+      v-bind="groupSetting"
+    />
+    <a-button type="primary" @click="handleSave">
+      保存所有项目
+    </a-button>
+  </div>
 </template>
 ```
 
-### PGrid
-
-高级表格组件，内置数据管理和工具栏功能。
-
-#### 属性
-
-| 属性          | 类型                 | 说明           | 默认值  |
-| ------------- | -------------------- | -------------- | ------- |
-| rowKey        | `string`             | 唯一标识字段   | 'id'    |
-| columns       | `ColumnProps[]`      | 表格列配置     | -       |
-| formConfig    | `PFormProps`         | 搜索表单配置   | -       |
-| toolbarConfig | `ToolbarConfig`      | 工具栏按钮配置 | -       |
-| pageConfig    | `PageConfig`         | 分页配置       | -       |
-| proxyConfig   | `ProxyConfig`        | 数据获取配置   | -       |
-| selectConfig  | `SelectConfig`       | 行选择配置     | -       |
-| scrollMode    | `'outer' \| 'inner'` | 滚动模式       | 'outer' |
-| fitHeight     | `number`             | 自适应高度调整 | -       |
-
-#### 示例
+#### 自定义菜单示例
 
 ```vue
 <script setup lang="ts">
-  import { ColumnProps, getButtonResponsive, labelColDict, PGridProps } from '@vue-ui-kit/ant';
-  import { computed } from 'vue';
-  import { hasAuth } from '...somewhere';
-  import { getChannelPage, deleteChannel, deleteChannels } from '...somewhere';
-  import type { Channel, ChannelParam } from '...somewhere';
-
-  const gridSetting = computed<PGridProps<Channel, ChannelParam>>(() => ({
-    selectConfig: {
-      multiple: true,
-    },
-    toolbarConfig: {
-      buttons: [
-        {
-          code: 'multiDelete',
-          content: t('批量删除'),
-          type: 'danger',
-        },
-      ],
-    },
-    columns: [
-      {
-        field: 'id',
-        title: 'ID',
-        width: 110,
-      },
-      {
-        field: 'name',
-        title: '渠道名称',
-        width: 140,
-      },
-      {
-        field: 'short_name',
-        title: '简称',
-        width: 140,
-      },
-      {
-        field: 'operator',
-        title: '操作人',
-        width: 120,
-      },
-      {
-        field: 'update_time',
-        title: '最近修改时间',
-        width: 180,
-      },
-      ...(hasAuth('common_channel_admin')
-        ? ([
-            {
-              title: '操作',
-              fixed: 'right',
-              width: 160,
-              cellRender: {
-                name: 'ButtonTree',
-                children: [
-                  {
-                    content: '编辑',
-                    type: 'link',
-                    clickEvt: ({ row }: { row: Channel }) => doEdit(row),
-                  },
-                  {
-                    content: '删除',
-                    type: 'link',
-                    danger: true,
-                    clickEvt: ({ row }: { row: Channel }) => confirmDelete(row),
-                  },
-                ],
-              },
-            },
-          ] as ColumnProps<Channel>[])
-        : []),
-    ],
-    formConfig: {
-      items: [
-        {
-          field: 'name',
-          title: '渠道名称',
-          labelCol: labelColDict[4],
-          itemRender: {
-            name: '$input',
-            props: {
-              placeholder: '请输入广告渠道名称',
-            },
-          },
-        },
-        {
-          col: getButtonResponsive(1),
-          align: 'right',
-          itemRender: {
-            name: '$buttons',
-            children: [
-              {
-                props: {
-                  content: '查询',
-                  htmlType: 'submit',
-                  type: 'primary',
-                },
-              },
-              {
-                props: {
-                  content: '重置',
-                  htmlType: 'reset',
-                },
-              },
-            ],
-          },
-        },
-      ],
-    },
-    pageConfig: {
-      pageSize: 10,
-    },
-    proxyConfig: {
-      response: {
-        total: 'total',
-        result: 'list',
-      },
-      ajax: {
-        query: ({ form, page }) =>
-          getChannelPage({
-            ...form,
-            ...page,
-          } as ChannelParam),
-        multiDelete: deleteChannels,
-      },
+import { ref, computed } from 'vue';
+
+const projects = ref([]);
+
+const groupSetting = computed(() => ({
+  title: '高级项目管理',
+  itemMenus: [
+    { content: '复制', code: 'copy' },
+    { content: '删除', code: 'delete' },
+    { content: '导出', code: 'export' },
+    { 
+      content: '归档', 
+      code: 'archive',
+      visibleMethod: ({ data }) => data.status !== 'archived'
     },
-  }));
+  ],
+  createItem: async ({ list }) => {
+    return {
+      name: `项目 ${list.length + 1}`,
+      status: 'active',
+      startDate: new Date().toISOString().split('T')[0],
+    };
+  },
+  menuHandler: ({ code, data, index }) => {
+    switch (code) {
+      case 'export':
+        exportProject(data);
+        break;
+      case 'archive':
+        archiveProject(data, index);
+        break;
+    }
+  },
+  getFormSetting: (data) => ({
+    // ... 表单配置
+  }),
+}));
 </script>
-<template>
-  <p-grid ref="gridEl" v-bind="gridSetting" />
-</template>
 ```
 
-### PFormGroup
+## 工具函数
 
-表单分组组件，用于将表单字段组织成可折叠的部分。
+### labelColDict
 
-#### 属性
+为不同文本长度预定义的标签列配置：
 
-| 属性           | 类型                   | 说明               |
-| -------------- | ---------------------- | ------------------ |
-| getFormSetting | `(data) => PFormProps` | 获取表单设置的函数 |
-| source         | `object`               | 表单数据源         |
+```ts
+import { labelColDict } from '@vue-ui-kit/ant';
+
+// 在表单项中使用
+{
+  field: 'shortField',
+  title: '姓名', // 2个字符
+  labelCol: labelColDict[2],
+}
+
+{
+  field: 'longerField', 
+  title: '项目描述', // 4+个字符
+  labelCol: labelColDict[4],
+}
+```
 
-#### 示例
+### 自定义渲染器
 
-```vue
-/*get-form-setting 本质就是生成内部form的computed属性的方法*/
-<template>
-  <p-form-group
-    :source="formData"
-    :get-form-setting="
-      (data) => ({
-        items: [
-          {
-            field: 'group1',
-            title: '分组1',
-            itemsRender: {
-              name: '$input',
-            },
-          },
-        ],
-      })
-    "
-  />
-</template>
+注册自定义表单字段渲染器：
+
+```tsx
+import UIKit from '@vue-ui-kit/ant';
+import { Switch } from 'ant-design-vue';
+
+UIKit.addRender('$switch', {
+  renderItemContent(
+    { props = {}, events = {} },
+    { data, field }
+  ) {
+    return (
+      <Switch
+        v-model:checked={data[field]}
+        {...props}
+        onChange={(...args) => {
+          events.change?.({ data, field }, ...args);
+        }}
+      />
+    );
+  },
+});
 ```
 
-### PromisePicker
+### 自定义格式化器
 
-支持异步数据的选择器组件。
+为 PGrid 注册自定义单元格格式化器：
 
-#### 属性
+```ts
+UIKit.addFormatter({
+  currency: ({ cellValue }) => `￥${cellValue?.toLocaleString() || '0'}`,
+  percentage: ({ cellValue }) => `${(cellValue * 100).toFixed(2)}%`,
+});
+```
 
-| 属性        | 类型               | 说明       |
-| ----------- | ------------------ | ---------- |
-| gridSetting | `PGridProps`       | 表格配置   |
-| title       | `string`           | 模态框标题 |
-| width       | `string \| number` | 模态框宽度 |
+## 常见问题
 
-#### 示例
+### 1. 使用 computed + v-bind 生成动态表格+表单时，表单选项更新导致表格重新渲染，如何解决？
+
+答案：将 formConfig 分离为另一个计算属性
 
 ```vue
-<script setup lang="ts">
-  import { ref } from 'vue';
-  import { PromisePickerInstance } from '@vue-ui-kit/ant';
-  import { Asset } from '...somewhere';
-  import { fetchUsers } from '...somewhere';
-
-  const pickerEl = ref<PromisePickerInstance<Asset>>();
-  const test = () => {
-    pickerEl.value!.pick().then(({ row }) => {
-      console.log(row);
-    });
-  };
-</script>
-<template>
-  <promise-picker
-    ref="pickerEl"
-    title="选择用户"
-    :grid-setting="{
-      columns: [
-        { title: '姓名', field: 'name' },
-        { title: '邮箱', field: 'email' },
-      ],
-      proxyConfig: {
-        ajax: {
-          query: fetchUsers,
-        },
-      },
-    }"
-  />
-</template>
+<p-grid v-bind="gridSetting" :form-config="computedFormConfig" />
 ```
 
-## Q&A
+### 2. 表格 ajax 目前只支持 multiDelete 和表格数据获取吗？
+
+答案：编辑详情在大多数情况下无法与表格一一对应，所以没有开发意义。多行删除需要配合使用：
 
-### 1. 使用computed +v-bind生成动态表格+表单时，表单内选项值更新，导致表格重新渲染，怎么办？
+```ts
+selectConfig: {
+  multiple: true,
+},
+toolbarConfig: {
+  buttons: {
+    code: "multipleDelete"
+  }
+}
+```
 
-答： 将formConfig 剥离出来写另外一个computed <p-grid v-bind="gridSetting" :form-config="computedFormConfig" />
+### 3. 为什么推荐 computed 方式？
 
-### 2. 目前表格ajax只支持了multiDelete和表格数据获取？
+答案：它简化了所有动态逻辑。对于复杂场景，您可以尝试使用 reactive 并自己维护，但在大多数情况下，computed 更方便。
 
-答： 编辑详情大部分情况下都和表格无法一一对应，所以没有开发意义。多行删除需要和selectConfig: { multiple: true, }, toolbarConfig》buttons>code:"multipleDelete" 一起使用
+## TypeScript 支持
+
+该库完全使用 TypeScript 编写，并提供全面的类型定义：
+
+```ts
+import type { 
+  PFormProps, 
+  PFormItemProps,
+  PFormGroupProps,
+  PGridProps,
+  ColumnProps 
+} from '@vue-ui-kit/ant';
+```
 
-### 3. 为什么推荐computed写法？
+## 许可证
 
-答： 简化所有动态逻辑 仅此而已，遇到复杂问题可以自己尝试reactive 然后去维护他 但大部分情况computed好用些
+MIT