AI 概念图｜企业 AI 开发系列教程，非产品实机截图。

✦ 01｜当企业有上千张表单，问题会发生什么变化

让 AI 写一个“姓名、电话、备注”的录入页面并不难。难的是企业里同时存在采购、库存、合同、设备、报销、质检等大量表单：相同控件被重复使用，字段不断变化，角色权限各不相同，历史数据还必须持续可用。

今天加一个下拉框，明天要远程搜索；今天上传报价文件，明天要按角色限制附件；今天只有主表，明天增加明细和审批。每次都在各页面重新实现，系统就会逐渐出现多种校验方式、多种存储格式和多套权限判断。

◆ 先校准一个数字

本文以 2026 年 9 月 26 日核对的吾码前端控件注册表为依据，介绍 44 类当前控件：16 类基础控件、28 类高级控件。大型系统中可以有成百上千个控件实例，但不能把实例数量当成内置控件类型数量。

表单级配置同时参照官方 iTdos 租户的 MCP 只读回读：diy_table 元表当前登记了 79 个字段。其中包括当前设计入口、系统字段、运行元数据与兼容字段。下面会分别说明用途，不把隐藏历史字段包装成已经启用的新功能。

◆ 阅读方式

• 想理解价值：先读第 1、2、8 节。
• 正在选控件：按第 3—7 节的业务场景查找。
• 准备让 AI 建系统：重点看数据源、附件、主子表、事件与最后的提示词和验收清单。

结构示意图｜表单定义、字段定义、运行时和业务数据相互关联，但职责不同。

✦ 02｜先认识三层配置：整张表单、单个字段、控件自身

◆ 第一层：diy_table 决定整张表单

标识与归属。 Name 是物理表名，Description 是可读的表中文名，Remark 用于补充说明；DataBaseName/DataBaseId 关联所属数据库。命名应使用稳定业务语义，避免把租户私有业务名、临时页面名和显示标题混为一谈。

布局与打开方式。 Column 控制 PC 端列布局；当前官方配置选项依次为单列、双列、三列、四列、六列，注意枚举值 5 对应“六列”，不能直接把值当列数。FormOpenType 支持 Dialog、Drawer、Page，FormOpenWidth 配置弹窗或抽屉宽度。

Tabs 定义整张表单的业务分组，字段 Tab 绑定所属组；TabsPosition 配置标签位置。FormLabelPosition 控制标签 left/right/top 对齐，DisplayDefaultField 控制默认系统字段是否展示。新建普通业务表单通常先采用合适宽度的弹窗；字段与子表很多时再评估抽屉或整页。

◆ 工作台、标题与记录切换

• FormPresentationMode：工作台 ControlCenter 或标准 Standard 呈现；FormPresentationDensity：紧凑 Compact 或舒适 Comfortable。
• FormNavigationTitle / FormNavigationCountText：分组导航标题与数量文案；FormSectionNavigation：Auto 或 Tabs 导航方式。
• FormSectionEyebrow / FormRequiredCountText：分组眉题与必填数量文案。
• FormWorkbenchEyebrow / FormWorkbenchDescription：工作台眉题与说明。
• FormNavigationFooterTitle / FormNavigationFooterHtml：导航底部提示标题和说明，HTML 仍应遵守系统内容安全规则。
• 记录切换提示 / FormRecordSelectorLabelFields：记录切换输入提示与显示字段，帮助用户辨识当前业务记录。
• FormPresentation：承载统一工作台展示配置的底层元数据。当前官方元表将它隐藏，常用配置优先通过可读字段和受支持入口维护。

◆ Banner：让用户进入表单就知道自己在看什么

FormBannerEnabled 控制顶部 Banner；旧表为空时当前规则也可显示，并根据字段类型推断内容。显式关闭才隐藏。标题、副标题和图片应服务业务识别，避免装饰信息挤占操作区域。

• FormBannerTitleField：名称、单号等主标题字段。
• FormBannerSubtitleField：客户、项目等副标题字段。
• FormBannerImageField：左侧图片字段，多图时使用首图，私有图遵循授权访问。
• FormBannerIcon：没有图片时的默认图标。
• FormBannerBackgroundField：背景图片、颜色或渐变来源字段。
• FormBannerTagFields：状态、分类等标签字段，可表达标签标题与色调；显式 [] 表示不显示标签。
• FormBannerMetrics：统计项 JSON，既可显示本表数值，也可配置接口引擎返回的统计。

