表单脚本（FORM）¶

配套：generate-form-file。JsonTemplate 字段键一律**小写**；Form 元数据多为**小写脚本字段名**或 camelCase（见各卡）。

表单级开关¶

是否可打开¶

项	内容
Label	`FORM:OPEN`
属性	`isopenablescript`
触发	打开表单
返回	Boolean；`true`=允许打开，`false`=禁止（空≈允许）

(function () {
  return getWebUser().getName() !== "smart";
})()

是否可编辑¶

项	内容
Label	`FORM:EDIT`
属性	`iseditablescript`
触发	打开表单
返回	Boolean；`true`=可编辑

(function () {
  return getWebUser().getName() !== "smart";
})()

水印¶

项	内容
Label	`FORM:WATERMARK`
属性	`waterMarkScript`
触发	打开表单（开启水印时）
返回	String；水印文案

(function () {
  return getWebUser().getName();
})()

留痕模式脚本¶

项	内容
Label	`FORM:LOG`
属性	`recordModeScript`（`recordMode=script`）
触发	按留痕逻辑求值
返回	依产品约定（常为模式相关布尔/串）

评论¶

场景	Label	属性	返回
隐藏评论	`FORM:COMMENT_HIDE`	`commentHiddenScrtipt`（历史拼写 Scrtipt）	Boolean；true=隐藏
评论执行	`FORM:COMMENT_REPLAY`	`commentExecuteScript`	依产品
评论标题	`FORM:COMMENT_TITLE`	`commentTitleScript`	String
评论标签	`FORM:COMMENT_TAG`	`commentFlagScript`	String/标记

值脚本¶

字段值¶

项	内容
Label	`FORM:FIELD_VALUE`
属性	XML/API：`valueScript`；JsonTemplate：`valuescript`；常配 `editmode=01` / `calculateonrefresh`
触发	打开表单 / 刷新计算
返回	控件显示或存值（类型随控件；多为 String）

硬规则：valuescript 非空时必须 IIFE 包装，禁止顶层裸 return（见 SKILL.md 通则、graalvm.md#7）。

// 错误
return getWebUser().getId();

// 正确 — 默认当前用户（userField 存用户 id）
(function () {
  return getWebUser().getId();
})()

(function () {
  var v = getItemValueAsString("报销人");
  if (v == null || v === "") {
    v = getWebUser().getName();
  }
  return v;
})()

计算文本等不落库控件同 Label，属性仍为 valuescript。

选项脚本¶

选项类控件选项¶

项	内容
Label	`FORM:FIELD_OPTION`
属性	JsonTemplate：`optionsscript`（`optionseditmode=01`）
触发	打开表单
返回	`Options`，或 `"1:A;2:B"` / `"A;B"`

(function () {
  var opts = createOptions();
  opts.add("", "");
  var datas = queryByDSName("MY_DS", "select id, name from t_user");
  if (datas != null) {
    for (var it = datas.iterator(); it.hasNext();) {
      var row = it.next();
      opts.add(row.get("name"), row.get("id"));
    }
  }
  return opts;
})()

适用于 Select / Radio / Checkbox / Suggest / SelectAbout 等。

opts.add 参数顺序与存值约定（硬规则）：

API：add(显示文本, 存值) — 写反会导致下拉显示英文码、库里却落下中文文案，选择视图按存值过滤时列表为空。
表单优先：数据库存储英文，在表单界面显示中文 — 例：opts.add("草稿","DRAFT")、opts.add("是","Y")；禁止 opts.add("DRAFT","草稿")。
Activity / 值脚本读写比较一律用英文存值；新写入不得再写中文存值。

Python 落盘：opts_pairs(("DRAFT","草稿"), ("Y","是"))（见 generate-form-file / form_template_builder）。

校验脚本¶

校验库（validatelibs）¶

字段校验**优先挂校验库**，写入 JsonTemplate validatelibs（字符串数组）。保存/提交时按数组执行。

系统默认校验库（空值必填：标题旁红色 *、空保存/提交拦截）：

core.dynaform.form.formfield.validate.checkEmpty_system

无需落盘 .valid；无条件必填时把该标识写入 validatelibs。

自定义校验库：按需新增，落盘见 generate-valid-file。已经存在的校验库可在表单字段「校验库」中勾选，勾选结果记入同一 validatelibs 数组（与系统库并存）。validatelibs 存的是该文件根 id（不是 name）。

