flame-plus 1.5.0 → 1.5.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "flame-plus",
   "type": "module",
-  "version": "1.5.0",
+  "version": "1.5.3",
   "description": "基于 element-plus 的组件库",
   "main": "./flameDist/flame-plus.es.js",
   "module": "./flameDist/flame-plus.es.js",

package/.claude/settings.json

@@ -1,11 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Read(//Users/albert/Workspaces/gmp/gmp-frontend/gmp-platform/node_modules/.pnpm/flame-plus@1.3.26_@element-plus+icons-vue@2.3.2_vue@3.3.4__@interactjs+core@1.10.27_@in_3c4e5d5dc5fd652459cb45b714b2aa3c/node_modules/flame-plus/flameDist/**)",
-      "Bash(pnpm run:*)"
-    ]
-  },
-  "enabledPlugins": {
-    "chrome-devtools-mcp@claude-plugins-official": true
-  }
-}

package/.claude/settings.local.json

@@ -1,42 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(python3:*)",
-      "Bash(npm run:*)",
-      "mcp__ide__getDiagnostics",
-      "Bash(cat /Users/albert/Workspaces/poba/flame-plus/node_modules/flame-types/lib/*.d.ts 2>/dev/null | head -30)",
-      "Bash(wc -l /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/*.ts /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/*.vue 2>/dev/null | head -20)",
-      "Bash(ls -la /Users/albert/Workspaces/spark/flame-types/src/ 2>/dev/null || find /Users/albert/Workspaces/spark/flame-types -name \"*.ts\" -o -name \"*.d.ts\" | head -30)",
-      "Bash(cd /Users/albert/Workspaces/spark/flame-types && npm install 2>&1)",
-      "Bash(npm pack:*)",
-      "Bash(cd /Users/albert/Workspaces/poba/flame-plus && npm install /Users/albert/Workspaces/spark/flame-types/flame-types-1.1.7.tgz 2>&1)",
-      "Bash(npm install:*)",
-      "Bash(npx vue-tsc:*)",
-      "Bash(grep -l \"framework.vue\" /Users/albert/.claude/plans/*.md 2>/dev/null | head -5)",
-      "Bash(npx run:*)",
-      "Bash(wc -l /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/framework.vue /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/utils/*.ts /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/components/DetailSettingsSlot.vue)",
-      "Bash(wc -l /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/types.ts /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/utils/*.ts /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/composables/*.ts /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/components/*.vue /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/*.ts /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/*.vue)",
-      "Bash(npx vite:*)",
-      "Bash(kill %1)",
-      "Bash(curl -s http://localhost:5173/)",
-      "Bash(curl -s 'http://localhost:5173/src/packages/components/framework/framework.vue?vue&type=style&index=0&lang.scss')",
-      "Bash(jobs -l)",
-      "Bash(npx skills:*)",
-      "mcp__plugin_chrome-devtools-mcp_chrome-devtools__list_pages",
-      "mcp__plugin_chrome-devtools-mcp_chrome-devtools__navigate_page",
-      "mcp__plugin_chrome-devtools-mcp_chrome-devtools__take_snapshot",
-      "mcp__plugin_chrome-devtools-mcp_chrome-devtools__take_screenshot",
-      "mcp__plugin_chrome-devtools-mcp_chrome-devtools__list_console_messages",
-      "mcp__plugin_chrome-devtools-mcp_chrome-devtools__get_console_message",
-      "mcp__plugin_chrome-devtools-mcp_chrome-devtools__evaluate_script",
-      "mcp__plugin_chrome-devtools-mcp_chrome-devtools__click",
-      "mcp__plugin_chrome-devtools-mcp_chrome-devtools__press_key",
-      "mcp__plugin_chrome-devtools-mcp_chrome-devtools__drag",
-      "mcp__plugin_chrome-devtools-mcp_chrome-devtools__wait_for",
-      "Bash(curl -s http://localhost:5173)"
-    ]
-  },
-  "enabledPlugins": {
-    "chrome-devtools-mcp@claude-plugins-official": true
-  }
-}

package/cursor_modelvalue_prop_type_check_issue.md