接口型统计使用 ApiEngineKey、ValuePath、ParamMap、RefreshSeconds 等配置；相同接口可以合并取数。统计口径必须由服务端按授权范围计算，不能把当前页明细的合计冒充全部明细合计。自动推断、显式空配置和主动关闭应分别理解。

◆ 数据治理、访问与树形结构

• EnableDataComment：业务记录评论；EnableDataLog：数据修改日志；DataLogRole：日志查看角色。
• EnableDataVersion：数据版本能力；EnableTrash：回收站。版本与回收站不能代替数据库备份和恢复演练。
• BindRole：表访问角色；IsAnonymousRead / IsAnonymousAdd：匿名读取与匿名新增开关。开启之前必须单独评估可暴露字段、频率与业务校验。
• ReadPrimary：要求原生列表、计数、汇总、树及导出读取本表所属主库；保留显式事务，不能修复已经建立的旧事务快照。
• IsTree：树形数据；TreeParentField / TreeParentFields / TreeHasChildren / TreeLazy：父字段、完整祖先链、有子级标识与懒加载。部分配置可能随上下文显示，不能只凭默认隐藏就认定能力不存在。

◆ 事件与运行边界

InFormV8、SubmitFormV8、OutFormV8 对应前端表单生命周期；SubmitBeforeServerV8、SubmitAfterServerV8 对应服务端提交前后；ServerDataV8 用于服务端数据处理；ApiReplace 用于受支持的接口替换扩展。具体执行顺序与事务影响在第 8 节展开。

V8Limit 是当前正向开关。默认关闭单次 Jint 执行超时、语句数、递归与累计分配预算；开启后应用这些单次限制。进程内存保护、取消、并发、嵌套深度、权限沙箱和数据库保护仍有各自规则。“不设单次预算”不能理解为没有运行治理。

DisableFormMaskBlur 是负向开关，开启后关闭表单遮罩毛玻璃。旧 FormMaskBlur 仅作存量兼容；旧 V8Unlimited 也为反向兼容字段，新配置使用 V8Limit。看到两个名字相近的字段时，应先确认当前协议与优先级。

◆ 元表中的其它字段，怎样看待

Id、CreateTime、UpdateTime、UserId、UserName、IsDeleted 是系统记录信息。ReportName/ReportId 用于报表关联。

DataSourceId、CacheParentKey、EnableCache、FormArticle、TableArticle、TableTabs、TableTabsPosition、RowAction、InputBorderStyle、FieldBorder 属于关联、隐藏或历史/运行配置，需要结合具体入口与版本使用。

DataEncryptTransfer、DataEncryptSave 当前也在元表中，但不能仅凭字段名称就宣称所有传输和存储都已加密。实际保护必须核对启用路径、覆盖范围、密钥管理与目标部署。生产传输应有正确 TLS，敏感业务字段应有明确的后端保护方案。

◆ 第二层：每个字段共有的属性

• 身份与数据：Name、Label、Type、DefaultValue、Data；字段名稳定，显示名称可读，数据类型和长度依据业务选择。
• 可见与只读：Visible、AppVisible、Readonly；PC 与移动端可分别设置。隐藏或只读不代替后端权限。
• 业务校验：NotEmpty、唯一性等规则；唯一性要考虑单字段或组合字段、空值、历史重复与并发。
• 布局与顺序：Sort、Tab、FormWidth、TableWidth；列表宽度与表单栅格宽度是两件事。
• 交互说明：输入提示文案、Description；帮助用户知道该填什么，不能把重要规则只藏在提示里。
• 运行扩展：Component 指定控件，Config 承载控件配置，字段 V8 负责必要的联动与事件。

普通字段默认不强制设置 FormWidth；CodeEditor、Textarea、RichText、上传、子表、地图和复杂布局需要时设 24 占整行。业务必填应由规则表达，不能把“必填”简单等同于为所有物理列创建 NOT NULL。

◆ 第三层：控件独立参数

同样叫“图片上传”，可能要求单图、多图、裁剪、压缩、私有访问与上传回调；同样叫“选择框”，可能来自静态字典、SQL、数据源或接口。下面按控件逐一展开。字段根属性与 Config 内属性要分清，配置键名以当前协议为准。

✦ 03｜16 类基础控件：从输入到动作

