@epxing/designer 5.3.0-beta.2 → 5.3.0-beta.4

package/API.md

@@ -1,160 +1,160 @@
-# @epxing/designer API
-
-页面设计器、可视化配置组件、字段配置面板及预览组件集合。
-
-本页对应包版本 `5.3.0-beta.2`。导出名、子路径和签名从当前源码、package.json 与类型声明生成。
-
-## 安装与使用
-
-
-```sh
-pnpm add @epxing/designer@5.3.0-beta.2
-```
-
-
-```js
-import Designer, { VisualComponent, PageDesigner } from '@epxing/designer'
-
-// app 已安装 core、基础组件及所需业务组件
-app.use(Designer)
-export default { extends: VisualComponent }
-```
-
-## 接入约定
-
-设计组件需要配置/元数据服务以及基础组件注册环境。default 插件同时安装公开设计组件及 widgetPreviews；具名组件适合局部使用和继承。远程共享产品应导入公开组件，插件由宿主安装。
-
-本版 JS 入口自动加载本包聚合样式，根导入和稳定子路径均无需手动 import style.css；保留显式样式入口以兼容旧代码。样式按包加载，产品覆盖样式放在框架导入之后。
-
-## 根入口完整导出
-
-| 导出名 | 形态 | 用途 | 参数 / 配置 / 事件 |
-| --- | --- | --- | --- |
-| `install` | 函数 | 向 Vue 应用注册本包的组件；通常通过 app.use(defaultPlugin) 调用。 | 见下方签名或接入约定 |
-| `ProcessFormItemVisual` | Vue 组件 | 流程表单项的可视化配置组件，继承 VisualComponent，按流程代码读取节点并编辑节点配置。 | [详细参考](../../docs/revision/designer/visual/widgets/ProcessFormItemVisual.md) |
-| `VisualComponent` | Vue 组件 | 可视化配置组件基类，维护 allConfigs、配置项变更及设计上下文；产品设计面板可继承。 | [详细参考](../../docs/revision/designer/visual/Component.md) |
-| `VisualConfigPage` | Vue 组件 | 页面可视化配置容器，组织页面属性与配置面板。 | [详细参考](../../docs/revision/designer/visual/config-page/VisualConfigPage.md) |
-| `VisualEntityList` | Vue 组件 | 实体列表的可视化配置组件，编辑列表字段、查询和操作配置。 | [详细参考](../../docs/revision/designer/visual/EntityList.md) |
-| `VisualEntitySubList` | Vue 组件 | 实体子列表的可视化配置组件，编辑子表字段与关联配置。 | [详细参考](../../docs/revision/designer/visual/EntitySubList.md) |
-| `VisualConfigField` | Vue 组件 | 表单字段配置面板，编辑字段及其显示、输入配置。 | [详细参考](../../docs/revision/designer/visual/config/Field.md) |
-| `VisualConfigListField` | Vue 组件 | 列表字段配置面板，编辑展示列和字段配置。 | [详细参考](../../docs/revision/designer/visual/config/ListField.md) |
-| `VisualConfigOrderField` | Vue 组件 | 排序字段配置面板，编辑排序字段及顺序。 | [详细参考](../../docs/revision/designer/visual/config/OrderField.md) |
-| `PageDesigner` | Vue 组件 | 可视化页面设计器，提供挂件库、页面画布、层级与属性面板。 | [详细参考](../../docs/revision/designer/page-designer/PageDesigner.md) |
-| `CardFormItemVisual` | Vue 组件 | 卡片表单项配置面板，编辑卡片中字段的呈现配置。 | [详细参考](../../docs/revision/designer/visual/widgets/CardFormItemVisual.md) |
-| `CarouselVisual` | Vue 组件 | 轮播容器配置面板，编辑轮播项和呈现配置。 | [详细参考](../../docs/revision/designer/visual/widgets/CarouselVisual.md) |
-| `CollapseVisual` | Vue 组件 | 折叠容器配置面板，编辑折叠项和交互配置。 | [详细参考](../../docs/revision/designer/visual/widgets/CollapseVisual.md) |
-| `DropdownVisual` | Vue 组件 | 下拉容器配置面板，编辑下拉内容和呈现配置。 | [详细参考](../../docs/revision/designer/visual/widgets/DropdownVisual.md) |
-| `LayoutConfig` | Vue 组件 | 布局配置面板，编辑容器和列的布局配置。 | [详细参考](../../docs/revision/designer/visual/widgets/LayoutConfig.md) |
-| `ListVisual` | Vue 组件 | 列表挂件配置面板，编辑条目和呈现配置。 | [详细参考](../../docs/revision/designer/visual/widgets/ListVisual.md) |
-| `MEntityListFindVisual` | Vue 组件 | 移动实体选择列表的可视化配置面板。 | [详细参考](../../docs/revision/designer/visual/widgets/MEntityListFindVisual.md) |
-| `TabsConfig` | Vue 组件 | 标签页配置面板，编辑标签项及其内容配置。 | [详细参考](../../docs/revision/designer/visual/widgets/TabsConfig.md) |
-| `widgetPreviews` | 对象 / 常量 | 设计器预览组件映射，供设计插件注册和画布预览使用。 | [详细参考](../../docs/revision/designer/api/page-designer/previews/index.md) |
-| `default` | 默认导出 | 设计插件对象，包含 install、公开设计组件及预览组件。 | 见下方签名或接入约定 |
-
-## 函数、类与工具对象
-
-签名中的 any 表示现有声明未进一步限定结构；源代码方法签名保留默认参数。异步结果与泛型以声明为准。
-
-### widgetPreviews
-
-设计器预览组件映射，供设计插件注册和画布预览使用。
-
-通过 `widgetPreviews.成员名` 访问，下面的成员不是额外的根具名导出。
-
-| 成员名 | 用途 | 配置参考 |
-| --- | --- | --- |
-| `ButtonPreview` | 按钮在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/button/Preview.md) |
-| `CardPreview` | 卡片在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/card/Preview.md) |
-| `IconPreview` | 图标在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/icon/Preview.md) |
-| `HtmlPreview` | HTML在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/html/Preview.md) |
-| `ImagePreview` | 图片在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/image/Preview.md) |
-| `NumPreview` | 数字在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/num/Preview.md) |
-| `VideoPreview` | 视频在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/video/Preview.md) |
-| `TextPreview` | 文本在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/text/Preview.md) |
-| `StepPreview` | 步骤在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/step/Preview.md) |
-| `GridPreview` | 网格在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/grid/Preview.md) |
-| `PageTabsPreview` | 页面标签在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/page-tabs/Preview.md) |
-| `TextEditorPreview` | 富文本在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/text-editor/Preview.md) |
-| `AddFormPreview` | 新增表单在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/add-form/Preview.md) |
-| `AddFormItemPreview` | 表单分组在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/add-form-item/Preview.md) |
-| `EntityListPreview` | 实体列表在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/entity-list/Preview.md) |
-| `EntitySubListPreview` | 实体子列表在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/entity-sub-list/Preview.md) |
-| `EntityVirtualListPreview` | 实体虚拟列表在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/entity-virtual-list/Preview.md) |
-| `LayoutPreview` | 布局容器在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/layout/Preview.md) |
-| `LayoutColumnPreview` | 布局列在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/layout/ColumnPreview.md) |
-| `CarouselPreview` | 轮播容器在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/carousel/Preview.md) |
-| `CarouselItemPreview` | 轮播项在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/carousel/CarouselItemPreview.md) |
-| `CollapsePreview` | 折叠容器在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/collapse/Preview.md) |
-| `CollapseItemPreview` | 折叠项在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/collapse/CollapseItemPreview.md) |
-| `DropdownPreview` | 下拉内容在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/dropdown/Preview.md) |
-| `TabsPreview` | 标签页容器在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/tabs/Preview.md) |
-| `TabsTabPanePreview` | 标签页内容在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/tabs/tab-pane/Preview.md) |
-| `FormFieldTextareaPreview` | 多行文本字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/Textarea.md) |
-| `FormFieldSelectPreview` | 选项字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/Select.md) |
-| `FormFieldRadioPreview` | 单选字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/Radio.md) |
-| `FormFieldObjectPreview` | 关联对象字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/Object.md) |
-| `FormFieldInputNumberPreview` | 数字字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/InputNumber.md) |
-| `FormFieldInputPreview` | 文本字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/Input.md) |
-| `FormFieldDatePreview` | 日期字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/Date.md) |
-| `FormFieldCheckboxPreview` | 多选字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/Checkbox.md) |
-
-## 稳定子路径
-
-下表按实际 package.json 的公开入口列出。default 使用默认导入，其他名称使用具名导入；类型接口用 import type。
-
-| 导入路径 | 完整导出名 | 用途 / 详细说明 |
-| --- | --- | --- |
-| `@epxing/designer/page-designer` | `default`、`WidgetPreviewMixin` | 可视化页面设计器，提供挂件库、页面画布、层级与属性面板。 [详细参考](../../docs/revision/designer/page-designer/PageDesigner.md) |
-| `@epxing/designer/visual-component` | `default` | 可视化配置组件基类，维护 allConfigs、配置项变更及设计上下文；产品设计面板可继承。 [详细参考](../../docs/revision/designer/visual/Component.md) |
-| `@epxing/designer/visual-entity-list` | `default` | 实体列表的可视化配置组件，编辑列表字段、查询和操作配置。 [详细参考](../../docs/revision/designer/visual/EntityList.md) |
-| `@epxing/designer/visual-entity-sub-list` | `default` | 实体子列表的可视化配置组件，编辑子表字段与关联配置。 [详细参考](../../docs/revision/designer/visual/EntitySubList.md) |
-| `@epxing/designer/style.css` | 可选的显式样式入口 | JS 入口自动加载本包样式；保留此路径以兼容旧代码。 |
-
-## 子路径补充导出
-
-本节列出仅在稳定子路径中提供的具名 API；从本节标题对应路径导入。
-
-### @epxing/designer/page-designer
-
-| 导出 / 调用签名 | 用途 | 详细接口 |
-| --- | --- | --- |
-| `WidgetPreviewMixin` | 画布挂件预览的公共混入，提供预览组件的上下文、交互和配置协议。 | [详细参考](../../docs/revision/designer/api/page-designer/widget-preview/Mixin.md) |
-
-## 源码兼容与其他入口
-
-/src 路径保留给已有产品和源码级扩展，可能包含平台内部实现；新产品优先采用上方根导出与稳定子路径。通配符表示按实际文件名匹配，不代表所有源码都属于根入口。
-
-| 公开路径模式 | 实际目标 |
-| --- | --- |
-| `@epxing/designer/src` | `./dist/src/index.js` |
-| `@epxing/designer/src/page-designer` | `./dist/src/page-designer/index.js` |
-| `@epxing/designer/src/page-designer/page-variable-panel` | `./dist/src/page-designer/page-variable-panel/index.js` |
-| `@epxing/designer/src/page-designer/previews` | `./dist/src/page-designer/previews/index.js` |
-| `@epxing/designer/src/page-designer/setting-panel` | `./dist/src/page-designer/setting-panel/index.js` |
-| `@epxing/designer/src/page-designer/template-attribute-panel` | `./dist/src/page-designer/template-attribute-panel/index.js` |
-| `@epxing/designer/src/page-designer/template-library` | `./dist/src/page-designer/template-library/index.js` |
-| `@epxing/designer/src/page-designer/widget-library` | `./dist/src/page-designer/widget-library/index.js` |
-| `@epxing/designer/src/page-designer/widget-preview` | `./dist/src/page-designer/widget-preview/index.js` |
-| `@epxing/designer/src/page-designer/widget-tree` | `./dist/src/page-designer/widget-tree/index.js` |
-| `@epxing/designer/src/visual` | `./dist/src/visual/index.js` |
-| `@epxing/designer/src/visual/config-page` | `./dist/src/visual/config-page/index.js` |
-| `@epxing/designer/src/visual/config-page/dashboard-theme-setting` | `./dist/src/visual/config-page/dashboard-theme-setting/index.js` |
-| `@epxing/designer/src/visual/step` | `./dist/src/visual/step/index.js` |
-| `@epxing/designer/src/*.css` | `./src/*.css` |
-| `@epxing/designer/src/*.scss` | `./src/*.scss` |
-| `@epxing/designer/src/*.png` | `./src/*.png` |
-| `@epxing/designer/src/*.svg` | `./src/*.svg` |
-| `@epxing/designer/src/*.jpg` | `./src/*.jpg` |
-| `@epxing/designer/src/*.gif` | `./src/*.gif` |
-| `@epxing/designer/src/*.woff` | `./src/*.woff` |
-| `@epxing/designer/src/*.woff2` | `./src/*.woff2` |
-| `@epxing/designer/src/*.ttf` | `./src/*.ttf` |
-| `@epxing/designer/src/*.js` | `./dist/src/*.js` |
-| `@epxing/designer/src/*.jsx` | `./dist/src/*.js` |
-| `@epxing/designer/src/*.vue` | `./dist/src/*.js` |
-| `@epxing/designer/src/*` | `./dist/src/*.js` |
-| `@epxing/designer/package.json` | `./package.json` |
-
-## 文档维护
-
-本页由 build/gen-package-api-docs.mjs 生成。修改公开入口并更新构建产物和类型声明后，在框架根运行 `pnpm docs:api`；`pnpm docs:api:check` 检查清单、类型、包内文档与站点镜像是否同步，同时验证页面编译和文档链接。用途和示例维护在 build/package-api-notes.mjs，组件和源码方法的详细参考位于 docs/revision。
+# @epxing/designer API
+
+页面设计器、可视化配置组件、字段配置面板及预览组件集合。
+
+本页对应包版本 `5.3.0-beta.4`。导出名、子路径和签名从当前源码、package.json 与类型声明生成。
+
+## 安装与使用
+
+
+```sh
+pnpm add @epxing/designer@5.3.0-beta.2
+```
+
+
+```js
+import Designer, { VisualComponent, PageDesigner } from '@epxing/designer'
+
+// app 已安装 core、基础组件及所需业务组件
+app.use(Designer)
+export default { extends: VisualComponent }
+```
+
+## 接入约定
+
+设计组件需要配置/元数据服务以及基础组件注册环境。default 插件同时安装公开设计组件及 widgetPreviews；具名组件适合局部使用和继承。远程共享产品应导入公开组件，插件由宿主安装。
+
+本版 JS 入口自动加载本包聚合样式，根导入和稳定子路径均无需手动 import style.css；保留显式样式入口以兼容旧代码。样式按包加载，产品覆盖样式放在框架导入之后。
+
+## 根入口完整导出
+
+| 导出名 | 形态 | 用途 | 参数 / 配置 / 事件 |
+| --- | --- | --- | --- |
+| `install` | 函数 | 向 Vue 应用注册本包的组件；通常通过 app.use(defaultPlugin) 调用。 | 见下方签名或接入约定 |
+| `ProcessFormItemVisual` | Vue 组件 | 流程表单项的可视化配置组件，继承 VisualComponent，按流程代码读取节点并编辑节点配置。 | [详细参考](../../docs/revision/designer/visual/widgets/ProcessFormItemVisual.md) |
+| `VisualComponent` | Vue 组件 | 可视化配置组件基类，维护 allConfigs、配置项变更及设计上下文；产品设计面板可继承。 | [详细参考](../../docs/revision/designer/visual/Component.md) |
+| `VisualConfigPage` | Vue 组件 | 页面可视化配置容器，组织页面属性与配置面板。 | [详细参考](../../docs/revision/designer/visual/config-page/VisualConfigPage.md) |
+| `VisualEntityList` | Vue 组件 | 实体列表的可视化配置组件，编辑列表字段、查询和操作配置。 | [详细参考](../../docs/revision/designer/visual/EntityList.md) |
+| `VisualEntitySubList` | Vue 组件 | 实体子列表的可视化配置组件，编辑子表字段与关联配置。 | [详细参考](../../docs/revision/designer/visual/EntitySubList.md) |
+| `VisualConfigField` | Vue 组件 | 表单字段配置面板，编辑字段及其显示、输入配置。 | [详细参考](../../docs/revision/designer/visual/config/Field.md) |
+| `VisualConfigListField` | Vue 组件 | 列表字段配置面板，编辑展示列和字段配置。 | [详细参考](../../docs/revision/designer/visual/config/ListField.md) |
+| `VisualConfigOrderField` | Vue 组件 | 排序字段配置面板，编辑排序字段及顺序。 | [详细参考](../../docs/revision/designer/visual/config/OrderField.md) |
+| `PageDesigner` | Vue 组件 | 可视化页面设计器，提供挂件库、页面画布、层级与属性面板。 | [详细参考](../../docs/revision/designer/page-designer/PageDesigner.md) |
+| `CardFormItemVisual` | Vue 组件 | 卡片表单项配置面板，编辑卡片中字段的呈现配置。 | [详细参考](../../docs/revision/designer/visual/widgets/CardFormItemVisual.md) |
+| `CarouselVisual` | Vue 组件 | 轮播容器配置面板，编辑轮播项和呈现配置。 | [详细参考](../../docs/revision/designer/visual/widgets/CarouselVisual.md) |
+| `CollapseVisual` | Vue 组件 | 折叠容器配置面板，编辑折叠项和交互配置。 | [详细参考](../../docs/revision/designer/visual/widgets/CollapseVisual.md) |
+| `DropdownVisual` | Vue 组件 | 下拉容器配置面板，编辑下拉内容和呈现配置。 | [详细参考](../../docs/revision/designer/visual/widgets/DropdownVisual.md) |
+| `LayoutConfig` | Vue 组件 | 布局配置面板，编辑容器和列的布局配置。 | [详细参考](../../docs/revision/designer/visual/widgets/LayoutConfig.md) |
+| `ListVisual` | Vue 组件 | 列表挂件配置面板，编辑条目和呈现配置。 | [详细参考](../../docs/revision/designer/visual/widgets/ListVisual.md) |
+| `MEntityListFindVisual` | Vue 组件 | 移动实体选择列表的可视化配置面板。 | [详细参考](../../docs/revision/designer/visual/widgets/MEntityListFindVisual.md) |
+| `TabsConfig` | Vue 组件 | 标签页配置面板，编辑标签项及其内容配置。 | [详细参考](../../docs/revision/designer/visual/widgets/TabsConfig.md) |
+| `widgetPreviews` | 对象 / 常量 | 设计器预览组件映射，供设计插件注册和画布预览使用。 | [详细参考](../../docs/revision/designer/api/page-designer/previews/index.md) |
+| `default` | 默认导出 | 设计插件对象，包含 install、公开设计组件及预览组件。 | 见下方签名或接入约定 |
+
+## 函数、类与工具对象
+
+签名中的 any 表示现有声明未进一步限定结构；源代码方法签名保留默认参数。异步结果与泛型以声明为准。
+
+### widgetPreviews
+
+设计器预览组件映射，供设计插件注册和画布预览使用。
+
+通过 `widgetPreviews.成员名` 访问，下面的成员不是额外的根具名导出。
+
+| 成员名 | 用途 | 配置参考 |
+| --- | --- | --- |
+| `ButtonPreview` | 按钮在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/button/Preview.md) |
+| `CardPreview` | 卡片在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/card/Preview.md) |
+| `IconPreview` | 图标在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/icon/Preview.md) |
+| `HtmlPreview` | HTML在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/html/Preview.md) |
+| `ImagePreview` | 图片在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/image/Preview.md) |
+| `NumPreview` | 数字在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/num/Preview.md) |
+| `VideoPreview` | 视频在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/video/Preview.md) |
+| `TextPreview` | 文本在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/text/Preview.md) |
+| `StepPreview` | 步骤在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/step/Preview.md) |
+| `GridPreview` | 网格在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/grid/Preview.md) |
+| `PageTabsPreview` | 页面标签在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/page-tabs/Preview.md) |
+| `TextEditorPreview` | 富文本在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/text-editor/Preview.md) |
+| `AddFormPreview` | 新增表单在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/add-form/Preview.md) |
+| `AddFormItemPreview` | 表单分组在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/add-form-item/Preview.md) |
+| `EntityListPreview` | 实体列表在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/entity-list/Preview.md) |
+| `EntitySubListPreview` | 实体子列表在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/entity-sub-list/Preview.md) |
+| `EntityVirtualListPreview` | 实体虚拟列表在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/entity-virtual-list/Preview.md) |
+| `LayoutPreview` | 布局容器在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/layout/Preview.md) |
+| `LayoutColumnPreview` | 布局列在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/layout/ColumnPreview.md) |
+| `CarouselPreview` | 轮播容器在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/carousel/Preview.md) |
+| `CarouselItemPreview` | 轮播项在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/carousel/CarouselItemPreview.md) |
+| `CollapsePreview` | 折叠容器在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/collapse/Preview.md) |
+| `CollapseItemPreview` | 折叠项在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/collapse/CollapseItemPreview.md) |
+| `DropdownPreview` | 下拉内容在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/dropdown/Preview.md) |
+| `TabsPreview` | 标签页容器在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/tabs/Preview.md) |
+| `TabsTabPanePreview` | 标签页内容在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/tabs/tab-pane/Preview.md) |
+| `FormFieldTextareaPreview` | 多行文本字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/Textarea.md) |
+| `FormFieldSelectPreview` | 选项字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/Select.md) |
+| `FormFieldRadioPreview` | 单选字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/Radio.md) |
+| `FormFieldObjectPreview` | 关联对象字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/Object.md) |
+| `FormFieldInputNumberPreview` | 数字字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/InputNumber.md) |
+| `FormFieldInputPreview` | 文本字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/Input.md) |
+| `FormFieldDatePreview` | 日期字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/Date.md) |
+| `FormFieldCheckboxPreview` | 多选字段在页面设计画布中的预览组件。 | [详细参考](../../docs/revision/designer/page-designer/previews/form-field/preview/Checkbox.md) |
+
+## 稳定子路径
+
+下表按实际 package.json 的公开入口列出。default 使用默认导入，其他名称使用具名导入；类型接口用 import type。
+
+| 导入路径 | 完整导出名 | 用途 / 详细说明 |
+| --- | --- | --- |
+| `@epxing/designer/page-designer` | `default`、`WidgetPreviewMixin` | 可视化页面设计器，提供挂件库、页面画布、层级与属性面板。 [详细参考](../../docs/revision/designer/page-designer/PageDesigner.md) |
+| `@epxing/designer/visual-component` | `default` | 可视化配置组件基类，维护 allConfigs、配置项变更及设计上下文；产品设计面板可继承。 [详细参考](../../docs/revision/designer/visual/Component.md) |
+| `@epxing/designer/visual-entity-list` | `default` | 实体列表的可视化配置组件，编辑列表字段、查询和操作配置。 [详细参考](../../docs/revision/designer/visual/EntityList.md) |
+| `@epxing/designer/visual-entity-sub-list` | `default` | 实体子列表的可视化配置组件，编辑子表字段与关联配置。 [详细参考](../../docs/revision/designer/visual/EntitySubList.md) |
+| `@epxing/designer/style.css` | 可选的显式样式入口 | JS 入口自动加载本包样式；保留此路径以兼容旧代码。 |
+
+## 子路径补充导出
+
+本节列出仅在稳定子路径中提供的具名 API；从本节标题对应路径导入。
+
+### @epxing/designer/page-designer
+
+| 导出 / 调用签名 | 用途 | 详细接口 |
+| --- | --- | --- |
+| `WidgetPreviewMixin` | 画布挂件预览的公共混入，提供预览组件的上下文、交互和配置协议。 | [详细参考](../../docs/revision/designer/api/page-designer/widget-preview/Mixin.md) |
+
+## 源码兼容与其他入口
+
+/src 路径保留给已有产品和源码级扩展，可能包含平台内部实现；新产品优先采用上方根导出与稳定子路径。通配符表示按实际文件名匹配，不代表所有源码都属于根入口。
+
+| 公开路径模式 | 实际目标 |
+| --- | --- |
+| `@epxing/designer/src` | `./dist/src/index.js` |
+| `@epxing/designer/src/page-designer` | `./dist/src/page-designer/index.js` |
+| `@epxing/designer/src/page-designer/page-variable-panel` | `./dist/src/page-designer/page-variable-panel/index.js` |
+| `@epxing/designer/src/page-designer/previews` | `./dist/src/page-designer/previews/index.js` |
+| `@epxing/designer/src/page-designer/setting-panel` | `./dist/src/page-designer/setting-panel/index.js` |
+| `@epxing/designer/src/page-designer/template-attribute-panel` | `./dist/src/page-designer/template-attribute-panel/index.js` |
+| `@epxing/designer/src/page-designer/template-library` | `./dist/src/page-designer/template-library/index.js` |
+| `@epxing/designer/src/page-designer/widget-library` | `./dist/src/page-designer/widget-library/index.js` |
+| `@epxing/designer/src/page-designer/widget-preview` | `./dist/src/page-designer/widget-preview/index.js` |
+| `@epxing/designer/src/page-designer/widget-tree` | `./dist/src/page-designer/widget-tree/index.js` |
+| `@epxing/designer/src/visual` | `./dist/src/visual/index.js` |
+| `@epxing/designer/src/visual/config-page` | `./dist/src/visual/config-page/index.js` |
+| `@epxing/designer/src/visual/config-page/dashboard-theme-setting` | `./dist/src/visual/config-page/dashboard-theme-setting/index.js` |
+| `@epxing/designer/src/visual/step` | `./dist/src/visual/step/index.js` |
+| `@epxing/designer/src/*.css` | `./src/*.css` |
+| `@epxing/designer/src/*.scss` | `./src/*.scss` |
+| `@epxing/designer/src/*.png` | `./src/*.png` |
+| `@epxing/designer/src/*.svg` | `./src/*.svg` |
+| `@epxing/designer/src/*.jpg` | `./src/*.jpg` |
+| `@epxing/designer/src/*.gif` | `./src/*.gif` |
+| `@epxing/designer/src/*.woff` | `./src/*.woff` |
+| `@epxing/designer/src/*.woff2` | `./src/*.woff2` |
+| `@epxing/designer/src/*.ttf` | `./src/*.ttf` |
+| `@epxing/designer/src/*.js` | `./dist/src/*.js` |
+| `@epxing/designer/src/*.jsx` | `./dist/src/*.js` |
+| `@epxing/designer/src/*.vue` | `./dist/src/*.js` |
+| `@epxing/designer/src/*` | `./dist/src/*.js` |
+| `@epxing/designer/package.json` | `./package.json` |
+
+## 文档维护
+
+本页由 build/gen-package-api-docs.mjs 生成。修改公开入口并更新构建产物和类型声明后，在框架根运行 `pnpm docs:api`；`pnpm docs:api:check` 检查清单、类型、包内文档与站点镜像是否同步，同时验证页面编译和文档链接。用途和示例维护在 build/package-api-notes.mjs，组件和源码方法的详细参考位于 docs/revision。