@@ -1,102 +0,0 @@
-# ModelValue prop type check issue
-_Exported on 2026/4/1 at GMT+8 15:24:02 from Cursor (2.6.22)_
-
----
-
-**User**
-
-排查问题
-
-MasterFormSwitch.vue?t=1775015461216:215 Invalid prop: type check failed for prop "modelValue". Expected Number | Null, got String with value "12". 
-Proxy(Object) {…}
- at <ElInputNumber>
-at <FlmInputNumber>
-at <ElFormItem>
-at <ElForm>
-at <Anonymous>
-at <BaseTransition>
-at <Transition>
-at <ElCollapseTransition>
-at <ElCollapseItem>
-at <ElCollapse>
-at <FlmCollapse>
-at <FlmDynamicForm>
-at <ElFocusTrap>
-at <ElOverlay>
-at <BaseTransition>
-at <Transition>
-at <Teleport>
-at <ElDrawer>
-at <MasterFormSwitch>
-at <KeepAlive>
-at <RouterView>
-at <AppView>
-at <ElScrollbar>
-at <Layout>
-at <RouterView>
-at <ElConfigProvider>
-at <ConfigGlobal>
-at <App> 
-(28) [{…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}, {…}]
-
-
-
----
-
-**Cursor**
-
-
-正在排查：`ElInputNumber` 的 `modelValue` 需要 `number | null`，但收到了字符串 `"12"`。正在查看 `MasterFormSwitch.vue` 与 `FlmInputNumber` 的数据流。
-
-
-
-
-## 结论
-
-这是 **Element Plus `el-input-number` 的类型校验**：`modelValue` 只能是 `number | null | undefined`，但当前收到的是字符串 **`"12"`**。  
-组件链是：`MasterFormSwitch` → `flm-dynamic-form` → `FlmInputNumber` → `ElInputNumber`。问题出在 **喂给动态表单的 model 里数字字段是字符串**，不是 `MasterFormSwitch` 模板里某一行写错类型。
-
-控制台里 `MasterFormSwitch.vue:215` 多半是 **Vite 带 query 的编译映射**，和源码行号不一定一致；真正相关的逻辑在下面这段。
-
-## 数据从哪来
-
-编辑时 `dynamicFormModel` 来自详情接口解析结果，或退化为表格行：
-
-```353:356:/Users/albert/Workspaces/gmp/gmp-frontend/gmp-platform/src/views/SPARKFORM/MasterFormSwitch/MasterFormSwitch.vue
-      dynamicFormModel.value =
-        Object.keys(fromApi).length > 0
-          ? { ...fromApi }
-          : { ...(data && typeof data === 'object' ? data : {}) }
-```
-
-`fromApi` 由 `parseDynamicFormGetDtlItems` 从 `dynamicFormGetDtl` 响应里拆出来，**不会做数字类型转换**，后端/JSON 里经常是 `"12"` 这种字符串：
-
-```289:317:/Users/albert/Workspaces/gmp/gmp-frontend/gmp-platform/src/views/SPARKFORM/MasterFormSwitch/MasterFormSwitch.vue
-const parseDynamicFormGetDtlItems = (res: any): Record<string, any> => {
-  // ...
-  if (typeof items === 'object') {
-    const row = (items as any).record ?? (items as any).row ?? items
-    if (row && typeof row === 'object' && !Array.isArray(row)) {
-      return { ...row }
-    }
-  }
-  return {}
-}
-```
-
-新增时 `dynamicFormModel` 先是 `{}`，一般 **不会** 立刻报这个错；**编辑**（或详情为空、走了表格行 `data` 回显）最容易复现。
-
-## 与 flame-plus 的关系
-
-你们仓库里的说明已经对齐根因：`flm-dynamic-form` / grid 把 model 里的值原样塞给控件，`FlmInputNumber` 又原样传给 `ElInputNumber`，**没有**把字符串数字转成 `number`。见 `docs/flame-plus-fix-input-number-string-modelValue.md`。
-
-## 处理思路（择一即可）
-
-1. **业务侧（本页）**：在赋给 `dynamicFormModel` 之前，按表单配置或字段元数据，对 `flmInputNumber` 对应字段做归一（空串/`null` 与 `Number()` 的规则见该文档表格）。  
-2. **组件库侧**：在 flame-plus 的 `FlmInputNumber`（或 grid 赋值处）统一归一 `modelValue`，升级依赖或用 `pnpm patch`。  
-3. **后端**：保证动态详情/列表里数值字段以 JSON number 返回（改动面取决于接口约定）。
-
-若只想先确认，可在 `editData` 里 `console.log(fromApi)` 或打断点，看对应数字字段是否为字符串 `"12"`。
-
-（当前为 Ask 模式，我无法直接改代码；若要我在项目里加归一或 patch，需要切换到 Agent 模式。）
-