◆ 01 Text｜单行文本

适合名称、编码、联系电话等短文本。可以配置 TextShowPassword、TextIcon、ShowIcon、TextIconPosition、TextApend、TextApendPosition，决定密码显示按钮、图标和前后缀文字。TextApend 是当前键名，不能由 AI 擅自改成另一个英文拼写。

ShowButton、ReadOnlyButton 与 SlotButtonV8Code 支持输入框旁的辅助动作；V8CodeBlur 与 KeyupV8Code 支持失焦和键盘联动。TextAutocomplete 属于相关文本补全配置。密码显示模式只改变呈现，不会自动把数据库里的明文变成安全密码哈希。

◆ 02 Guid｜标识字段

用于记录标识和关联标识，默认按只读用途设计。它也复用文本输入的相应配置入口，但 Id 的生成、不可变性与关系含义由平台和数据规则决定。不要为了好看改写业务记录主键；外键显示通常应通过关联名称改善可读性。

◆ 03 Textarea｜多行文本

适合备注、原因、简短说明。Config.Textarea.DefaultRows 设置默认行数；配合字段宽度、占位文字和必填规则。它保存文本，不承担富文本排版，也不应被当作复杂业务对象的无结构堆放区。

◆ 04 NumberText｜数字输入

适合数量、价格、比例等。NumberTextStep 设置步长，NumberTextPrecision 设置小数位，NumberTextBtn 与 NumberTextBtnPosition 控制增减按钮和位置；历史或运行逻辑中的 NumberTextMath 应结合当前支持方式使用。

金额还需要数据库精度、舍入规则和服务端重算。前端显示两位小数，不能证明后端计算过程没有误差；库存、额度等约束也不能只靠输入框限制。

◆ 05 DateTime｜日期与时间

DateTimeType 选择日期/时间相关显示类型，具体可选项由当前设计器提供。用于生日、交货日、执行时间时，应区分“日期”与“时间点”，并明确时区、空值与范围查询规则。显示格式不能替代统一的存储和接口约定。

◆ 06 Select｜单选下拉

用于状态、客户、供应商等单值选择。数据源支持 Data、KeyValue、Sql、DataSource、ApiEngine；SelectLabel 指定显示字段，SelectSaveField 指定保存字段，SelectSaveFormat 区分 Text/Json 等受支持形式。

EnableSearch 控制搜索交互，DataSourceSqlRemote 控制远程搜索模式。

◆ 07 MultipleSelect｜多选下拉

用于责任人、适用地区、业务标签等多值选择，复用相同数据源与显示/保存映射。必须定义多值最终存储格式以及服务端过滤方式；不要让某个页面存名称数组，另一个页面存逗号拼接 Id，还期待它们自然兼容。

◆ 08 Radio｜单选组

少量互斥选项适合全部展开，例如普通/加急、内部/外部。沿用数据源和 Key/Value 映射；选项值保持稳定。业务含义改变时应评估旧数据映射，不能仅替换文字就认为完成迁移。

◆ 09 Checkbox｜复选组

适合少量可同时选择的项目，如通知方式、附加服务。配置选项和存储格式后，还要验证空选择、全选、禁用选项与历史值回显。选项很多时应评估多选下拉、穿梭框或树选择。

◆ 10 Switch｜开关

适合明确的启用/停用状态。Config.Switch 提供 DisplayMode、VisualStyle、ActiveText、InactiveText、Title、Description、Icon，支持不同显示样式和卡片说明。视觉开关值要与后端实际状态约定一致，不能把字符串“0”误当成真值。

◆ 11 Rate｜评分

Config.Rate.Max 设置最大分值，AllowHalf 允许半星，Clearable 控制清空，ShowScore 和 ScoreTemplate 控制分数展示。适合服务评价与质量评分；评分维度、可修改时间和异常值范围仍需要业务规则。

◆ 12 Progress｜进度

Config.Progress.Type 支持线形、圆形和仪表盘；StrokeWidth、ShowText、TextInside、Status、Color 控制线宽、文字、状态和颜色。进度值应来自可解释的业务计算；一次上传或一个后台任务的不同阶段，不宜用随时间增长的假进度代替真实状态。

◆ 13 Slider｜滑块

Config.Slider.Min、Max、Step 定义范围与步长；Range 选择区间，ShowInput 显示输入框，ShowStops 显示间断点。适合阈值、百分比、范围条件；开启区间后，保存值形态会与单值不同，需同步后端处理。

