.form 文件 Schema¶

位置：/{应用}.application/module/{模块}.module/{表单名}.form（目录）　|　XML 根：Form　|　与技能对齐：generate-form-file 机制背景（动态表同步 .create_form_table、索引）见 [[design/table-schema/overview]] §6.2/§7。

1. 用途与落盘¶

表单 = 动态表单定义 + JsonTemplate 布局模板。**目录**形态，内含同名元数据文件与 .activity 操作文件：

/{应用}.application/module/{模块}.module/{表单名}.form/{表单名}.form
/{应用}.application/module/{模块}.module/{表单名}.form/{操作名}.activity

id 规则：文件根 id（<Form id>、<activity id>）= __ + 短 UUID；templatecontext 内字段 id / 布局节点 id = 短 UUID（无 __）。字段 name 用英文 → 动态表列 ITEM_ + 大写 name。

2. Form 属性表¶

属性	类型	默认	说明
`id`	string（子元素）	须生成	`__` + 短 UUID
`name`	string	—	必填；动态表 `TLK_{name}`
`type`	int	1	见 type 表；保存后勿改
`templatecontext`	CDATA	—	JsonTemplate 字符串（见 §4）
`showType`	string	new	新建默认拖拽（`new`）。印刷/经典才用 `old`。Java 未赋值时可能是 `old`，落盘勿沿用
`styleId` / `permissionType` / `orderno`	string/int	public/1	样式库/权限/排序
`isopenablescript` / `iseditablescript`	CDATA		可打开/可编辑脚本
`confirmLeaveEdit` / `showWaterMark` / `openComment` / `showLog`	bool	false	开关
`showLogType`	string	default	default/table
`recordMode` / `recordModeScript`	string/CDATA	every	日志记录模式 every/other/script
`mappingStr`	CDATA		仅 type=65536 必填（映射列配置）
`layoutType`	string		mobile：horizontal/vertical
`version`	int		保存自增
`parentId` / `applicationid`	string		模块/应用

type¶

值	含义	动态表
1	普通	TLK_
2	标签页片段	否
3	流程参数	PARM_
4	数据模型	外部
16	子表单	TLK_
256	查询表单	否
4096	首页	—
65536	映射表单（映射已有业务表）	否
1048576	模板表单	否

3. XML 骨架¶

<?xml version="1.0" encoding="UTF-8"?>
<Form>
  <id>FORM_UUID</id>
  <name>LeaveRequest</name>
  <type>1</type>
  <showType>new</showType>
  <permissionType>public</permissionType>
  <orderno>1</orderno>
  <description><![CDATA[请假申请]]></description>
  <showLog>false</showLog>
  <templatecontext><![CDATA[{"fields":[],"layout":{...}}]]></templatecontext>
</Form>

4. templatecontext → JsonTemplate¶

根对象为 fields + layout，可选 mobileAutoLayout、pcLayoutMode（禁止旧根级 formPanel）。mobileAutoLayout 缺省/null/空视为 true（mobile 沿用 PC）；仅显式 false 时编译 layout.mobile。新建默认拖拽：pcLayoutMode 缺省或 "pc"；仅 "classic" 编译印刷布局 layout.classicPc。写出用 classicPc，旧键 layout.classic 只读兼容。

字段布局键只写在 fieldRef，禁止写在 fields 的 *Field 上（myselfrows、layout、paddingtop/right/bottom/left、showTitle、showfieldtitle、width、widthunit）。Java FormJsonTemplateCompiler.resolveFieldRef 会丢弃 fields 上的同名残留，不从字段定义兜底。PC / Mobile 可各写一份。JsonTemplate 不写 style 对象；编译器由 padding* / direction / myselfrows 重建 inline style。布局容器的 myselfrows / padding* / direction 仍写在布局节点上。

{
  "fields": [
    { "inputField": { "scope": "inputField", "id": "fld-001", "name": "title",
      "fieldtype": "VALUE_TYPE_VARCHAR", "texttype": "text" } }
  ],
  "layout": {
    "pc": {
      "formPanel": {
        "scope": "formPanel",
        "id": "fp-001",
        "children": [
          { "fieldRef": {
            "scope": "fieldRef",
            "fieldId": "fld-001",
            "myselfrows": 100,
            "layout": "horizontal",
            "showTitle": true,
            "paddingtop": 5,
            "paddingright": 10,
            "paddingbottom": 10,
            "paddingleft": 10,
            "width": 100,
            "widthunit": "%"
          } }
        ]
      }
    },
    "classicPc": { "formPanel": { "scope": "formPanel", "children": [] } },
    "mobile": null
  },
  "mobileAutoLayout": true,
  "pcLayoutMode": "pc"
}

项	约定
`fields`	数组；元素 `{ [scope]: { scope, id, 业务 props... } }`；不含布局键与 `style`
`layout.pc.formPanel`	拖拽默认权威；子节点每项为单键对象（键 = scope）
`layout.classicPc`	印刷布局；新建拖拽写空 `formPanel`
`pcLayoutMode`	新建 `pc`；印刷才 `classic`
布局节点	`formPanel` / `container` / `twoColumnContainer` 等；字段以 `{ "fieldRef": { "scope":"fieldRef", "fieldId", 布局键... } }` 引用
默认布局	普通字段成对放 `twoColumnContainer`（两列 `container`），禁止 fieldRef 直挂 formPanel
`mobileAutoLayout`	可选；缺省 true；`false` 时 `layout.mobile` 为 `{ formPanel: ... }`
字段键名	设计器小写键：`hiddenscript`、`texttype`、`datepattern`、`viewid`
勿输出	UI 缓存键：`editProp`、`viewsoptions`、`optionstextoptions`、`processprevalue`、`formsOptions`；字段 `style`

动态表列规则：存值字段（ValueStoreField 且 onlyCalculate!=true）→ 列 ITEM_{NAME大写}；$ 开头字段名 → 去 $ 大写、无前缀；映射表单列名由 mappingStr.columnMappings 指定。字段类型 → VARCHAR/NUMBER/DATE/TEXT(CLOB)/BLOB。

5. .activity（表单工具栏操作）¶

独立文件，XML 根 activity，camelCase 属性。常用 type：

type	含义	type	含义
34	保存	5	流程处理（预设时 `onActionFlow` 必填）
4	保存并启动流程	33	流程启动
11	保存并返回	10	返回
42	保存并新建	8	关闭窗口
19	保存草稿不校验	14/30/25	网页打印/自定义打印/PDF 导出
21	保存并复制	43	跳转
13	自定义	26/28/37/46	下载/电子签章/分享/在线签章

通用属性：id/name/type/icontype/icon/fontUrl/beforeActionScript/actionScript/afterActionScript/readonlyScript/hiddenScript/orderno 等。

6. 动态表同步（落盘后必做）¶

手工落盘 .form 不触发建表；type∈{1,3,16} 须向 workspace/.sync/ 投递 {前缀}.create_form_table（内容 = .form 内层同名文件 URI，如 /LeaveOA.application/module/Leave.module/LeaveRequest.form/LeaveRequest.form），成功进 .done/、失败进 .failed/。细节见 [[design/table-schema/overview]] §7.5。

7. 相关¶

资源	文档
所属模块	[[module-file]]
视图（数据来源）	[[view-file]]
流程挂接（activity type=5/4/33）	[[flow-file]]
动态表列结构	`design/table-schema/overview.md`（动态表节）
生成操作指南	`agent-skills-usage/skills/generate-form-file/SKILL.md`（含全字段 scope 表、form_template_builder.py）