package/docs/flame-plus-attrfields-onchange-support.md

@@ -1,201 +0,0 @@
-# FlameFramework attrFields onChange 支持修改文档
-
-## 问题描述
-
-FlameFramework 的 `attrFields` 配置中的 `props.onChange` 回调无法被触发，导致级联选择（项目 → 表 → 字段）无法在属性面板中实现。
-
-## 问题根因
-
-### 文件：`/Users/albert/Workspaces/poba/flame-plus/src/packages/components/complex/flmForm/flmForm.vue`
-
-在 `controlDom` 函数（约第 215-266 行）中：
-
-```javascript
-const controlDom = (
-  prop: string,
-  controlType: ControlTypes,
-  controlConfig: ControlConfig
-) => {
-  const config: FormModel = { ...controlConfig }
-  const event = controlType === ControlTypes['flmInput'] ? 'onInput' : 'onChange'
-  config[event] = (value: any) => formChange(value, prop)  // ⚠️ 这里覆盖了原有的 onChange
-  config['modelValue'] = formModel[prop]
-  // ...
-}
-```
-
-**问题**：`flmForm` 在渲染控件时，**强制覆盖**了 `onChange`/`onInput` 事件处理器，导致 `attrFields.props` 中传入的 `onChange` 回调被替换，永远不会被调用。
-
-## 修改方案
-
-### 方案一：保留原有 onChange 并链式调用（推荐）
-
-修改 `flmForm.vue` 中的 `controlDom` 函数：
-
-```javascript
-const controlDom = (
-  prop: string,
-  controlType: ControlTypes,
-  controlConfig: ControlConfig
-) => {
-  const config: FormModel = { ...controlConfig }
-  const event = controlType === ControlTypes['flmInput'] ? 'onInput' : 'onChange'
-
-  // 保存原有的 onChange/onInput 回调
-  const originalHandler = controlConfig[event]
-
-  // 链式调用：先调用内部 formChange，再调用原有回调
-  config[event] = (value: any) => {
-    formChange(value, prop)
-    if (typeof originalHandler === 'function') {
-      originalHandler(value)
-    }
-  }
-
-  config['modelValue'] = formModel[prop]
-
-  // ... 后续代码保持不变
-}
-```
-
-### 方案二：新增 `onValueChange` 专用回调属性
-
-在 `types.ts` 中扩展 `AttrFieldConfig`：
-
-```typescript
-// /Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/types.ts
-
-export interface AttrFieldConfig {
-  key: string
-  label: string
-  component: AttrFieldComponent
-  props?: Record<string, unknown>
-  /** 值变化时的回调，不同于 props.onChange，此回调不会被覆盖 */
-  onValueChange?: (value: unknown, model: Record<string, unknown>) => void
-  visible?: (model: Record<string, unknown>) => boolean
-}
-```
-
-然后在 `FrameworkAttrFieldsForm.vue` 中处理：
-
-```javascript
-// FrameworkAttrFieldsForm.vue
-
-const formItems = computed(() => {
-  return visibleFields.value
-    .filter((f) => componentToControlType[f.component])
-    .map((f) => {
-      const controlType = componentToControlType[f.component] as ControlTypes
-      return {
-        prop: f.key,
-        label: f.label,
-        controlType,
-        controlConfig: {
-          ...(f.props ?? {}),
-          'model-value': shadowModel[f.key],
-          // 传递 onValueChange 回调
-          _onValueChange: f.onValueChange
-        }
-      }
-    })
-})
-```
-
-然后在 `flmForm.vue` 中调用：
-
-```javascript
-config[event] = (value: any) => {
-  formChange(value, prop)
-  // 调用自定义回调
-  if (typeof controlConfig._onValueChange === 'function') {
-    controlConfig._onValueChange(value, formModel)
-  }
-}
-```
-
-## 推荐方案：方案一
-
-方案一修改最小，只需修改 `flmForm.vue` 一个文件，且保持向后兼容。
-
-## 修改步骤
-
-### Step 1: 修改 flmForm.vue
-
-文件路径：`/Users/albert/Workspaces/poba/flame-plus/src/packages/components/complex/flmForm/flmForm.vue`
-
-找到 `controlDom` 函数（约第 215 行），修改如下：
-
-```javascript
-const controlDom = (
-  prop: string,
-  controlType: ControlTypes,
-  controlConfig: ControlConfig
-) => {
-  const config: FormModel = { ...controlConfig }
-  const event = controlType === ControlTypes['flmInput'] ? 'onInput' : 'onChange'
-
-  // ====== 新增：保存并链式调用原有回调 ======
-  const originalHandler = controlConfig[event]
-  config[event] = (value: any) => {
-    // 1. 内部表单状态更新
-    formChange(value, prop)
-    // 2. 调用外部传入的回调（如果有）
-    if (typeof originalHandler === 'function') {
-      originalHandler(value)
-    }
-  }
-  // ====== 修改结束 ======
-
-  config['modelValue'] = formModel[prop]
-
-  // ... 后续代码保持不变
-}
-```
-
-### Step 2: 重新构建 flame-plus
-
-```bash
-cd /Users/albert/Workspaces/poba/flame-plus
-pnpm run build
-```
-
-### Step 3: 更新 gmp-frontend 依赖
-
-```bash
-cd /Users/albert/Workspaces/gmp/gmp-frontend/gmp-platform
-pnpm update flame-plus
-```
-
-## 验证方式
-
-修改完成后，在 `MasterForm.vue` 的 `attrFields` 中使用 `onChange`：
-
-```typescript
-attrFields: [
-  {
-    key: 'config.projectName',
-    label: '项目',
-    component: 'select',
-    props: {
-      placeholder: '请选择项目',
-      filterable: true,
-      options: PROJECT_OPTIONS,
-      onChange: (val: string) => {
-        console.log('项目已选择:', val)
-        if (val) loadTableOptions(val)
-      }
-    }
-  },
-  // ...
-]
-```
-
-当用户在属性面板中选择项目时，控制台应输出 `项目已选择: xxx`，并且 `loadTableOptions` 应被调用。
-
-## 相关文件
-
-| 文件 | 说明 |
-|------|------|
-| `/Users/albert/Workspaces/poba/flame-plus/src/packages/components/complex/flmForm/flmForm.vue` | 核心修改文件 |
-| `/Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/components/FrameworkAttrFieldsForm.vue` | attrFields 渲染组件 |
-| `/Users/albert/Workspaces/poba/flame-plus/src/packages/components/framework/types.ts` | 类型定义 |

