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

244 lines
7.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
> 本文档分两部分:
> 上半部分是**怎么用这个仓库**(构建、上传、与宿主的契约),
> 下半部分是**视图模型代码本身的逐段解析**。
---
# 一、怎么用:从写视图模型到页面上线
## 这个仓库是干什么的
每次构建产出**一个视图模型**的自包含脚本。上传到宿主后端后,
宿主的 `UmRemoteClass` 会在运行时加载它 —— 于是**新增一张表格页不需要改前端代码、
不需要重新打包发版**。
## 完整链路
| 步骤 | 做什么 |
| --- | --- |
| ① | 在 `src/<名字>.ts` 写视图模型(用 funjiaui 的装饰器) |
| ② | `npm run build:vm <名字>`,产出 `dist/<名字>.iife.js` |
| ③ | 把该文件上传到宿主的静态目录(`server/static/`) |
| ④ | 在宿主的 `dataDict` 表 `MENU_JSON` 里加一条路由 `/app/dynamicTable/<小写名字>/<文件名>/<标题>` |
| ⑤ | 宿主加载脚本 → 取 `window[<名字>]` → 渲染表格 |
```bash
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` 而不是自己拼接口路径,这样换系统只改宿主一处:
```js
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 字段装饰器
```typescript
@tcpd({ "lang": "", "def": "消息", minWidth: 120 })
@tfcpd({ "lang": "", "def": "消息", fieldType: "string", rule: [{ "type": "require", message: "不能为空" }] })
message: string = ""
```
- `@tcpd`:配置表格列属性
- minWidth:最小列宽
- def:列显示名称
- `@tfcpd`:配置表单字段属性
- fieldType:字段类型
- rule:验证规则
#### 2.2 方法装饰器
```typescript
@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 数据获取
```typescript
@tcmd({ "key": "table:searchFormMethod", "value": { "type": "getList", "es": "onAfter" } })
getList = async (params: any) => {
return await api.getNoticeList(params);
}
```
- 通过API获取通知列表
- 装饰器配置为搜索表单的后置方法
#### 3.2 新增操作
```typescript
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 编辑操作
```typescript
@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 删除操作
```typescript
@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 动态显示控制
```typescript
isShow = (rowData: any) => {
return rowData?.source_add_type == "1";
}
```
- 通过判断数据字段决定是否显示操作按钮
#### 4.2 用户上下文
```typescript
static userId: any;
```
- 通过静态属性存储当前用户ID
- 在提交操作时自动附加到请求参数
### 5. 使用建议
1. **用户ID设置**:
```typescript
// 在使用前设置当前用户ID
Notice.userId = store.getters.userId;
```
2. **自定义操作扩展**:
```typescript
@tcmd({
"value": {
"id": 1,
"type": "customOperateEvent",
"title": "详情",
isShow: (row) => row.status === 1
}
})
customAction = (rowId: number) => {
router.push(`/detail/${rowId}`);
}
```
3. **表单验证增强**:
```typescript
@tfcpd({
fieldType: "number",
rule: [
{ type: "require", message: "不能为空" },
{ validator: (v) => v > 0, message: "必须大于0" }
]
})
sort: number = 1;
```
4. **国际化支持**:
```typescript
@tcpd({ lang: "notice.message", def: "消息" })
```
该设计通过装饰器实现了高度可配置的表格组件,建议结合具体业务需求扩展装饰器配置,并确保API接口的异常处理完备。