resolver-egretimp-plus 0.1.139 → 0.1.141

package//344/275/277/347/224/250/346/211/213/345/206/214.md

@@ -0,0 +1,1216 @@
+# Sa-Egretimp Resolver 使用手册
+
+## 目录
+
+- [项目概述](#项目概述)
+- [核心架构](#核心架构)
+- [快速开始](#快速开始)
+- [配置结构](#配置结构)
+- [组件系统](#组件系统)
+- [规则引擎](#规则引擎)
+- [事件编排](#事件编排)
+- [API 参考](#api-参考)
+- [高级用法](#高级用法)
+- [最佳实践](#最佳实践)
+
+---
+
+## 项目概述
+
+**Sa-Egretimp Resolver** 是一个基于 JSON 配置驱动的动态表单/页面渲染器，基于 Vue 3 + Element Plus 构建。它支持：
+
+- 🎯 **配置驱动**：通过 JSON 配置动态渲染页面，无需编写模板代码
+- 🔄 **双向数据绑定**：通过 `v-model` 实现数据同步
+- 📐 **响应式布局**：支持栅格系统、Tab、折叠面板、循环列表等复杂布局
+- 🎭 **多模式支持**：操作模式（operate）、详情模式（detail）、日志模式（log）
+- 🌐 **国际化**：支持中英文切换
+- ⚡ **规则引擎**：支持字段联动、显隐控制、禁用控制等动态规则
+- 🔌 **事件编排**：支持按钮点击后的服务调用、弹窗打开、数据校验等复杂交互
+- 📱 **双端支持**：同时支持 PC 端（Web）和移动端（H5）
+
+### 技术栈
+
+- **框架**：Vue 3 (Composition API)
+- **UI 库**：Element Plus (PC端) / 自定义 H5 组件库 (移动端)
+- **构建工具**：Webpack + Babel
+- **规则引擎**：json-rules-engine
+- **工具库**：lodash-es, dayjs, axios
+
+---
+
+## 核心架构
+
+### 渲染流程
+
+```
+配置数据 (JSON)
+    ↓
+parsePageConfig() - 解析配置，构建组件树
+    ↓
+normalConfig() - 标准化配置，处理嵌套、循环、规则
+    ↓
+Renderer - 遍历配置，动态渲染组件
+    ↓
+AnalysisComponent - 分析单个配置项，绑定属性、事件、规则
+    ↓
+实际组件 (Element Plus / 自定义组件)
+```
+
+### 核心模块
+
+| 模块 | 路径 | 职责 |
+|------|------|------|
+| **Resolver** | `src/index.jsx` | 根组件，提供全局依赖注入 |
+| **Renderer** | `src/renderer.jsx` | 配置渲染器，遍历配置生成 VNode |
+| **AnalysisComponent** | `src/analysisComponent.jsx` | 组件分析器，处理属性绑定、事件、规则 |
+| **pageConfig Hook** | `src/hooks/pageConfig.js` | 配置加载与解析 |
+| **rulesDriver** | `src/rules/rulesDriver.js` | 规则驱动引擎 |
+| **eventOrchestration** | `src/components/helper/eventOrchestration.js` | 事件编排（服务调用、弹窗等） |
+
+### 数据流
+
+```
+props.config (配置) ──────────────────────────────┐
+                                                    ↓
+props.modelValue (数据) ─→ dynamicMapComp (配置-数据映射) ←→ 组件 refValue
+                                                    ↓
+                                            rulesDriver (规则监听)
+                                                    ↓
+                                            触发显隐/禁用/赋值等操作
+```
+
+---
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+npm install resolver-egretimp-plus
+```
+
+### 2. 基础使用
+
+```vue
+<template>
+  <Resolver
+    :config="pageConfig"
+    v-model="formData"
+    :mode="mode"
+    :selects="selectOptions"
+    :axiosInstance="axios"
+    :messageInstance="ElMessage"
+    :loadingInstance="loadingService"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import Resolver from 'resolver-egretimp-plus/web'
+import { ElMessage } from 'element-plus'
+import axios from 'axios'
+
+// 页面配置（从后端获取或本地定义）
+const pageConfig = ref({
+  metaType: 'CustomComponentFormLayout',
+  pmPageMetaList: [
+    {
+      metaCode: 'username',
+      metaNameZh: '用户名',
+      metaType: 'input',
+      requiredFlag: '1',
+      span: 12
+    },
+    {
+      metaCode: 'status',
+      metaNameZh: '状态',
+      metaType: 'select',
+      selectKey: 'status_options',
+      span: 12
+    }
+  ]
+})
+
+// 表单数据
+const formData = ref({})
+
+// 模式：operate | detail | log
+const mode = ref('operate')
+
+// 下拉选项
+const selectOptions = ref({
+  status_options: [
+    { label: '启用', value: '1' },
+    { label: '禁用', value: '0' }
+  ]
+})
+
+// 获取 ref
+import { ref } from 'vue'
+const resolverRef = ref(null)
+
+// 校验表单
+const handleSubmit = async () => {
+  await resolverRef.value.validate((valid) => {
+    if (valid) {
+      console.log('表单数据:', formData.value)
+    }
+  })
+}
+</script>
+```
+
+### 3. 从后端加载配置
+
+```vue
+<script setup>
+import { useBuildInData } from 'resolver-egretimp-plus/web'
+import { ElMessage, ElLoading } from 'element-plus'
+
+const { pageConfig, getPageConfig, selects } = useBuildInData({
+  messageInstance: ElMessage,
+  loadingInstance: ElLoading.service(),
+  requestTraceId: 'unique-trace-id',
+  lang: 'zh',
+  isH5: false
+})
+
+// 获取配置
+getPageConfig({
+  busiIdentityId: 'your-business-id',
+  pageId: 'your-page-id'
+}, {
+  configCb: (config) => {
+    console.log('配置加载完成', config)
+  },
+  selectsCb: (selects) => {
+    console.log('枚举加载完成', selects)
+  }
+})
+</script>
+
+<template>
+  <Resolver
+    :config="pageConfig"
+    v-model="formData"
+    :selects="selects"
+  />
+</template>
+```
+
+---
+
+## 配置结构
+
+### 配置层级
+
+```json
+{
+  "metaType": "CustomComponentFormLayout",  // 根节点类型
+  "span": 24,                                // 栅格占位
+  "labelWidth": "84px",                      // 标签宽度
+  "pmPageMetaList": [                        // 子组件配置列表
+    {
+      "metaCode": "field_code",              // 字段编码（唯一标识）
+      "metaNameZh": "字段名称",               // 中文名称
+      "metaType": "input",                   // 组件类型
+      "requiredFlag": "1",                   // 是否必填：1-是，0-否
+      "editFlag": "1",                       // 是否可编辑：1-是，0-否
+      "span": 12,                            // 栅格占位（1-24）
+      "seqNo": 1,                            // 排序号
+      "displayType": "1",                    // 显示类型：1-显示，0-隐藏
+      "hireRelat": []                        // 关联规则
+    }
+  ]
+}
+```
+
+### 常用 metaType 映射
+
+| metaType | 渲染组件 | 说明 |
+|----------|----------|------|
+| `input` | `ElInput` | 文本输入框 |
+| `textarea` | `ElInput` (type="textarea") | 多行文本 |
+| `select` | `ElSelect` | 下拉选择 |
+| `radio` | `ElRadio` | 单选框 |
+| `checkbox` | `ElCheckbox` | 复选框 |
+| `date` | `ElDatePicker` | 日期选择 |
+| `date-range` | `ElDatePicker` (type="daterange") | 日期范围 |
+| `time` | `ElTimePicker` | 时间选择 |
+| `number` | `ElInputNumber` | 数字输入 |
+| `button` | `ElButton` | 按钮 |
+| `static-text` | `ElText` | 静态文本 |
+| `table` | `CustomComponentTable` | 表格 |
+| `tab` | `CustomComponentTabs` | 标签页 |
+| `tab-pane` | `CustomComponentTabPane` | 标签页面板 |
+| `collapse` | `CustomComponentCollapse` | 折叠面板 |
+| `card` | `CustomComponentCollapse` | 卡片 |
+| `cycle` | `CustomComponentCycle` | 循环列表 |
+| `tree` | `CustomComponentTree` | 树形控件 |
+| `pagination` | `ElPagination` | 分页 |
+
+### 布局配置
+
+#### 栅格布局
+
+```json
+{
+  "metaType": "CustomComponentFormLayout",
+  "inline": true,
+  "pmPageMetaList": [
+    {
+      "metaCode": "field1",
+      "span": 12,        // 占用 12/24 = 50% 宽度
+      "offset": 0        // 左侧偏移格数
+    },
+    {
+      "metaCode": "field2",
+      "md": 8,           // 中等屏幕占 8 格
+      "lg": 6            // 大屏幕占 6 格
+    }
+  ]
+}
+```
+
+#### Tab 标签页
+
+```json
+{
+  "metaCode": "main_tabs",
+  "metaType": "tab",
+  "pmPageMetaList": [
+    {
+      "metaCode": "tab1",
+      "metaType": "tab-pane",
+      "labelZh": "基本信息",
+      "defaultShowFlag": "1",  // 默认显示
+      "pmPageMetaList": [
+        // tab1 的字段配置
+      ]
+    },
+    {
+      "metaCode": "tab2",
+      "metaType": "tab-pane",
+      "labelZh": "详细信息",
+      "pmPageMetaList": [
+        // tab2 的字段配置
+      ]
+    }
+  ]
+}
+```
+
+#### 折叠面板
+
+```json
+{
+  "metaCode": "collapse_panel",
+  "metaType": "collapse",
+  "needWrap": "1",       // 是否使用卡片包裹
+  "pmPageMetaList": [
+    {
+      "metaCode": "section1",
+      "metaType": "tab-pane",
+      "labelZh": "基本信息",
+      "pmPageMetaList": []
+    }
+  ]
+}
+```
+
+#### 循环列表（动态表格行）
+
+```json
+{
+  "metaCode": "detail_list",
+  "metaType": "cycle",
+  "pmPageMetaList": [
+    {
+      "metaCode": "item_name",
+      "metaType": "input",
+      "labelZh": "项目名称"
+    },
+    {
+      "metaCode": "item_amount",
+      "metaType": "number",
+      "labelZh": "金额"
+    }
+  ]
+}
+```
+
+对应的数据结构：
+
+```javascript
+{
+  detail_list: [
+    { item_name: '项目A', item_amount: 1000 },
+    { item_name: '项目B', item_amount: 2000 }
+  ]
+}
+```
+
+---
+
+## 组件系统
+
+### 内置组件
+
+项目提供了丰富的内置组件，位于 `src/components/packages-web/` 目录：
+
+#### 表单组件
+
+- **ElInput** - 文本输入框（支持文本、密码、多行等）
+- **ElSelect** - 下拉选择框
+- **ElRadio** - 单选框组
+- **ElCheckbox** - 复选框组
+- **ElDatePicker** - 日期选择器
+- **ElTimePicker** - 时间选择器
+- **ElInputNumber** - 数字输入框
+- **ElButton** - 按钮
+
+#### 布局组件
+
+- **CustomComponentFormLayout** - 表单布局容器
+- **CustomComponentRow** - 行布局
+- **CustomComponentCol** - 列布局
+- **CustomComponentTabs** - 标签页容器
+- **CustomComponentTabPane** - 标签页面板
+- **CustomComponentCollapse** - 折叠面板
+- **CustomComponentCycle** - 循环列表
+- **CustomComponentDialog** - 对话框
+
+#### 数据展示组件
+
+- **CustomComponentTable** - 数据表格（支持分页、选择、排序）
+- **CustomComponentTree** - 树形控件
+- **CustomComponentSteps** - 步骤条
+- **CustomComponentPlain** - 纯文本展示（用于表格列禁用时）
+
+#### 功能组件
+
+- **CustomComponentSelectEmployees** - 员工选择器
+- **CustomComponentEditor** - 富文本编辑器
+- **CustomComponentSendMail** - 邮件发送
+- **CustomComponentFileImport** - 文件导入
+- **CustomComponentFileExport** - 文件导出
+- **CustomComponentInputDialog** - 输入对话框
+
+### 自定义组件
+
+#### 注册自定义组件
+
+```vue
+<script setup>
+import MyCustomComponent from './MyCustomComponent.vue'
+
+const customComponents = {
+  MyCustomComponent
+}
+</script>
+
+<template>
+  <Resolver
+    :components="customComponents"
+    :config="pageConfig"
+    v-model="formData"
+  />
+</template>
+```
+
+#### 配置中使用自定义组件
+
+```json
+{
+  "metaCode": "custom_field",
+  "metaType": "MyCustomComponent",
+  "labelZh": "自定义字段",
+  "customProp1": "value1",
+  "customProp2": "value2"
+}
+```
+
+#### 自定义组件规范
+
+自定义组件需要遵循以下规范：
+
+```vue
+<template>
+  <div>
+    <input :value="modelValue" @input="$emit('update:modelValue', $event.target.value)" />
+  </div>
+</template>
+
+<script setup>
+defineProps({
+  modelValue: [String, Number, Object, Array],
+  config: Object,          // 配置对象
+  disabled: Boolean,       // 是否禁用
+  required: Boolean,       // 是否必填
+  options: Array,          // 选项数据
+  placeholder: String,     // 占位符
+  mode: String             // 当前模式：operate | detail | log
+})
+
+defineEmits(['update:modelValue'])
+</script>
+```
+
+### 组件通用 Props
+
+所有组件都会自动注入以下属性：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `modelValue` | Any | 绑定值（v-model） |
+| `config` | Object | 配置对象 |
+| `disabled` | Boolean | 是否禁用 |
+| `required` | Boolean | 是否必填 |
+| `clearable` | Boolean | 是否可清除 |
+| `options` | Array | 下拉选项 |
+| `placeholder` | String | 占位符 |
+| `mode` | String | 当前模式 |
+| `width` | String | 组件宽度 |
+| `tableData` | Array | 表格数据（表格列中） |
+| `rowScope` | Object | 行数据（表格列中）`{row, $index}` |
+
+---
+
+## 规则引擎
+
+规则引擎用于实现字段联动、显隐控制、禁用控制、值变更等功能。
+
+### 规则结构
+
+```json
+{
+  "relId": "rule_001",
+  "pmRuleConditionVOList": [
+    {
+      "conditionType": "1",        // 条件类型：1-字段值
+      "leftCode": "status",        // 左侧字段
+      "operator": "==",            // 操作符
+      "rightVal": "1"              // 右侧值
+    }
+  ],
+  "pmRuleTargetEventVoList": [
+    {
+      "eventType": "1",            // 事件类型：1-显示/隐藏，2-禁用/启用，3-必填/非必填
+      "targetCode": "detail_field", // 目标字段
+      "eventValue": "1"            // 事件值
+    }
+  ]
+}
+```
+
+### 条件操作符
+
+| 操作符 | 说明 |
+|--------|------|
+| `==` | 等于 |
+| `!=` | 不等于 |
+| `>` | 大于 |
+| `<` | 小于 |
+| `>=` | 大于等于 |
+| `<=` | 小于等于 |
+| `in` | 包含于 |
+| `not in` | 不包含于 |
+| `like` | 模糊匹配 |
+
+### 事件类型
+
+| eventType | 说明 | eventValue |
+|-----------|------|------------|
+| `1` | 显示/隐藏 | `1`-显示，`0`-隐藏 |
+| `2` | 禁用/启用 | `1`-禁用，`0`-启用 |
+| `3` | 必填/非必填 | `1`-必填，`0`-非必填 |
+| `4` | 赋值 | 目标值 |
+
+### 规则示例
+
+#### 示例 1：字段显隐联动
+
+当 `status` 为 `1` 时，显示 `detail_field`：
+
+```json
+{
+  "relId": "rule_show_detail",
+  "pmRuleConditionVOList": [
+    {
+      "leftCode": "status",
+      "operator": "==",
+      "rightVal": "1"
+    }
+  ],
+  "pmRuleTargetEventVoList": [
+    {
+      "eventType": "1",
+      "targetCode": "detail_field",
+      "eventValue": "1"
+    }
+  ]
+}
+```
+
+#### 示例 2：字段禁用联动
+
+当 `type` 为 `readonly` 时，禁用 `name` 字段：
+
+```json
+{
+  "relId": "rule_disable_name",
+  "pmRuleConditionVOList": [
+    {
+      "leftCode": "type",
+      "operator": "==",
+      "rightVal": "readonly"
+    }
+  ],
+  "pmRuleTargetEventVoList": [
+    {
+      "eventType": "2",
+      "targetCode": "name",
+      "eventValue": "1"
+    }
+  ]
+}
+```
+
+### 规则挂载位置
+
+规则配置在页面配置的 `_originConfig` 中：
+
+```json
+{
+  "pmPageMetaList": [],
+  "_originConfig": {
+    "lcpPageRuleVOList": [
+      // 规则列表
+    ]
+  }
+}
+```
+
+---
+
+## 事件编排
+
+事件编排用于处理按钮点击后的复杂交互，包括服务调用、弹窗打开、数据校验等。
+
+### 按钮配置
+
+```json
+{
+  "metaCode": "submit_btn",
+  "metaType": "button",
+  "labelZh": "提交",
+  "lcpPageServiceMapVOList": [
+    {
+      "serviceCode": "/api/submit",
+      "httpMethod": "post",
+      "serviceType": "1",        // 1-融合服务
+      "transactionType": "1",    // 1-查询服务
+      "busiIdentityId": "biz_001",
+      "inParamMappingList": [    // 入参映射
+        {
+          "orignParam": "username",
+          "destParam": "userName"
+        }
+      ],
+      "outParamMappingList": [   // 出参映射
+        {
+          "orignParam": "result.data",
+          "destParam": "result_field"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 服务调用流程
+
+```
+按钮点击
+    ↓
+beforeRequestService (请求前钩子)
+    ↓
+发送 HTTP 请求
+    ↓
+afterRequestService (请求后钩子)
+    ↓
+处理返回数据 (outParamMappingList)
+    ↓
+更新组件 refValue
+```
+
+### 钩子函数
+
+#### beforeRequestService
+
+请求发送前执行，可用于修改请求参数或中断请求：
+
+```javascript
+{
+  metaCode: 'submit_btn',
+  metaType: 'button',
+  beforeRequestService: ({ dynamicMapComp, reqData, service }) => {
+    // 修改请求参数
+    reqData.customField = 'custom_value'
+    
+    // 返回 false 中断请求
+    if (!reqData.username) {
+      return false
+    }
+    
+    // 返回 true 或 Promise 继续请求
+    return true
+  }
+}
+```
+
+#### afterRequestService
+
+请求成功后执行：
+
+```javascript
+{
+  metaCode: 'submit_btn',
+  metaType: 'button',
+  afterRequestService: (response, { dynamicMapComp, reqData }) => {
+    console.log('请求成功', response.data)
+    // 可执行额外逻辑
+  }
+}
+```
+
+### 弹窗配置
+
+```json
+{
+  "metaCode": "open_dialog_btn",
+  "metaType": "button",
+  "labelZh": "打开弹窗",
+  "lcpPagePopupMapVO": {
+    "popupBusiIdentityId": "dialog_biz_001",
+    "objOrList": "0",          // 0-对象，1-列表
+    "inParamMappingList": [    // 传入弹窗的参数
+      {
+        "orignParam": "id",
+        "destParam": "dialogId"
+      }
+    ],
+    "outParamMappingList": [   // 弹窗返回的参数
+      {
+        "orignParam": "selectedData",
+        "destParam": "selected_field"
+      }
+    ],
+    "outDisplayTrigger": "confirm_btn",  // 弹窗中确认按钮编码
+    "closedTrigger": "close_btn"         // 弹窗中关闭按钮编码
+  }
+}
+```
+
+---
+
+## API 参考
+
+### Resolver 组件 Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `config` | Object | null | 页面配置对象 |
+| `modelValue` | Object | null | 表单数据（v-model） |
+| `mode` | String | 'operate' | 模式：operate/detail/log |
+| `components` | Object | {} | 自定义组件映射 |
+| `selects` | Object | {} | 下拉枚举数据 |
+| `lang` | String | 'zh' | 语言：zh/en |
+| `dataLoad` | Boolean | false | 是否开始执行规则初始化 |
+| `buttonActions` | Object | {} | 按钮动作集合 |
+| `axiosInstance` | Object/Function | null | Axios 实例 |
+| `axiosConfig` | Object | null | Axios 配置（用于生成实例） |
+| `messageInstance` | Object/Function | null | 消息提示实例 |
+| `loadingInstance` | Object/Function | null | 加载实例 |
+| `confirmInstance` | Object/Function | null | 确认框实例 |
+| `openChildDialogInstance` | Function | null | 打开子弹窗实例 |
+| `copyModal` | Object/Function | null | 复制弹窗实例 |
+| `polyfillConfigs` | Object | {} | 配置补丁 |
+| `dialogComponents` | Object | {} | 输入弹窗中的组件 |
+| `loadEvnetsReq` | Object | {} | 加载服务请求参数 |
+| `dialogReq` | Object | {} | 弹窗请求数据 |
+| `parentRootValue` | Object | {} | 父页面根数据（弹窗中） |
+| `parentDynamicMapComp` | Object | {} | 父页面配置映射（弹窗中） |
+| `selectionsObj` | Object | {} | 父页面已选数据（弹窗中） |
+| `requestTraceId` | String | - | 请求追踪 ID |
+| `loadModuleCache` | Object | {} | 动态组件加载缓存 |
+| `builtPolyfillReq` | Object | {} | 内置接口额外参数 |
+| `openBpm` | Boolean | false | 是否开启 BPM 流程 |
+| `bpmMessage` | Object/Function | {} | BPM 参数 |
+| `bpmSubmitBtn` | String | '' | BPM 提交按钮编码 |
+| `bpmActions` | Object | {} | BPM 动作配置 |
+| `bpmConfigs` | Object | {} | BPM 配置 |
+| `bpmBtns` | Array | [] | BPM 按钮列表 |
+| `bpmBtnPosition` | Number | 3 | BPM 按钮位置 |
+| `isH5` | Boolean | false | 是否 H5 模式 |
+| `getNativeComps` | Function | - | 获取原生组件 |
+| `loadEventsBefore` | Function | null | 加载服务前钩子 |
+| `loadEventsAfter` | Function | null | 加载服务后钩子 |
+| `messageCb` | Function | - | 消息回调 |
+
+### Resolver 组件 Events
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `update:modelValue` | (value) | 数据变更 |
+| `rootStoreChange` | (store) | 根存储变更 |
+| `loadEvnetsCompleted` | (result) | 加载服务完成 |
+
+### Resolver 组件 Expose
+
+通过 `ref` 可访问的方法和属性：
+
+| 属性/方法 | 类型 | 说明 |
+|-----------|------|------|
+| `validate` | Function | 表单校验 `(callback) => void` |
+| `dynamicMapComp` | Object | 配置-数据映射对象 |
+| `pageConfig` | Object | 页面配置 |
+| `rootForm` | Ref | 根表单引用 |
+| `getRequestTraceId` | Function | 获取请求追踪 ID |
+| `toExecuteLoadServices` | Function | 执行加载服务 |
+| `getBpmInstance` | Function | 获取 BPM 实例 |
+
+### useBuildInData Hook
+
+用于从后端加载配置和枚举数据：
+
+```javascript
+import { useBuildInData } from 'resolver-egretimp-plus/web'
+
+const {
+  pageConfig,      // 页面配置 Ref
+  selects,         // 枚举数据 Ref
+  getPageConfig,   // 获取配置方法
+  getSelects       // 获取枚举方法
+} = useBuildInData({
+  messageInstance: ElMessage,
+  loadingInstance: loadingService,
+  requestTraceId: 'trace-id',
+  lang: 'zh',
+  isH5: false
+})
+
+// 获取配置
+getPageConfig(reqData, {
+  configCb: (config) => {},  // 配置加载完成回调
+  selectsCb: (selects) => {}, // 枚举加载完成回调
+  selectPolyReq: {}           // 枚举额外参数
+})
+
+// 获取枚举
+getSelects(reqData, selectsCb)
+```
+
+---
+
+## 高级用法
+
+### 1. 动态组件加载
+
+支持从远程加载 Vue 组件：
+
+```json
+{
+  "metaCode": "remote_component",
+  "metaType": "MyRemoteComponent",
+  "isCustom": true,
+  "fileId": "/path/to/component"
+}
+```
+
+### 2. 配置补丁（polyfillConfigs）
+
+在运行时动态修改配置：
+
+```javascript
+const polyfillConfigs = {
+  'username': (config, instance, { parentRootValue, parentDynamicMapComp }) => {
+    return {
+      requiredFlag: '1',
+      labelZh: '用户名（必填）'
+    }
+  }
+}
+
+<Resolver :polyfillConfigs="polyfillConfigs" />
+```
+
+### 3. 生命周期钩子
+
+在配置中定义组件生命周期：
+
+```json
+{
+  "metaCode": "field_with_hooks",
+  "metaType": "input",
+  "onMounted": "console.log('组件已挂载', props, selects)",
+  "onVnodeMounted": "function(props, vnode, selects) { ... }",
+  "onVnodeUnmounted": "function(props) { ... }"
+}
+```
+
+### 4. 即时点击事件
+
+配置加载完成后自动执行按钮点击事件：
+
+```json
+{
+  "metaCode": "auto_load_btn",
+  "metaType": "button",
+  "immediateClickEvent": true,
+  "hidden": "1",
+  "lcpPageServiceMapVOList": []
+}
+```
+
+### 5. 表单校验
+
+#### 基础校验
+
+```javascript
+const resolverRef = ref(null)
+
+resolverRef.value.validate((valid) => {
+  if (valid) {
+    console.log('校验通过')
+  } else {
+    console.log('校验失败')
+  }
+})
+```
+
+#### 自定义校验规则
+
+```json
+{
+  "metaCode": "email",
+  "metaType": "input",
+  "validRegs": [
+    {
+      "pattern": "/^\\w+([-+.]\\w+)*@\\w+([-.]\\w+)*\\.\\w+([-.]\\w+)*$/",
+      "message": "邮箱格式不正确",
+      "messageEn": "Invalid email format"
+    }
+  ]
+}
+```
+
+#### 自定义校验函数
+
+```javascript
+{
+  metaCode: 'custom_field',
+  metaType: 'input',
+  validators: [(rule, value, callback, config) => {
+    if (value === 'invalid') {
+      callback(new Error('值无效'))
+    } else {
+      callback()
+    }
+  }]
+}
+```
+
+### 6. 数据驱动规则（OPEN_DATA_RULES）
+
+开启数据驱动规则后，规则引擎会实时监听数据变化：
+
+```javascript
+<Resolver :open-data-rules="true" />
+```
+
+规则会基于 `dynamicHireRelat` 路径进行精确匹配和触发。
+
+### 7. 循环组件动态渲染
+
+循环组件（表格、cycle）会根据数据数组动态生成配置：
+
+```javascript
+// 数据结构
+{
+  items: [
+    { name: 'Item 1', price: 100 },
+    { name: 'Item 2', price: 200 }
+  ]
+}
+
+// 配置
+{
+  metaCode: 'items',
+  metaType: 'cycle',
+  pmPageMetaList: [
+    { metaCode: 'name', metaType: 'input' },
+    { metaCode: 'price', metaType: 'number' }
+  ]
+}
+```
+
+系统会为每个数组项创建独立的配置实例，路径为 `items[0]->name`, `items[1]->name` 等。
+
+### 8. 弹窗交互
+
+#### 打开弹窗
+
+```javascript
+// 父页面按钮配置
+{
+  metaCode: 'open_select_btn',
+  metaType: 'button',
+  lcpPagePopupMapVO: {
+    popupBusiIdentityId: 'select_dialog',
+    inParamMappingList: [
+      { orignParam: 'type', destParam: 'dialogType' }
+    ],
+    outParamMappingList: [
+      { orignParam: 'selectedId', destParam: 'selected_id' }
+    ],
+    outDisplayTrigger: 'confirm_btn'
+  }
+}
+```
+
+#### 弹窗中间钩子
+
+```javascript
+{
+  metaCode: 'open_select_btn',
+  metaType: 'button',
+  middleOpenDialog: ({ inputParams, outputParams, dynamicMapComp }) => {
+    // 处理弹窗返回数据
+    return {
+      selected_id: outputParams.selectedId + '_processed'
+    }
+  }
+}
+```
+
+### 9. BPM 流程集成
+
+支持致远 BPM 流程集成：
+
+```vue
+<Resolver
+  :open-bpm="true"
+  :bpm-message="bpmMessage"
+  :bpm-submit-btn="submit_btn"
+  :bpm-actions="bpmActions"
+  :bpm-configs="bpmConfigs"
+  :bpm-btns="bpmBtns"
+/>
+```
+
+### 10. 懒加载优化
+
+组件支持懒加载，可提升首屏渲染性能：
+
+```json
+{
+  "metaCode": "heavy_component",
+  "metaType": "CustomComponentTable",
+  "_notOpenLazy": false  // 默认开启懒加载
+}
+```
+
+自定义组件会禁用父级链路的懒加载。
+
+---
+
+## 最佳实践
+
+### 1. 配置管理
+
+- **配置分离**：将不同业务场景的配置分开管理
+- **配置缓存**：使用 `requestTraceId` 标识请求，便于缓存和追踪
+- **配置校验**：加载配置后进行结构校验，避免渲染错误
+
+### 2. 性能优化
+
+- **开启懒加载**：对复杂组件（表格、Tab）开启懒加载
+- **合理设置 span**：避免过度嵌套导致渲染性能下降
+- **使用 dataLoad 控制**：在数据准备好后再开启规则引擎
+
+```javascript
+const dataLoad = ref(false)
+
+// 数据加载完成后
+onMounted(async () => {
+  await loadData()
+  dataLoad.value = true
+})
+
+<Resolver :data-load="dataLoad" />
+```
+
+### 3. 错误处理
+
+- **全局错误捕获**：使用 `onErrorCaptured` 捕获组件渲染错误
+- **服务调用错误**：在 `afterRequestService` 中处理错误
+- **校验错误提示**：使用 `messageInstance` 统一错误提示
+
+### 4. 数据流管理
+
+- **单向数据流**：通过 `v-model` 管理数据，避免直接修改
+- **使用 deepMerge**：合并数据时使用 `deepMerge` 避免覆盖
+- **监听 rootStoreChange**：实时监听数据变化
+
+```javascript
+<Resolver @root-store-change="handleDataChange" />
+
+const handleDataChange = (data) => {
+  console.log('数据变更', data)
+}
+```
+
+### 5. 国际化
+
+- **配置多语言**：在配置中使用 `labelZh` 和 `labelEn`
+- **动态切换**：通过 `lang` prop 切换语言
+- **提示语适配**：错误提示、占位符等都需要适配
+
+```json
+{
+  "metaCode": "username",
+  "labelZh": "用户名",
+  "labelEn": "Username",
+  "defPlacehold": "请输入用户名",
+  "defPlaceholdEn": "Please enter username"
+}
+```
+
+### 6. 移动端适配
+
+- **使用 H5 组件**：设置 `isH5: true` 使用移动端组件
+- **简化布局**：移动端建议使用卡片、列表布局
+- **触摸优化**：按钮、输入框大小适合触摸操作
+
+```vue
+<Resolver :is-h5="true" />
+```
+
+### 7. 调试技巧
+
+- **查看 dynamicMapComp**：通过 `resolverRef.value.dynamicMapComp` 查看配置映射
+- **性能标记**：系统内置了 Performance API 标记，可在 DevTools 中查看
+- **规则调试**：在规则中添加 `console.log` 输出调试信息
+
+### 8. 安全注意事项
+
+- **配置来源可信**：确保配置数据来自可信的后端接口
+- **XSS 防护**：避免在配置中使用未过滤的用户输入
+- **eval 使用**：配置中的 `onMounted` 等字符串函数会使用 eval，需谨慎使用
+
+---
+
+## 常见问题
+
+### Q1: 组件不渲染怎么办？
+
+检查以下几点：
+1. `config` 是否正确传递
+2. `metaType` 是否在组件库中存在
+3. `displayType` 是否为 `1`（显示）
+4. 是否被规则隐藏（`hidden == '1'`）
+
+### Q2: 规则不生效怎么办？
+
+检查以下几点：
+1. `hireRelat` 是否正确配置
+2. `dataLoad` 是否为 `true`
+3. 规则条件是否匹配当前数据
+4. 查看控制台是否有规则执行日志
+
+### Q3: 表单校验失败但无提示？
+
+检查以下几点：
+1. `messageInstance` 是否正确传递
+2. `requiredFlag` 是否为 `'1'`
+3. `dynamicHireRelat` 路径是否正确
+4. 自定义校验函数是否正确调用 `callback`
+
+### Q4: 弹窗数据无法回传？
+
+检查以下几点：
+1. `outParamMappingList` 映射是否正确
+2. `outDisplayTrigger` 按钮编码是否匹配
+3. `middleOpenDialog` 是否正确返回数据
+4. 弹窗中是否正确触发了确认按钮
+
+### Q5: 循环组件数据不同步？
+
+检查以下几点：
+1. 数据路径是否正确（如 `items[0]->name`）
+2. `rowIndex` 是否正确设置
+3. 是否使用了正确的 `dynamicHireRelat`
+
+---
+
+## 附录
+
+### 配置字段完整参考
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `metaCode` | String | 是 | 字段编码（唯一标识） |
+| `metaNameZh` | String | 是 | 中文名称 |
+| `metaNameEn` | String | 否 | 英文名称 |
+| `metaType` | String | 是 | 组件类型 |
+| `renderby` | String | 否 | 渲染组件类型（覆盖 metaType） |
+| `requiredFlag` | String | 否 | 是否必填：1-是，0-否 |
+| `editFlag` | String | 否 | 是否可编辑：1-是，0-否 |
+| `displayType` | String | 否 | 显示类型：1-显示，0-隐藏 |
+| `hidden` | String/Boolean | 否 | 是否隐藏 |
+| `span` | Number | 否 | 栅格占位（1-24） |
+| `offset` | Number | 否 | 左侧偏移格数 |
+| `md` | Number/Object | 否 | 中等屏幕占位 |
+| `lg` | Number/Object | 否 | 大屏幕占位 |
+| `seqNo` | Number | 否 | 排序号 |
+| `labelZh` | String | 否 | 中文标签 |
+| `labelEn` | String | 否 | 英文标签 |
+| `labelWidth` | String | 否 | 标签宽度 |
+| `labelHidden` | String | 否 | 是否隐藏标签 |
+| `defPlacehold` | String | 否 | 中文占位符 |
+| `defPlaceholdEn` | String | 否 | 英文占位符 |
+| `clearableFlag` | String | 否 | 是否可清除 |
+| `selectKey` | String | 否 | 下拉选项 key |
+| `hireRelat` | Array | 否 | 关联规则 |
+| `pmPageMetaList` | Array | 否 | 子组件配置 |
+| `extendAttr` | String | 否 | 扩展属性（JSON 字符串） |
+| `defStyle` | String | 否 | 默认样式（JSON 字符串） |
+| `validRegs` | Array/Object | 否 | 校验规则 |
+| `validators` | Array | 否 | 自定义校验函数 |
+| `regexPattern` | String | 否 | 正则校验（JSON 字符串） |
+| `slots` | Object | 否 | 插槽配置 |
+| `class` | String | 否 | CSS 类名 |
+| `style` | Object | 否 | 内联样式 |
+
+### 版本历史
+
+| 版本 | 日期 | 说明 |
+|------|------|------|
+| 0.1.140 | - | 当前版本 |
+
+### 相关资源
+
+- **Element Plus 文档**：https://element-plus.org/
+- **Vue 3 文档**：https://cn.vuejs.org/
+- **json-rules-engine**：https://github.com/CacheControl/json-rules-engine
+
+---
+
+## 联系与支持
+
+如有问题或建议，请联系开发团队。
+
+**包名**：`resolver-egretimp-plus`  
+**作者**：caowb  
+**许可证**：ISC