◆ 14 ColorPicker｜颜色选择

Config.ColorPicker.ShowAlpha 控制透明度，Format 支持 hex/rgb/hsl/hsv，Size 调整尺寸，Predefine 设置预设颜色。适合标签、图例与主题辅助配置，仍应检查深浅色模式下文字对比度。

◆ 15 AutoNumber｜自动编号

适合订单号、工单号、资产编号。AutoNumberFixed、AutoNumberLength、AutoNumberFields 配置固定部分、长度与关联字段；AutoNumber.DataRule、CreateRule 表达数据和生成规则。编号应由可靠服务端机制管理，关注并发、重试、唯一性以及是否允许断号。

◆ 16 Button｜按钮

Config.Button.Type、Icon 等控制样式；PreviewCanClick 决定查看模式下是否可点，RefreshTableAfterClick 控制完成后刷新，Loading 用于运行时反馈。按钮事件可以调用接口或打开页面，但重要业务动作必须在服务端重新校验权限、状态和幂等。

AI 概念图｜少量稳定控件可以组合出大量业务表单；图中模块不是实际控件截图。

✦ 04｜9 类内容与布局控件：让复杂表单仍然读得懂

◆ 17 Divider｜分割线

DividerPosition 控制标题位置，Config.Divider.Icon 与 Tag 配置图标和相关呈现。适合给连续字段添加可读边界；它提供视觉分隔，不会自动形成业务数据分组或访问权限。

◆ 18 CollapseGroup｜折叠分组

Config.CollapseGroup.DefaultCollapsed 决定初始折叠；ScopeMode、FieldCount 等定义影响字段范围，可使用直到下一个分组的受支持模式。Description、Icon、Theme、ShowFieldCount 控制说明、图标、主题与数量显示。

适合“常用信息展开、偶尔使用的信息折叠”。先测试折叠区域里必填错误的定位和展开行为，避免用户只看到“校验失败”却找不到字段。布局控件通常需要占整行。

◆ 19 Tabs｜字段级页签

字段级 Tabs 与 diy_table.Tabs 不是同一层。Config.FieldTabs 可配置 ScopeMode、TotalFieldCount、DefaultActiveKey、Type、Position、Stretch、ShowFieldCount、CaptureRest、Description 和 Tabs 列表。

当前页签项使用 Key、Title、Icon，以及按数量模式的 FieldCount 或手动模式的 FieldKeys。它适合局部复杂区域；总字段作用范围、末页是否接收剩余字段和默认页签，应明确配置并检查，不能依赖字段顺序变化后仍“刚好正确”。

◆ 20 Alert｜提示信息

Config.Alert.Title、Content、Type、Effect、ShowIcon 配置标题、内容、提示类型、视觉效果与图标。适合填写说明、业务提醒和状态提示。提示不应代替真正校验；HTML 内容仍需遵守系统安全限制。

◆ 21 StaticText｜静态文本

Config.StaticText.Title、Content、Align、Theme 用于说明性文字、引用与辅助信息。适合放置业务流程说明、计算口径和注意事项。不要把频繁变更的关键业务规则只写在静态文本里。

◆ 22 Html｜HTML 展示

Config.Html.UseFieldValue 决定使用字段值还是配置内容，Content、MinHeight、Padding 控制内容和布局。适合受控格式展示；它不是任意脚本执行容器。来自用户或外部系统的 HTML 需要安全过滤与可信边界。

◆ 23 RichText｜富文本

适合文章、知识库、产品说明和图文内容。当前编辑器产品配置可使用 WangEditor；Config.RichText.Limit 决定文件公开/私有语义。富文本中的图片、视频和附件，不能因为“嵌进正文”就脱离文件权限体系。

• Image.Enabled / MaxSize / MaxCount：是否允许图片、单文件大小与数量；MaxSize 单位为 MB。
• Image.Preview / CompressMaxSize / CompressMaxWidth：压缩开关、压缩目标体积与最大宽度；CompressMaxSize 单位为 KB，应与 MaxSize 区分。
• Video.Enabled / MaxSize / MaxCount：视频上传能力与限制。
• File.Enabled / MaxSize / MaxCount / Accept：附件开关、大小、数量及允许的类型范围。

