From 6dff7b82ccaedcae4d9ffe95c329f98c965be1ea Mon Sep 17 00:00:00 2001 From: wc24 Date: Fri, 21 Aug 2026 20:05:37 +0800 Subject: [PATCH] =?UTF-8?q?0.9.0:=20=E5=AF=BC=E5=85=A5=E5=AF=BC=E5=87=BA?= =?UTF-8?q?=E5=8D=8F=E8=AE=AE=E6=94=B9=E6=88=90=20sheet=20=E8=A1=A8(?= =?UTF-8?q?=E5=A4=9A=20sheet)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit export 返回 { sheet 名: 行数组 },import 收同样的形状 —— 一份负载对应一个 xlsx 工作簿。默认仍是单张表(以 moduleKey 命名),模块重写 export/import 就能自定义 多 sheet(如商品/商店/销售规则一次搬完),不必再把多张表压扁成 __t/__data 两列 塞进一个 sheet。 import 取同名 sheet、没有就退回第一张:手工在 Excel 里建的表叫 Sheet1,老版本 前端发的是裸数组,两种都不该白导。 --- README.md | 29 ++++++++++++++ package.json | 2 +- src/IShrimpType.ts | 13 ++++++- src/Shrimp/ShrimpTableModule.ts | 23 ++++++++--- src/main/index.ts | 1 + test/exportSheets.test.ts | 67 +++++++++++++++++++++++++++++++++ 6 files changed, 126 insertions(+), 9 deletions(-) create mode 100644 test/exportSheets.test.ts diff --git a/README.md b/README.md index a35dddf..76a35ff 100644 --- a/README.md +++ b/README.md @@ -362,6 +362,35 @@ class UserTable extends ShrimpTableModule { } ``` +### 导入导出:多 sheet + +`export`/`import` 的负载是 **`IShrimpSheets` = `{ sheet 名: 行数组 }`**,一份对应一个 xlsx 工作簿。 +默认行为:导出一张以 `moduleKey` 命名的 sheet;导入取同名 sheet,没有就退回第一张(手工在 Excel 里建的表叫 `Sheet1`,也能导)。 + +要一个模块导出多张表(比如"商品 / 商店 / 销售规则"一次搬完),重写这两个方法就行,前端会按 key 自动建 sheet、按名字读回来: + +```ts +class ShopTable extends ShrimpTableModule { + async export(): Promise { + return { + goods: await GoodsDB.find().lean(), + shop: await ShopDB.find().lean(), + saleRule: await SaleRuleDB.find().lean(), + } + } + async import(data?: IShrimpSheets) { + for (const row of data?.goods ?? []) { /* 先建商品,记 oldId → newId */ } + for (const row of data?.shop ?? []) { /* 再建商店 */ } + for (const row of data?.saleRule ?? []) { /* 最后用映射还原引用 */ } + } +} +``` + +注意: +- sheet 名受 Excel 限制 —— 超 31 字符或含 `[]:*?/\` 会被前端替换/截断,别拿长 key 当 sheet 名。 +- 单元格放不下对象/数组,前端导出时会把它们 `JSON.stringify`;导入时由字段类型的 `reqFilter`(如 `tab` 的 `parse`)还原。所以嵌套结构建议声明成有 handler 的类型,或自己在 `import` 里 parse。 +- 老版本(≤ v0.8.x)的裸数组负载仍能导入,会被当成单张表。 + ### 字段级 reqFilter / validate 通过 `registerTypeHandler` 注册自定义 type 的处理器: diff --git a/package.json b/package.json index 684e1e1..553c80b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "shrimp-server", - "version": "0.8.1", + "version": "0.9.0", "description": "Shrimp 框架后端 — 声明式字段驱动的 Node.js 管理后台框架(Express + Mongoose + JWT)", "main": "dist/main/index.js", "types": "dist/main/index.d.ts", diff --git a/src/IShrimpType.ts b/src/IShrimpType.ts index 2e83eb0..fda8cdd 100644 --- a/src/IShrimpType.ts +++ b/src/IShrimpType.ts @@ -123,11 +123,20 @@ export interface ITableProto { delete(id: string): Promise } +/** + * 导入导出的负载形态：sheet 名 -> 行数组，对应 xlsx 的一个工作簿。 + * + * 普通模块就是一个 sheet（默认以 moduleKey 命名）；模块重写 export/import + * 就能自定义多 sheet（如「商品/商店/销售规则」各一张），前端按 key 建/读 sheet。 + * 兼容：老版本的裸数组负载等价于「单 sheet」，两端都会归一。 + */ +export type IShrimpSheets = Record + /** 完整 Table 协议（后端可用，含管理操作） */ export interface ITableCrudProto extends ITableProto { clear(query?: IPageQuery & any): Promise - export(query?: IPageQuery & any): Promise - import(data?: T[], ownerId?: string): Promise + export(query?: IPageQuery & any): Promise + import(data?: IShrimpSheets | T[], ownerId?: string): Promise } // ============== 预制数据模型 ============== diff --git a/src/Shrimp/ShrimpTableModule.ts b/src/Shrimp/ShrimpTableModule.ts index 9dfa870..157e9c7 100644 --- a/src/Shrimp/ShrimpTableModule.ts +++ b/src/Shrimp/ShrimpTableModule.ts @@ -1,6 +1,6 @@ import { IFieldConfig, IFieldTypeHandler, IShrimpQuery, IShrimpCondition, IShrimpPopulate, - IPageQuery, IPageResult, ITableCrudProto, ILabel, ShrimpConfig, ShrimpError, ShrimpFieldTypes, + IPageQuery, IPageResult, ITableCrudProto, IShrimpSheets, ILabel, ShrimpConfig, ShrimpError, ShrimpFieldTypes, } from "../IShrimpType" import { Shrimp } from "./Shrimp" import { ShrimpModule, IShrimpModuleOptions } from "./ShrimpModule" @@ -457,7 +457,7 @@ export class ShrimpTableModule = ITableCrudProto } return await this.dataSource.clear() } - async export(query?: IPageQuery & any): Promise { + async export(query?: IPageQuery & any): Promise { const shrimpQuery = this.buildQuery(query) delete shrimpQuery.offset delete shrimpQuery.limit @@ -465,11 +465,22 @@ export class ShrimpTableModule = ITableCrudProto result.list = await this.prepareResponseItems(result.list) // export 只取全量原始数据，不做序列化；结构化字段(如 tab)的字符串化交前端(生成 xlsx 时)。 // import 端如传字符串，由各类型 reqFilter(如 tab 的 parse)还原。 - return result.list.map(item => this.filterHidden(item)) + // 默认一张以 moduleKey 命名的 sheet；要多 sheet 就重写本方法返回多个 key。 + return { [this.moduleKey]: result.list.map(item => this.filterHidden(item)) } } - async import(data?: T[], ownerId?: string): Promise { - if (!data || data.length === 0) return - for (const raw of data) { + /** + * 从导入负载里取本模块这一张表的行。 + * 取 moduleKey 同名 sheet，没有就退回第一张 —— 手工在 Excel 里建的表叫 Sheet1， + * 老版本前端发的是裸数组，两种都不该白导。多 sheet 模块请重写 import 自己分派。 + */ + protected pickSheet(data?: IShrimpSheets | T[]): any[] { + if (!data) return [] + if (Array.isArray(data)) return data + return data[this.moduleKey] ?? Object.values(data)[0] ?? [] + } + async import(data?: IShrimpSheets | T[], ownerId?: string): Promise { + const rows = this.pickSheet(data) + for (const raw of rows) { const item = { ...raw } as Record if (ownerId && this.ownerKey) item[this.ownerKey] = ownerId const id = item._id ? String(item._id) : undefined diff --git a/src/main/index.ts b/src/main/index.ts index e4b5538..065c175 100644 --- a/src/main/index.ts +++ b/src/main/index.ts @@ -40,6 +40,7 @@ export type { IMenuItem, ITableProto, ITableCrudProto, + IShrimpSheets, IUser, IRole, IOperationLog, diff --git a/test/exportSheets.test.ts b/test/exportSheets.test.ts new file mode 100644 index 0000000..69ab9ec --- /dev/null +++ b/test/exportSheets.test.ts @@ -0,0 +1,67 @@ +import { describe, it, expect } from "vitest" +import { Shrimp, ShrimpTableModule, MemoryShrimpCrud, ShrimpFieldTypes } from "../src/main" +import type { IShrimpSheets } from "../src/main" + +type Row = { _id: string; name: string } + +function makeModule() { + const shrimp = new Shrimp() + const crud = new MemoryShrimpCrud() + const mod = new ShrimpTableModule(shrimp, "tag", crud, [ + { key: "name", label: "名称", type: ShrimpFieldTypes.String }, + ], "标签") + mod.initCrud() + return { crud, mod } +} + +describe("导入导出的 sheet 契约", () => { + it("export 返回以 moduleKey 命名的单张 sheet", async () => { + const { crud, mod } = makeModule() + await crud.add({ name: "热门" } as any) + const sheets = await mod.export({}) + expect(Object.keys(sheets)).toEqual(["tag"]) + expect(sheets.tag.map(r => r.name)).toEqual(["热门"]) + }) + + it("import 认同名 sheet", async () => { + const { crud, mod } = makeModule() + await mod.import({ other: [{ name: "别人的" }], tag: [{ name: "热门" }] }) + const all = await crud.list({}) + expect(all.list.map(r => r.name)).toEqual(["热门"]) + }) + + it("没有同名 sheet 时退回第一张(手工 Excel 的 Sheet1)", async () => { + const { crud, mod } = makeModule() + await mod.import({ Sheet1: [{ name: "热门" }] }) + expect((await crud.list({})).list.map(r => r.name)).toEqual(["热门"]) + }) + + it("老版本前端发的裸数组仍然能导", async () => { + const { crud, mod } = makeModule() + await mod.import([{ name: "热门" }] as any) + expect((await crud.list({})).list.map(r => r.name)).toEqual(["热门"]) + }) + + it("多 sheet 由模块重写 export/import 自行分派", async () => { + const shrimp = new Shrimp() + const goods = new MemoryShrimpCrud() + const shops = new MemoryShrimpCrud() + class ShopModule extends ShrimpTableModule { + async export(): Promise { + return { goods: (await goods.list({})).list, shop: (await shops.list({})).list } + } + async import(data?: IShrimpSheets): Promise { + for (const row of data?.goods ?? []) await goods.add(row as any) + for (const row of data?.shop ?? []) await shops.add(row as any) + } + } + const mod = new ShopModule(shrimp, "shop", shops, [ + { key: "name", label: "名称", type: ShrimpFieldTypes.String }, + ], "商店") + + await mod.import({ goods: [{ name: "木剑" }], shop: [{ name: "杂货铺" }] }) + const sheets = await mod.export() + expect(sheets.goods.map(r => r.name)).toEqual(["木剑"]) + expect(sheets.shop.map(r => r.name)).toEqual(["杂货铺"]) + }) +})