@ebiz/designer-components 0.1.2 → 0.1.5

package/src/components/senior/EbizSForm/README.md

@@ -1,158 +1,158 @@
-# EbizSForm 高级表单组件
-
-EbizSForm是一个基于TDesign Form封装的高级表单组件，提供了丰富的表单功能，包括本地表单数据管理、表单验证、API提交和详情数据加载等。
-
-## 主要特性
-
-1. **本地表单数据管理**：通过`localFormData`管理表单数据，实现数据的双向绑定
-2. **详情接口支持**：通过`detailApiConfig`配置详情API，支持加载表单详情数据
-3. **API调用机制**：使用`dataService.fetch(params, apiConfig)`方式调用API，符合系统规范
-4. **表单验证**：支持完整的表单验证功能，并与API调用无缝衔接
-5. **丰富的方法支持**：提供`openForm`、`loadDetailData`、`setFormData`等丰富的方法
-
-## 基本用法
-
-```vue
-<template>
-  <EbizSForm 
-    ref="formRef" 
-    :data="formData" 
-    :rules="formRules" 
-    :api-config="apiConfig"
-    :detail-api-config="detailApiConfig"
-    @success="handleSuccess"
-    @error="handleError"
-    @detail-loaded="handleDetailLoaded"
-  >
-    <EbizSFormItem label="用户名" name="username" type="input" />
-    <EbizSFormItem label="密码" name="password" type="input" />
-  </EbizSForm>
-</template>
-
-<script setup>
-import { ref, reactive } from 'vue';
-import { EbizSForm, EbizSFormItem } from '@ebiz/designer-components';
-
-const formRef = ref(null);
-const formData = reactive({
-  username: '',
-  password: ''
-});
-
-const formRules = {
-  username: [
-    { required: true, message: '请输入用户名', trigger: 'blur' }
-  ],
-  password: [
-    { required: true, message: '请输入密码', trigger: 'blur' }
-  ]
-};
-
-// API配置
-const apiConfig = {
-  key: 'userSubmit',
-  apiId: 'user.submit',
-  apiType: '3'
-};
-
-// 详情API配置
-const detailApiConfig = {
-  key: 'userDetail',
-  apiId: 'user.detail',
-  apiType: '1'
-};
-
-// 加载详情数据
-const loadDetail = (id) => {
-  formRef.value.loadDetailData(id);
-};
-
-// 事件处理
-const handleSuccess = (response) => {
-  console.log('提交成功:', response);
-};
-
-const handleError = (error) => {
-  console.error('提交失败:', error);
-};
-
-const handleDetailLoaded = (data) => {
-  console.log('详情数据加载成功:', data);
-};
-</script>
-```
-
-## Props
-
-| 属性名             | 类型      | 默认值     | 说明                                |
-| ----------------- | --------- | --------- | ----------------------------------- |
-| data              | Object    | {}        | 表单数据对象                        |
-| labelAlign        | String    | 'right'   | 标签对齐方式：'left'/'right'/'top'  |
-| layout            | String    | 'vertical'| 表单布局方式：'vertical'/'inline'   |
-| labelWidth        | String    | '100px'   | 标签宽度                           |
-| rules             | Object    | {}        | 表单验证规则                        |
-| apiConfig         | Object    | null      | API配置，用于表单提交               |
-| detailApiConfig   | Object    | null      | 详情API配置，用于加载表单数据       |
-| resetOnSuccess    | Boolean   | false     | 提交成功后是否重置表单              |
-| showResultMessage | Boolean   | true      | 是否显示结果消息                    |
-
-## 事件
-
-| 事件名        | 说明                    | 参数                           |
-| ------------ | ----------------------- | ------------------------------ |
-| submit       | 表单提交时触发           | formData: 表单数据对象         |
-| success      | API调用成功时触发        | response: 成功响应数据         |
-| error        | API调用失败时触发        | error: 错误信息                |
-| reset        | 表单重置时触发           | context: 重置上下文            |
-| validate     | 表单验证时触发           | result: 验证结果               |
-| detail-loaded| 详情数据加载成功时触发    | data: 详情数据                 |
-| detail-error | 详情数据加载失败时触发    | error: 错误信息                |
-
-## 方法
-
-通过ref可以调用组件实例的以下方法：
-
-| 方法名          | 说明                     | 参数                           |
-| -------------- | ------------------------ | ------------------------------ |
-| submit         | 提交表单                  | 无                             |
-| reset          | 重置表单                  | 无                             |
-| validate       | 验证表单                  | 无                             |
-| validateFields | 验证指定字段              | fields: 字段名或字段名数组      |
-| clearValidate  | 清除验证结果              | fields: 字段名或字段名数组，可选 |
-| openForm       | 打开表单并设置参数        | params: 参数对象                |
-| loadDetailData | 加载详情数据              | id: 记录ID                     |
-| setFormData    | 设置表单数据              | data: 要设置的数据对象          |
-| getFormData    | 获取表单数据              | 无                             |
-| clearFormData  | 清空表单数据              | 无                             |
-
-## API配置对象说明
-
-apiConfig和detailApiConfig的格式如下：
-
-```javascript
-{
-  key: 'apiKey',        // API的键名
-  apiId: 'module.api',  // API的标识ID
-  apiType: '3'          // API类型，对应dataService中的类型
-}
-```
-
-apiType常用值：
-- '0': 列表查询
-- '1': 详情查询
-- '3': 数据新增
-- '5': 数据修改
-- '7': 数据删除
-
-## 与EbizSDialog组件的比较
-
-EbizSForm与EbizSDialog组件有相似的API调用和表单数据处理机制，两者都：
-
-1. 使用本地表单数据管理（localFormData）
-2. 支持详情数据加载（detailApiConfig）
-3. 采用相同的API调用方式（dataService.fetch）
-4. 不修改apiConfig对象
-
-选择使用哪个组件取决于具体的场景需求：
-- 如果需要在页面上直接显示表单，使用EbizSForm
+# EbizSForm 高级表单组件
+
+EbizSForm是一个基于TDesign Form封装的高级表单组件，提供了丰富的表单功能，包括本地表单数据管理、表单验证、API提交和详情数据加载等。
+
+## 主要特性
+
+1. **本地表单数据管理**：通过`localFormData`管理表单数据，实现数据的双向绑定
+2. **详情接口支持**：通过`detailApiConfig`配置详情API，支持加载表单详情数据
+3. **API调用机制**：使用`dataService.fetch(params, apiConfig)`方式调用API，符合系统规范
+4. **表单验证**：支持完整的表单验证功能，并与API调用无缝衔接
+5. **丰富的方法支持**：提供`openForm`、`loadDetailData`、`setFormData`等丰富的方法
+
+## 基本用法
+
+```vue
+<template>
+  <EbizSForm 
+    ref="formRef" 
+    :data="formData" 
+    :rules="formRules" 
+    :api-config="apiConfig"
+    :detail-api-config="detailApiConfig"
+    @success="handleSuccess"
+    @error="handleError"
+    @detail-loaded="handleDetailLoaded"
+  >
+    <EbizSFormItem label="用户名" name="username" type="input" />
+    <EbizSFormItem label="密码" name="password" type="input" />
+  </EbizSForm>
+</template>
+
+<script setup>
+import { ref, reactive } from 'vue';
+import { EbizSForm, EbizSFormItem } from '@ebiz/designer-components';
+
+const formRef = ref(null);
+const formData = reactive({
+  username: '',
+  password: ''
+});
+
+const formRules = {
+  username: [
+    { required: true, message: '请输入用户名', trigger: 'blur' }
+  ],
+  password: [
+    { required: true, message: '请输入密码', trigger: 'blur' }
+  ]
+};
+
+// API配置
+const apiConfig = {
+  key: 'userSubmit',
+  apiId: 'user.submit',
+  apiType: '3'
+};
+
+// 详情API配置
+const detailApiConfig = {
+  key: 'userDetail',
+  apiId: 'user.detail',
+  apiType: '1'
+};
+
+// 加载详情数据
+const loadDetail = (id) => {
+  formRef.value.loadDetailData(id);
+};
+
+// 事件处理
+const handleSuccess = (response) => {
+  console.log('提交成功:', response);
+};
+
+const handleError = (error) => {
+  console.error('提交失败:', error);
+};
+
+const handleDetailLoaded = (data) => {
+  console.log('详情数据加载成功:', data);
+};
+</script>
+```
+
+## Props
+
+| 属性名             | 类型      | 默认值     | 说明                                |
+| ----------------- | --------- | --------- | ----------------------------------- |
+| data              | Object    | {}        | 表单数据对象                        |
+| labelAlign        | String    | 'right'   | 标签对齐方式：'left'/'right'/'top'  |
+| layout            | String    | 'vertical'| 表单布局方式：'vertical'/'inline'   |
+| labelWidth        | String    | '100px'   | 标签宽度                           |
+| rules             | Object    | {}        | 表单验证规则                        |
+| apiConfig         | Object    | null      | API配置，用于表单提交               |
+| detailApiConfig   | Object    | null      | 详情API配置，用于加载表单数据       |
+| resetOnSuccess    | Boolean   | false     | 提交成功后是否重置表单              |
+| showResultMessage | Boolean   | true      | 是否显示结果消息                    |
+
+## 事件
+
+| 事件名        | 说明                    | 参数                           |
+| ------------ | ----------------------- | ------------------------------ |
+| submit       | 表单提交时触发           | formData: 表单数据对象         |
+| success      | API调用成功时触发        | response: 成功响应数据         |
+| error        | API调用失败时触发        | error: 错误信息                |
+| reset        | 表单重置时触发           | context: 重置上下文            |
+| validate     | 表单验证时触发           | result: 验证结果               |
+| detail-loaded| 详情数据加载成功时触发    | data: 详情数据                 |
+| detail-error | 详情数据加载失败时触发    | error: 错误信息                |
+
+## 方法
+
+通过ref可以调用组件实例的以下方法：
+
+| 方法名          | 说明                     | 参数                           |
+| -------------- | ------------------------ | ------------------------------ |
+| submit         | 提交表单                  | 无                             |
+| reset          | 重置表单                  | 无                             |
+| validate       | 验证表单                  | 无                             |
+| validateFields | 验证指定字段              | fields: 字段名或字段名数组      |
+| clearValidate  | 清除验证结果              | fields: 字段名或字段名数组，可选 |
+| openForm       | 打开表单并设置参数        | params: 参数对象                |
+| loadDetailData | 加载详情数据              | id: 记录ID                     |
+| setFormData    | 设置表单数据              | data: 要设置的数据对象          |
+| getFormData    | 获取表单数据              | 无                             |
+| clearFormData  | 清空表单数据              | 无                             |
+
+## API配置对象说明
+
+apiConfig和detailApiConfig的格式如下：
+
+```javascript
+{
+  key: 'apiKey',        // API的键名
+  apiId: 'module.api',  // API的标识ID
+  apiType: '3'          // API类型，对应dataService中的类型
+}
+```
+
+apiType常用值：
+- '0': 列表查询
+- '1': 详情查询
+- '3': 数据新增
+- '5': 数据修改
+- '7': 数据删除
+
+## 与EbizSDialog组件的比较
+
+EbizSForm与EbizSDialog组件有相似的API调用和表单数据处理机制，两者都：
+
+1. 使用本地表单数据管理（localFormData）
+2. 支持详情数据加载（detailApiConfig）
+3. 采用相同的API调用方式（dataService.fetch）
+4. 不修改apiConfig对象
+
+选择使用哪个组件取决于具体的场景需求：
+- 如果需要在页面上直接显示表单，使用EbizSForm
 - 如果需要在弹窗中显示表单，使用EbizSDialog