package/docs/framework-dynamic-form-value-retrieval.md

@@ -1,153 +0,0 @@
-# 动态表单取值与提交数据详解
-
-本文说明 **`flmDynamicForm` 运行时**如何汇总各分组数据、数据在 **`flmGridForm`** 中如何维护，以及 **`componentList` 自定义控件**为何必须遵守 `onChange` / `onInput` 契约才能出现在提交结果中。
-
-与外部组件注册、设计器配置形态相关的说明见：[framework-external-components.md](./framework-external-components.md)。
-
----
-
-## 1. 总览：数据从哪来
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ flmDynamicForm (config.groups + config.buttons)                  │
-│   ├─ type === 'form'  → flmGridForm (每个分组一个实例)              │
-│   │       └─ 内部 reactive: formModel { [prop]: value }          │
-│   └─ type === 'subForm' → flm-sub-form + 本组件内 subFormData     │
-│                                                                  │
-│ 底部按钮 submit/cancel/reset → getDynamicFormData() → emit        │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-**要点**：
-
-- 动态表单**不会**遍历 DOM 或调用各控件的「取值 API」；**只读 `flmGridForm` 暴露的 `formModel` 与子表单的 `subFormData`**。
-- 任一表单项的值要进提交 payload，必须在用户交互时通过 `flmGridForm` 已注入的回调写进 `formModel[prop]`（见第 3 节）。
-
----
-
-## 2. 提交时：`getDynamicFormData` 行为
-
-源码：`src/packages/components/complex/flmDynamicForm/flmDynamicForm.vue`。
-
-### 2.1 `type === 'form'` 分组
-
-1. 用分组 **`id`** 在 `formRefs` 里取对应的 **`flmGridForm` 实例**（通过 `ref` 回调挂载）。
-2. 从实例上解析 **`formModel`**（兼容多种 Vue 3 实例形态）：
-
-   - `inst.formModel`
-   - `inst.exposed.formModel`
-   - `inst.$.exposed.formModel`
-   - `inst.$.setupState.formModel`
-
-3. 若当前 `id` 取不到 `formModel`，会**兜底**：在 `formRefs` 里找**第一个**能 `pickFormModel` 成功的实例（多表单分组时若 `id` 不一致可能出现合并错乱，应保证配置里 **`group.id` 与 ref 使用的 id 一致**）。
-4. 将 `formModel` **深拷贝为普通对象**后 **`Object.assign` 到结果根对象**，即：**同一动态表单里多个 `form` 分组的字段会摊平到同一层**；若不同分组出现相同 `prop` 键，**后遍历的分组会覆盖先遍历的**。
-
-### 2.2 `type === 'subForm'` 分组
-
-- 数据来自 **`subFormData[id]`**（与 `flm-sub-form` 的 `v-model` 同步），在结果中为 **`payload[groupId] = 行数组`**，**不摊平到根对象**。
-
-### 2.3 底部按钮与事件参数
-
-- `submit` / `cancel` / `reset`：`emit(event, getDynamicFormData())`，即上述合并后的 **payload**。
-- 其他按钮：`emit('customEvent', { event, data: btn })`，**不带**自动汇总的表单数据；若业务需要当前表单值，需自行 `ref` 动态表单或在外层监听并缓存。
-
----
-
-## 3. `flmGridForm` 内：`formModel` 如何写入
-
-源码：`src/packages/components/complex/flmGirdForm/flmGridForm.vue`。
-
-### 3.1 核心结构
-
-- `formModel`：`reactive<Record<string, any>>({})`，通过 **`expose({ formModel, reset })`** 暴露给父级。
-- 任意字段更新统一走 **`formChange(value, prop)`** → **`formModel[prop] = value`**。
-
-### 3.2 与配置的双向同步
-
-- **`props.config.model`** 变化时：`updateFormModel` 把外部 model 合并进 `formModel`；`updateControl` 把 `formModel` 同步回各 `controlConfig` 的展示值（`modelValue` 或 `model-value`，由 `isInputControl` 决定）。
-- **`formModel` 变化时：`watch(formModel, …)` → `updateControl`，保证控件 config 上的当前值与模型一致。
-
-### 3.3 表单项 `prop` 即 `formModel` 的键
-
-每个 `items[]` 项有 **`prop`（字符串）**。`controlDom` 里注入回调时使用的就是这个 **`prop`**：
-
-```ts
-;(config as any)[event] = (value: any) => formChange(value, prop)
-```
-
-因此 **提交对象里字段名 = 各表单项的 `prop`**。设计器保存时，`FlameFramework` 通常用控件内部 id 作为 `prop`（如 `ctrl_xxx_时间戳`），业务若需要固定业务字段名，需在**加载配置后映射**或改设计器生成规则（见外部组件指南第 5 节）。
-
----
-
-## 4. 控件渲染分支与「写回」方式
-
-`controlDom` 对不同类型处理不同，**只有写回路径接上了 `formChange`，值才会进 `formModel`**。
-
-| 类型 / 分支 | 写回方式 |
-|-------------|----------|
-| **`flmInput`** | `config.onInput` → `formChange(value, prop)`（注意不是 `onChange`） |
-| **`flmSearchSelect`** | 单独渲染，使用 `onUpdate` 等，内部再 `formChange` |
-| **`flmDatePicker`** | `onUpdate:modelValue` → `formChange` |
-| **`flmImage` / 上传** | `onUpload` 等 → `formChange` |
-| **`FlmEditor`** | `onUpdate` → `formChange` |
-| **其余（含 `resolveComponent` 自定义）** | 拷贝后的 `config` 上挂 **`onChange`**（非 flmInput）→ `formChange`；渲染 **`<DynamicComp config={config} />`** |
-
-**自定义组件（`componentList` 拖入、保存为某 `controlType`）**落在最后一行：**必须**在用户改值时调用传入的 **`config.onChange(newValue)`**。若错误地只使用 `emit('update:modelValue')` 而父级未绑定，**不会**更新 `formModel`。
-
-若某自定义控件**错误地把 `controlType` 设成 `flmInput`**，则框架会注入 **`onInput`**；此时组件内应调用 **`config.onInput`**，而不是 `onChange`。
-
----
-
-## 5. 单独使用 `flmGridForm` 时的取值
-
-未包在 `flmDynamicForm` 里时：
-
-- **提交类按钮**：`flmGridForm` 内在校验通过后 **`emit('submit', formModel)`**（引用同一 reactive 对象）。
-- **程序化读取**：父组件通过 **`ref` + `expose`** 拿到子组件实例，读取 **`formModel`**（与 `flmDynamicForm` 的 `pickFormModel` 目标一致）。
-
-`flmDynamicForm` 正是依赖子级 **`expose` 的 `formModel`** 做聚合，而不是依赖 `submit` 事件参数。
-
----
-
-## 6. 常见问题与排障
-
-### 6.1 基础控件有值，自定义控件提交没有
-
-1. 确认运行时 **`resolveComponent(controlType)`** 能解析到正确组件（全局注册名与 JSON 中 `controlType` 一致）。  
-2. 在自定义组件内确认用户操作后是否调用了 **`config.onChange`**（或 **`config.onInput`** 当类型为 `flmInput`）。  
-3. 确认没有把 `formModel` 当作只读：应通过回调写回，而不是仅本地 `ref`。
-
-### 6.2 多个 `form` 分组字段「串了」或只有一部分有数据
-
-- 检查每个 **`form` 分组的 `id`** 是否与 `flmDynamicForm` 里 `setFormRef(id, el)` 使用的 id 一致。  
-- 若 `id` 缺失或重复，`pickFormModel` 可能走到兜底逻辑，导致读到错误或单个实例。
-
-### 6.3 `prop` 为设计器 id，与后端字段不一致
-
-- 属**配置形态**问题：在加载 JSON 后批量改写 `items[].prop`，或在保存/加载管线做映射；不在 `getDynamicFormData` 内自动转换。
-
-### 6.4 `subForm` 有数据，`form` 没有
-
-- `subForm` 走 **`subFormData`**；`form` 走 **`flmGridForm.formModel`**。两套机制独立，勿混用。
-
----
-
-## 7. 相关源码索引
-
-| 主题 | 路径 |
-|------|------|
-| 汇总提交、`formRefs`、`pickFormModel`、`getDynamicFormData` | `src/packages/components/complex/flmDynamicForm/flmDynamicForm.vue` |
-| `formModel`、`formChange`、`controlDom`、各特殊分支、`expose` | `src/packages/components/complex/flmGirdForm/flmGridForm.vue` |
-| 保存时 `items[].prop` / `controlType` / `controlConfig` | `src/packages/components/framework/framework.vue` → `buildFrameworkConfig` |
-| 自定义控件契约（注册与设计器） | [framework-external-components.md](./framework-external-components.md) |
-
----
-
-## 8. 自检清单（取值相关）
-
-- [ ] 自定义控件在变更时调用 **`config.onChange`**（或 **`config.onInput`** 当 `controlType === 'flmInput'`）  
-- [ ] 从 **`config.modelValue` / `config['model-value']`** 读取当前值并与展示同步  
-- [ ] 多 **`form` 分组**时 **`group.id` 唯一且稳定**，与 ref 键一致  
-- [ ] 需要固定业务字段名时，已对 **`items[].prop`** 或 payload 做映射  
-- [ ] **`subForm`** 数据在 payload 中为 **`payload[groupId]`** 数组，而非根级扁平字段