私有文件应保存稳定资源标识，在访问时获得授权地址，不能把短期签名 URL 永久写进正文。公开知识文章可按业务明确设置公开存储；合同、内控资料等应按实际保密要求处理。

◆ 24 CodeEditor｜代码编辑器

Config.CodeEditor.Height、DisplayMode、ButtonText 控制编辑区高度、内嵌/弹窗模式和按钮文案；当前专项配置还提供 Language、V8CodeType；运行配置还支持 LanguageField 与 LanguageMap 按其它字段切换语言。

按钮文案可使用 charCount、lineCount 这样的受支持占位信息。

适合接口脚本、表达式和配置代码。能编辑代码不等于有权执行任何操作；保存权限、运行沙箱、接口权限和审核规则仍分别生效。普通业务表单不应向无关角色暴露可执行代码入口。

◆ 25 JsonTable｜JSON 表格

适合规模可控、随主记录一起保存的结构化数组，例如配置项、规则列表和模板定义。Config.JsonTable.Columns 定义列；

列可带 Id、Sort、Label、Key、Component、Width、MinWidth、Required、Visible、DefaultValue、输入提示文案、Readonly、Config、Data、KeyValueList。

列控件有自己的配置与数据映射；批量导入数据源可使用 DataSource、Sql、DataSourceId、ApiEngineKey/DataSourceApiEngineKey、SelectLabel、DataSourceSqlRemote 等当前支持项。应核对源数据到列 Key 的映射以及默认值。

JsonTable 把数组作为主记录中的一个值管理；需要独立查询、索引、权限、汇总和大量明细的业务，通常更适合 TableChild 关系子表。两个控件外观都像表格，但数据生命周期不同。

✦ 05｜2 类上传控件：文件安全从表单开始

◆ 26 ImgUpload｜图片上传

Config.ImgUpload.Limit 控制是否禁止匿名访问；Multiple 决定单图/多图，MaxCount 限制数量，Tips 显示说明，Preview 决定是否压缩，MaxSize 限制 MB 体积，SaveFullPath 决定保存路径形式。运行展示还涉及 ShowFileList 等受支持属性。

裁剪是一组独立配置。 Crop.Enabled 控制默认开启状态；Mode 支持自由、固定或可选比例的受支持模式；Ratio、CustomWidth、CustomHeight 定义比例；AllowZoom、AllowRotate、AllowFlip 决定缩放、旋转和镜像工具。

“默认开启裁剪”与“强制用户必须裁剪”含义不同，具体交互要看当前模式。头像、证件、商品图有不同的比例和质量要求，不宜为所有图片套用同一条压缩规则。

上传前逻辑使用 Config.Upload.BeforeUploadV8；上传成功后使用Config.Upload.UploadSuccessV8并可触发标准字段事件。实际可上传类型、体积和权限最终由服务端控制，前端限制只能帮助用户尽早发现问题。

图片处理还要区分原始文件与展示文件。当前设计中原始图按私有资源保护，表单保存展示用途的图片引用。业务需要原图时应走授权能力，不能从可见缩略图地址推断原图也是公开文件。

◆ 27 FileUpload｜文件上传

Config.FileUpload 同样包括 Limit、Multiple、MaxCount、Tips、MaxSize、SaveFullPath 等。适合合同、报价、证明和技术附件。单文件/多文件会影响保存形态，接口、导出和旧数据回显要一起校验。

Office 能力有三个独立开关： EnableOfficePreview 控制在线预览，AllowOfficeEdit 控制在线编辑，EnableOfficeVersion 控制编辑版本号。它们还依赖目标环境中实际配置的 Office 服务、网络与授权，并非只打开一个开关就自动具备所有文档编辑条件。

◆ 附件角色权限：比“文件设为私有”更细

• EnableRolePermission：启用附件角色权限，启用时强制使用私有文件访问语义。
• ConfigurableRoleIds：允许配置的角色范围；留空按当前规则可选择全部角色，填写时应使用真实角色 Id。
• HideUnauthorizedFiles：是否隐藏无权访问的附件行；隐藏后保存仍应保留原附件。
• ShowUnauthorizedFileName：是否允许仅展示无权附件的名称；展示名称不授予预览、下载或修改权限。
• DisableRoleInheritance：关闭角色级别继承；默认规则下更高 Level 可继承较低 Level 的访问权，同级不同角色不自动互相继承。
• VisibleRoleIds：单个附件的可见角色信息，结合所属业务记录权限一起判断。

