jianghu-ui 1.0.1

package/src/components/JhFormFields/JhFormFields.md

@@ -0,0 +1,647 @@
+# JhFormFields - 表单字段集组件
+
+JhFormFields 是基于 Ant Design ProComponents FieldSet 设计的表单字段集组件,支持字段依赖、动态联动等高级特性。可以独立使用,也可以在 JhForm 中组合使用。
+
+## ✨ 特性
+
+- 🔗 **字段依赖** - 类似 ProFormDependency,支持字段间的依赖关系
+- 🎯 **动态联动** - 字段的显示/隐藏、启用/禁用可根据其他字段值动态变化
+- 📦 **字段分组** - 支持字段分组展示,提高表单可读性
+- 🎨 **多种布局** - 支持 horizontal、vertical、inline 三种布局模式
+- 📐 **响应式** - 支持响应式栅格布局
+- 💡 **提示信息** - 支持 title、description、tooltip 等多种提示方式
+- 🎭 **只读模式** - 支持只读展示
+- 🔧 **灵活配置** - 支持边框样式、紧凑模式等多种配置
+- 🧩 **组合使用** - 可在 JhForm 中组合多个 JhFormFields
+
+## 📦 安装
+
+```javascript
+import JhFormFields from '@/components/JhFormFields/JhFormFields.vue';
+```
+
+## 🔨 基础用法
+
+### 简单示例
+
+```vue
+<template>
+  <JhFormFields
+    v-model="formData"
+    :fields="fields"
+    title="基本信息"
+    description="请填写您的基本信息"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      formData: {
+        username: '',
+        email: '',
+      },
+      fields: [
+        {
+          key: 'username',
+          label: '用户名',
+          type: 'text',
+          placeholder: '请输入用户名',
+          required: true,
+        },
+        {
+          key: 'email',
+          label: '邮箱',
+          type: 'text',
+          placeholder: '请输入邮箱',
+          rules: 'email',
+        },
+      ],
+    };
+  },
+};
+</script>
+```
+
+## 📋 API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| value (v-model) | 表单数据对象 | `Object` | `{}` |
+| fields | 字段配置数组 | `Array<FieldConfig>` | `[]` |
+| title | 标题 | `String` | `''` |
+| description | 描述信息 | `String` | `''` |
+| tooltip | 提示信息 | `String` | `''` |
+| layout | 布局模式 | `'horizontal' \| 'vertical' \| 'inline'` | `'vertical'` |
+| showLabels | 是否显示标签 | `Boolean` | `true` |
+| labelWidth | 标签宽度(horizontal 布局) | `Number \| String` | `'auto'` |
+| labelAlign | 标签对齐方式 | `'left' \| 'right' \| 'center'` | `'right'` |
+| showRequiredMark | 是否显示必填标记 | `Boolean` | `true` |
+| readonly | 只读模式 | `Boolean` | `false` |
+| disabled | 禁用模式 | `Boolean` | `false` |
+| defaultDense | 默认紧凑模式 | `Boolean` | `true` |
+| defaultFilled | 默认填充样式 | `Boolean` | `true` |
+| defaultOutlined | 默认轮廓样式 | `Boolean` | `false` |
+| defaultColsMd | 默认列宽(md 断点) | `Number` | `6` |
+| hideDetails | 隐藏详情信息 | `Boolean \| String` | `false` |
+| dense | 紧凑模式 | `Boolean` | `false` |
+| bordered | 显示边框 | `Boolean` | `false` |
+| dependencies | 依赖字段数组 | `Array<String>` | `[]` |
+| rowProps | 传递给内部 `v-row` 的属性 | `Object` | `{}` |
+
+### FieldConfig 字段配置
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| key | 字段唯一标识 | `String` | - |
+| label | 字段标签 | `String` | - |
+| type | 字段类型 | `String` | `'text'` |
+| placeholder | 占位符 | `String` | - |
+| required | 是否必填 | `Boolean` | `false` |
+| rules | 验证规则 | `Array \| String` | - |
+| defaultValue | 默认值 | `Any` | - |
+| cols | 响应式列宽配置 | `Number \| Object` | - |
+| visible | 是否可见 | `Boolean \| Function` | `true` |
+| disabled | 是否禁用 | `Boolean \| Function` | `false` |
+| readonly | 是否只读 | `Boolean \| Function` | `false` |
+| tooltip | 提示信息 | `String` | - |
+| extra | 额外提示信息 | `String` | - |
+| dependencies | 依赖字段数组 | `Array<String>` | - |
+| onDependencyChange | 依赖变化回调 | `Function` | - |
+| options | 选项数据 | `Array \| Function` | - |
+| layout | 字段布局(覆盖全局) | `String` | - |
+| labelWidth | 标签宽度(覆盖全局) | `Number \| String` | - |
+| labelAlign | 标签对齐(覆盖全局) | `String` | - |
+
+### 字段类型 (type)
+
+- **text** - 文本输入框
+- **textarea** - 文本域
+- **number** - 数字输入框
+- **select** - 下拉选择框
+- **autocomplete** - 自动完成
+- **date** - 日期选择器
+- **time** - 时间选择器
+- **color** - 颜色选择器
+- **slider** - 数值滑块
+- **range-slider** - 区间滑块
+- **switch** - 开关
+- **checkbox** - 复选框
+- **radio** - 单选按钮组
+- **slot** - 自定义插槽
+- **group** - 分组标题
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+|--------|------|----------|
+| input | 值变化(v-model) | `(values: Object)` |
+| field-input | 字段输入 | `{ key, value, values }` |
+| field-change | 字段改变 | `{ key, value, values }` |
+| field-blur | 字段失焦 | `{ key, value, values }` |
+| dependency-change | 依赖字段变化 | `{ key, value, oldValue, values }` |
+| field-dependency-change | 字段依赖变化 | `{ field, dependency, value, oldValue, values }` |
+| reset | 重置 | `(values: Object)` |
+
+### Methods
+
+| 方法名 | 说明 | 参数 | 返回值 |
+|--------|------|------|--------|
+| getValues | 获取所有字段值 | - | `Object` |
+| setFieldsValue | 设置多个字段值 | `(values: Object)` | - |
+| setFieldValue | 设置单个字段值 | `(key: String, value: Any)` | - |
+| resetFields | 重置所有字段 | - | - |
+
+### Slots
+
+| 插槽名 | 说明 | 参数 |
+|--------|------|------|
+| title | 自定义标题 | - |
+| footer | 底部内容 | `{ values }` |
+| field-{key} | 自定义字段(type='slot') | `{ field, value, values, updateField }` |
+
+## 🎨 拓展字段类型示例
+
+```js
+fields: [
+  {
+    key: 'themeColor',
+    label: '主题色',
+    type: 'color',
+    defaultValue: '#4caf50',
+    pickerProps: { mode: 'hexa' }, // 透传到 v-color-picker
+  },
+  {
+    key: 'opacity',
+    label: '透明度',
+    type: 'slider',
+    min: 0,
+    max: 100,
+    step: 5,
+    thumbLabel: true,
+  },
+  {
+    key: 'priceRange',
+    label: '价格区间',
+    type: 'range-slider',
+    min: 0,
+    max: 1000,
+    step: 10,
+    defaultValue: [100, 600],
+  },
+];
+```
+
+> 📌 `type='color'` 会自动在文本框内显示颜色块，可用 `pickerProps` 调整 `v-color-picker`。滑块类字段支持 `min/max/step/thumbLabel/ticks` 等常用参数，也可通过 `field.props` 继续透传到对应 Vuetify 组件。
+
+## 🎯 核心特性详解
+
+### 1. 字段依赖 (ProFormDependency)
+
+字段依赖是 JhFormFields 的核心特性,类似于 Ant Design ProComponents 的 ProFormDependency。
+
+#### 基础依赖
+
+```javascript
+fields: [
+  {
+    key: 'userType',
+    label: '用户类型',
+    type: 'radio',
+    options: [
+      { text: '个人用户', value: 'personal' },
+      { text: '企业用户', value: 'company' },
+    ],
+  },
+  {
+    key: 'personalName',
+    label: '真实姓名',
+    type: 'text',
+    // 根据 userType 动态显示
+    visible: (values) => values.userType === 'personal',
+    dependencies: ['userType'],
+  },
+  {
+    key: 'companyName',
+    label: '公司名称',
+    type: 'text',
+    visible: (values) => values.userType === 'company',
+    dependencies: ['userType'],
+  },
+]
+```
+
+#### 多字段依赖
+
+```javascript
+{
+  key: 'discountAmount',
+  label: '优惠金额',
+  type: 'number',
+  // 依赖多个字段
+  visible: (values) => values.hasDiscount && values.discountType === 'fixed',
+  dependencies: ['hasDiscount', 'discountType'],
+}
+```
+
+#### 动态选项
+
+```javascript
+{
+  key: 'province',
+  label: '省份',
+  type: 'select',
+  // 根据国家动态生成省份选项
+  options: (values) => {
+    const provinceMap = {
+      china: [
+        { text: '北京', value: 'beijing' },
+        { text: '上海', value: 'shanghai' },
+      ],
+      usa: [
+        { text: '加利福尼亚', value: 'california' },
+        { text: '纽约', value: 'newyork' },
+      ],
+    };
+    return provinceMap[values.country] || [];
+  },
+  dependencies: ['country'],
+}
+```
+
+#### 动态禁用
+
+```javascript
+{
+  key: 'username',
+  label: '用户名',
+  type: 'text',
+  // 根据条件动态禁用
+  disabled: (values) => !values.agreeTerms,
+  dependencies: ['agreeTerms'],
+}
+```
+
+### 2. 依赖变化回调
+
+```javascript
+{
+  key: 'province',
+  label: '省份',
+  type: 'select',
+  dependencies: ['country'],
+  // 当依赖字段变化时触发
+  onDependencyChange: (depKey, newVal, oldVal, values) => {
+    console.log(`${depKey} 从 ${oldVal} 变为 ${newVal}`);
+    // 可以在这里执行额外的逻辑
+  },
+}
+```
+
+### 3. 全局依赖监听
+
+```vue
+<JhFormFields
+  v-model="formData"
+  :fields="fields"
+  :dependencies="['country', 'userType']"
+  @dependency-change="handleDependencyChange"
+/>
+```
+
+```javascript
+methods: {
+  handleDependencyChange({ key, value, oldValue, values }) {
+    console.log(`依赖字段 ${key} 变化:`, value);
+    // 执行全局依赖逻辑
+  },
+}
+```
+
+## 🎨 使用示例
+
+### 1. 基础用法
+
+```vue
+<JhFormFields
+  v-model="formData"
+  :fields="fields"
+  title="基本信息"
+  description="请填写您的基本信息"
+/>
+```
+
+### 2. 水平布局
+
+```vue
+<JhFormFields
+  v-model="formData"
+  :fields="fields"
+  layout="horizontal"
+  :labelWidth="100"
+  labelAlign="right"
+  :defaultColsMd="12"
+/>
+```
+
+### 3. 行内布局(搜索表单)
+
+```vue
+<JhFormFields
+  v-model="formData"
+  :fields="searchFields"
+  layout="inline"
+>
+  <template #footer>
+    <v-btn color="primary">搜索</v-btn>
+    <v-btn text>重置</v-btn>
+  </template>
+</JhFormFields>
+```
+
+### 4. 字段分组
+
+```javascript
+fields: [
+  { type: 'group', title: '基本信息' },
+  { key: 'username', label: '用户名', type: 'text' },
+  { key: 'email', label: '邮箱', type: 'text' },
+  
+  { type: 'group', title: '联系方式', divider: true, description: '请填写您的联系方式' },
+  { key: 'phone', label: '手机号', type: 'text' },
+  { key: 'address', label: '地址', type: 'textarea', cols: { md: 12 } },
+]
+```
+
+### 5. 带边框样式
+
+```vue
+<JhFormFields
+  v-model="formData"
+  :fields="fields"
+  title="基本信息"
+  bordered
+/>
+```
+
+### 6. 只读模式
+
+```vue
+<JhFormFields
+  v-model="formData"
+  :fields="fields"
+  title="用户详情"
+  readonly
+/>
+```
+
+### 7. 自定义字段插槽
+
+```vue
+<JhFormFields v-model="formData" :fields="fields">
+  <template #field-rating="{ value, updateField }">
+    <v-rating
+      :value="value"
+      @input="updateField('rating', $event)"
+      color="warning"
+    />
+  </template>
+  
+  <template #field-color="{ value, updateField }">
+    <v-color-picker
+      :value="value"
+      @input="updateField('color', $event)"
+    />
+  </template>
+</JhFormFields>
+```
+
+```javascript
+fields: [
+  {
+    key: 'rating',
+    label: '评分',
+    type: 'slot',
+    defaultValue: 3,
+  },
+  {
+    key: 'color',
+    label: '颜色',
+    type: 'slot',
+    defaultValue: '#1976D2',
+  },
+]
+```
+
+### 8. 响应式布局
+
+```javascript
+fields: [
+  {
+    key: 'field1',
+    label: '字段1',
+    type: 'text',
+    cols: {
+      xs: 12,  // 手机端全宽
+      sm: 6,   // 平板端半宽
+      md: 4,   // 桌面端1/3宽
+      lg: 3,   // 大屏1/4宽
+    },
+  },
+]
+```
+
+## 🔧 在 JhForm 中使用
+
+JhFormFields 可以在 JhForm 中组合使用,实现更灵活的表单布局:
+
+```vue
+<template>
+  <v-form>
+    <!-- 基本信息字段集 -->
+    <JhFormFields
+      v-model="formData"
+      :fields="basicFields"
+      title="基本信息"
+      bordered
+    />
+    
+    <!-- 用户类型字段集 -->
+    <JhFormFields
+      v-model="formData"
+      :fields="typeFields"
+      title="用户类型"
+      bordered
+      class="mt-4"
+    />
+    
+    <!-- 联系方式字段集 -->
+    <JhFormFields
+      v-model="formData"
+      :fields="contactFields"
+      title="联系方式"
+      bordered
+      class="mt-4"
+    />
+    
+    <!-- 提交按钮 -->
+    <v-row class="mt-4">
+      <v-col cols="12" class="text-right">
+        <v-btn class="mr-2" @click="resetForm">重置</v-btn>
+        <v-btn color="primary" @click="submitForm">提交</v-btn>
+      </v-col>
+    </v-row>
+  </v-form>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      formData: {},
+      basicFields: [
+        { key: 'username', label: '用户名', type: 'text', required: true },
+        { key: 'email', label: '邮箱', type: 'text', rules: 'email' },
+      ],
+      typeFields: [
+        {
+          key: 'userType',
+          label: '用户类型',
+          type: 'radio',
+          options: [
+            { text: '个人用户', value: 'personal' },
+            { text: '企业用户', value: 'company' },
+          ],
+        },
+        {
+          key: 'personalName',
+          label: '真实姓名',
+          type: 'text',
+          visible: (values) => values.userType === 'personal',
+          dependencies: ['userType'],
+        },
+      ],
+      contactFields: [
+        { key: 'phone', label: '手机号', type: 'text', rules: 'phone' },
+        { key: 'address', label: '地址', type: 'textarea', cols: { md: 12 } },
+      ],
+    };
+  },
+  methods: {
+    submitForm() {
+      console.log('提交数据:', this.formData);
+    },
+    resetForm() {
+      this.formData = {};
+    },
+  },
+};
+</script>
+```
+
+## 💡 高级用法
+
+### 复杂联动示例
+
+```javascript
+fields: [
+  {
+    key: 'productType',
+    label: '商品类型',
+    type: 'radio',
+    options: [
+      { text: '实物商品', value: 'physical' },
+      { text: '虚拟商品', value: 'virtual' },
+      { text: '服务商品', value: 'service' },
+    ],
+  },
+  {
+    key: 'weight',
+    label: '重量(kg)',
+    type: 'number',
+    visible: (values) => values.productType === 'physical',
+    dependencies: ['productType'],
+  },
+  {
+    key: 'downloadUrl',
+    label: '下载链接',
+    type: 'text',
+    visible: (values) => values.productType === 'virtual',
+    dependencies: ['productType'],
+  },
+  {
+    key: 'serviceTime',
+    label: '服务时长(小时)',
+    type: 'number',
+    visible: (values) => values.productType === 'service',
+    dependencies: ['productType'],
+  },
+  { type: 'group', title: '优惠设置', divider: true },
+  {
+    key: 'hasDiscount',
+    label: '启用优惠',
+    type: 'checkbox',
+    checkboxLabel: '启用优惠价格',
+  },
+  {
+    key: 'discountType',
+    label: '优惠类型',
+    type: 'radio',
+    options: [
+      { text: '固定金额', value: 'fixed' },
+      { text: '百分比', value: 'percent' },
+    ],
+    visible: (values) => values.hasDiscount,
+    dependencies: ['hasDiscount'],
+  },
+  {
+    key: 'discountAmount',
+    label: '优惠金额',
+    type: 'number',
+    visible: (values) => values.hasDiscount && values.discountType === 'fixed',
+    dependencies: ['hasDiscount', 'discountType'],
+  },
+  {
+    key: 'discountPercent',
+    label: '优惠百分比',
+    type: 'number',
+    suffix: '%',
+    visible: (values) => values.hasDiscount && values.discountType === 'percent',
+    dependencies: ['hasDiscount', 'discountType'],
+  },
+]
+```
+
+## 🎯 最佳实践
+
+1. **合理使用字段依赖** - 使用 `dependencies` 数组明确声明字段间的依赖关系
+2. **避免循环依赖** - 确保字段依赖关系不形成循环
+3. **使用字段分组** - 将相关字段分组,提高表单可读性
+4. **动态选项优化** - 使用函数动态生成选项时,注意性能优化
+5. **边框样式** - 使用 `bordered` 属性区分不同的字段集
+6. **组合使用** - 在复杂表单中,使用多个 JhFormFields 组合
+7. **响应式设计** - 使用 `cols` 配置实现响应式布局
+8. **只读模式** - 详情页面使用只读模式展示数据
+
+## 🔗 与 ProComponents 的对应关系
+
+| ProComponents | JhFormFields | 说明 |
+|---------------|--------------|------|
+| ProFormFieldSet | JhFormFields | 字段集组件 |
+| ProFormDependency | dependencies + visible/disabled | 字段依赖 |
+| fieldProps | props | 字段属性 |
+| dependencies | dependencies | 依赖字段数组 |
+| transform | - | 暂不支持 |
+
+## 📚 相关组件
+
+- [JhForm](../JhForm) - 高级表单组件
+- [JhFormList](../JhFormList) - 动态表单列表
+- [JhTable](../JhTable) - 高级表格
+
+## 📄 License
+
+MIT