shrimp-admin

Shrimp 框架前端 —— 一种经典解决方案(不是框架本身),消费 shrimp-server 暴露的 ShrimpServer 路由契约 + ShrimpTable 数据形状契约,基于 Vue 3 + Element Plus 实现一套可直接用的后台壳。

如果你想换 UI 库或者换前端技术栈,直接照 shrimp-server 的约定再写一份就行,不依赖本包。

安装

npm i git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.3.0

shrimp-admin 是源码 ship(.ts + .vue 直接发),由消费侧 Vite 编译。

使用

// 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 页

<!-- 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