Files
funjia-admin-viewmodel-temp…/doc.md
T
funjia 4eafb9ebfe fix: 修正插件构建配置,与宿主 __FUNJIA_HOST__ 契约对齐
原配置产出的是「在别的系统里跑不起来」的产物,三处一起修:

1. **external 与 globals 对不上**
   原来 external 了 funjia-axios 却没有 output.globals 映射,
   rollup 自己猜的全局名与宿主挂的 window.axios 不一致,插件静默失效。
   现在 external / globals 收口到一张 HOST_GLOBALS 表,只列宿主真正提供的
   三个全局:vue / funjiaui / axios。顺带修掉 external 里 'axois' 的拼写错误。
   element-plus 改为**不 external**(共享它需要宿主 import * as ElementPlus,
   会关掉 tree-shaking 把整个库塞进宿主包),由插件自带。

2. **output.exports 必须是 default**
   视图模型是 export default class,宿主直接把它当类用。
   用 named(或 rollup 见到 __esModule 时自动选 named)会产出命名空间对象
   window.Notice = { default: [class] },表现为「脚本加载成功、控制台无报错、
   但表格一列都不出来」的静默失败。

3. **入口/全局名不再手工改配置文件**
   新增 scripts/build-vm.mjs,用法 `npm run build:vm Notice`:
   由 VIEWMODEL 环境变量驱动 entry 与 lib.name,并对名字做合法性校验、
   对入口文件做存在性校验、失败时列出可用的视图模型。
   脚本内不走 npx(Windows 上 .bin 符号链接缺失时会报「vite 不是内部或外部命令」),
   直接用 process.execPath 跑 vite 的 JS 入口;日志保持纯 ASCII,
   避免控制台 GBK 代码页把中文输出变成乱码。

顺带:
- package.json 的 git 依赖 http:// 改 https://(80 端口不可达),
  funjiaui 升到 v1.4.0(宿主用的版本,装饰器语义要对齐)
- doc.md 补「怎么用」(链路 / 契约 / 注意事项),下半部分代码解析保留

已验证:npm run build:vm Notice 产出 12.2 KiB 的 IIFE,
在 vm 里执行后 window.Notice 是可实例化的类(含 getList / onAdd / getDetail /
onEdit / delByIds 与 operateWidth / isEdit),放进宿主静态目录后
「通知」「标签」两页正常渲染出表格(分别 6 行 / 10 行真实数据,控制台无报错)。
2026-09-25 11:06:07 +08:00

7.8 KiB
Raw Blame History

本文档分两部分: 上半部分是怎么用这个仓库(构建、上传、与宿主的契约), 下半部分是视图模型代码本身的逐段解析。


一、怎么用:从写视图模型到页面上线

这个仓库是干什么的

每次构建产出一个视图模型的自包含脚本。上传到宿主后端后, 宿主的 UmRemoteClass 会在运行时加载它 —— 于是新增一张表格页不需要改前端代码、 不需要重新打包发版。

完整链路

步骤 做什么
① 在 src/<名字>.ts 写视图模型(用 funjiaui 的装饰器)
② npm run build:vm <名字>,产出 dist/<名字>.iife.js
③ 把该文件上传到宿主的静态目录(server/static/)
④ 在宿主的 dataDict 表 MENU_JSON 里加一条路由 /app/dynamicTable/<小写名字>/<文件名>/<标题>
⑤ 宿主加载脚本 → 取 window[<名字>] → 渲染表格
npm run build:vm Notice     # 产出 dist/Notice.iife.js
npm run build:vm Tag
npm run build:vm            # 不带参数时列出可用的视图模型
npm run dev                 # 本地起宿主演示站(需要后端在 4873)

⚠️ 与宿主的契约(改构建配置前必读)

宿主项目里 src/common/host.ts 的 PLUGIN_GLOBALS 是唯一约定来源。 本仓库 vite.config.ts 的 HOST_GLOBALS 必须与它一致:

插件 external 的模块 宿主提供的全局
vue window.vue
funjiaui window.funjiaui
funjia-axios window.axios

三条容易踩的规则:

  1. lib.name 会成为 IIFE 的全局名。 宿主取的是 window[首字母大写的 name],所以 lib.name = 'Notice' 必须对应菜单路由里的 notice。名字只能是合法 JS 标识符(构建时会校验)。
  2. output.exports 必须是 default,不能是 named。 视图模型是 export default class,宿主直接把它当类用。 若被包成命名空间(window.Notice = { default: ... }), 表现是「脚本加载成功、控制台无报错、但表格一列都不出来」—— 最难查的静默失败。代价:视图模型只能有 default 导出。
  3. vue 绝不能重复打包,element-plus 必须自己打包。 两份 Vue 会破坏响应式与实例识别(所以 vue 是 external); 而 element-plus 共享需要宿主 import * as ElementPlus、会关掉 tree-shaking、 把整个组件库塞进宿主包,不划算 —— 所以它不设 external,由插件自带。

视图模型能依赖什么

  • window.funjiaui — 装饰器与组件
  • window.vue — Vue 运行时
  • window.axios — 宿主已配置好的请求实例(含鉴权与响应解包)
  • window.__FUNJIA_HOST__ — 显式契约对象,含 contractVersion / app / api / resource