类型	`validatelibs` 记入值	落盘
系统默认（空值/必填）	`core.dynaform.form.formfield.validate.checkEmpty_system`	平台内置
系统其它（如字段唯一）	`core.dynaform.form.formfield.validate.checkFieldUnique_system`	平台内置；映射表单禁止 unique，见下节
自定义	`.valid` 根 `id`（如 `__w1DsV5XNQ30qjzAGBjK`）	`{软件}.application/valid/{名称}.valid`

"validatelibs": [
  "core.dynaform.form.formfield.validate.checkEmpty_system"
]

多个库同数组：

"validatelibs": [
  "core.dynaform.form.formfield.validate.checkEmpty_system",
  "__YourCustomValidId"
]

做	不做
无条件必填：挂系统默认 `checkEmpty_system`	禁止用 `worklimitchecked=true` 冒充必填
可复用/业务校验：先写 `.valid`，再在字段上勾选记入 `validatelibs`	禁止用字段 `validaterule` 手写「不能为空」代替系统默认库
条件必填（如病假才要附件）也做成自定义 `.valid` 再勾选	不要把可复用规则只写在单个字段的 `validaterule` 里

字段校验脚本（validaterule）¶

项	内容
Label	`FORM:FIELD_VALIDATE`
属性	JsonTemplate：`validaterule`
触发	保存/校验时（在已挂 `validatelibs` 之外的字段级脚本）
返回	失败=提示 String；成功=`""`

仅用于**该字段一次性、不可复用**的脚本。可复用规则一律 .valid + validatelibs。

(function () {
  var v = getItemValueAsString("amount");
  if (v == null || String(v).trim() === "") return "";
  if (parseFloat(v) <= 0) return "'金额'必须大于 0";
  return "";
})()

字段唯一（编码重复）¶

场景	推荐做法	禁止 / 慎用
普通表单（`TLK_*`，type≠65536）	`validatelibs` 挂 `core.dynaform.form.formfield.validate.checkFieldUnique_system`；或脚本内 `checkFieldUnique(fieldName, fieldValue, msg)`	—
映射表单（type=65536 → `MD_*` 等业务表）	字段 `validaterule` + 保存类 activity `beforeActionScript` 用 `queryBySQL` 查映射物理表；排除当前 `MAPPINGID`	禁止 `checkFieldUnique` / `checkFieldUnique_system`（会误查其它 `TLK_`，拼出非法 SQL 抛错）；禁止 `$SQL`（表单/操作上下文未定义*，`$SQL` 仅见定时任务等）

映射表单唯一校验示例（validaterule 返回提示字符串）：