◆ 上传链路还有哪些容易遗漏的事

上传请求需要绑定当前表、字段、模块与记录上下文，不能仅靠一个“这是私有文件”的前端布尔值。上传证明属于短期过程数据，不应当作永久业务字段保存。文件名、扩展名、类型、大小和后端允许范围都需要校验。

下载前后的服务端事件可用于进一步业务校验和审计，应按当前私有文件事件协议使用。不要在日志中写入原文密钥或长期可用的私有地址，也不要把一次下载成功当作所有角色权限都已验证。

权限示意图｜用户身份、业务记录和附件规则共同决定文件能否访问。

✦ 06｜8 类选择与组织控件：把数据关系表达清楚

◆ 28 Autocomplete｜自动补全

适合可输入并从建议项选择的场景。复用数据源配置，明确显示字段、保存字段和搜索方式。用户输入自由文本后是否必须命中一个有效业务对象，应由业务规则决定，不能把“有建议列表”误认为“已经绑定外键”。

◆ 29 TagInput｜标签输入

Config.TagInput 配置输入提示文案、建议标签（Options）和最大数量（MaxCount）。适合业务备注型标签；需要严格字典管理时，应选固定选项并验证合法值，避免“华东”“华东区”“华东区域”在统计中成为三种含义相同的数据。

◆ 30 Transfer｜穿梭框

Config.Transfer.LeftTitle、RightTitle、Filterable、Options 决定左右标题、搜索和选项。适合从一个规模可控的集合中挑选对象。选项要有稳定标识，已停用或已删除的历史选择也应有明确的回显与保存策略。

◆ 31 Cascader｜级联选择

适合分类、地区和层级目录。公共 SelectSaveField、SelectLabel 映射值和名称；Config.Cascader.Children、ParentField、ParentFields、Disabled、Leaf 定义树形数据字段；

Lazy、Filterable、Multiple、EmitPath 控制懒加载、搜索、多选及保存完整路径或末级值。

父子关系可以由嵌套数据或规范父字段表达。完整祖先链的格式要遵守当前协议；选父级、选叶子和多选组合的含义要事先决定，不能等到报表阶段才补数据解释。

◆ 32 Address｜地址选择

Config.Address.ShowAllLevels 控制完整路径展示，CheckStrictly 控制父子节点是否可独立选择，Separator 控制路径分隔符。适合行政区划选择；详细街道门牌通常应有独立文本字段，行政区划变更也要考虑历史地址可读性。

◆ 33 Department｜部门选择

Config.Department.Multiple、Filterable、EmitPath 决定多选、搜索与路径保存。部门选择应基于当前租户组织结构；选择某部门不自动授予该部门的数据权限，部门撤并和人员调动也要有业务处理规则。

◆ 34 SelectTree｜树形下拉

适合在紧凑输入空间里选择层级节点。除 SelectSaveField、SelectLabel 外，Config.SelectTree 提供 Children、ParentField、ParentFields、Disabled、Leaf、Lazy、Filterable、Multiple；

PageSize 控制支持的节点分页，ParentChildLinkage 决定父子联动。

大量节点要关注初始加载、远程搜索和已选节点回显。只加载当前一页节点时，也必须能正确显示已保存的历史选项，不能因候选列表未加载就把有效值清空。

◆ 35 TreeCheckbox｜树形权限勾选

适合具有层级的勾选矩阵。Config.TreeCheckbox.DataSourceType、DataSourceApi 配置来源；ShowSearch、ShowIcon、DefaultExpandAll 控制体验；NameColumnWidth、NameColumnLabel、PermissionColumnLabel 控制列宽与标题。

它能帮助表达权限选择，但授权最终应由可信服务端保存和执行。不能把客户端构造的勾选对象直接当成当前用户可以分配任何权限的证明。

◆ 数据源配置，应该统一理解一次

• Data：少量普通静态选项。
• KeyValue：稳定 Key 与可读 Value 分离，适合状态等字典。
• Sql：受支持 SQL 数据源，动态条件应参数化，避免拼接输入。
• DataSource：引用已配置的数据源，便于集中维护和复用。
• ApiEngine：引用接口引擎返回候选项，适合业务过滤、外部集成和动态计算。

Sql、DataSourceId、DataSourceApiEngineKey 分别关联对应来源；ParamData 传递必要参数。远程搜索必须在服务端落实权限、搜索条件与规模限制。前端过滤供应商列表不能防止用户直接请求一个无权访问的供应商 Id。