package/README.md

@@ -1,46 +1,46 @@
-# @epxing/designer
-
-[完整公开 API、导入方式与示例](./API.md)
-
-从 5.3.0-beta.2 起，导入本包 JS 时自动加载包级样式，根入口和稳定子路径均无需手动引入 style.css。显式样式入口继续兼容旧代码；产品覆盖样式放在框架导入之后。
-
-可视化配置体系包 - **设计态独有，运行时按需加载**。
-
-## 范围
-
-- `src/frame/page-designer/`（整目录）
-- 各 package 的 `Visual.vue` / `Config.vue`（T07 抽出，14+ 处）
-- 各 package 的 `Preview.vue`（T08 抽出，35+ 处）
-- `src/frame/views/visual/`
-- `src/frame/views/{FormDesign,ExcelDesign,Bpmn}.vue`
-- `src/frame/views/report/` / `src/frame/views/match/`
-- `src/frame/packages/visual-config-page/`
-
-## 加载策略
-
-`apps/platform` 路由层 `() => import('@epxing/designer')` 懒加载，运行时进入设计页面才下载。
-
-## 依赖
-
-- `@epxing/utils`
-- `@epxing/theme`
-- `@epxing/core`
-- `@epxing/components`
-
-## 状态
-
-已提供公共根入口、稳定组件子路径和类型声明。
-
-
-## 独立包公共入口（2026-10-22）
-
-根入口及稳定子路径提供类型声明。先安装 core 与需要的 component，再按需安装本包。
-
-产品设计面板可从根入口具名导入 VisualComponent、VisualEntityList 等，或默认导入 `@epxing/designer/visual-component`。远程产品通过 epxShared 复用宿主设计态组件，整包安装由宿主负责。详见 `docs/guide/getting-started/packages.md`。
-
-```js
-import plugin from '@epxing/designer'
-app.use(plugin)
-```
-
-工作区构建：`pnpm --filter @epxing/designer build`。pack/publish 的 prepack 会重建；版本由 Changesets 独立管理。旧 `/src/*` 入口保留。完整初始化、打包与远程共享流程见 docs/build-and-publish.md。
+# @epxing/designer
+
+[完整公开 API、导入方式与示例](./API.md)
+
+从 5.3.0-beta.2 起，导入本包 JS 时自动加载包级样式，根入口和稳定子路径均无需手动引入 style.css。显式样式入口继续兼容旧代码；产品覆盖样式放在框架导入之后。
+
+可视化配置体系包 - **设计态独有，运行时按需加载**。
+
+## 范围
+
+- `src/frame/page-designer/`（整目录）
+- 各 package 的 `Visual.vue` / `Config.vue`（T07 抽出，14+ 处）
+- 各 package 的 `Preview.vue`（T08 抽出，35+ 处）
+- `src/frame/views/visual/`
+- `src/frame/views/{FormDesign,ExcelDesign,Bpmn}.vue`
+- `src/frame/views/report/` / `src/frame/views/match/`
+- `src/frame/packages/visual-config-page/`
+
+## 加载策略
+
+`apps/platform` 路由层 `() => import('@epxing/designer')` 懒加载，运行时进入设计页面才下载。
+
+## 依赖
+
+- `@epxing/utils`
+- `@epxing/theme`
+- `@epxing/core`
+- `@epxing/components`
+
+## 状态
+
+已提供公共根入口、稳定组件子路径和类型声明。
+
+
+## 独立包公共入口（2026-10-22）
+
+根入口及稳定子路径提供类型声明。先安装 core 与需要的 component，再按需安装本包。
+
+产品设计面板可从根入口具名导入 VisualComponent、VisualEntityList 等，或默认导入 `@epxing/designer/visual-component`。远程产品通过 epxShared 复用宿主设计态组件，整包安装由宿主负责。详见 `docs/guide/getting-started/packages.md`。
+
+```js
+import plugin from '@epxing/designer'
+app.use(plugin)
+```
+
+工作区构建：`pnpm --filter @epxing/designer build`。pack/publish 的 prepack 会重建；版本由 Changesets 独立管理。旧 `/src/*` 入口保留。完整初始化、打包与远程共享流程见 docs/build-and-publish.md。