(function () {
  var code = getItemValueAsString("code");
  if (code == null || code === "") {
    return "";
  }
  var mappingId = getItemValueAsString("MAPPINGID");
  var safe = String(code).replace(/'/g, "''");
  var sql = "SELECT ID FROM MD_ISO_CATEGORY WHERE CODE='" + safe + "'";
  if (mappingId != null && mappingId !== "") {
    sql += " AND ID<>'" + String(mappingId).replace(/'/g, "''") + "'";
  }
  try {
    var docs = queryBySQL(sql);
    if (docs != null && docs.size() > 0) {
      return "分类编码已存在，不能重复";
    }
  } catch (e) {
    return "分类编码唯一性校验失败：" + e;
  }
  return "";
})()

保存拦截见 activity.md#映射表单唯一-保存前置（createAlert）。改盘后须 clear_cache。

SQL API 按上下文¶

API	表单字段脚本 / activity 前后置	定时任务 `taskScript`
`queryBySQL(sql)` → `Collection<Document>`	✅	✅（亦可用）
`checkFieldUnique(...)`	✅ 仅普通 TLK 表单；映射表单 ❌	一般不适用
`$SQL.query` / `$SQL.execute`	❌ 未定义	✅（本仓库 task 常用）

隐藏脚本¶

控件隐藏¶

项	内容
Label	`FORM:FIELD_HIDE`
属性	`hiddenScript` / `hiddenscript`
触发	打开表单
返回	Boolean；`true`=隐藏

(function () {
  return getCurrentDocument().getItemValueAsString("IsStartup") === "02";
})()

打印时隐藏¶

项	内容
Label	`FORM:FIELD_PRINT_HIDE`
属性	`hiddenPrintScript` / `hiddenprintscript`
触发	打印
返回	Boolean；`true`=打印时隐藏

(function () {
  return false;
})()

Tab 页签、包含元素等同类属性：hiddenScript / hiddenPrintScript（Tab 子项常为 camelCase）。

只读脚本¶

控件只读¶

项	内容
Label	`FORM:FIELD_READONLY`
属性	`readonlyScript` / `readonlyscript`；Tab：`readOnlyScript`
触发	打开表单
返回	Boolean；`true`=只读

(function () {
  return getCurrentDocument().getItemValueAsString("IsStartup") === "02";
})()

描述 / 问卷 / 二维码¶

字段描述¶

项	内容
Label	`FORM:FIELD_DESCRIPTION`
属性	`discript`（描述脚本）
触发	打开表单
返回	String；描述文案

调查问卷¶

项	内容
Label	`FORM:FIELD_QUESTION`
属性	`questionscript`
触发	打开表单
返回	Question 列表

(function () {
  var q = createQuestion(1, "你的爱好（多选）");
  q.addCheckboxOption("羽毛球", "羽毛球");
  var qs = new java.util.ArrayList();
  qs.add(q);
  return qs;
})()

二维码内容¶

项	内容
Label	`FORM:FIELD_QR_CONTENT`
属性	二维码内容脚本
触发	打开表单
返回	String（可为 URL）

(function () {
  return "https://www.baidu.com/";
})()

按钮与确认¶

表单工具栏 .activity 脚本见 activity.md。按钮**字段** JsonTemplate 常用：

场景	Label	属性
执行前	（同 ACTIVITY 前置语义）	`beforeactionscript`
动作		`actionscript`
执行后		`afteractionscript`
跳转 URL	`ACTIVITY:DISPATCHERURL` 语义	`actiondispatcherurlscript`
文件名	`ACTIVITY:FILENAME` 语义	`filenamescript`
签章位置	`FORM:FIELD_SIGN_POSITION`	`signaturePosScript`
视图选择确认	`FORM:FIELD_OK`	`okscript`
确认回调	`FORM:FIELD_OK_CALLBACK`	`callbackscript`

按钮执行前（示例）¶

(function () {
  return createConfirm("确定要提交文档？");
})()

返回：无 / 警告 String / Message（Confirm、Alert）。

按钮执行后（示例）¶

(function () {
  sendMail(getItemValueAsString("from"), getItemValueAsString("to"),
    getItemValueAsString("subject"), getItemValueAsString("content"));
})()

无强制返回值。

Tab / HTML / 上传 / 签名 / 摘要¶

场景	Label	属性	返回
Tab 标题	`FORM:FIELD_TAB_TITLE`	`titleScript`	String
Tab 选中	`FORM:FIELD_TAB_SELECTED`	`selectedscript`	Boolean/选中逻辑
Tab 刷新检查	`FORM:FIELD_TAB_CHECK_REFRESH`	`selectRefreshScript`	Boolean
HTML 内容	`FORM:FIELD_HTML`	HTML 脚本属性	String HTML
签名	`FORM:FIELD_SIGNATURE`	签章相关	依控件
上传下载权限	`FORM:FIELD_UPLOAD_DOWNLOAD`	`downloadscript`	Boolean/权限
上传删除	`FORM:FIELD_UPLOAD_REMOVE`	`deletescript`	Boolean
上传重命名	`FORM:FIELD_UPLOAD_RENAME`	`renamescript`	Boolean
上传预览	`FORM:FIELD_UPLOAD_PREVIEW`	`previewscript`	Boolean
在线编辑	`FORM:FIELD_UPLOAD_ONLINEEDIT`	`editscript`	Boolean
新版本	`FORM:FIELD_UPLOAD_VERSION_RENEW`	`newversionscript`	Boolean
版本比较	`FORM:FIELD_UPLOAD_VERSION_COMPARE`	`versioncomparescript`	Boolean
版本还原	`FORM:FIELD_UPLOAD_VERSION_REVERT`	`restorescript`	Boolean
上传水印	`FORM:FIELD_UPLOAD_WATERMARK`	`watermarkscript`	String/水印
摘要	`FORM:SUMMARY`	摘要脚本	String
打印 HTML	`FORM:TOHTML`	打印转换脚本	String HTML

上传权限类最短例：

(function () {
  return true;
})()

跳过¶

Label	说明
`FORM:UNKNOW`	运行时兜底，不写入业务定义
`FORM:ACTIVITY`	表单关联操作标签；工具栏脚本写在 `.activity`，见 activity.md
`FORM:FIELD_CACULATE`	源码已注释，不使用