docs(README): 覆盖颗粒度限定到 3 个入口 + 加 login 覆盖示例

- 删掉 "components/* 都可覆盖" 的误导清单(框架内 peer 引用是硬编码静态 import)
- 明确 3 类入口: router targets / module routes / field registry
- 加完整可跑的 login.vue 覆盖例子
This commit is contained in:
2026-05-25 18:03:42 +08:00
parent de18412010
commit ebe5937fb6
+67 -18
View File
@@ -43,7 +43,7 @@ app.mount('#app')
└── src/shrimp/ 消费侧目录,可任意命名 └── src/shrimp/ 消费侧目录,可任意命名
├── components/ ├── components/
│ ├── login.vue 覆盖框架内置 login 页 │ ├── login.vue 覆盖框架内置 login 页
│ ├── topbar.vue 覆盖顶栏 │ ├── layout.vue 覆盖整体布局壳
│ └── fields/ │ └── fields/
│ └── FieldRelativeTime.vue 注册字段类型 relativeTime │ └── FieldRelativeTime.vue 注册字段类型 relativeTime
└── module/ └── module/
@@ -52,34 +52,83 @@ app.mount('#app')
└── orders.vue 子模块,parent=user └── orders.vue 子模块,parent=user
``` ```
### 框架内置 slot(可覆盖,suffix 列表) ### 覆盖颗粒度只在 3 个入口
``` 框架内 .vue 之间的 peer 引用是**硬编码静态 import**,override 颗粒度就停在下面这 3 类入口,不会一路传递下去:
components/login.vue components/404.vue components/layout.vue
components/logo.vue components/navMenu.vue components/sideM.vue | 入口 | 后缀 | 说明 |
components/topbar.vue components/userbar.vue | --- | --- | --- |
components/ShrimpLangSwitch.vue components/ShrimpPowerTree.vue | **router targets** | `components/login.vue`、`components/layout.vue`、`components/404.vue` | vue-router 三个根级路由组件 |
components/ShrimpTable.vue components/ShrimpEditDrawer.vue | **module routes** | `module/<key>.vue`、`module/<parent>/<sub>.vue` | 走 `registerRoute` 的业务模块/子模块 |
components/ShrimpFilterDrawer.vue components/ShrimpFilterTrigger.vue | **field registry** | `components/fields/Field<X>.vue` | 字段类型注册表(文件名首字母小写 = type 键) |
components/ShrimpSearchInput.vue
components/fields/Field{String,Boolean,Date,Json,Number,Password,Relation,Select,Tab,Textarea,RelativeTime}.vue 想换更细的部件(比如 layout 里的 topbar)就在消费侧的 `layout.vue` 自己组装 — 框架不再代理任何 peer 切换。
```
### 字段类型注册 ### 字段类型注册
`components/fields/Field<X>.vue` 自动注册类型 `<x>`(首字母小写): `components/fields/Field<X>.vue` 自动注册类型 `<x>`(首字母小写):
| 文件 | type 注册键 | | 文件 | type 注册键 |
| ------------------------ | ------------------ | | -------------------------- | ---------------- |
| `FieldString.vue` | `string` | | `FieldString.vue` | `string` |
| `FieldRelativeTime.vue` | `relativeTime` | | `FieldRelativeTime.vue` | `relativeTime` |
| 你自己的 `FieldMyType.vue` | `myType` | | 你自己的 `FieldMyType.vue` | `myType` |
后端 moduleInfo 里 `field.type === 'myType'` 时就用你这个组件。 后端 moduleInfo 里 `field.type === 'myType'` 时就用你这个组件。内置类型: `string` / `boolean` / `date` / `json` / `number` / `password` / `relation` / `select` / `tab` / `textarea` / `relativeTime`。
### 业务模块 ### 业务模块
`components/X.vue` 命中 `moduleKey === 'X'` 的路由,自动作为内容页。子表用嵌套目录(`module/<parent>/<sub>.vue`)。 `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` 路由就会用你这份替换内置版本。
## 消费的契约 ## 消费的契约