jianghu-ui 1.0.6 → 1.0.7

package/src/components/JhStepsForm/JhStepsForm.md

@@ -1,666 +0,0 @@
-# JhStepsForm - 分步表单
-
-基于 Ant Design ProComponents StepsForm 设计的分步表单组件，用于将复杂表单拆分为多个步骤，提升用户体验。
-
-## 特性
-
-- 📝 **多步骤表单** - 将复杂表单拆分为多个步骤，降低用户填写负担
-- 🎯 **步骤导航** - 支持步骤点击跳转、上一步/下一步操作
-- ✅ **表单验证** - 每个步骤支持独立验证，确保数据准确性
-- 🎨 **灵活布局** - 支持水平/垂直布局，适应不同场景
-- 🔧 **高度可定制** - 支持自定义步骤内容、按钮、样式等
-- 📦 **表单实例管理** - 提供 formMapRef 访问所有步骤表单实例
-- 🎭 **插槽支持** - 支持自定义步骤内容和提交按钮渲染
-
-## 基础用法
-
-```vue
-<template>
-  <jh-steps-form
-    :steps="steps"
-    @finish="handleFinish"
-  >
-    <template #step-confirm="{ formData }">
-      <div>确认信息...</div>
-    </template>
-  </jh-steps-form>
-</template>
-
-<script>
-export default {
-  data() {
-    return {
-      steps: [
-        {
-          title: '基本信息',
-          subTitle: '填写基本信息',
-          fields: [
-            {
-              name: 'username',
-              label: '用户名',
-              type: 'text',
-              required: true,
-            },
-            {
-              name: 'email',
-              label: '邮箱',
-              type: 'email',
-              required: true,
-            },
-          ],
-        },
-        {
-          title: '详细信息',
-          fields: [
-            {
-              name: 'address',
-              label: '地址',
-              type: 'text',
-            },
-          ],
-        },
-        {
-          title: '确认信息',
-          slot: 'step-confirm',
-        },
-      ],
-    };
-  },
-  methods: {
-    handleFinish(data) {
-      console.log('提交数据:', data);
-    },
-  },
-};
-</script>
-```
-
-## API
-
-### Props
-
-| 参数 | 说明 | 类型 | 默认值 |
-|------|------|------|--------|
-| steps | 步骤配置数组 | `Array<StepConfig>` | `[]` |
-| initialStep | 初始步骤索引 (从0开始) | `number` | `0` |
-| value / v-model | 当前激活步骤 (支持 v-model) | `number` | `null` |
-| current | 当前步骤 (支持 .sync) | `number` | `null` |
-| editable | 是否可编辑已完成的步骤 | `boolean` | `false` |
-| vertical | 是否垂直布局 | `boolean` | `false` |
-| altLabels | 是否替代标签模式 | `boolean` | `false` |
-| outlined | 输入框样式 | `boolean` | `true` |
-| dense | 紧凑模式 | `boolean` | `false` |
-| submitting | 提交中状态 | `boolean` | `false` |
-| previousButtonText | 上一步按钮文本 | `string` | `'上一步'` |
-| nextButtonText | 下一步按钮文本 | `string` | `'下一步'` |
-| finishButtonText | 完成按钮文本 | `string` | `'完成'` |
-| validateStep | 步骤验证函数 | `Function` | `null` |
-| transformBeforeFinish | 数据转换函数(最终提交前) | `Function` | `null` |
-| onCurrentChange | 步骤变化回调 | `Function` | `null` |
-| onFormChange | 表单字段变化回调 | `Function` | `null` |
-| stepsProps | 传递给 v-stepper 的额外属性 | `object` | `{}` |
-| formProps | 传递给所有步骤表单的公共属性 | `object` | `{}` |
-| stepFormRender | 自定义步骤表单渲染 | `Function` | `null` |
-| submitter | 提交按钮配置 | `object \| boolean` | `null` |
-| containerStyle | 容器样式 | `object \| string` | `null` |
-
-### StepConfig
-
-步骤配置对象：
-
-```typescript
-interface StepConfig {
-  title: string;           // 步骤标题
-  subTitle?: string;       // 步骤副标题
-  slot?: string;           // 自定义插槽名称
-  fields?: Array<Field>;   // 表单字段配置 (使用 JhForm)
-}
-```
-
-### Submitter 配置
-
-```typescript
-interface Submitter {
-  render?: false | Function;      // false 隐藏按钮，Function 自定义渲染
-  showPrevious?: boolean;         // 是否显示上一步按钮
-  previousText?: string;          // 上一步按钮文本
-  previousButtonProps?: object;   // 上一步按钮属性
-  nextText?: string;              // 下一步按钮文本
-  nextButtonProps?: object;       // 下一步按钮属性
-  submitText?: string;            // 提交按钮文本
-  submitButtonProps?: object;     // 提交按钮属性
-}
-```
-
-### Events
-
-| 事件名 | 说明 | 回调参数 |
-|--------|------|----------|
-| finish | 完成所有步骤时触发 | `(formData: object)` |
-| change | 表单数据变化时触发 | `(formData: object)` |
-| step-change | 步骤变化时触发 | `({ current: number, step: StepConfig })` |
-| input | v-model 更新事件 | `(stepIndex: number)` |
-| update:current | .sync 更新事件 | `(stepIndex: number)` |
-
-### Slots
-
-| 插槽名 | 说明 | 参数 |
-|--------|------|------|
-| [step.slot] | 自定义步骤内容 | `{ step, index, formData }` |
-| submitter | 自定义提交按钮 | `{ step, index, onPrevious, onNext, onFinish, submitting, validating }` |
-| default | 默认步骤内容 | `{ step, index, formData }` |
-
-### Methods
-
-| 方法名 | 说明 | 参数 | 返回值 |
-|--------|------|------|--------|
-| goToStep | 跳转到指定步骤 | `(stepIndex: number)` | - |
-| reset | 重置表单 | - | - |
-| getFormData | 获取所有表单数据 | - | `object` |
-| setFormData | 设置表单数据 | `(data: object)` | - |
-| getFormMapRef | 获取表单实例映射 | - | `object` |
-| getStepFormRef | 获取指定步骤的表单实例 | `(stepIndex: number)` | `FormInstance \| null` |
-| validateAll | 验证所有步骤 | - | `Promise<boolean>` |
-
-## 使用示例
-
-### 基础分步表单
-
-```vue
-<jh-steps-form
-  :steps="steps"
-  @finish="handleFinish"
-/>
-```
-
-### 可编辑步骤
-
-允许用户点击已完成的步骤返回修改：
-
-```vue
-<jh-steps-form
-  :steps="steps"
-  editable
-  @finish="handleFinish"
-/>
-```
-
-### 垂直布局
-
-适用于侧边栏或窄屏场景：
-
-```vue
-<jh-steps-form
-  :steps="steps"
-  vertical
-  @finish="handleFinish"
-/>
-```
-
-### 自定义步骤内容
-
-使用插槽自定义某个步骤的内容：
-
-```vue
-<jh-steps-form :steps="steps" @finish="handleFinish">
-  <template #step-custom="{ formData }">
-    <v-card>
-      <v-card-title>自定义内容</v-card-title>
-      <v-card-text>
-        <!-- 自定义内容 -->
-      </v-card-text>
-    </v-card>
-  </template>
-</jh-steps-form>
-```
-
-### 自定义验证
-
-```vue
-<jh-steps-form
-  :steps="steps"
-  :validate-step="validateStep"
-  @finish="handleFinish"
-/>
-
-<script>
-export default {
-  methods: {
-    async validateStep({ step, stepIndex, formData }) {
-      // 自定义验证逻辑
-      if (stepIndex === 0) {
-        const username = formData.step0?.username;
-        if (username === 'admin') {
-          this.$message.error('用户名已存在');
-          return false;
-        }
-      }
-      return true;
-    },
-  },
-};
-</script>
-```
-
-### 数据转换
-
-在提交前转换数据格式：
-
-```vue
-<jh-steps-form
-  :steps="steps"
-  :transform-before-finish="transformData"
-  @finish="handleFinish"
-/>
-
-<script>
-export default {
-  methods: {
-    transformData(formData) {
-      // 合并所有步骤数据
-      return {
-        ...formData.step0,
-        ...formData.step1,
-        ...formData.step2,
-      };
-    },
-  },
-};
-</script>
-```
-
-### 自定义按钮
-
-```vue
-<jh-steps-form
-  :steps="steps"
-  :submitter="{
-    previousText: 'Back',
-    nextText: 'Continue',
-    submitText: 'Submit',
-    previousButtonProps: { color: 'secondary' },
-    nextButtonProps: { color: 'primary', large: true },
-  }"
-  @finish="handleFinish"
-/>
-```
-
-### 隐藏按钮
-
-```vue
-<jh-steps-form
-  :steps="steps"
-  :submitter="{ render: false }"
-  @finish="handleFinish"
-/>
-```
-
-### 使用 v-model 控制当前步骤
-
-```vue
-<template>
-  <div>
-    <v-btn @click="currentStep = 0">跳转到第一步</v-btn>
-    <jh-steps-form
-      v-model="currentStep"
-      :steps="steps"
-      @finish="handleFinish"
-    />
-  </div>
-</template>
-
-<script>
-export default {
-  data() {
-    return {
-      currentStep: 0,
-    };
-  },
-};
-</script>
-```
-
-### 访问表单实例
-
-```vue
-<template>
-  <div>
-    <jh-steps-form
-      ref="stepsForm"
-      :steps="steps"
-      @finish="handleFinish"
-    />
-    <v-btn @click="validateAllSteps">验证所有步骤</v-btn>
-  </div>
-</template>
-
-<script>
-export default {
-  methods: {
-    async validateAllSteps() {
-      const isValid = await this.$refs.stepsForm.validateAll();
-      console.log('所有步骤验证结果:', isValid);
-      
-      // 获取表单实例映射
-      const formMapRef = this.$refs.stepsForm.getFormMapRef();
-      console.log('表单实例:', formMapRef);
-      
-      // 获取指定步骤的表单实例
-      const step0Form = this.$refs.stepsForm.getStepFormRef(0);
-      if (step0Form) {
-        step0Form.validate();
-      }
-    },
-  },
-};
-</script>
-```
-
-### 监听步骤变化
-
-```vue
-<jh-steps-form
-  :steps="steps"
-  :on-current-change="handleStepChange"
-  @finish="handleFinish"
-/>
-
-<script>
-export default {
-  methods: {
-    handleStepChange(stepIndex) {
-      console.log('当前步骤:', stepIndex);
-      // 可以在这里做一些操作，比如埋点统计
-    },
-  },
-};
-</script>
-```
-
-### 监听表单字段变化
-
-```vue
-<jh-steps-form
-  :steps="steps"
-  :on-form-change="handleFormChange"
-  @finish="handleFinish"
-/>
-
-<script>
-export default {
-  methods: {
-    handleFormChange({ stepIndex, values, allValues }) {
-      console.log('步骤索引:', stepIndex);
-      console.log('当前步骤值:', values);
-      console.log('所有值:', allValues);
-    },
-  },
-};
-</script>
-```
-
-### 传递公共表单属性
-
-```vue
-<jh-steps-form
-  :steps="steps"
-  :form-props="{
-    outlined: true,
-    dense: true,
-    hideDetails: 'auto',
-  }"
-  @finish="handleFinish"
-/>
-```
-
-### 自定义容器样式
-
-```vue
-<jh-steps-form
-  :steps="steps"
-  :container-style="{
-    maxWidth: '800px',
-    margin: '0 auto',
-    padding: '24px',
-  }"
-  @finish="handleFinish"
-/>
-```
-
-## 完整示例：员工入职流程
-
-```vue
-<template>
-  <v-container>
-    <jh-steps-form
-      ref="employeeForm"
-      v-model="currentStep"
-      :steps="steps"
-      editable
-      :submitting="submitting"
-      :validate-step="validateStep"
-      :transform-before-finish="transformData"
-      :on-current-change="handleStepChange"
-      @finish="handleFinish"
-    >
-      <template #step-confirm="{ formData }">
-        <v-card outlined>
-          <v-card-title>请确认以下信息</v-card-title>
-          <v-card-text>
-            <v-simple-table>
-              <tbody>
-                <tr v-for="(value, key) in flattenData(formData)" :key="key">
-                  <td class="font-weight-bold">{{ key }}</td>
-                  <td>{{ value }}</td>
-                </tr>
-              </tbody>
-            </v-simple-table>
-          </v-card-text>
-        </v-card>
-      </template>
-    </jh-steps-form>
-  </v-container>
-</template>
-
-<script>
-export default {
-  data() {
-    return {
-      currentStep: 0,
-      submitting: false,
-      steps: [
-        {
-          title: '基本信息',
-          subTitle: '填写员工基本信息',
-          fields: [
-            {
-              name: 'name',
-              label: '姓名',
-              type: 'text',
-              required: true,
-              cols: 12,
-              md: 6,
-            },
-            {
-              name: 'email',
-              label: '邮箱',
-              type: 'email',
-              required: true,
-              cols: 12,
-              md: 6,
-            },
-            {
-              name: 'phone',
-              label: '手机号',
-              type: 'tel',
-              required: true,
-              cols: 12,
-              md: 6,
-            },
-          ],
-        },
-        {
-          title: '岗位信息',
-          subTitle: '设置员工岗位',
-          fields: [
-            {
-              name: 'department',
-              label: '部门',
-              type: 'select',
-              options: [
-                { text: '技术部', value: 'tech' },
-                { text: '产品部', value: 'product' },
-                { text: '市场部', value: 'marketing' },
-              ],
-              required: true,
-              cols: 12,
-              md: 6,
-            },
-            {
-              name: 'position',
-              label: '职位',
-              type: 'text',
-              required: true,
-              cols: 12,
-              md: 6,
-            },
-          ],
-        },
-        {
-          title: '确认信息',
-          subTitle: '请确认填写的信息',
-          slot: 'step-confirm',
-        },
-      ],
-    };
-  },
-  methods: {
-    async validateStep({ step, stepIndex, formData }) {
-      // 自定义验证逻辑
-      if (stepIndex === 0) {
-        const email = formData.step0?.email;
-        if (email && !email.includes('@company.com')) {
-          this.$message.warning('请使用公司邮箱');
-          return false;
-        }
-      }
-      return true;
-    },
-    
-    transformData(formData) {
-      // 合并所有步骤数据
-      return {
-        ...formData.step0,
-        ...formData.step1,
-      };
-    },
-    
-    handleStepChange(stepIndex) {
-      console.log('切换到步骤:', stepIndex);
-      // 埋点统计
-    },
-    
-    async handleFinish(data) {
-      this.submitting = true;
-      try {
-        // 提交数据到服务器
-        await this.$api.createEmployee(data);
-        this.$message.success('员工入职信息提交成功');
-        this.$refs.employeeForm.reset();
-      } catch (error) {
-        this.$message.error('提交失败: ' + error.message);
-      } finally {
-        this.submitting = false;
-      }
-    },
-    
-    flattenData(formData) {
-      const result = {};
-      Object.values(formData).forEach(stepData => {
-        Object.assign(result, stepData);
-      });
-      return result;
-    },
-  },
-};
-</script>
-```
-
-## 最佳实践
-
-### 1. 步骤数量
-
-- 建议 3-5 个步骤，不宜过多
-- 每个步骤的字段数量控制在 5-10 个
-
-### 2. 步骤命名
-
-- 使用清晰简洁的步骤标题
-- 提供副标题说明步骤目的
-
-### 3. 表单验证
-
-- 每个步骤都应该有必要的验证
-- 使用 `validateStep` 进行自定义验证
-- 在下一步前验证当前步骤
-
-### 4. 数据管理
-
-- 使用 `formData` 存储所有步骤数据
-- 使用 `transformBeforeFinish` 转换数据格式
-- 在最后一步展示确认信息
-
-### 5. 用户体验
-
-- 开启 `editable` 允许用户返回修改
-- 提供清晰的步骤指示
-- 在提交时显示 loading 状态
-
-## 注意事项
-
-1. **步骤索引从 0 开始**
-2. **表单数据按 `step${index}` 格式存储**
-3. **使用 `slot` 时需要在步骤配置中指定 `slot` 属性**
-4. **`validateStep` 返回 `false` 会阻止进入下一步**
-5. **`submitter.render = false` 会完全隐藏按钮区域**
-
-## 与 Ant Design ProComponents 的对应关系
-
-| ProComponents | JhStepsForm | 说明 |
-|---------------|-------------|------|
-| StepsForm | JhStepsForm | 主组件 |
-| StepForm | steps[].fields | 步骤配置 |
-| current | value / current | 当前步骤 |
-| onCurrentChange | onCurrentChange | 步骤变化回调 |
-| formMapRef | getFormMapRef() | 表单实例映射 |
-| stepsProps | stepsProps | Steps 属性 |
-| formProps | formProps | 表单公共属性 |
-| submitter | submitter | 提交按钮配置 |
-| onFinish | @finish | 完成事件 |
-
-## 更新日志
-
-### v1.1.0 (2024-11-09)
-
-**新增功能**
-- ✨ 新增 `formMapRef` 表单实例管理
-- ✨ 新增 `onCurrentChange` 步骤变化回调
-- ✨ 新增 `onFormChange` 表单字段变化回调
-- ✨ 新增 `stepsProps` 传递给 v-stepper 的属性
-- ✨ 新增 `formProps` 传递给所有表单的公共属性
-- ✨ 新增 `submitter` 提交按钮配置
-- ✨ 新增 `containerStyle` 容器样式配置
-- ✨ 新增 `current` prop 支持 .sync 修饰符
-- ✨ 新增 `getFormMapRef()` 方法
-- ✨ 新增 `getStepFormRef(index)` 方法
-- ✨ 新增 `validateAll()` 方法
-
-**优化改进**
-- 🎨 优化步骤切换逻辑，支持 v-model 和 .sync
-- 🎨 优化表单实例管理，自动维护 formMapRef
-- 🎨 优化按钮配置，支持更灵活的自定义
-- 📝 完善文档和示例
-
-### v1.0.0
-
-- 🎉 初始版本发布