package/dist/src/page-designer/PageDesigner.js

@@ -151,6 +151,17 @@ const _sfc_main = {
           };
         }
       });
+    },
+    // 切换组件后预览区会按新组件重建 DOM，选中浮层需重新定位到新元素（选中其它组件由上面的监听处理）
+    "designer.selectedWidget.contentType"() {
+      const widget = this.designer.selectedWidget;
+      if (!widget || this.selectedWidgetData.widget !== widget) return;
+      this.$nextTick(() => {
+        this.selectedWidgetData = {
+          ...this.selectedWidgetData,
+          element: document.querySelector(`[data-widget-id="${widget.id}"]`)
+        };
+      });
     }
   },
   methods: {

package/dist/src/page-designer/designer.js

@@ -955,6 +955,27 @@ function createDesigner(vueInstance) {
         }
       }
     },
+    /**
+     * 切换组件类型：只换 contentType（及自定义组件的 type 标记），组件 id 不变，
+     * 因此按 id 存的组件配置（itemConfigs）、子组件、样式等全部保留
+     * @param { Object } widget 要切换的组件
+     * @param { Object } widgetInfo 目标组件记录（组件库中的 FM_PAGE）
+     */
+    switchWidget(widget, widgetInfo) {
+      const oldInfo = this.getWidgetByType(widget.contentType, widget.type) || {};
+      const property = {
+        contentType: widgetInfo.CODE,
+        type: widgetInfo.COMPONENT_SOURCE === "custom" ? "custom" : null
+      };
+      if (!widget.title || widget.title === oldInfo.TITLE) {
+        property.title = widgetInfo.TITLE;
+      }
+      this.updateWidget(widget.id, property);
+      const { metaId } = this.widgetConfig[widget.id] || {};
+      if (widgetInfo.CODE === "chart" && !metaId) {
+        this.updateWidgetConfig(widget.id, { metaId: this.page.metaId });
+      }
+    },
     addContainerByDbClick(container) {
       const newCon = this.copyNewContainerWidget(container);
       this.widgetList.push(newCon);

package/dist/src/page-designer/previews/add-form/Preview.js

@@ -2,7 +2,7 @@ import '../../../../style.css';
 import _sfc_main from "./Preview.vue.js";
 /* empty css             */
 import _export_sfc from "../../../../_virtual/_plugin-vue_export-helper.js";
-const AddFormPreview = /* @__PURE__ */ _export_sfc(_sfc_main, [["__scopeId", "data-v-59a0f3d2"]]);
+const AddFormPreview = /* @__PURE__ */ _export_sfc(_sfc_main, [["__scopeId", "data-v-0554afd8"]]);
 export {
   AddFormPreview as default
 };

package/dist/src/page-designer/previews/add-form/Preview.vue.js

@@ -1,4 +1,4 @@
-import { createVNode, createTextVNode, resolveComponent, mergeProps, isVNode } from "vue";
+import { createVNode, resolveComponent, mergeProps, createTextVNode, isVNode } from "vue";
 import previewMixin from "../../widget-preview/Mixin.js";
 import { MobileActionSheet } from "@epxing/components/src/mobile";
 function _isSlot(s) {
@@ -196,14 +196,13 @@ const _sfc_main = {
       }, [this.renderCatalogList(this.childWidgetList)])]);
     },
     renderForm() {
-      let _slot2;
       const {
-        operateFlag,
-        showCatalog
+        operatePosition
       } = this.$configs;
+      const operateTop = operatePosition === "top" && !this.$isMobile;
       return createVNode("div", {
         "class": "epx-add-form__content"
-      }, [createVNode("div", {
+      }, [operateTop && this.renderOperateArea(true), createVNode("div", {
         "class": "epx-add-form__field-group epx-page-designer-widget-preview__drop-zone",
         "ref": "addForm"
       }, [createVNode("div", {
@@ -223,7 +222,17 @@ const _sfc_main = {
         }, [this.renderComponent(component)]);
       }), this.childWidgetList.length === 0 && createVNode("div", {
         "class": "epx-page-designer-widget-preview__no-widget"
-      }, [createTextVNode("拖拽表单项到这里")])])]), !this.readonly && operateFlag && !(showCatalog && !this.$isMobile) && createVNode("div", null, [this.$isMobile ? createVNode("div", {
+      }, [createTextVNode("拖拽表单项到这里")])])]), !operateTop && this.renderOperateArea(false)]);
+    },
+    // 表单区按钮区；PC 端开了目录时按钮在目录区渲染，此处不渲染
+    renderOperateArea(top) {
+      let _slot2;
+      const {
+        operateFlag,
+        showCatalog
+      } = this.$configs;
+      if (this.readonly || !operateFlag || showCatalog && !this.$isMobile) return null;
+      return createVNode("div", null, [this.$isMobile ? createVNode("div", {
         "class": ["epx-add-form__m-buttongroup", {
           "epx-add-form__m-button-more": this.operates.length > 3
         }]
@@ -257,7 +266,9 @@ const _sfc_main = {
       }, {
         default: () => [operate.text]
       }))])]) : createVNode("div", {
-        "class": "epx-add-form__button-group"
+        "class": ["epx-add-form__button-group", {
+          "epx-add-form__button-group--top": top
+        }]
       }, [this.operates.map((operate) => createVNode(resolveComponent("el-button"), mergeProps({
         "loading": this.httpLoading[operate.handler + "-" + operate.text],
         "size": "default",
@@ -273,7 +284,7 @@ const _sfc_main = {
         default: () => [operate.icon && createVNode("i", {
           "class": [operate.icon]
         }, null), operate.text]
-      }))])])]);
+      }))])]);
     }
   },
   created() {