wc24/shrimp-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

业务模块不再需要消费侧薄壳：内置 module/_default.vue 兜底

Browse Source 
后端 moduleInfo 已经声明了字段、筛选、可用事件，ShrimpTable 要的只有一个
moduleKey，而 registerRoute 本来就把它当 props 传下去——「后端声明了模块，
前端就该渲染出来」是本包消费的契约，缺一个四行的壳不该让菜单点不开。

resolveVue 未命中时改为回落到 module/_default.vue，不再 warn+丢路由。
消费侧的 module/<key>.vue 仍按后缀优先命中，_default 本身也可被覆盖，纯增量。

顺带把 xlsx 补进 peerDependencies：ShrimpTable 是静态 import 它的，
漏装则 vite 直接起不来，而模板里一直没写。
This commit is contained in:
wc24
2026-08-14 14:41:44 +08:00
parent 4b6f260227
commit 6bd334a937
4 changed files with 46 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+24 -14
View File
@@ -20,16 +20,17 @@ shrimp-admin 是**源码 ship**(.ts + .vue 直接发),不带构建产物,由消
"type": "module", "type": "module",
"scripts": { "dev": "vite", "build": "vite build" }, "scripts": { "dev": "vite", "build": "vite build" },
"dependencies": { "dependencies": {
"shrimp-admin": "git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.8.2", "shrimp-admin": "git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.8.4",
// ⚠️ 不能删 —— 下面 6 个是 shrimp-admin 的 peerDependencies, // ⚠️ 不能删 —— 下面 7 个是 shrimp-admin 的 peerDependencies,
// 必须由消费侧显式装进自己的 dependencies,不能指望 npm 提升碰巧能 import 到 // 必须由消费侧显式装进自己的 dependencies,不能指望 npm 提升碰巧能 import 到
"vue": "^3.5.0", "vue": "^3.5.0",
"vue-router": "^4.5.0", "vue-router": "^4.5.0",
"vue-i18n": "^9.14.0", "vue-i18n": "^9.14.0",
"axios": "^1.7.0", "axios": "^1.7.0",
"element-plus": "^2.10.0", "element-plus": "^2.10.0",
"@element-plus/icons-vue": "^2.3.0" "@element-plus/icons-vue": "^2.3.0",
"xlsx": "^0.18.5" // ⚠️ 不能删 —— ShrimpTable 的导入/导出按钮直接 import 它,少了 vite 起不来
}, },
"devDependencies": { "devDependencies": {
"@vitejs/plugin-vue": "^5.2.0", "@vitejs/plugin-vue": "^5.2.0",
@@ -94,23 +95,29 @@ app.use(createShrimpAdmin({
app.mount('#app') app.mount('#app')
``` ```
## 4. 每个业务模块一个薄壳 `src/shrimp/module/<key>.vue` ## 4. 业务模块:默认什么都不用写
⚠️ **不能省。**后端有几个 moduleKey,这里就得有几个文件 —— 这**不是「覆盖」,是「注册」**:框架的内置兜底只兜自己的 login/layout/404,不认识你的业务模块,少一个那个菜单就点不开。 后端声明了几个 moduleKey,前端就自动有几个菜单、几张表 —— 字段、筛选、可用操作全在 moduleInfo 里,内置的 `module/_default.vue` 拿 moduleKey 渲染出来就是了。**不需要为每个模块建文件。**
只在有**真实增量**时才写 `src/shrimp/module/<key>.vue` 覆盖它(加列插槽、换布局、塞额外操作):
```vue ```vue
<!-- src/shrimp/module/product.vue —— 后端 moduleKey === 'product' --> <!-- src/shrimp/module/product.vue —— 后端 moduleKey === 'product' -->
<template> <template>
<ShrimpTable moduleKey="product" /> <ShrimpTable moduleKey="product">
<template #column-price="{ row }">
<span :class="row.price > 1000 ? 'is-expensive' : ''">￥{{ row.price }}</span>
</template>
</ShrimpTable>
</template> </template>
<script setup lang="ts"> <script setup lang="ts">
// 字段、筛选、编辑全由后端 moduleInfo 声明,ShrimpTable 自动渲染,这里不写业务代码 // 字段、筛选、编辑仍由后端 moduleInfo 声明,这里只加自己那点增量
import { ShrimpTable } from 'shrimp-admin' import { ShrimpTable } from 'shrimp-admin'
</script> </script>
``` ```
反过来,内置的 `login.vue` / `layout.vue` / `404.vue` **一个都不用写** —— 框架内置兜底,只在你真有增量时才覆盖(见下面「唯一约定」)。 内置的 `login.vue` / `layout.vue` / `404.vue` 同理,**一个都不用写**(见下面「唯一约定」)。
--- ---
@@ -121,7 +128,7 @@ import { ShrimpTable } from 'shrimp-admin'
| 你看到的 | 病因 | 改哪 | | 你看到的 | 病因 | 改哪 |
| --- | --- | --- | | --- | --- | --- |
| `resolveVue: components/layout.vue not found in sources`,整页白屏 | shrimp-admin 被 vite 预打包了 | vite.config `optimizeDeps.exclude: ['shrimp-admin']` | | `resolveVue: components/layout.vue not found in sources`,整页白屏 | shrimp-admin 被 vite 预打包了 | vite.config `optimizeDeps.exclude: ['shrimp-admin']` |
| `module component not found: module/<key>.vue`,菜单点不开 | 少了业务模块薄壳 | 补 `src/shrimp/module/<key>.vue`,模板第 4 节 | | `Failed to resolve import "xlsx"`,vite 起不来 | 少装 peerDependency `xlsx` | `npm i xlsx`,模板第 1 节 |
| 页面出来了但没样式,**图标巨大** | 没引 element-plus 基础样式 | main.ts 加两行 css,模板第 3 节 | | 页面出来了但没样式,**图标巨大** | 没引 element-plus 基础样式 | main.ts 加两行 css,模板第 3 节 |
| 能登录、菜单也有,但**所有列表都 404** | 服务端装的是 Express 4 | 服务端升到 `express@^5` | | 能登录、菜单也有,但**所有列表都 404** | 服务端装的是 Express 4 | 服务端升到 `express@^5` |
| `does not provide an export named 'default'`(dayjs / element-plus) | 依赖被装了两份 | vite.config `resolve.dedupe`,模板第 2 节 | | `does not provide an export named 'default'`(dayjs / element-plus) | 依赖被装了两份 | vite.config `resolve.dedupe`,模板第 2 节 |
@@ -146,9 +153,9 @@ Vite dev 默认用 **esbuild** 把 node_modules 里的裸导入预打包成 `nod
`shrimp-admin/style` 只包含框架自己的覆盖样式与暗色变量(`fix.scss` / `dark.scss` 等),**不含** element-plus 本体的样式表。element-plus 是 peerDependency、由消费侧安装,它的基础样式自然也该由消费侧引 —— 框架替你引会锁死版本、也挡住你换主题。顺序不能反:覆盖必须在基础之后。 `shrimp-admin/style` 只包含框架自己的覆盖样式与暗色变量(`fix.scss` / `dark.scss` 等),**不含** element-plus 本体的样式表。element-plus 是 peerDependency、由消费侧安装,它的基础样式自然也该由消费侧引 —— 框架替你引会锁死版本、也挡住你换主题。顺序不能反:覆盖必须在基础之后。
## 业务模块薄壳 ## `xlsx`
框架靠 `sources` 里扫到的 `module/<key>.vue` 去 `registerRoute`。它没有别的途径知道你有哪些业务模块 —— 后端 moduleInfo 只告诉它「有个 key 叫 product」,渲染成哪个组件得你指定。壳里只有一行 `<ShrimpTable>`,但这一行就是那次指定。 `ShrimpTable` 的导入/导出按钮是**静态** `import * as XLSX from 'xlsx'`,不是按需加载 —— 就算你的后台从不点那两个按钮,模块解析也绕不过去。它是 peerDependency 而不是 dependency,理由和 element-plus 一样:版本该由消费侧定。
# 唯一约定: `sources` 路径后缀覆盖 # 唯一约定: `sources` 路径后缀覆盖
@@ -163,11 +170,14 @@ Vite dev 默认用 **esbuild** 把 node_modules 里的裸导入预打包成 `nod
│ └── fields/ │ └── fields/
│ └── FieldRelativeTime.vue 注册字段类型 relativeTime │ └── FieldRelativeTime.vue 注册字段类型 relativeTime
└── module/ └── module/
├── product.vue 业务模块,routed by moduleKey ├── product.vue 覆盖业务模块 product 的默认表格
├── _default.vue 覆盖「所有没单独写壳的模块」用的那份
└── user/ └── user/
└── orders.vue 子模块,parent=user └── orders.vue 子模块,parent=user
``` ```
`module/` 下一个文件都没有也能跑 —— 那时每个模块都落到内置的 `module/_default.vue`。
### 覆盖颗粒度只在这几个入口 ### 覆盖颗粒度只在这几个入口
框架内 .vue 之间的 peer 引用是**硬编码静态 import**,override 颗粒度就停在下面这几类入口,不会一路传递下去: 框架内 .vue 之间的 peer 引用是**硬编码静态 import**,override 颗粒度就停在下面这几类入口,不会一路传递下去:
@@ -175,7 +185,7 @@ Vite dev 默认用 **esbuild** 把 node_modules 里的裸导入预打包成 `nod
| 入口 | 后缀 | 说明 | | 入口 | 后缀 | 说明 |
| --- | --- | --- | | --- | --- | --- |
| **router targets** | `components/login.vue`、`components/layout.vue`、`components/404.vue` | vue-router 三个根级路由组件 | | **router targets** | `components/login.vue`、`components/layout.vue`、`components/404.vue` | vue-router 三个根级路由组件 |
| **module routes** | `module/<key>.vue`、`module/<parent>/<sub>.vue` | 走 `registerRoute` 的业务模块/子模块 | | **module routes** | `module/<key>.vue`、`module/<parent>/<sub>.vue`、`module/_default.vue` | 走 `registerRoute` 的业务模块/子模块;都没写就用内置 `_default` |
| **field registry** | `components/fields/Field<X>.vue` | 字段类型注册表(文件名首字母小写 = type 键) | | **field registry** | `components/fields/Field<X>.vue` | 字段类型注册表(文件名首字母小写 = type 键) |
| **顶栏** | `components/userbar.vue` | 右上角那一条(语言、全屏、用户菜单),整体替换 | | **顶栏** | `components/userbar.vue` | 右上角那一条(语言、全屏、用户菜单),整体替换 |
@@ -199,7 +209,7 @@ Vite dev 默认用 **esbuild** 把 node_modules 里的裸导入预打包成 `nod
### 业务模块 ### 业务模块
`module/<key>.vue` 命中 `moduleKey === '<key>'` 的路由,自动作为内容页。子表用嵌套目录(`module/<parent>/<sub>.vue`)。 `module/<key>.vue` 命中 `moduleKey === '<key>'` 的路由,自动作为内容页。子表用嵌套目录(`module/<parent>/<sub>.vue`)。没写的模块落到 `module/_default.vue`,消费侧写一份同名文件即可整体换掉那个默认。
### 例子: 覆盖 login 页 ### 例子: 覆盖 login 页
package.json
+3 -2
View File
@@ -1,6 +1,6 @@
{ {
"name": "shrimp-admin", "name": "shrimp-admin",
"version": "0.8.3", "version": "0.8.4",
"private": true, "private": true,
"description": "Shrimp 框架前端 — 消费 ShrimpServer + ShrimpTable 契约的经典 Vue3 + Element Plus 实现", "description": "Shrimp 框架前端 — 消费 ShrimpServer + ShrimpTable 契约的经典 Vue3 + Element Plus 实现",
"main": "src/index.ts", "main": "src/index.ts",
@@ -27,7 +27,8 @@
"vue-i18n": "^9.0.0", "vue-i18n": "^9.0.0",
"axios": "^1.0.0", "axios": "^1.0.0",
"element-plus": "^2.0.0", "element-plus": "^2.0.0",
"@element-plus/icons-vue": "^2.0.0" "@element-plus/icons-vue": "^2.0.0",
"xlsx": "^0.18.0"
}, },
"devDependencies": { "devDependencies": {
"@types/node": "^20.0.0", "@types/node": "^20.0.0",
src/VueAdmin.ts
+4 -2
View File
@@ -281,8 +281,10 @@ export class VueAdmin extends ShrimpClient {
try { try {
importer = resolveVue(`module/${componentPath}.vue`) importer = resolveVue(`module/${componentPath}.vue`)
} catch { } catch {
console.warn(`[shrimp-admin] module component not found: module/${componentPath}.vue`) // 消费侧没给这个模块的壳,用内置通用表格顶上。
return // moduleKey 下面本来就当 props 传下去,而 ShrimpTable 要的只有它——
// 「后端声明了模块,前端就该渲染出来」是本包消费的契约,缺一个壳不该让菜单点不开。
importer = resolveVue("module/_default.vue")
} }
this.router.addRoute("layout", { this.router.addRoute("layout", {
path: info.path || "/" + info.name, path: info.path || "/" + info.name,
src/module/_default.vue
+15
View File
@@ -0,0 +1,15 @@
<template>
<ShrimpTable :moduleKey="moduleKey" />
</template>
<script lang="ts" setup>
// 业务模块的内置兜底：消费侧没给 module/<key>.vue 时用这份。
// 后端 moduleInfo 已经把字段、筛选、可用事件都声明清楚了，ShrimpTable 要的只有一个 moduleKey——
// 所以「有个模块叫 xxx」这件事本身就够渲染出一张表，不必再让消费侧写一遍。
// 有增量（加列插槽、换布局）时照旧写 module/<key>.vue 覆盖，后缀匹配消费侧优先。
import ShrimpTable from '../components/ShrimpTable.vue'
// events 也声明出来：registerRoute 是连 events 一起当 props 传下来的，
// 不声明它会掉进 attrs 一路透传到 ShrimpTable 的根元素上。
defineProps<{ moduleKey: string; events?: string[] }>()
</script>