wc24
ebe5937fb6
- 删掉 "components/* 都可覆盖" 的误导清单(框架内 peer 引用是硬编码静态 import) - 明确 3 类入口: router targets / module routes / field registry - 加完整可跑的 login.vue 覆盖例子
139 lines
5.4 KiB
Markdown
139 lines
5.4 KiB
Markdown
# shrimp-admin
|
|
|
|
Shrimp 框架前端 —— 一种**经典解决方案**(不是框架本身),消费 [shrimp-server](http://git.zeromvc.com/wc24/shrimp-server) 暴露的 `ShrimpServer` 路由契约 + `ShrimpTable` 数据形状契约,基于 **Vue 3 + Element Plus** 实现一套可直接用的后台壳。
|
|
|
|
如果你想换 UI 库或者换前端技术栈,直接照 shrimp-server 的约定再写一份就行,不依赖本包。
|
|
|
|
## 安装
|
|
|
|
```bash
|
|
npm i git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.3.0
|
|
```
|
|
|
|
shrimp-admin 是**源码 ship**(.ts + .vue 直接发),由消费侧 Vite 编译。
|
|
|
|
## 使用
|
|
|
|
```ts
|
|
// main.ts
|
|
import { createApp } from 'vue'
|
|
import { createShrimpAdmin, App } from 'shrimp-admin'
|
|
import 'shrimp-admin/style'
|
|
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',
|
|
TIMEOUT: 10000,
|
|
},
|
|
locales: { 'zh-cn': zhCn, en },
|
|
sources: import.meta.glob('./shrimp/**/*.vue'),
|
|
}))
|
|
app.mount('#app')
|
|
```
|
|
|
|
## 唯一约定: `sources` 路径后缀覆盖
|
|
|
|
消费侧把所有要交给框架的 .vue 通过单个 `sources` 入口注入(`import.meta.glob` 必须由消费侧自己调用,vite 静态扫描相对调用文件)。框架按**文件路径后缀**匹配,同后缀消费侧优先,内置兜底。
|
|
|
|
```
|
|
项目/
|
|
└── src/shrimp/ 消费侧目录,可任意命名
|
|
├── components/
|
|
│ ├── login.vue 覆盖框架内置 login 页
|
|
│ ├── layout.vue 覆盖整体布局壳
|
|
│ └── fields/
|
|
│ └── FieldRelativeTime.vue 注册字段类型 relativeTime
|
|
└── module/
|
|
├── product.vue 业务模块,routed by moduleKey
|
|
└── user/
|
|
└── orders.vue 子模块,parent=user
|
|
```
|
|
|
|
### 覆盖颗粒度只在 3 个入口
|
|
|
|
框架内 .vue 之间的 peer 引用是**硬编码静态 import**,override 颗粒度就停在下面这 3 类入口,不会一路传递下去:
|
|
|
|
| 入口 | 后缀 | 说明 |
|
|
| --- | --- | --- |
|
|
| **router targets** | `components/login.vue`、`components/layout.vue`、`components/404.vue` | vue-router 三个根级路由组件 |
|
|
| **module routes** | `module/<key>.vue`、`module/<parent>/<sub>.vue` | 走 `registerRoute` 的业务模块/子模块 |
|
|
| **field registry** | `components/fields/Field<X>.vue` | 字段类型注册表(文件名首字母小写 = type 键) |
|
|
|
|
想换更细的部件(比如 layout 里的 topbar)就在消费侧的 `layout.vue` 自己组装 — 框架不再代理任何 peer 切换。
|
|
|
|
### 字段类型注册
|
|
|
|
`components/fields/Field<X>.vue` 自动注册类型 `<x>`(首字母小写):
|
|
|
|
| 文件 | type 注册键 |
|
|
| -------------------------- | ---------------- |
|
|
| `FieldString.vue` | `string` |
|
|
| `FieldRelativeTime.vue` | `relativeTime` |
|
|
| 你自己的 `FieldMyType.vue` | `myType` |
|
|
|
|
后端 moduleInfo 里 `field.type === 'myType'` 时就用你这个组件。内置类型: `string` / `boolean` / `date` / `json` / `number` / `password` / `relation` / `select` / `tab` / `textarea` / `relativeTime`。
|
|
|
|
### 业务模块
|
|
|
|
`module/<key>.vue` 命中 `moduleKey === '<key>'` 的路由,自动作为内容页。子表用嵌套目录(`module/<parent>/<sub>.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
|