wc24
fef886de87
配 shrimp-server v0.9.0:export 返回 { sheet 名: 行数组 },这边逐 key 建 sheet;
导入把工作簿里所有 sheet 都发回后端(旧版只读第一张、其余静默丢弃),哪张怎么用
由模块的 import 决定。sheet 名按 Excel 限制截断/替换,否则 book_append_sheet 直接抛。
293 lines
16 KiB
Markdown
293 lines
16 KiB
Markdown
# shrimp-admin
|
|
|
|
Shrimp 框架前端 —— 一种**经典解决方案**(不是框架本身),消费 [shrimp-server](http://git.zeromvc.com/wc24/shrimp-server) 暴露的 `ShrimpServer` 路由契约 + `ShrimpTable` 数据形状契约,基于 **Vue 3 + Element Plus** 实现一套可直接用的后台壳。
|
|
|
|
如果你想换 UI 库或者换前端技术栈,直接照 shrimp-server 的约定再写一份就行,不依赖本包。
|
|
|
|
shrimp-admin 是**源码 ship**(.ts + .vue 直接发),不带构建产物,由消费侧 Vite 编译。这省掉了框架的构建步骤,代价是**有几件事 npm 装完不会自动生效**,必须消费侧显式配 —— 下面的接入模板已经把它们全写进去了。
|
|
|
|
---
|
|
|
|
# 接入模板
|
|
|
|
> **整段抄,不要自己攒。** 标了「⚠️ 不能删」的行看起来多余,删掉的后果写在每行旁边;
|
|
> 现存的 theseus-admin / hand-admin / bug-book 三个项目里,这些行一行不差全都在。
|
|
|
|
## 1. package.json
|
|
|
|
```jsonc
|
|
{
|
|
"type": "module",
|
|
"scripts": { "dev": "vite", "build": "vite build" },
|
|
"dependencies": {
|
|
"shrimp-admin": "git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.9.0",
|
|
|
|
// ⚠️ 不能删 —— 下面 7 个是 shrimp-admin 的 peerDependencies,
|
|
// 必须由消费侧显式装进自己的 dependencies,不能指望 npm 提升碰巧能 import 到
|
|
"vue": "^3.5.0",
|
|
"vue-router": "^4.5.0",
|
|
"vue-i18n": "^9.14.0",
|
|
"axios": "^1.7.0",
|
|
"element-plus": "^2.10.0",
|
|
"@element-plus/icons-vue": "^2.3.0",
|
|
"xlsx": "^0.18.5" // ⚠️ 不能删 —— ShrimpTable 的导入/导出按钮直接 import 它,少了 vite 起不来
|
|
},
|
|
"devDependencies": {
|
|
"@vitejs/plugin-vue": "^5.2.0",
|
|
"sass-embedded": "^1.80.0", // ⚠️ 不能删 —— shrimp-admin/style 是 .scss
|
|
"typescript": "^5.6.0",
|
|
"vite": "^6.0.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
服务端那侧另有一条硬约束:**shrimp-server 要求 Express 5**(它的兜底路由用了 `/*path` 具名通配,Express 4 只会当字面路径)。装成 4 的症状是能登录、能出菜单,但**所有** `POST /<moduleKey>/list` 都 404。
|
|
|
|
## 2. vite.config.ts
|
|
|
|
```ts
|
|
import { defineConfig } from 'vite'
|
|
import vue from '@vitejs/plugin-vue'
|
|
|
|
export default defineConfig({
|
|
plugins: [vue()],
|
|
optimizeDeps: {
|
|
// ⚠️ 不能删 —— 删了整页白屏,报 resolveVue: components/layout.vue not found in sources
|
|
exclude: ['shrimp-admin'],
|
|
// ⚠️ 也不能删 —— 上面这行让 vite 的依赖扫描停在本包门口,看不见本包 import 的
|
|
// element-plus / xlsx。消费侧 src/ 下如果没有自己的业务 .vue 顺手 import 到它们,
|
|
// 它们就一次都没被预打包,内部的 CJS 依赖(dayjs)原样送进浏览器 → 整页白屏,
|
|
// 控制台只有一行 does not provide an export named 'default'。列的就是下面那份 peer 清单
|
|
include: ['vue', 'vue-router', 'vue-i18n', 'axios', 'element-plus', '@element-plus/icons-vue', 'xlsx'],
|
|
},
|
|
resolve: {
|
|
// ⚠️ 不能删 —— 删了 element-plus 与 shrimp-admin 各带一份 vue/dayjs,互操作错位
|
|
dedupe: ['vue', 'vue-i18n', 'vue-router', 'element-plus', 'dayjs'],
|
|
},
|
|
server: {
|
|
// 开发期后台接口由 vite 转发,前端一律走相对路径,不注入任何后端地址
|
|
proxy: { '/admin-api': { target: 'http://127.0.0.1:8080', changeOrigin: true } },
|
|
},
|
|
})
|
|
```
|
|
|
|
## 3. src/main.ts
|
|
|
|
```ts
|
|
import { createApp } from 'vue'
|
|
|
|
// ⚠️ 不能删,且必须在 shrimp-admin/style 之前 ——
|
|
// 删了页面能出来但整个掉样式,最显眼的症状是图标被撑到巨大
|
|
import 'element-plus/dist/index.css'
|
|
import 'element-plus/theme-chalk/display.css'
|
|
import 'shrimp-admin/style'
|
|
|
|
import { createShrimpAdmin, App } from 'shrimp-admin'
|
|
import zhCn from './locales/zh-cn.json'
|
|
import en from './locales/en.json'
|
|
|
|
const app = createApp(App)
|
|
app.use(createShrimpAdmin({
|
|
config: {
|
|
API_URL: '/admin-api', // 相对路径,由 vite proxy 转发
|
|
TIMEOUT: 10000,
|
|
},
|
|
locales: { 'zh-cn': zhCn, en },
|
|
// ⚠️ import.meta.glob 必须写在消费侧的文件里(vite 静态扫描相对本文件),
|
|
// 不能封装成函数从别处调
|
|
sources: import.meta.glob('./shrimp/**/*.vue'),
|
|
}))
|
|
app.mount('#app')
|
|
```
|
|
|
|
## 4. 业务模块:默认什么都不用写
|
|
|
|
后端声明了几个 moduleKey,前端就自动有几个菜单、几张表 —— 字段、筛选、可用操作全在 moduleInfo 里,内置的 `module/_default.vue` 拿 moduleKey 渲染出来就是了。**不需要为每个模块建文件。**
|
|
|
|
只在有**真实增量**时才写 `src/shrimp/module/<key>.vue` 覆盖它(加列插槽、换布局、塞额外操作):
|
|
|
|
```vue
|
|
<!-- src/shrimp/module/product.vue —— 后端 moduleKey === 'product' -->
|
|
<template>
|
|
<ShrimpTable moduleKey="product">
|
|
<template #column-price="{ row }">
|
|
<span :class="row.price > 1000 ? 'is-expensive' : ''">￥{{ row.price }}</span>
|
|
</template>
|
|
</ShrimpTable>
|
|
</template>
|
|
|
|
<script setup lang="ts">
|
|
// 字段、筛选、编辑仍由后端 moduleInfo 声明,这里只加自己那点增量
|
|
import { ShrimpTable } from 'shrimp-admin'
|
|
</script>
|
|
```
|
|
|
|
内置的 `login.vue` / `layout.vue` / `404.vue` 同理,**一个都不用写**(见下面「唯一约定」)。
|
|
|
|
---
|
|
|
|
# 出错对照表
|
|
|
|
接入时按症状反查,不必先懂原理。
|
|
|
|
| 你看到的 | 病因 | 改哪 |
|
|
| --- | --- | --- |
|
|
| `resolveVue: components/layout.vue not found in sources`,整页白屏 | shrimp-admin 被 vite 预打包了 | vite.config `optimizeDeps.exclude: ['shrimp-admin']` |
|
|
| `Failed to resolve import "xlsx"`,vite 起不来 | 少装 peerDependency `xlsx` | `npm i xlsx`,模板第 1 节 |
|
|
| 页面出来了但没样式,**图标巨大** | 没引 element-plus 基础样式 | main.ts 加两行 css,模板第 3 节 |
|
|
| 编辑器报 `找不到 'shrimp-admin/style' 的副作用导入的模块或类型声明` | 本包低于 v0.8.6:`./style` 导出没有 types 条件,开了 `noUncheckedSideEffectImports` 的项目解不出类型 | 升到 `v0.8.6` |
|
|
| 能登录、菜单也有,但**所有列表都 404** | 服务端装的是 Express 4 | 服务端升到 `express@^5` |
|
|
| `does not provide an export named 'default'`(dayjs),整页白屏 | element-plus 从没被预打包过,它的 CJS 依赖被原样送进浏览器 | vite.config `optimizeDeps.include`,模板第 2 节 |
|
|
| `does not provide an export named 'default'`(其他包) | 依赖被装了两份 | vite.config `resolve.dedupe`,模板第 2 节 |
|
|
|
|
## 验收: 必须在浏览器里打开页面
|
|
|
|
`vite build` 通过、`curl` 打接口通,**都不算接入完成**。上表前三行全部逃得过构建和接口测试:
|
|
|
|
- dev 用 esbuild 预打包、build 用 rollup,是**两套转换管线**。rollup 正确处理 node_modules 里的 `import.meta.glob`,所以第 1 行的问题在 `vite build` 下一路绿灯,只在 dev 复现。
|
|
- 样式和路由注册只在浏览器运行时才成立,接口测试根本不经过它们。
|
|
|
|
# 那几行为什么不能删
|
|
|
|
## `optimizeDeps.exclude: ['shrimp-admin']`
|
|
|
|
Vite dev 默认用 **esbuild** 把 node_modules 里的裸导入预打包成 `node_modules/.vite/deps/shrimp-admin.js`。两个后果:
|
|
|
|
- 框架的内置组件表靠 `import.meta.glob('./{components,module}/**/*.vue')` 收集,这是 **Vite 编译期宏**,esbuild 不认识,会原样抄进产物;等它在 `.vite/deps/` 目录下才被展开时,那个目录里一个 `.vue` 都没有 → 内置表变成空对象 `{}` → 内置兜底全部落空。
|
|
- 预打包等于复制出第二份模块实例,`vueAdmin` 单例会分裂成两个,消费侧拿到的和框架内部用的不是同一个。
|
|
|
|
## `optimizeDeps.include: [...]`
|
|
|
|
上面那条 `exclude` 的代价:vite 的依赖扫描从 `index.html` 顺着消费侧的源码走,走到 `shrimp-admin` 就停了 —— 被 exclude 的包不进扫描,所以**框架 import 了什么,vite 一无所知**。
|
|
|
|
以前这不出事:消费侧总要写几个业务模块 `.vue`,里面顺手 `import { ElMessage } from 'element-plus'`,扫描器照样摸得到。而从 v0.8.4 起模块壳可以一个都不写(见「业务模块」一节),于是完全可能出现**消费侧 `src/` 里没有任何一处 import element-plus** —— 它整包从未被预打包,所有 `element-plus/es/**` 被原样送给浏览器,其中的 `import dayjs from 'dayjs'` 指向一个 CJS 文件,当场炸:
|
|
|
|
The requested module '/node_modules/dayjs/dayjs.min.js' does not provide an export named 'default'
|
|
|
|
整页白屏,控制台就这一行,`vite build`(rollup)一路绿灯。
|
|
|
|
**不要顺着报错一个个补 `dayjs`、`dayjs/plugin/customParseFormat`……** 那是在追症状,换个 element-plus 版本要重列一遍。**也不要用 `optimizeDeps.entries` 指向 `node_modules/shrimp-admin/src/**`** —— 扫描器不认 node_modules 里的入口 glob,实测加了等于没加(`.vite/deps/_metadata.json` 里仍然只有 `vue`)。
|
|
|
|
正确的做法是把本包用到的运行时依赖点名列出,那份清单就是下面 peerDependencies 本身 —— 消费侧本来就得装它们,这里只是再说一句「请预打包」。
|
|
|
|
## element-plus 的两行 css
|
|
|
|
`shrimp-admin/style` 只包含框架自己的覆盖样式与暗色变量(`fix.scss` / `dark.scss` 等),**不含** element-plus 本体的样式表。element-plus 是 peerDependency、由消费侧安装,它的基础样式自然也该由消费侧引 —— 框架替你引会锁死版本、也挡住你换主题。顺序不能反:覆盖必须在基础之后。
|
|
|
|
## `xlsx`
|
|
|
|
`ShrimpTable` 的导入/导出按钮是**静态** `import * as XLSX from 'xlsx'`,不是按需加载 —— 就算你的后台从不点那两个按钮,模块解析也绕不过去。它是 peerDependency 而不是 dependency,理由和 element-plus 一样:版本该由消费侧定。
|
|
|
|
工作簿的形状由**后端**决定(v0.9.0 起):`export` 返回 `{ sheet 名: 行数组 }`,前端按 key 逐张建 sheet;导入则把工作簿里**所有** sheet 原样发回后端(旧版只发第一张),哪张怎么用由模块的 `import` 决定。前端在这条链上只做两件脏活:对象/数组列 `JSON.stringify`,以及把 sheet 名按 Excel 限制(≤31 字符、不含 `[]:*?/\`)截断替换。
|
|
|
|
# 唯一约定: `sources` 路径后缀覆盖
|
|
|
|
消费侧把所有要交给框架的 .vue 通过单个 `sources` 入口注入(`import.meta.glob` 必须由消费侧自己调用,vite 静态扫描相对调用文件)。框架按**文件路径后缀**匹配,同后缀消费侧优先,内置兜底。
|
|
|
|
```
|
|
项目/
|
|
└── src/shrimp/ 消费侧目录,可任意命名
|
|
├── components/
|
|
│ ├── login.vue 覆盖框架内置 login 页
|
|
│ ├── layout.vue 覆盖整体布局壳
|
|
│ └── fields/
|
|
│ └── FieldRelativeTime.vue 注册字段类型 relativeTime
|
|
└── module/
|
|
├── product.vue 覆盖业务模块 product 的默认表格
|
|
├── _default.vue 覆盖「所有没单独写壳的模块」用的那份
|
|
└── user/
|
|
└── orders.vue 子模块,parent=user
|
|
```
|
|
|
|
`module/` 下一个文件都没有也能跑 —— 那时每个模块都落到内置的 `module/_default.vue`。
|
|
|
|
### 覆盖颗粒度只在这几个入口
|
|
|
|
框架内 .vue 之间的 peer 引用是**硬编码静态 import**,override 颗粒度就停在下面这几类入口,不会一路传递下去:
|
|
|
|
| 入口 | 后缀 | 说明 |
|
|
| --- | --- | --- |
|
|
| **router targets** | `components/login.vue`、`components/layout.vue`、`components/404.vue` | vue-router 三个根级路由组件 |
|
|
| **module routes** | `module/<key>.vue`、`module/<parent>/<sub>.vue`、`module/_default.vue` | 走 `registerRoute` 的业务模块/子模块;都没写就用内置 `_default` |
|
|
| **field registry** | `components/fields/Field<X>.vue` | 字段类型注册表(文件名首字母小写 = type 键) |
|
|
| **顶栏** | `components/userbar.vue` | 右上角那一条(语言、全屏、用户菜单),整体替换 |
|
|
|
|
**表里没有的路径不会被覆盖,而且不报错**——写了个 `components/topbar.vue` 放进 sources,框架照样用内置那份,页面正常打开、你的文件被静默忽略。想换更细的部件就在消费侧的 `layout.vue` 里自己组装,框架不代理 peer 切换。
|
|
|
|
### 字段类型注册
|
|
|
|
`components/fields/Field<X>.vue` 自动注册类型 `<x>`(首字母小写):
|
|
|
|
| 文件 | type 注册键 |
|
|
| -------------------------- | ---------------- |
|
|
| `FieldString.vue` | `string` |
|
|
| `FieldRelativeTime.vue` | `relativeTime` |
|
|
| 你自己的 `FieldMyType.vue` | `myType` |
|
|
|
|
后端 moduleInfo 里 `field.type === 'myType'` 时就用你这个组件。
|
|
|
|
内置类型以 `src/components/fields/` 目录为准,当前是: `array` / `boolean` / `date` / `number` / `object` / `password` / `relation` / `relativeTime` / `select` / `string` / `tab` / `textarea`。其中 `relativeTime` 是本实现独有的,shrimp-server 的 `ShrimpFieldTypes` 里没有。
|
|
|
|
**没有 `json`。** 后端发一个没注册的 type 过来不会报错,`getFieldComponent` 静默回落成 `string` 渲染,只在控制台留一条 warning——列照样出、内容不对。字符串数组要用 `array` + `item`,嵌套对象用 `object` + `fields`。
|
|
|
|
### 业务模块
|
|
|
|
`module/<key>.vue` 命中 `moduleKey === '<key>'` 的路由,自动作为内容页。子表用嵌套目录(`module/<parent>/<sub>.vue`)。没写的模块落到 `module/_default.vue`,消费侧写一份同名文件即可整体换掉那个默认。
|
|
|
|
### 例子: 覆盖 login 页
|
|
|
|
```vue
|
|
<!-- src/shrimp/components/login.vue -->
|
|
<template>
|
|
<div class="custom-login">
|
|
<h2>{{ vueAdmin.adminConfig.title || 'Admin' }}</h2>
|
|
<el-form :model="form" :rules="rules" @keyup.enter="login">
|
|
<el-form-item prop="user">
|
|
<el-input v-model="form.user" :placeholder="$t('login.userPlaceholder')" />
|
|
</el-form-item>
|
|
<el-form-item prop="password">
|
|
<el-input v-model="form.password" :placeholder="$t('login.PWPlaceholder')" show-password />
|
|
</el-form-item>
|
|
<el-button type="primary" :loading="info.islogin" @click="login">
|
|
{{ $t('login.signIn') }}
|
|
</el-button>
|
|
</el-form>
|
|
</div>
|
|
</template>
|
|
|
|
<script lang="ts" setup>
|
|
import { reactive, computed } from 'vue'
|
|
import { useI18n } from 'vue-i18n'
|
|
import { vueAdmin } from 'shrimp-admin'
|
|
|
|
const { t } = useI18n()
|
|
const info = reactive({ islogin: false })
|
|
const form = reactive({ user: '', password: '' })
|
|
const rules = computed(() => ({
|
|
user: [{ required: true, message: t('login.userError'), trigger: 'blur' }],
|
|
password: [{ required: true, message: t('login.PWError'), trigger: 'blur' }],
|
|
}))
|
|
|
|
function login() {
|
|
info.islogin = true
|
|
vueAdmin.fetchLogin({ username: form.user, password: form.password })
|
|
.then(async (data: any) => {
|
|
vueAdmin.token = data.token
|
|
await vueAdmin.loadUserInfo()
|
|
vueAdmin.router.push(vueAdmin.getFirstMenuPath())
|
|
})
|
|
.catch((e: any) => console.warn('[Login]', e.message))
|
|
.finally(() => { info.islogin = false })
|
|
}
|
|
</script>
|
|
```
|
|
|
|
只要文件落在 `src/shrimp/components/login.vue`,被 `sources` 的 glob 扫到,框架的 `/login` 路由就会用你这份替换内置版本。
|
|
|
|
# 消费的契约
|
|
|
|
参见 shrimp-server README `## 约定` 章节。本包消费以下条件契约:
|
|
|
|
- **ShrimpTable**: list 响应 `{list,total,page,pageSize,totalPages}` / 字段 type 枚举 / populate `${key}_label`
|
|
- **ShrimpServer**: HTTP 路由 / JWT Bearer / IUserAccessor 返回的 powers
|