推荐用 resource 而不是自己拼接口路径,这样换系统只改宿主一处:

const { getList, get, add, update, remove } = window.__FUNJIA_HOST__.resource("Notice");

注意事项

  • 插件脚本要纳入版本控制。 脚本不在库里的话,换台机器部署就会少文件, 而页面只会「空白」或不给你任何提示。
  • 运行时脚本没有类型检查、没有 sourcemap,字段名写错通常不报错、只是不生效。 视图模型里挂上配置体检(funjiaui 的 diagnose)能兜住这类静默失败。
  • npm install 在本机可能较慢,且 esbuild 的 postinstall 在 Windows 上偶发 EBUSY; 可用 npm install --ignore-scripts 绕过(不影响构建)。

二、视图模型代码解析

这段代码是一个使用装饰器实现的Vue表格组件配置类,主要用于管理系统中的通知(Notice)数据的增删改查操作。以下是对代码的详细分析:

1. 核心功能

  • 数据展示:通过装饰器配置表格列和搜索表单
  • CRUD操作:实现通知的创建、读取、更新、删除功能
  • 表单验证:内置字段验证规则
  • 权限控制:支持动态显示操作按钮
  • API集成:与后端接口对接

2. 主要装饰器解析

2.1 字段装饰器

@tcpd({ "lang": "", "def": "消息", minWidth: 120 })
@tfcpd({ "lang": "", "def": "消息", fieldType: "string", rule: [{ "type": "require", message: "不能为空" }] })
message: string = ""
  • @tcpd:配置表格列属性
    • minWidth:最小列宽
    • def:列显示名称
  • @tfcpd:配置表单字段属性
    • fieldType:字段类型
    • rule:验证规则

2.2 方法装饰器

@tcmd({
    "key": "table:toolbar",
    "value": {
        "type": "添加",
        "priority": 1,
        "es": "onAfter",
        "dialogContent": UmTableForm,
        "dialogTitle": "增加",
        "dialogWidth": 650
    }
})
onAdd = async (data: any) => { ... }
  • @tcmd:配置表格操作
    • type:操作类型(添加/编辑/删除)
    • dialogContent:使用的表单组件
    • dialogWidth:对话框宽度
    • sort:操作按钮排序

3. 核心方法说明

3.1 数据获取

@tcmd({ "key": "table:searchFormMethod", "value": { "type": "getList", "es": "onAfter" } })
getList = async (params: any) => {
    return await api.getNoticeList(params);
}
  • 通过API获取通知列表
  • 装饰器配置为搜索表单的后置方法

3.2 新增操作

onAdd = async (data: any) => {
    const { code, msg } = await api.addNotice({ ...data, userId: Notice.userId });
    return { code: code === 0 ? 0 : 1, message: msg };
}
  • 提交新增请求
  • 自动附加用户ID
  • 返回操作结果

3.3 编辑操作

@tcmd({ "value": { "type": "edit", "es": "onBefore", ... } })
getDetail = async (rowId: number) => {
    const { data } = await api.getNotice({ id: rowId });
    return data;
}

@tcmd({ "value": { "type": "edit", "es": "onAfter", ... } })
onEdit = async (params: any) => {
    const { code, msg } = await api.updateNotice({ ...params, userId: Notice.userId });
    return { code: code === 0 ? 0 : 1, message: msg };
}
  • 分两个阶段处理:
    1. getDetail:编辑前获取详情数据
    2. onEdit:提交编辑请求

3.4 删除操作

@tcmd({
    "value": {
        "type": "del",
        "es": "onAfter",
        "dialogContent": "确定要删除该条数据吗?"
    }
})
delByIds = async (rowId: number) => {
    const { code, msg } = await api.deleteNotice({ ids: [rowId] });
    return { code: code === 0 ? 0 : 1, message: msg };
}
  • 删除前弹出确认对话框
  • 支持批量删除(当前实现为单条删除)

4. 特色功能实现

4.1 动态显示控制

isShow = (rowData: any) => {
    return rowData?.source_add_type == "1";
}
  • 通过判断数据字段决定是否显示操作按钮

4.2 用户上下文

static userId: any;
  • 通过静态属性存储当前用户ID
  • 在提交操作时自动附加到请求参数

5. 使用建议

  1. 用户ID设置:
// 在使用前设置当前用户ID
Notice.userId = store.getters.userId;
  1. 自定义操作扩展:
@tcmd({
    "value": {
        "id": 1,
        "type": "customOperateEvent",
        "title": "详情",
        isShow: (row) => row.status === 1
    }
})
customAction = (rowId: number) => {
    router.push(`/detail/${rowId}`);
}
  1. 表单验证增强:
@tfcpd({
    fieldType: "number",
    rule: [
        { type: "require", message: "不能为空" },
        { validator: (v) => v > 0, message: "必须大于0" }
    ]
})
sort: number = 1;
  1. 国际化支持:
@tcpd({ lang: "notice.message", def: "消息" })

该设计通过装饰器实现了高度可配置的表格组件,建议结合具体业务需求扩展装饰器配置,并确保API接口的异常处理完备。