0.9.0: 按后端给的 sheet 表建/读工作簿(多 sheet)

配 shrimp-server v0.9.0:export 返回 { sheet 名: 行数组 },这边逐 key 建 sheet; 导入把工作簿里所有 sheet 都发回后端(旧版只读第一张、其余静默丢弃),哪张怎么用由模块的 import 决定。sheet 名按 Excel 限制截断/替换,否则 book_append_sheet 直接抛。
exports: ./style 加 types 条件，消掉 noUncheckedSideEffectImports 下的 TS2307
2026-08-21 20:06:14 +08:00 · 2026-08-14 16:19:12 +08:00 · 2026-08-14 15:55:36 +08:00 · 2026-08-14 14:41:44 +08:00 · 2026-08-11 16:57:43 +08:00 · 2026-08-11 12:18:48 +08:00
13 changed files with 425 additions and 63 deletions
@@ -4,37 +4,183 @@ Shrimp 框架前端 —— 一种**经典解决方案**(不是框架本身),消

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

-## 安装
+shrimp-admin 是**源码 ship**(.ts + .vue 直接发),不带构建产物,由消费侧 Vite 编译。这省掉了框架的构建步骤,代价是**有几件事 npm 装完不会自动生效**,必须消费侧显式配 —— 下面的接入模板已经把它们全写进去了。

-```bash
-npm i git+http://git.zeromvc.com/wc24/shrimp-admin.git#v0.3.0
+---
+
+# 接入模板
+
+> **整段抄,不要自己攒。** 标了「⚠️ 不能删」的行看起来多余,删掉的后果写在每行旁边;
+> 现存的 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-admin 是**源码 ship**(.ts + .vue 直接发),由消费侧 Vite 编译。
+服务端那侧另有一条硬约束:**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
-// main.ts
 import { createApp } from 'vue'
-import { createShrimpAdmin, App } from 'shrimp-admin'
+
+// ⚠️ 不能删,且必须在 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',
+        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')
 ```

-## 唯一约定: `sources` 路径后缀覆盖
+## 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 静态扫描相对调用文件)。框架按**文件路径后缀**匹配,同后缀消费侧优先,内置兜底。

@@ -47,22 +193,26 @@ app.mount('#app')
    │   └── fields/
    │       └── FieldRelativeTime.vue 注册字段类型 relativeTime
    └── module/
-        ├── product.vue               业务模块,routed by moduleKey
+        ├── product.vue               覆盖业务模块 product 的默认表格
+        ├── _default.vue              覆盖「所有没单独写壳的模块」用的那份
        └── user/
            └── orders.vue            子模块,parent=user
 ```

-### 覆盖颗粒度只在 3 个入口
+`module/` 下一个文件都没有也能跑 —— 那时每个模块都落到内置的 `module/_default.vue`。

-框架内 .vue 之间的 peer 引用是**硬编码静态 import**,override 颗粒度就停在下面这 3 类入口,不会一路传递下去:
+### 覆盖颗粒度只在这几个入口
+
+框架内 .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` | 走 `registerRoute` 的业务模块/子模块 |
+| **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` | 右上角那一条(语言、全屏、用户菜单),整体替换 |

-想换更细的部件(比如 layout 里的 topbar)就在消费侧的 `layout.vue` 自己组装 — 框架不再代理任何 peer 切换。
+**表里没有的路径不会被覆盖,而且不报错**——写了个 `components/topbar.vue` 放进 sources,框架照样用内置那份,页面正常打开、你的文件被静默忽略。想换更细的部件就在消费侧的 `layout.vue` 里自己组装,框架不代理 peer 切换。

 ### 字段类型注册

@@ -74,11 +224,15 @@ app.mount('#app')
 | `FieldRelativeTime.vue`    | `relativeTime`   |
 | 你自己的 `FieldMyType.vue` | `myType`         |

-后端 moduleInfo 里 `field.type === 'myType'` 时就用你这个组件。内置类型: `string` / `boolean` / `date` / `json` / `number` / `password` / `relation` / `select` / `tab` / `textarea` / `relativeTime`。
+后端 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/<key>.vue` 命中 `moduleKey === '<key>'` 的路由,自动作为内容页。子表用嵌套目录(`module/<parent>/<sub>.vue`)。没写的模块落到 `module/_default.vue`,消费侧写一份同名文件即可整体换掉那个默认。

 ### 例子: 覆盖 login 页