供应商选择的约定
显示：供应商名称；保存：供应商 Id。
来源：按当前用户授权范围查询的接口或数据源。
联动：选择后回填联系人与结算方式。
提交：服务端重新确认供应商有效且当前用户有权使用。

✦ 07｜9 类关系与扩展控件：让表单连接真实业务

◆ 36 OpenTable｜弹出表格选择

适合在商品、客户等复杂列表中搜索、筛选和选择记录。Config.OpenTable.BtnName、MultipleSelect、BeforeOpenV8、SubmitV8 定义按钮、多选及打开/确认逻辑；ShowDialog、SearchAppend 等用于相应运行控制。

打开前可以按当前单据设置筛选，确认后回填选中的 Id 与必要业务字段。筛选应当由明确参数表达，且服务器再次验证授权范围；表格展示条件不等于接口权限。

◆ 37 JoinTable｜关联表格

用于关联显示另一个业务模块的表格。Config.JoinTable.TableId、ModuleName、ModuleId、Where 关联目标表、模块和条件。适合从客户记录查看订单列表等场景；关联条件必须准确，避免打开一条记录却显示全表数据。

◆ 38 JoinForm｜关联表单

在当前表单中嵌入一条相关记录的完整表单。Config.JoinForm.TableId/TableName 指定目标表；JoinFieldName 指定当前记录中保存关联 Id 的字段；Id、FormMode、_SearchEqual 等用于受支持的定位、模式与条件。

JoinForm 对应“一条相关记录”，不能代替一对多子表。应避免关联自身形成循环；还要验证无关联值、关联记录删除、只读模式及目标记录权限。

◆ 39 TableChild｜关系子表

典型场景是订单与商品明细、项目与工作项。根配置 TableChildTableId、TableChildSysMenuId、TableChildSysMenuName、TableChildFkFieldName 指定子表、子模块与外键；TableChildRowClickV8 处理相应行事件。

Config.TableChild.PrimaryTableFieldName 默认关联主表 Id；ImportAutoFillFk 控制导入时补齐外键；FieldRelations 表达主子字段联动；DisablePagination、NoneDefaultHeight 控制分页和展示；

Data、SearchAppend 等服务运行数据与过滤。

LastTableId/LastTableMenuId/LastTableName 等关联上下文信息要按当前接口传递。真正重要的是：子表拥有有效外键与索引，模块绑定正确；主键尚未建立时不会误查全表；取消新增不会遗留孤立明细；删除与修改遵循业务状态。

◆ 40 Map｜地图

适合客户位置、设备位置和服务地址。Config.MapCompany 按系统或受支持地图供应商选择，如 System、AMap、Baidu、Tencent；应结合当前租户实际地图配置。地图密钥和域名授权属于可信配置，不应直接写进用户可编辑业务字段。

位置数据涉及地址、中心点、缩放与经纬度关联字段。定位权限、坐标系、逆地理编码和不同终端表现需要验证，不能只检查地图底图是否显示。

◆ 41 MapArea｜地图区域

适合围栏、服务范围、园区和地块。与地图配置协同，保存区域路径等结构数据。验证多点闭合、区域修改、清空、回显和坐标系统；若用于安全或业务准入判断，服务端应独立计算边界。

◆ 42 Qrcode｜二维码

Config.Qrcode.DisplayWidth、ShowDownload、DownloadText 设置预览宽度与下载入口。运行时可以通过 DataAppend 提供 Code、title、titleValue、fields、Color、CardColor、FileName、createTime 等支持的二维码卡片内容。

适合资产标签、工单入口和业务凭证。二维码内容通常应为可撤销、受权限约束的业务入口；不要把长期 Token、数据库凭据或敏感原文直接编码进公开可扫描图片。

◆ 43 FontAwesome｜图标选择

用于菜单、业务分类和展示配置。Config.FontAwesome.AllowClear、PreviewSize、DefaultIcon 控制清空、预览尺寸与空值图标。保存的是系统支持的图标标识，不能把任意外部脚本或 HTML 当作图标数据。

◆ 44 DevComponent｜定制组件

当标准控件无法表达专业交互时，通过 DevComponentName、DevComponentPath 连接受支持的自定义组件。可按平台约定接入共享前端组件或微服务组件，并处理兼容路径映射。

