1

2026-04-15 15:05:36 +08:00
parent 3f27c350e2
commit 6cd965a336
1 changed files with 170 additions and 10 deletions
--- a/README.md
+++ b/README.md
@@ -737,18 +737,178 @@ Main 中示例：`<ABackTop container=".content-wrapper" :height="100" :bottom="
 | **CommonIcon** | `type`：普通 `Icon` 名；自定义图标以 `_` 开头配合 `md-icons`。`size`、`color` 可选。 |
 | **LoadFlower** | 全屏 loading 占位（与 `http` 的 `showLoad` 通过 DOM `id` 联动），一般随 `Main` 挂载，无需单独使用。 |

-### 12.12 未全局注册、按需引用的组件
+### 12.12 未全局注册、按需引用的组件（详细）

-以下在 `src/components` 下，需在页面中 **import** 后注册或局部引用：
+以下组件不在 `registerGlobalComponents` 中，需要页面内 `import` 后再注册。示例路径基于源码工程 `@/components/...`。

-| 路径/名称 | 说明 |
-|-----------|------|
-| `login-form` | 登录表单：`userNameRules`、`passwordRules`；校验通过 `@on-success-valid` 抛出 `{ userName, password }`。 |
-| `date-picker/index.vue` | 对 `DatePicker` 的 `v-model` 封装，`change`/`input`。 |
-| `switch/index.vue` | 对 `Switch` 的 `v-model` 封装。 |
-| `cron-input` | Cron 表达式下拉选择。 |
-| `main/pageHead.vue` | 页面顶栏条：当 `$route.meta.type === '功能'` 时显示返回；默认插槽放按钮。 |
-| `markdown`、`cropper` 等 | 见各目录 `index.js` / 入口组件。 |
+#### 12.12.1 `login-form/login-form.vue`（`LoginForm`）
+
+- 用途：登录页账号密码表单，内置 Enter 提交与 `Form.validate`。
+- Props：
+  - `userNameRules: Array`（默认必填）
+  - `passwordRules: Array`（默认必填）
+- 事件：
+  - `on-success-valid`：校验成功后抛出 `{ userName, password }`
+
+```vue
+<LoginForm @on-success-valid="handleLogin" />
+```
+
+#### 12.12.2 `date-picker/index.vue`（`DatePicker` 封装）
+
+- 用途：统一 `DatePicker` 的 `v-model` 语义。
+- Props：`value`
+- 事件：`input`、`change`
+- 说明：其余能力通过 `v-bind="$attrs"` 透传到 iView `DatePicker`。
+
+```vue
+<DatePicker v-model="form.start_time" type="datetime" />
+```
+
+#### 12.12.3 `switch/index.vue`（`FrameworkSwitch`）
+
+- 用途：布尔/0/1 字段统一开关封装，避免 `<Switch>` 名称冲突。
+- Props：`value`（支持 `true/false/1/0/'1'/'0'/'true'/'false'`）
+- 事件：`input`、`change`、`on-change`
+
+```vue
+<FrameworkSwitch v-model="form.is_platform" />
+```
+
+#### 12.12.4 `cron-input/index.vue`
+
+- 用途：可视化拼 Cron（`minute hour day month dayOfWeek`）字符串。
+- Props：`value`（Cron 字符串）
+- 事件：`input`
+- 说明：点击下拉后可选分钟/小时/日/月/周，点“确定”写回 Cron。
+
+```vue
+<cron-input v-model="form.cron_time" />
+```
+
+#### 12.12.5 `main/pageHead.vue`
+
+- 用途：页面头部工具条；当 `this.$route.meta.type === '功能'` 时显示返回按钮。
+- 插槽：默认插槽（放新增/导出等按钮）
+- 内置方法：`goBack()`（`this.$router.go(-1)`）
+
+```vue
+<pageHead>
+  <Button type="primary">新增</Button>
+</pageHead>
+```
+
+#### 12.12.6 `markdown/markdown.vue`（`MarkdownEditor`）
+
+- 用途：基于 `simplemde` 的 Markdown 编辑器。
+- Props：
+  - `value: String`
+  - `options: Object`（SimpleMDE 配置）
+  - `localCache: Boolean`（默认 `true`，写入 `localStorage.markdownContent`）
+- 事件：`input`、`on-change`、`on-focus`、`on-blur`
+
+```vue
+<MarkdownEditor v-model="form.md_content" :local-cache="false" />
+```
+
+#### 12.12.7 `cropper/index.vue`（`Cropper`）
+
+- 用途：图片裁剪（`cropperjs`），默认 1:1 比例。
+- Props：`src`、`preview`、`moveStep`、`cropButtonText`
+- 事件：`on-crop`（回传裁剪后的 `File`）
+- 说明：默认要求图片尺寸至少 `500x500`，否则提示错误。
+
+```vue
+<Cropper :src="imageUrl" @on-crop="handleCroppedFile" />
+```
+
+#### 12.12.8 `upload/Custom.vue`
+
+- 用途：通用文件上传（显示文件名与上传进度，上传至 OSS）。
+- Props：`value`、`accept`、`btnText`
+- 事件：`input`（上传成功后的 OSS 地址）
+- 方法：`clear()`
+
+```vue
+<CustomUpload v-model="form.file_url" accept=".zip,.pdf" btn-text="上传附件" />
+```
+
+#### 12.12.9 `md-icons/icons.vue`（`Icons`）
+
+- 用途：渲染项目内 iconfont 图标（`iconfont icon-${type}`）。
+- Props：`type`（必填）、`color`、`size`
+
+```vue
+<Icons type="dashboard" :size="18" color="#2d8cf0" />
+```
+
+### 12.13 仅内部子组件（通常不单独直接使用）
+
+这些组件由父组件组合使用，业务页面一般不直接引用；如需复用，建议复制其父组件交互一起接入。
+
+| 组件路径 | 主要被谁使用 | 作用 |
+|----------|--------------|------|
+| `main/components/side-menu/side-menu-item.vue` | `SideMenu` | 递归渲染 `Submenu` 节点与子菜单。 |
+| `main/components/terminal/terminal.vue` | `main/components/terminal/index.vue` | 终端内容面板（当前为“终端功能暂未启用”占位）。 |
+| `split-pane/trigger.vue` | `split-pane/split.vue` | 分割条拖拽手柄视图。 |
+| `treeGrid/component/subThead.vue` | `treeGrid/index.vue` | 树表头部渲染。 |
+| `treeGrid/component/subColmns.vue` | `treeGrid/index.vue`/`subTreeGrid.vue` | `colgroup` 宽度控制。 |
+| `treeGrid/component/subTreeGrid.vue` | `treeGrid/index.vue` | 子树递归渲染、展开收起状态维护。 |
+| `treeGrid/component/renderCol.vue` | `treeGrid/index.vue`/`subTreeGrid.vue` | 安全执行列 `render(h, params)`。 |
+| `upload/mod/fileBtn.vue` | `upload/Custom.vue`/`upload/mod/fileListModal.vue` | 文件选择按钮。 |
+| `upload/mod/fileListModal.vue` | 上传业务页（按需） | 批量选文件 +（可选）批量上传 + 回调。 |
+
+### 12.14 `src/components` 全量组件索引（按路径）
+
+> 说明：下表覆盖 `src/components/**/*.vue`。`注册方式` 里“全局”表示由 `registerGlobalComponents` 自动注册；“按需”表示需手动引入；“内部”表示被父组件组合使用。
+
+| 组件路径 | 注册方式 | 入口章节 |
+|----------|----------|----------|
+| `asyncModal/index.vue` | 全局 | 12.6 |
+| `common-icon/common-icon.vue` | 全局 | 12.11 |
+| `cropper/index.vue` | 按需 | 12.12.7 |
+| `cron-input/index.vue` | 按需 | 12.12.4 |
+| `date-picker/index.vue` | 按需 | 12.12.2 |
+| `editor/index.vue` | 全局 | 12.5 |
+| `FloatPanel/index.vue` | 全局 | 12.10 |
+| `info-card/infor-card.vue` | 全局（`InfoCard`） | 12.8 |
+| `load-flower/index.vue` | 全局 | 12.11 |
+| `login-form/login-form.vue` | 按需 | 12.12.1 |
+| `main/main.vue` | 全局（`Main`） | 12.1 |
+| `main/pageHead.vue` | 按需 | 12.12.5 |
+| `main/components/a-back-top/index.vue` | 内部（可按需） | 12.1 / 12.11 |
+| `main/components/fullscreen/fullscreen.vue` | 内部（可按需） | 12.1 |
+| `main/components/header-bar/header-bar.vue` | 内部（可按需） | 12.1 |
+| `main/components/header-bar/custom-bread-crumb/custom-bread-crumb.vue` | 内部（可按需） | 12.1 |
+| `main/components/header-bar/sider-trigger/sider-trigger.vue` | 内部（可按需） | 12.1 |
+| `main/components/language/language.vue` | 内部（可按需） | 12.1 |
+| `main/components/side-menu/collapsed-menu.vue` | 内部 | 12.1 |
+| `main/components/side-menu/side-menu-item.vue` | 内部 | 12.13 |
+| `main/components/side-menu/side-menu.vue` | 内部（可按需） | 12.1 |
+| `main/components/terminal/index.vue` | 内部（可按需） | 12.1 |
+| `main/components/terminal/terminal.vue` | 内部 | 12.13 |
+| `main/components/user/user.vue` | 内部（可按需） | 12.1 |
+| `markdown/markdown.vue` | 按需 | 12.12.6 |
+| `md-icons/icons.vue` | 按需 | 12.12.9 |
+| `parent-view/parent-view.vue` | 全局（`ParentView`） | 12.1 |
+| `split-pane/split.vue` | 全局（`SplitPane`） | 12.9 |
+| `split-pane/trigger.vue` | 内部 | 12.13 |
+| `switch/index.vue` | 按需 | 12.12.3 |
+| `tables/editModal.vue` | 全局（`editModal`） | 12.6 |
+| `tables/fieldItem.vue` | 全局（`fieldItem`） | 12.7 |
+| `tables/fieldRenderer.vue` | 全局（`FieldRenderer`） | 12.7 |
+| `tables/index.vue` | 全局（`Tables`） | 12.2 |
+| `text-area/index.vue` | 全局（`TextArea`） | 12.11 |
+| `treeGrid/index.vue` | 全局（`TreeGrid`） | 12.3 |
+| `treeGrid/component/renderCol.vue` | 内部 | 12.13 |
+| `treeGrid/component/subColmns.vue` | 内部 | 12.13 |
+| `treeGrid/component/subThead.vue` | 内部 | 12.13 |
+| `treeGrid/component/subTreeGrid.vue` | 内部 | 12.13 |
+| `upload/Custom.vue` | 按需 | 12.12.8 |
+| `upload/Multiple.vue` | 全局（`UploadMultiple`） | 12.4 |
+| `upload/Single.vue` | 全局（`UploadSingle`） | 12.4 |
+| `upload/mod/fileBtn.vue` | 内部 | 12.13 |
+| `upload/mod/fileListModal.vue` | 内部（可按需） | 12.13 |

 ---