@@ -130,7 +284,7 @@ function login() {

 只要文件落在 `src/shrimp/components/login.vue`,被 `sources` 的 glob 扫到,框架的 `/login` 路由就会用你这份替换内置版本。

-## 消费的契约
+# 消费的契约

 参见 shrimp-server README `## 约定` 章节。本包消费以下条件契约:

@@ -1,12 +1,12 @@
 {
    "name": "shrimp-admin",
-    "version": "0.1.0",
+    "version": "0.8.3",
    "lockfileVersion": 3,
    "requires": true,
    "packages": {
        "": {
            "name": "shrimp-admin",
-            "version": "0.1.0",
+            "version": "0.8.3",
            "dependencies": {
                "shrimp-server": "git+http://git.zeromvc.com/wc24/shrimp-server.git#v0.5.0"
            },
@@ -1,6 +1,6 @@
 {
    "name": "shrimp-admin",
-    "version": "0.7.6",
+    "version": "0.9.0",
    "private": true,
    "description": "Shrimp 框架前端 — 消费 ShrimpServer + ShrimpTable 契约的经典 Vue3 + Element Plus 实现",
    "main": "src/index.ts",
@@ -10,20 +10,28 @@
            "types": "./src/index.ts",
            "default": "./src/index.ts"
        },
-        "./style": "./src/style/style.scss",
+        "./style": {
+            "types": "./src/style/style.d.ts",
+            "default": "./src/style/style.scss"
+        },
        "./package.json": "./package.json"
    },
    "files": [
        "src",
        "README.md"
    ],
+    "scripts": {
+        "check:contract": "node scripts/check-contract.mjs",
+        "sync:contract": "node scripts/check-contract.mjs --fix"
+    },
    "peerDependencies": {
        "vue": "^3.3.0",
        "vue-router": "^4.0.0",
        "vue-i18n": "^9.0.0",
        "axios": "^1.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": {
        "@types/node": "^20.0.0",
@@ -0,0 +1,61 @@
+/**
+ * 契约副本工具:比对 / 同步 src/IShrimpType.ts 与 shrimp-server 那份。
+ *
+ *   node scripts/check-contract.mjs          比对,漂了就非零退出
+ *   node scripts/check-contract.mjs --fix    从 shrimp-server 复制过来(自动保留前端副本的注释头)
+ *
+ * 为什么需要它:副本靠人工同步,漂了一整代都没被发现——
+ * 副本停在旧的 json 类型、缺 object/array/fields/item/parse/refs。
+ * 前端对未注册的字段类型静默回落到 string,所以漂移不报错、只悄悄渲染错。
+ * (同样是"改了就复制过去"的约定,goby 的 GobyClient.ts 四份拷贝已经全漂了,
+ *  区别只在于那份复制后归消费侧拥有、漂了无所谓,而这份两边必须字节一致。)
+ *
+ * 只比对注释块之后的正文:两边的头部本来就该不同,一份是契约、一份声明自己是副本。
+ */
+import { readFileSync, writeFileSync, existsSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import { dirname, resolve } from "node:path"
+
+const here = dirname(fileURLToPath(import.meta.url))
+const mine = resolve(here, "../src/IShrimpType.ts")
+const fix = process.argv.includes("--fix")
+const argPath = process.argv.find(a => !a.startsWith("--") && a !== process.argv[0] && a !== process.argv[1])
+
+const theirs = [
+    argPath && resolve(argPath, "src/IShrimpType.ts"),
+    resolve(here, "../node_modules/shrimp-server/src/IShrimpType.ts"),
+    resolve(here, "../../shrimp-server/src/IShrimpType.ts"),
+].filter(Boolean).find(existsSync)
+
+if (!theirs) {
+    // 消费侧的前端项目不装后端包,找不到是正常的,不该让它们的构建挂掉
+    console.log("skip: 找不到 shrimp-server 源码,无从比对")
+    process.exit(0)
+}
+
+const split = f => {
+    const s = readFileSync(f, "utf8")
+    const i = s.indexOf("*/") + 2
+    return { head: s.slice(0, i), body: s.slice(i) }
+}
+
+const a = split(mine)
+const b = split(theirs)
+
+if (a.body === b.body) {
+    console.log("✅ 契约副本与 shrimp-server 一致")
+    process.exit(0)
+}
+
+if (fix) {
+    writeFileSync(mine, a.head + b.body)
+    console.log("✅ 已从 shrimp-server 同步契约副本(保留原注释头)")
+    console.log("   " + theirs + "\n → " + mine)
+    process.exit(0)
+}
+
+console.error("❌ 契约副本已漂移")
+console.error("   副本: " + mine)
+console.error("   契约: " + theirs)
+console.error("   修法: npm run sync:contract")
+process.exit(1)
@@ -1,15 +1,18 @@
 /**
 * Shrimp 类型契约 — 前后端 wire protocol 定义(前端副本)
 *
- * @syncedFrom shrimp-server contract 1.0.0
+ * 这是 shrimp-server/src/IShrimpType.ts 的逐字副本(除本注释块外)。
+ * 不要在这里改 wire protocol,先改 shrimp-server 那份升版本,再整份 cp 过来。
 *
- * 这是 shrimp-server/src/IShrimpType.ts 的逐字副本。
- * 不要在这里改 wire protocol,先改 shrimp-server 那份升版本,再 copy 过来更新 @syncedFrom。
+ * 本文件由 shrimp-server 的 postbuild 自动同步过来,手改会被下次 build 覆盖。
+ * 手动同步: npm run sync:contract   只想看漂没漂: npm run check:contract
+ * 自动同步这件事存在的原因是:曾经靠人工复制,漂了一整代都没人发现——
+ * 副本停在旧的 json 类型、缺 object/array/fields/item/parse/refs,
+ * 而前端对未注册类型静默回落到 string,所以漂移不会报错、只会悄悄渲染错。
 *
 * 故意保留副本而不 import 'shrimp-server' 的原因:
- *   - shrimp-server 入口会把 mongoose / express 牵进前端 bundle
- *   - 拆 './types' 子入口会绕开 vite optimize、可读性也差
- *   - 类型契约低频改动,版本号对照即可
+ *   - shrimp-server 默认入口会把 mongoose / express 牵进前端 bundle
+ *   - 前端项目不该为一份纯类型去装后端包
 */

 /** 业务错误码 */
@@ -122,11 +125,20 @@ export interface ITableProto<T> {
    delete(id: string): Promise<boolean>
 }

+/**
+ * 导入导出的负载形态：sheet 名 -> 行数组，对应 xlsx 的一个工作簿。
+ *
+ * 普通模块就是一个 sheet（默认以 moduleKey 命名）；模块重写 export/import
+ * 就能自定义多 sheet（如「商品/商店/销售规则」各一张），前端按 key 建/读 sheet。
+ * 兼容：老版本的裸数组负载等价于「单 sheet」，两端都会归一。
+ */
+export type IShrimpSheets = Record<string, any[]>
+
 /** 完整 Table 协议（后端可用，含管理操作） */
 export interface ITableCrudProto<T> extends ITableProto<T> {
    clear(query?: IPageQuery & any): Promise<boolean>
-    export(query?: IPageQuery & any): Promise<T[]>
-    import(data?: T[], ownerId?: string): Promise<void>
+    export(query?: IPageQuery & any): Promise<IShrimpSheets>
+    import(data?: IShrimpSheets | T[], ownerId?: string): Promise<void>
 }

 // ============== 预制数据模型 ==============
@@ -238,8 +250,9 @@ export const ShrimpFieldTypes = {
    Textarea: "textarea" as ShrimpFieldType,
    Password: "password" as ShrimpFieldType,
    Relation: "relation" as ShrimpFieldType,
-    Json: "json" as ShrimpFieldType,
    Tab: "tab" as ShrimpFieldType,
+    Object: "object" as ShrimpFieldType,
+    Array: "array" as ShrimpFieldType,
 }

 /** 字段可编辑状态 */
@@ -279,6 +292,12 @@ export interface IFieldConfig {
    rules?: IFieldRule[]          // 通用验证规则（前后端共用）
    /** tab 类型专用：每个 type 对应的子字段配置 */
    tabs?: { key: any; label: ILabel; fields: IFieldConfig[] }[]
+    /** object 类型专用：嵌套字段组 */
+    fields?: IFieldConfig[]
+    /** array 类型专用：每个元素的字段配置(递归 IFieldConfig；元素无需 key，label 用作每项标题) */
+    item?: IFieldConfig
+    /** tab 类型专用：import 反序列化(把字符串还原成对象，如 xlsx 导入)，默认 JSON.parse */
+    parse?: (text: string) => any
 }

 /** 通用验证规则（前后端共用） */
@@ -315,6 +334,7 @@ export interface IPageResult<T> {
    page: number       // 当前页码
    pageSize: number   // 每页数量
    totalPages: number // 总页数
+    refs?: Record<string, Record<string, any>>  // relation 显示名字典: { moduleKey: { id: 显示名 } }，前端显示时查名，替代逐行 _label
 }

 // ============== 数据源查询协议 ==============
@@ -78,6 +78,15 @@ export function resolveVue(suffix: string): VueLoader {
    for (const key in internalSources) {
        if (key.endsWith(tail)) return internalSources[key] as any
    }
+    // 内置表整个是空的,说明本包被 esbuild 预打包了——import.meta.glob 是 vite 编译期宏,
+    // 预打包不认它,内置组件一个都收不到。报"找不到 layout.vue"会把人引向错误的方向。
+    if (Object.keys(internalSources).length === 0) {
+        throw new Error(
+            `[shrimp-admin] 内置组件表为空,本包没有被 vite 正常转换。\n` +
+            `  消费侧 vite.config 需要: optimizeDeps: { exclude: ["shrimp-admin"] }\n` +
+            `  (或直接用 shrimp-admin/vite 提供的插件,它会自动加上)`
+        )
+    }
    throw new Error(`[shrimp-admin] resolveVue: ${suffix} not found in sources`)
 }

@@ -88,6 +97,19 @@ export function resolveVue(suffix: string): VueLoader {

 const fieldRegistry = new Map<string, Component>()

+/** 未注册类型每种只喊一次——表格逐格调 getFieldComponent,不去重会刷屏 */
+const warnedTypes = new Set<string>()
+function warnOnce(type: string, moduleKey?: string, fieldKey?: string) {
+    if (warnedTypes.has(type)) return
+    warnedTypes.add(type)
+    console.warn(
+        `[shrimp-admin] 字段类型 "${type}" 没有对应组件,已按 string 渲染` +
+        (moduleKey || fieldKey ? `(出现在 ${moduleKey ?? '?'}.${fieldKey ?? '?'})` : '') +
+        `\n  已注册: ${[...fieldRegistry.keys()].sort().join(', ')}` +
+        `\n  要么后端把 type 改成上面之一,要么消费侧补一个 shrimp/components/fields/Field${type.charAt(0).toUpperCase() + type.slice(1)}.vue`
+    )
+}
+
 function deriveFieldType(path: string): string | null {
    const m = path.match(/\/components\/fields\/Field([A-Z][A-Za-z0-9]*)\.vue$/)
    if (!m) return null
@@ -127,7 +149,12 @@ export class VueAdmin extends ShrimpClient {
    moduleRoutes = new Map<string, IRouteInfo>()

    getFieldComponent(_moduleKey: string, type: string, _fieldKey?: string): Component {
-        return fieldRegistry.get(type) || fieldRegistry.get('string')!
+        const hit = fieldRegistry.get(type)
+        if (hit) return hit
+        // 类型词汇表是开放的(消费侧放个 Field<X>.vue 就能扩),所以这里不能报错、只能回落。
+        // 但静默回落等于打错字永远发现不了——曾经有个 json 类型这么活了一整代。
+        warnOnce(type, _moduleKey, _fieldKey)
+        return fieldRegistry.get('string')!
    }

    /** 目标模块能否作为「单项查看」跳转目标:已按权限注册路由 且 非子模块。返回其路由信息或 undefined(不可跳) */
@@ -254,8 +281,10 @@ export class VueAdmin extends ShrimpClient {
        try {
            importer = resolveVue(`module/${componentPath}.vue`)
        } 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", {
            path: info.path || "/" + info.name,
@@ -4,11 +4,18 @@
        <el-form :model="localFilterData">
            <template v-for="field in filterableFields" :key="field.key">
                <el-form-item :label="vueAdmin.t(field.label)">
+                    <div class="filter-field-row">
+                        <div class="filter-field-control">
                            <slot :name="`filter-${field.key}`" :field="field" :data="localFilterData">
-                        <component :is="vueAdmin.getFieldComponent(moduleKey, field.type, field.key)" :field="field"
-                            :model-value="localFilterData[field.key]"
+                                <component :is="vueAdmin.getFieldComponent(moduleKey, field.type, field.key)"
+                                    :field="field" :model-value="localFilterData[field.key]"
                                    @update:model-value="onFieldChange(field.key, $event)" mode="filter" />
                            </slot>
+                        </div>
+                        <!-- 单独清空该字段:常驻、无值时禁用(不 v-if,避免按钮显隐导致布局闪动) -->
+                        <el-button link :icon="CircleClose" class="filter-clear"
+                            :disabled="!hasValue(field.key)" @click="clearField(field.key)" />
+                    </div>
                </el-form-item>
            </template>
        </el-form>
@@ -21,6 +28,7 @@

 <script lang="ts" setup>
 import { ref, watch } from 'vue'
+import { CircleClose } from '@element-plus/icons-vue'
 import { IFieldConfig } from '../IShrimpType'
 import { vueAdmin } from '../VueAdmin'

@@ -68,6 +76,21 @@ function onFieldChange(key: string, value: any) {
    localFilterData.value = { ...localFilterData.value, [key]: value }
 }

+// 该字段当前是否有筛选值(决定单独清空按钮是否出现);范围 {gte,lte}/数组按内容判空
+function hasValue(key: string): boolean {
+    const v = localFilterData.value[key]
+    if (v == null || v === '') return false
+    if (Array.isArray(v)) return v.length > 0
+    if (typeof v === 'object') return Object.keys(v).length > 0
+    return true
+}
+
+// 单独清空某个字段:只摘掉这一个 key,其余筛选条件不动
+function clearField(key: string) {
+    const { [key]: _, ...rest } = localFilterData.value
+    localFilterData.value = rest
+}
+
 function handleReset() {
    closedByReset.value = true
    localFilterData.value = {}
@@ -101,4 +124,23 @@ function handleConfirm() {
 .shrimp-drawer .el-drawer__body .el-form-item {
    margin-bottom: 20px;
 }
+
+.filter-field-row {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    width: 100%;
+}
+
+.filter-field-control {
+    flex: 1;
+    min-width: 0;
+}
+
+.filter-clear {
+    flex: none;
+    padding: 0;
+    font-size: 16px;
+    color: var(--el-text-color-secondary);
+}
 </style>
@@ -35,7 +35,7 @@
                    </el-table-column>
                </template>

-                <el-table-column :label="$t('base.operation')" :width="rowActionsWidth" v-if="hasRowActions">
+                <el-table-column :label="$t('base.operation')" :width="resolvedRowActionsWidth" v-if="hasRowActions">
                    <template #default="{ row }">
                        <el-button v-if="hasActiveField && can('edit')" link :type="row.active ? 'warning' : 'success'" :icon="row.active ? VideoPause : VideoPlay" size="large" @click="handleToggleActive(row)" />
                        <el-button v-if="can('edit')" link type="primary" :icon="Edit" size="large" @click="handleEdit(row)" />
@@ -100,6 +100,8 @@ interface Props {
    pageSize?: number
    /** 显式锁定的筛选条件(覆盖自动 ownerKey 推断);用户无法修改,会合并进 filter 并在筛选抽屉中隐藏 */
    baseFilter?: Record<string, any>
+    /** 显式指定操作列宽度;传入后覆盖按内置按钮数量自动计算的宽度,适用于 row-actions 插槽塞了多个按钮的场景 */
+    rowActionsWidth?: number | string
 }

 const props = withDefaults(defineProps<Props>(), {
@@ -287,7 +289,8 @@ function handleSubJump(sub: IModuleInfo, row: any) {

 const hasRowActions = computed(() => can('edit') || can('delete') || hasActiveField.value || subModules.value.length > 0 || !!slots['row-actions'])

-const rowActionsWidth = computed(() => {
+const resolvedRowActionsWidth = computed(() => {
+    if (props.rowActionsWidth != null && props.rowActionsWidth !== '') return props.rowActionsWidth
    let n = 0
    if (hasActiveField.value && can('edit')) n++
    if (can('edit')) n++
@@ -446,6 +449,27 @@ function buildFilter(): Record<string, any> | undefined {
    return Object.keys(filter).length > 0 ? filter : undefined
 }

+/** 归一成 sheet 表：老后端(或手写 json)发裸数组时,当作以 moduleKey 命名的单张表 */
+function toSheets(data: any): Record<string, any[]> {
+    if (Array.isArray(data)) return { [props.moduleKey]: data }
+    return data || {}
+}
+
+/** xlsx 单元格放不下对象/数组(会变 [object Object]),通用地 JSON 序列化(覆盖 tab 等结构化字段)。
+ *  import 时这些字符串由后端各类型 reqFilter 还原。 */
+function stringifyRow(row: Record<string, any>): Record<string, any> {
+    const out: Record<string, any> = {}
+    for (const [k, v] of Object.entries(row)) {
+        out[k] = (v !== null && typeof v === 'object') ? JSON.stringify(v) : v
+    }
+    return out
+}
+
+/** Excel 的硬限制:sheet 名不得超 31 字符、不得含 []:*?/\ ,越界 book_append_sheet 直接抛 */
+function sheetName(key: string): string {
+    return key.replace(/[[\]:*?/\\]/g, '_').slice(0, 31) || 'Sheet1'
+}
+
 async function handleExport() {
    emit('export')
    try {
@@ -458,19 +482,12 @@ async function handleExport() {
            query.sortOrder = currentSortOrder.value
        }
        if (ownerId.value) query.ownerId = ownerId.value
-        const list = await api.export(query)
-        // 后端只发原始对象；xlsx 单元格放不下对象/数组(会变 [object Object])，这里通用地 JSON 序列化
-        // (覆盖 tab 等结构化字段)。import 时这些字符串由后端各类型 reqFilter 还原。
-        const rows = list.map((row: Record<string, any>) => {
-            const out: Record<string, any> = {}
-            for (const [k, v] of Object.entries(row)) {
-                out[k] = (v !== null && typeof v === 'object') ? JSON.stringify(v) : v
-            }
-            return out
-        })
-        const ws = XLSX.utils.json_to_sheet(rows)
+        const sheets = toSheets(await api.export(query))
        const wb = XLSX.utils.book_new()
-        XLSX.utils.book_append_sheet(wb, ws, props.moduleKey)
+        for (const [name, rows] of Object.entries(sheets)) {
+            const ws = XLSX.utils.json_to_sheet((rows || []).map(stringifyRow))
+            XLSX.utils.book_append_sheet(wb, ws, sheetName(name))
+        }
        XLSX.writeFile(wb, `${props.moduleKey}_export_${Date.now()}.xlsx`)
        ElMessage.success(t('base.success'))
    } catch (e: any) {
@@ -492,17 +509,19 @@ async function handleFileChange(e: Event) {
    const file = target.files?.[0]
    if (!file) return
    try {
-        let data: any[]
+        let sheets: Record<string, any[]>
        if (file.name.endsWith('.json')) {
-            const text = await file.text()
-            data = JSON.parse(text)
+            sheets = toSheets(JSON.parse(await file.text()))
        } else {
+            // 整本工作簿原样交给后端:哪张 sheet 怎么用,由模块的 import 决定(默认取同名/第一张)
            const buf = await file.arrayBuffer()
            const wb = XLSX.read(buf, { type: 'array' })
-            const ws = wb.Sheets[wb.SheetNames[0]]
-            data = XLSX.utils.sheet_to_json(ws)
+            sheets = {}
+            for (const name of wb.SheetNames) {
+                sheets[name] = XLSX.utils.sheet_to_json(wb.Sheets[name])
            }
-        await api.import(data, ownerId.value)
+        }
+        await api.import(sheets, ownerId.value)
        ElMessage.success(t('base.success'))
        await refresh()
    } catch (e: any) {
@@ -43,15 +43,18 @@
 </template>

 <script lang="ts" setup>
-import { ref, watch } from "vue";
-import { vueAdmin } from "../VueAdmin";
+import { ref, watch, defineAsyncComponent } from "vue";
+import { vueAdmin, resolveVue } from "../VueAdmin";
 import { type IMenuItem } from "../IShrimpType";
 import SideM from "./sideM.vue";
 import navMenu from "./navMenu.vue";
 import Topbar from "./topbar.vue";
-import Userbar from "./userbar.vue";
 import Logo from "./logo.vue";

+// 顶栏走 resolveVue,消费侧放 shrimp/components/userbar.vue 即可整体替换。
+// 其余内置组件仍是静态 import——等真有人要覆盖再逐个放开,不预先把整棵树异步化。
+const Userbar = defineAsyncComponent(resolveVue("components/userbar.vue"));
+
 // 初始化选中菜单
 let currentPath = vueAdmin.router.currentRoute.value.path;
 let pick = vueAdmin.getMenuIndex(currentPath);
@@ -2,7 +2,7 @@
 //
 // 消费侧用法见 README.md。本文件只做 re-export。

-// ===== 类型契约(IShrimpType 本地副本,@syncedFrom shrimp-server contract 1.0.0)=====
+// ===== 类型契约(IShrimpType 是 shrimp-server 那份的副本,由其 postbuild 自动同步)=====
 export {
    ShrimpCode,
    ShrimpError,
@@ -20,6 +20,7 @@ export type {
    IMenuItem,
    ITableProto,
    ITableCrudProto,
+    IShrimpSheets,
    IUser,
    IRole,
    IOperationLog,
@@ -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>
@@ -55,6 +55,11 @@ textarea {
 	display: flex;
 	flex: 1;
 	overflow: auto;
+	/* 挂载点没加 class="aminui" 时的兜底:#app 已经是 height:100%(本文件开头),
+	   但它是块级容器,上面那行 flex:1 在块级父容器里不生效,布局会塌成内容高度——
+	   侧边栏比页面矮一截、还跟着表格异步加载忽长忽短,且不报错、页面照常打开。
+	   父级确实是 .aminui 时,flex:1 1 0% 接管尺寸,这行等价不冲突。 */
+	height: 100%;
 }

 /* 全局滚动条样式 */
@@ -0,0 +1,5 @@
+// `shrimp-admin/style` 的类型出口。样式表本身没有类型可言，这里要回答的只是
+// 「这个说明符解析得到东西」——消费侧开了 noUncheckedSideEffectImports 时，
+// import 'shrimp-admin/style' 落到 .scss 上会报 TS2307,因为 TS 不认识 .scss。
+// package.json 的 exports 里用 types 条件指向本文件,bundler 照旧拿 default 那条 .scss。
+export {}
Author	SHA1	Message	Date
wc24	fef886de87	0.9.0: 按后端给的 sheet 表建/读工作簿(多 sheet) 配 shrimp-server v0.9.0:export 返回 { sheet 名: 行数组 },这边逐 key 建 sheet; 导入把工作簿里所有 sheet 都发回后端(旧版只读第一张、其余静默丢弃),哪张怎么用由模块的 import 决定。sheet 名按 Excel 限制截断/替换,否则 book_append_sheet 直接抛。	2026-08-21 20:06:14 +08:00
wc24	16d8c6b9ed	exports: ./style 加 types 条件，消掉 noUncheckedSideEffectImports 下的 TS2307	2026-08-14 16:19:12 +08:00
wc24	b22f3713c3	README: 补 optimizeDeps.include —— 零模块壳时 element-plus 从未被预打包会白屏	2026-08-14 15:55:36 +08:00
wc24	6bd334a937	业务模块不再需要消费侧薄壳：内置 module/_default.vue 兜底后端 moduleInfo 已经声明了字段、筛选、可用事件，ShrimpTable 要的只有一个 moduleKey，而 registerRoute 本来就把它当 props 传下去——「后端声明了模块，前端就该渲染出来」是本包消费的契约，缺一个四行的壳不该让菜单点不开。 resolveVue 未命中时改为回落到 module/_default.vue，不再 warn+丢路由。消费侧的 module/<key>.vue 仍按后缀优先命中，_default 本身也可被覆盖，纯增量。顺带把 xlsx 补进 peerDependencies：ShrimpTable 是静态 import 它的，漏装则 vite 直接起不来，而模板里一直没写。	2026-08-14 14:41:44 +08:00
wc24	4b6f260227	docs: 内置字段类型照 fields/ 目录重列——删掉不存在的 json，补上 array/object，点明未注册类型是静默回落	2026-08-11 16:57:43 +08:00
wc24	00c2211271	0.8.2 顶栏改走 resolveVue,撤掉 headerWidgets headerWidgets 是往 userbar 里插组件的口子:VueAdmin 收一个组件数组、userbar 用 v-for 渲染。它绕开了本包唯一的覆盖机制(sources 路径后缀),等于给同一件事开了第二条路——而且是条窄路,只能往那一处塞,插进去的东西也没法参与 userbar 自身的布局与样式。撤掉它,同时把真问题补上:userbar 之前根本不可覆盖(layout.vue 静态 import), 消费侧就算按约定放了 shrimp/components/userbar.vue 也会被静默忽略——这才是当初需要 headerWidgets 的原因。现在 userbar 走 resolveVue,整条顶栏都能换。代价:想改顶栏得整份重写内置那 92 行,不能只插一个部件。这是有意的,覆盖颗粒度本来就停在入口级(README 那张表),不为单个部件开代理。 README 同步:补上 userbar 这一行,并写明表外路径会被静默忽略、不报错。	2026-08-11 12:18:48 +08:00
wc24	2ce6fd6d2f	0.8.1: 布局不再依赖消费侧给挂载点加 class="aminui" .aminui-wrapper 补 height:100%。#app 本来就有 height:100%(app.scss 开头), 但它是块级容器,wrapper 的 flex:1 在块级父容器里空转,布局塌成内容高度—— 侧边栏比页面矮一截,还跟着表格异步加载忽长忽短。不报错、页面照常打开, 所以接入方发现不了,只会当成 CSS 小毛病。父级确实是 .aminui 时 flex:1 1 0% 接管尺寸,这行等价不冲突,存量消费侧不受影响。已验证:atf-admin 删掉 index.html 上的 class="aminui" 后, project / point / requirement 三个页面侧边栏高度均为 851(此前缺类时 634)。	2026-08-10 19:55:52 +08:00
wc24	603e33d17f	0.8.0: 契约副本刷齐并改为自动同步;未注册字段类型不再静默回落契约副本(src/IShrimpType.ts)此前漂了一整代:停在旧的 json 类型, 缺 object / array / IFieldConfig.fields / IFieldConfig.item / parse / IPageResult.refs。而本包自己的组件早就在读这些字段——FieldArray 读 field.item、FieldObject 读 fields、 FieldRelation 与 ShrimpTable 读 refs。等于组件在用、类型说没有。接入方照这份副本理解 shrimp 能渲染什么,只会得出"结构化数据只有 json"的结论。现在由 shrimp-server 的 postbuild 单向覆盖过来(它是契约真身), 本仓库另提供 npm run check:contract / sync:contract 手动比对与同步。注释头不参与同步,它声明的是"我是副本",与契约正文是两回事。 VueAdmin.getFieldComponent:未注册类型仍回落成 string(类型词汇表是开放的, 消费侧放个 Field<X>.vue 就能扩,改成严格校验会当场打死 theseus 的 gesture/goodsList 和 hand 的 dropList/matterPointDropList),但按类型去重告警一次, 打印出现位置、已注册类型和两条修法。上面那个 json 就是这么静默活下来的。 resolveVue:内置组件表为空时报"本包没被 vite 正常转换、消费侧缺 optimizeDeps.exclude", 不再报"找不到 layout.vue"把人引去查文件路径。 README 重写成可照抄的接入模板 + 出错对照表 + "那几行为什么不能删"。版本与 shrimp-server 归一到 0.8.0,删掉 @syncedFrom 这条手维护的版本标记。	2026-08-10 19:48:57 +08:00
lbin	b7042c8387	操作栏宽度	2026-07-23 19:11:08 +08:00
lbin	bed4d4dc4a	add: bar components	2026-07-10 15:11:42 +08:00
wc24	ab312fb24f	chore: bump 0.7.10(与 shrimp-server 版本归一)	2026-06-30 17:47:10 +08:00
wc24	546d95c926	fix(filter): 单独清空按钮改禁用态切换,常驻不显隐(避免布局闪动)	2026-06-30 17:34:59 +08:00
wc24	6b0a6118e0	feat(filter): 筛选抽屉每个字段可单独清空每行加 CircleClose 清空按钮(有值才出现),只摘掉该 key、其余条件不动。比依赖各字段组件自身 clearable 更通用(range/relation/必填字段筛选时也能清)。	2026-06-30 17:30:16 +08:00