变更历史操作

control_history

初始化控件变更历史记录监控。

语法

control_history(formKey, ids, params)

参数

参数名	类型	必填	说明
formKey	string/Object	是	历史记录唯一标识，相同 key 归属同一张单据；可传入单据 ID、单据编号或自定义业务标识
ids	Array	是	需要监控的控件 ID 列表，示例：["username","name","mobile","table"]
params	Object	否	预留扩展参数

formKey 对象参数说明

当 formKey 传入对象时，支持以下属性：

参数名	类型	必填	说明
form_key	string	是	单据唯一 key
form_scene	string	否	控件场景标识
form_type	string	否	控件类型标识

提示：三项组合一致才判定为同一张单据。

示例

// 字符串形式 formKey
control_history("order_20250101001", ["username", "name", "mobile"], {});

// 对象形式 form_key
var formKeyObj = {
    form_key: "order_20250101001",
    form_scene: "order_edit",
    form_type: "sales_order"
};
control_history(formKeyObj, ["username", "name", "mobile", "product_table"], {});

// 携带扩展参数初始化
control_history("order_20250101001", ["username", "name"], {
    enableLog: true,
    logLevel: "detail"
});

---

control_history_save

自动保存控件变更历史记录。

说明

自动检测同一单据下已初始化控件的数据变更，存在差异则自动生成历史记录。

⚠️ 表格控件不支持自动记录，表格场景请使用手动保存接口；保存完成后执行回调函数。

语法

control_history_save(callBack, params)

参数

参数名	类型	必填	说明
callBack	Function	否	保存成功回调
params	Object	否	预留扩展参数

示例

// 基础自动保存
control_history_save(() => {
  console.log("历史记录保存成功");
});

// 携带扩展参数
control_history_save(() => {
  console.log("历史记录保存成功");
}, {
    async: true,
    timeout: 5000
});

---

control_history_savecus

手动保存变更历史（适用于表格或自定义场景）。

语法

control_history_savecus(formKey, data, callback)

参数

参数名	类型	必填	说明
formKey	string/Object	是	历史记录唯一标识，相同 key 归属同一张单据
data	Object	是	变更数据；html_id 留空代表全局记录，包含原始值与新值
callback	Function	否	保存成功回调

data 参数说明

参数名	类型	必填	说明
html_id	string	否	控件 ID，留空代表全局记录
original_val	any	是	修改前原始值
new_val	any	是	修改后新值

callBack 参数说明

参数名	类型	必填	说明
getData	Function	否	获取回调数据
success	Function	否	成功回调（需自行处理返回数据）
error	Function	否	失败回调
complete	Function	否	完成回调

示例

// 保存单个控件变更记录
control_history_savecus("order_20250101001", {
    html_id: "username",
    original_val: "张三",
    new_val: "李四"
}, function() {
    console.log("控件历史记录保存成功");
});

// 保存表格控件变更记录
control_history_savecus("order_20250101001", {
    html_id: "product_table",
    original_val: [{id: 1, name: "产品A", qty: 10}],
    new_val: [{id: 1, name: "产品A", qty: 15}]
}, function() {
    console.log("表格历史记录保存成功");
});

// 保存页面全局变更记录
control_history_savecus("order_20250101001", {
    original_val: "订单已创建",
    new_val: "订单已审核"
}, function() {
    console.log("全局历史记录保存成功");
});

---

control_history_list

打开单据变更历史记录弹窗。

语法

control_history_list(formKey, params)

参数

参数名	类型	必填	说明
formKey	string/Object	是	历史记录唯一标识，相同 key 归属同一张单据
params	Object	否	预留扩展参数

示例

// 打开单据变更历史弹窗
control_history_list("order_20250101001", {});

// 携带扩展参数
control_history_list("order_20250101001", {
    pageSize: 20,
    showUser: true
});

// 对象形式 formKey
var formKeyObj = {
    form_key: "order_20250101001",
    form_scene: "order_detail"
};
control_history_list(formKeyObj, {});

---

功能说明

功能简介

用于记录表单控件的数据变更记录。控件存在变更历史时，右上角展示红色小三角标识，点击可快速查看修改轨迹。

标准使用流程

1. 调用 control_history，初始化需要监控历史变更的控件；
2. 普通输入类控件：使用 control_history_save 实现自动记录；
3. 表格控件或自定义场景：使用 control_history_savecus 手动写入变更记录；
4. 调用 control_history_list，弹窗展示完整变更历史。

注意事项

1. 表格控件不支持自动记录，必须调用手动保存接口；
2. form_key 作为单据唯一标识，相同 key 视为同一份单据；
3. 存在变更历史的控件会显示红色小三角，支持点击查看历史；
4. 自动保存接口会自动对比数据差异，仅发生变更时生成记录。