Title: 📋 表单、字段属性、事件
Canonical: https://microi.net/doc/form-engine/form-field-info.html
Page-Modified: 2026-11-05T09:09:34.000Z
Source: published HTML document body; page revision is not a capability verification date.

# 📋 表单、字段属性、事件

表单属性与字段属性的各类 V8 事件详解

---

## 📸 表单与字段配置预览

[Microi吾码表单设计器的图片上传字段设置弹窗，展示上传、多图、压缩、裁剪与 V8 扩展配置: https://file.microi.net/itdos/official-docs/images/0e554ede46e8b9b6f13e1834eec28a7718ed5d1cd32180f1a1f13fb445a10791/202610/form-field-image-upload-settings.jpg]

控件专项配置：图片上传、多图、压缩、原图保留、裁剪与 V8 扩展集中维护。

[Microi吾码表单设计器的单行文本字段设置弹窗，展示图标、复合文字、插槽按钮和 V8 事件: https://file.microi.net/itdos/official-docs/images/824bb1072ad7c320c3cf878853c62e8eddc7a02281d7862467e69111554df4a9/202610/form-field-text-settings.jpg]

字段交互配置：显示、复合文字、插槽按钮、失焦与键盘 V8 事件在暗色主题下完整呈现。

## 字段说明的呈现规则

在【表单属性 → 字段说明模式】选择当前表的显示方式，保存到 diy_table.FieldDescriptionMode，作用于新增、编辑和详情中的普通字段：

模式	|	显示规则	|

inline（默认）	|	Label 在左/右时，说明在整行下方显示紧凑灰字；Label 在顶部时，说明在标题旁单行省略，悬停可看全文	|

tooltip	|	Label 旁显示感叹号图标，鼠标悬停或键盘聚焦显示完整说明；窄屏可点击查看	|

未设置、空值和 null 保持 inline，不改变旧表外观。CollapseGroup、Tab 等布局组件自己的 说明保持原规则。字段说明不能代替必填、格式、权限与服务器端校验。

AI 配置时使用 microi_create_table/microi_update_table 的 fieldDescriptionMode， 或 Manifest 的 tables[].fieldDescriptionMode。配置需配套前后端与表单引擎应用，写后回读再检查实际表单。

## 数据表格单元格对齐

【字段属性 → 表格对齐】保存为顶层 diy_field.TableAlign，支持 auto/left/center/right。 空值、null 和 auto 按控件语义选择默认，显式设置可覆盖：

内容	|	自动对齐	|

文本、日期、选项、部门、自动编号	|	左对齐	|

数字输入	|	右对齐	|

布尔和视觉控件	|	居中	|

未知扩展控件	|	参考真实物理类型，数值右对齐、布尔居中，其余左对齐	|

模块复合列的 ViewSchema.Layout.List.Columns[].Align 保留独立优先级，不被字段默认覆盖。 AI 使用标准字段工具的 tableAlign，或 Manifest 的 tables[].fields[].tableAlign； 不要写进控件 Config。更新时省略此属性会保留原值，显式空值恢复自动。

---

## 📄 表单属性

### 前端进入表单 V8 事件

可以做一些默认值处理：

js

```
//如果是新增数据
if(V8.FormMode == 'Add'){//FormMode可能的值：Add（新增）、Edit（编辑）、View（预览）
    V8.FormSet('Name', V8.CurrentUser.Name);//设置默认值
}
```

---

### 前端提交表单前 V8 事件

可以做一些表单验证，提升用户体验：

- 注意：如果直接通过如Postman调用接口的方式来进行增删改，此前端V8事件事件并“不会执行”（后端V8事件会执行）

js

```
//若代码出现return Code为0时，则会在前端阻止表单继续提交
return { Code : 0, Msg : '错误信息，已阻止表单提交！' };

//表单提交类型，可能的值：Insert、Update、Delete
var submitType = V8.FormSubmitAction;
```

### 前端离开表单后V8事件

- 一般建议使用【服务器端表单提交后V8事件】

- 此事件可以做一些特殊业务逻辑处理

### V8 代码版本

表单设计器保存表单/字段 V8、VS Code 推送以及 MCP 修改表单事件、字段事件、接口引擎或工作流节点代码时，服务端会比较保存前后的代码。只有代码内容真实变化才会向 mic_data_version 新增版本；仅调整布局、字段标题等非代码配置不会产生空版本。

代码编辑器的【版本】只负责查看、对比和恢复。预览与对比使用 Monaco 只读编辑器；对比左侧为历史版本、右侧为当前代码，行级和字符级差异使用背景色标识，不再需要手动“保存当前版本”。

### 详情右侧评论与版本

接口引擎详情的评论通过可信入口提交。服务端校验父菜单、父表与父记录，固定作者和回复归属； 评论表使用 ParentTableId + TableRowId 绑定记录。旧评论缺少父表归属时不自动回填或猜测。 表单引擎应用 v7.7.5 补齐归属字段、评论复合索引及主库回读，需要配合支持该能力的前后端。

版本列表只读取版本号、动作和时间。代码管理表的有效平台管理员点击【预览】【查看差异】或 【加载】时，才按父表、记录及版本 Id 读取一条代码快照；【加载】后仍需正常保存才会生效。 代码快照仅覆盖其中包含的代码字段，不会清空名称、路由或其它未包含的配置。

打开、刷新或预览面板均不写入历史版本，也没有新增定时轮询或启动回填。 定时任务的运行时间更新继续使用原有条件更新，不触发日志、版本或表单事件；真实代码变化才生成版本。

### 服务器端数据处理V8事件

- 该事件会在获取列表数据后每一行执行、获取表单数据后执行。

- 已封装对象：

- a）V8.RowIndex：列表数据的行索引，0开始

- b）V8.Form：列表数据每行对象、表单数据对象

- c）V8.NotSaveField：指定哪些字段在编辑时不保存

- d）V8.CacheData：用于缓存数据

- 可以实现某些字段脱敏，如：V8.Form.价格 = "";此时一定要设置：V8.NotSaveField = ["价格"];否则在修改数据时会将写到数据库。

- 示例：

javascript

```
// 这里只决定返回值是否脱敏；真正的数据访问权限必须由后端授权策略强制。
// 平台超级管理员阈值为 Level >= 9999。
if(Number(V8.CurrentUser.Level || 0) < 9999){
    V8.Form.Price = "***";//脱敏
    V8.Form.CompanyName = "***";//脱敏
    V8.NotSaveField = ["Price", "CompanyName"];//告诉前端，此字段在编辑时不保存
}
```

### 服务器端表单提交前V8事件

- 此事件在事务中执行

- 注意：如果直接通过Postman调用接口的方式来进行增删改，此V8事件代码“仍会执行”

- 注意：如果是在后端V8事件、接口引擎中调用V8.FormEngine进行增删改，此事件“不会执行”（开发者一般只想做基本的增删改，防止出现意料之外的动作），但可以通过传入_InvokeType:'Client'实现也执行此事件

展开查看 JavaScript 代码（28 行）

js

```
//表单提交类型，可能的值：Insert、Update、Delete
var submitType = V8.FormSubmitAction;

//若代码出现return，并且未指定Code的值、或Code值不等于1时，则会在后端阻止表单继续提交，并且自动回滚事务，无需手动执行V8.DbTrans.Rollback()
return { Code : 0, Msg : '错误信息，已阻止表单提交！' };

//若代码出现return，并且未指定Code的值，则会在后端阻止表单继续提交，并且自动回滚事务，无需手动执行V8.DbTrans.Rollback()
return { A : 111, B : 222 };
//此时增删改接口会返回数据格式：
{ Code : 0, Data : { A : 111, B : 222 }, Msg : "执行[表单提交前V8事件]失败，V8事件返回结果：{ A : 111, B : 222 }" }

//在事务中操作其它表
var result = V8.FormEngine.UptFormData('other_table', {
    _Where:[]
}, V8.DbTrans);
if(result.Code != 1){
    //此时可无需执行V8.DbTrans.Rollback()回滚事务，平台会自动回滚事务
    return { Code : 0, Msg : 'other_table修改失败，已阻止表单提交！已回滚事务！' };
}

//执行其它接口引擎时，可选传入V8.DbTrans对象。此时一般此接口内部也无需手动提交或回滚事务。
result = V8.ApiEngine.Run('apiengine_key', {
    Form : V8.Form//传入当前表单数据
}, V8.DbTrans);
//防止某些接口引擎未返回数据，而是返回的null导致result.Code报错，所以这里的判断是【result && result.Code != 1】
if(result && result.Code != 1){
    return result;//平台会自动回滚事务，无需手动执行V8.DbTrans.Rollback();
}
```

### 服务器端表单提交后V8事件

- 此事件仍在事务中执行，如果要获取当前表单提交后的数据，需要使用V8.DbTrans对象来获取

- 注意：如果直接通过Postman调用接口的方式来进行增删改，此V8事件代码“仍会执行”

- 注意：如果是在后端V8事件、接口引擎中调用V8.FormEngine进行增删改，此事件“不会执行”（开发者一般只想做基本的增删改，防止出现意料之外的动作），但可以通过传入_InvokeType:'Client'实现也执行此事件

展开查看 JavaScript 代码（33 行）

js

```
//若代码出现return，并且未指定Code的值、或Code值不等于1时，则会在后端阻止表单继续提交，并且自动回滚事务，无需手动执行V8.DbTrans.Rollback()
return { Code : 0, Msg : '错误信息，已阻止表单提交！' };

//若代码出现return，并且未指定Code的值，则会在后端阻止表单继续提交，并且自动回滚事务，无需手动执行V8.DbTrans.Rollback()
return { A : 111, B : 222 };
//此时增删改接口会返回数据格式：
{ Code : 0, Data : { A : 111, B : 222 }, Msg : "执行[表单提交后V8事件]失败，V8事件返回结果：{ A : 111, B : 222 }" }

//在事务中操作其它表
var result = V8.FormEngine.UptFormData('other_table', {
    _Where:[]
}, V8.DbTrans);
if(result.Code != 1){
    //此时可无需执行V8.DbTrans.Rollback()回滚事务，平台会自动回滚事务
    return { Code : 0, Msg : 'other_table修改失败，已阻止表单提交！已回滚事务！' };
}

//在事务中获取当前数据。也可以使用V8.Form访问前端传入的当前数据，但可能数据字段并不完整
result = V8.FormEngine.GetFormData('this_table', {
    Id : V8.Form.Id
}, V8.DbTrans);//若不传入V8.DbTrans对象，则在修改、删除事件中获取的是老数据。而在新增事件中获取不到数据，因为事务还未提交。

//表单提交类型，可能的值：Insert、Update、Delete
var submitType = V8.FormSubmitAction;

//执行其它接口引擎时，可选传入V8.DbTrans对象。此时一般此接口内部也无需手动提交或回滚事务。
result = V8.ApiEngine.Run('apiengine_key', {
    Form : V8.Form
}, V8.DbTrans);
//防止某些接口引擎未返回数据，而是返回的null导致result.Code报错，所以这里的判断是【result && result.Code != 1】
if(result && result.Code != 1){
    return result;//平台会自动回滚事务，无需手动执行V8.DbTrans.Rollback();
}
```

## 字段属性

### 绑定角色

- 当字段绑定了角色时，只有该角色在查看表单时才能看到此字段