定制组件应遵守 modelValue 与更新事件、编辑/查看模式、校验、移动端、深浅色和卸载清理约定。复杂排产、图形编辑、三维选择可以走这个扩展入口；每个业务页面无边界复制一套组件，会重新带回维护分叉。

AI 概念图｜主记录、明细、相关业务和扩展组件各自保留清晰职责。

✦ 08｜让 AI 建表单：交付的是业务闭环

◆ 一张表单的事件顺序

打开时，前端 InFormV8 可以调整显隐、默认值和交互；提交前，SubmitFormV8 给用户及时反馈；服务器接收后，SubmitBeforeServerV8 执行可信业务检查；写入后，SubmitAfterServerV8 仍在事务范围内处理相关业务；最后由前端相应事件处理刷新和后续交互。

ServerDataV8 处理读取数据时的服务端加工，应结合当前数据过滤协议使用。OutFormV8 的具体触发与提交/关闭动作有关，不能据名称推断每一种关闭行为都完全一样。客户端事件不是对外部 HTTP 请求的安全保证。

// 示例：服务端表单提交前校验，业务表已存在 Amount 字段
if (V8.FormSubmitAction !== 'Del') {
  var amount = Number(V8.Form.Amount);
  if (!isFinite(amount) || amount <= 0) {
    return { Code: 0, Msg: '金额必须大于0' };
  }
}
return { Code: 1 };

这段示例只演示校验位置。真实订单金额应从有效明细和可信价格规则重算，再做额度与状态校验；不能直接信任前端传来的合计。共享事务内调用其它表操作时，应传递 V8.DbTrans，按引擎协议返回结果，不自行抢先提交。

◆ 给 WorkBuddy / Codex / DeepSeek Harness 的任务说明

请按当前项目规范设计采购申请表单，先只读盘点。
读取当前租户 Schema、Manifest 协议和相关 Skills。
复用客户/商品模型，明确主表、明细、外键和字段映射。
列出控件选择、独立配置、角色范围和服务端校验。
先 plan 和 dry-run；按授权写入后回读，再做业务验收。

AI 应输出一份能审查的方案：普通字段不滥设整行宽度，重控件合理占行；菜单包含列表列、搜索列、隐藏列、排序与移动端核心字段；新增字段、关系和事件通过合适的声明式资源或应用升级机制管理。

◆ 用六组验收覆盖常见失败

• 输入与数据：必填、空值、超长文本、金额精度、日期、选项历史值；保存后重新读取，确认实际存储格式。
• 角色与权限：不同角色打开、直接调用接口、跨记录访问、导出和附件下载；验证服务器最终结果。
• 关系与事务：新增主表与明细、修改、取消、删除、失败回滚、重复提交，检查孤立数据与重复业务动作。
• 文件与富文本：大小、类型、单多文件、压缩裁剪、私有回显、签名过期、Office 依赖与无权限场景。
• 界面与终端：分组、错误定位、弹窗滚动、键盘、移动端、查看模式、长字段和窄屏。
• 规模与维护：大数据候选项、树懒加载、子表分页、慢接口、字段变更、应用升级与回滚。

◆ 表单引擎的长期收益在哪里

当同一种上传规则、选项映射或只读呈现在多个模块里被复用，改进可以集中落到共同实现；业务差异继续由字段配置、事件和扩展组件表达。团队仍需测试受影响场景，但不必永远维护大量彼此略有差异的复制代码。

选择框架时，可以用一张真实订单表单验证这些能力，再追加一次字段变更、一次权限调整和一次明细扩展。比较首次实现与后续维护的投入，比单独比较“AI 几分钟画出了表单”更有意义。

◆ 资料入口与版本说明

• 吾码表单引擎文档：https://microi.net/doc/form-engine/form-engine-info
• 吾码前后端 V8 文档：https://microi.net/doc/v8-engine/v8-client 与 https://microi.net/doc/v8-engine/v8-server

本文控件清单、专项配置与表单元数据基于 2026 年 9 月 26 日当前源码和官方租户只读资料核对。配置项是否在界面出现，会受版本、控件类型、权限和上下文影响；上线项目应按目标环境再次验证。

本文由AI辅助创作，配图包含AI生成的概念图；架构与配置示意图为确定性绘制。概念图不代表产品实机界面，技术内容依据当前官方资料与实现核对。