数据格式规范与操作示例
不同类型的数据格式会有不同，包括字符串、字符串数组、布尔值等。位置和地址控件使用特定格式的字符串，下文详细说明各控件类型的数据格式规范及取值、赋值操作示例。
单行文本
数据格式为文本字符串，最多存储 200 个字符。赋值超过 200 个字符将报错，例如："文本内容"。
取值
string s = this.Request.BizObject["字段编码"] + string.Empty;
赋值
this.Request.BizObject["字段编码"] = "文本内容";
多行文本
数据格式为文本字符串，例如："多行文本内容"。
取值
string s = this.Request.BizObject["字段编码"] + string.Empty;
赋值
this.Request.BizObject["字段编码"] = "多行文本内容";
下拉框
数据格式为文本字符串，最多存储 200 个字符。赋值超过 200 个字符将报错，例如："选项1"。
取值
string s = this.Request.BizObject["字段编码"] + string.Empty;
赋值
this.Request.BizObject["字段编码"] = "选项1";
单选框
数据格式为文本字符串，最多存储 200 个字符。赋值超过 200 个字符将报错，例如："选项1"。
取值
string s = this.Request.BizObject["字段编码"] + string.Empty;
赋值
this.Request.BizObject["字段编码"] = "选项1";
复选框
数据格式为文本字符串，最多存储 200 个字符。赋值超过 200 个字符将报错，例如："选项1;选项2"。
⚠️ 注意
复选框存储的数据为多个选项通过分号分隔的字符串
取值
string s = this.Request.BizObject["字段编码"] + string.Empty;
赋值
this.Request.BizObject["字段编码"] = "选项1;选项2";
流水号
数据格式为文本字符串，最多存储 200 个字符。赋值超过 200 个字符将报错，例如："BZ20250901002"。
该字段为系统生成字段，不可赋值。
取值
string s = this.Request.BizObject["字段编码"] + string.Empty;
日期
数据结构为日期格式的字符串，例如：
"2025-08-01"
"2025-08-20 08:13:10"
"2025-08-20 00:00:00"
取值
string strTime = this.Request.BizObject["字段编码"] + string.Empty;
DateTime dTime = DateTime.MinValue;
DateTime.TryParse(strTime, out dTime);
赋值
this.Request.BizObject["字段编码"] = "2025-08-01";
this.Request.BizObject["字段编码"] = new DateTime(2025,08,01);
是否
数据格式为布尔值，例如：true、false。
取值
string boolStr = this.Request.BizObject["控件编码"] + string.Empty;
bool bValue;
bool.TryParse(boolStr, out bValue);
赋值
this.Request.BizObject["字段编码"] = true;
this.Request.BizObject["字段编码"] = false;
数值
数据格式为数值格式的字符串，例如：
"123"
"1234"
"123.456"
取值
string numStr = this.Request.BizObject["控件编码"] + string.Empty;
decimal result = 0m;
decimal.TryParse(numStr, out result);
赋值
可使用数值格式字符串或数值直接赋值：
this.Request.BizObject["字段编码"] = "123";
this.Request.BizObject["字段编码"] = 123;
this.Request.BizObject["字段编码"] = 123.456m;
地址
数据格式为 JSON 格式字符串，包含 adcode、adname、Detail 三部分，最多存储 200 个字符，例如：
"{\"adcode\":\"440305\",\"adname\":\"广东省 深圳市 南山区\",\"Detail\":\"详细地址\"}"。
赋值为其他格式将导致加载报错。
取值
string addressStr = this.Request.BizObject["控件编码"] + string.Empty;
Dictionary <string, string> addrDict = this.Deserialize<Dictionary<string, string>>(addressStr);
string adcode = addrDict.ContainsKey("adcode") ? addrDict["adcode"] : "";
string adname = addrDict.ContainsKey("adname") ? addrDict["adname"] : "";
赋值
Dictionary<string, string> addrDict = new Dictionary<string, string>();
addrDict["adcode"] = "440305";
addrDict["adname"] = "广东省 深圳市 南山区";
addrDict["Detail"] = "详细地址";
this.Request.BizObject["字段编码"] = this.Serialize(addrDict);
位置
数据格式为 JSON 格式字符串，包含 Address、Point、CSType、WGS84Point 等部分，例如：
"{\"Address\":\"广东省深圳市福田区莲花街道益田路市民广场\",\"Point\":{\"lat\":22.540862,\"lng\":114.05644},\"CSType\":2,\"WGS84Point\":{\"lng\":114.05132789740453,\"lat\":22.54358194824299}}"。
赋值为其他格式将导致加载报错。
取值
string locationStr = this.Request.BizObject["控件编码"] + string.Empty;
Dictionary <string, string> locationDict = this.Deserialize<Dictionary<string, string>>(locationStr);
string Address = locationDict.ContainsKey("Address") ? locationDict["Address"] : "";
赋值
Dictionary<string, object> locationDict = new Dictionary<string, object>();
locationDict["Address"] = "广东省深圳市福田区莲花街道益田路市民广场";
locationDict["Point"] = new Dictionary<string, double> { { "lat", 22.540862 }, { "lng", 114.05644 } };
this.Request.BizObject["字段编码"] = this.Serialize(locationDict);
人员单选
数据格式为字符串，最多存储 200 个字符，例如："21517f93-1355-41ea-8833-c97e81592a4f"。
取值
string userId = this.Request.BizObject["控件编码"] + string.Empty;
赋值
this.Request.BizObject["字段编码"] = "21517f93-1355-41ea-8833-c97e81592a4f";
部门单选
数据格式为字符串，最多存储 200 个字符，例如："67761576-0eb0-41f4-ab6b-3ba181fa90e7"。
取值
string deptId = this.Request.BizObject["字段编码"] + string.Empty;
赋值
this.Request.BizObject["字段编码"] = "67761576-0eb0-41f4-ab6b-3ba181fa90e7";
人员多选
数据格式为字符串数组，例如：["21517f93-1355-41ea-8833-c97e81592a4f", "21517f93-1355-41ea-8833-c97e81592a4e"]。
取值
string[] multiUserValue = this.Request.BizObject["字段编码"] as string[];
if(multiUserValue != null)
{
//
}
赋值
this.Request.BizObject["字段编码"] = new string[] {"21517f93-1355-41ea-8833-c97e81592a4f"};
部门多选
数据格式为字符串数组，例如：["67761576-0eb0-41f4-ab6b-3ba181fa90e7", "67761576-0eb0-41f4-ab6b-3ba181fa90e6"]。
取值
string[] multiDeptValue = this.Request.BizObject["字段编码"] as string[];
if(multiDeptValue != null)
{
//
}
赋值
this.Request.BizObject["字段编码"] = new string[] {"67761576-0eb0-41f4-ab6b-3ba181fa90e7"};
关联表单
数据格式为字符串，最多存储 200 个字符，例如："67761576-0eb0-41f4-ab6b-3ba181fa90e7"。
取值
string relationId = this.Request.BizObject["字段编码"] + string.Empty;
赋值
this.Request.BizObject["字段编码"] = "67761576-0eb0-41f4-ab6b-3ba181fa90e7";
关联多选
数据格式为字符串数组，例如：["57761576-0eb0-41f4-ab6b-3ba181fa90e7", "9bc7bf7c-b61a-4593-aeb5-22c25548c68e"]。
取值
string[] multiRelationValue = this.Request.BizObject["字段编码"] as string[];
if(multiRelationValue != null)
{
//
}
数据库中关联多选数据存储在独立表，SQL 查询方式如下：
select * from I_表单编码_关联表单多选控件编码;
关联多选数据表字段说明：
| 字段名 | 字段描述 |
|---|---|
objectid |
表单数据 ID |
valueindex |
关联表单多选控件值的索引序号（从 0 开始） |
propertyvalue |
关联表单多选控件值 |
赋值
this.Request.BizObject["字段编码"] = new string[] {
"57761576-0eb0-41f4-ab6b-3ba181fa90e7",
"9bc7bf7c-b61a-4593-aeb5-22c25548c68e"
}
附件
附件字段存储附件 ID 数组，附件名称、大小等信息存储在 BizObjectFile 表，详见 H3.DataModel.BizObjectFileHeader 类。
取值
BizObject 中附件字段值为 H3.DataModel.BizObjectFileHeader[] 类型。
⚠️ 注意
新增数据时无法获取附件 ID
- 通过
BizObject获取指定字段附件 ID：
H3.DataModel.BizObjectFileHeader[] fileheaders = this.Request.BizObject["字段编码"] as H3.DataModel.BizObjectFileHeader[];
List<string> fileIds = new List<string>();
if(fileheaders != null)
{
foreach(H3.DataModel.BizObjectFileHeader fileHeader in fileheaders)
{
fileIds.Add(fileHeader.ObjectId);
}
}
- 通过业务数据 ID 获取所有字段附件 ID：
List<string> fileIds = new List<string>();
string[] ObjectDataId = { "业务数据Id" }; //表单的 objectid
H3.DataModel.BizObjectFileHeader[] fileobject = this.Request.Engine.BizObjectManager.GetBizObjectFileHeaders(ObjectDataId);
if(fileobject != null && fileobject.Length > 0)
{
foreach(H3.DataModel.BizObjectFileHeader item in fileobject)
{
fileIds.Add(item.FileId);
}
}
赋值
附件不可通过 BizObject 直接赋值，需通过以下方式：
- 页面上传附件
- 第三方 API 上传
- 其他表单复制附件
复制
参考复制文件接口 IBizObjectManager.CopyFiles：
// 主表内附件控件复制到主表内附件控件
this.Request.Engine.BizObjectManager.CopyFiles("原-主表编码",
"",
"原-主表内附件控件编码",
"原-主表数据ObjectId",
"新-主表编码",
"",
"新-主表内附件控件编码",
"新-主表数据ObjectId",
true,
true);
// 主表内附件控件复制到子表内附件控件
this.Request.Engine.BizObjectManager.CopyFiles("原-主表编码",
"",
"原-主表内附件控件编码",
"原-主表数据ObjectId",
"新-主表编码",
"新-子表编码",
"新-子表内附件控件编码",
"新-子表数据ObjectId",
true,
true);
// 子表内附件控件复制到主表内附件控件
this.Request.Engine.BizObjectManager.CopyFiles("原-主表编码",
"原-子表编码",
"原-子表内附件控件编码",
"原-子表数据ObjectId",
"新-主表编码",
"",
"新-主表内附件控件编码",
"新-主表数据ObjectId",
true,
true);
// 子表内附件控件复制到子表内附件控件
this.Request.Engine.BizObjectManager.CopyFiles("原-主表编码",
"原-子表编码",
"原-子表内附件控件编码",
"原-子表数据ObjectId",
"新-主表编码",
"新-子表编码",
"新-子表内附件控件编码",
"新-子表数据ObjectId",
true,
true);
/*
CopyFiles 参数说明：
参数1：覆盖/添加模式（true=覆盖，false=添加）
参数2：覆盖时是否物理删除原附件（true=物理删除，false=仅删除记录）
*/
删除
根据附件 ID 删除附件，参考 IBizObjectManager.RemoveFile：
this.Engine.BizObjectManager.RemoveFile("fileId", false);
获取图片链接
string ObjectDataId = this.Request.BizObjectId; //表单的 objectid
//支持多个数据 ObjectId 查询
H3.DataModel.BizObjectFileHeader[] fileobject = this.Request.Engine.BizObjectManager.GetBizObjectFileHeaders(
new string[] { ObjectDataId });
if(fileobject != null && fileobject.Length > 0)
{
foreach(H3.DataModel.BizObjectFileHeader item in fileobject)
{
//获取缩略图链接
string thumbnailUrl = this.Engine.BizObjectManager.GetBizObjectFileThumbnailUrl(item);
}
}
//获取原图链接（FileId：附件 ID）
string url="https://www.h3yun.com/Form/DoPreview/?attachmentId="+FileId;
子表
子表数据独立存储，通过 ParentObjectId 字段与主表数据关联。子表数据可通过主表数据更新、删除或新增，也可独立操作。建议通过主表数据操作子表数据以确保子表计算公式和事件正常触发。
取值
子表数据在 H3.DataModel.BizObject 中为 H3.DataModel.BizObject[] 类型；
在 H3.Data.Serialization.VirtualObject 中为 H3.Data.Serialization.VirtualObject[] 类型。
子表字段操作与主表一致：
H3.DataModel.BizObject[] childDatas =
this.Request.Engine.BizObject["子表编码"] as H3.DataModel.BizObject[];
H3.Data.Serialization.VirtualObject childVos
= masterVirtualObject.GetPropertyValue("子表编码") as H3.Data.Serialization.VirtualObject[];
赋值
新增时
主表数据新增时同步新增子表数据：
// 假设主表 masterBo 已存在
// 获取子表结构体
H3.DataModel.BizObjectSchema childSchema = masterBo.Schema.GetChildSchema(childSchemaCode);
// 定义子表数据集
List<H3.DataModel.BizObject> newChildBoList = new List<H3.DataModel.BizObject>();
// 创建子表对象并加入集合
H3.DataModel.BizObject childBo1 = new H3.DataModel.BizObject(engine, childSchema, H3.Organization.User.SystemUserId);
childBo1["字段编码"] = "xxxxx";
newChildBoList.Insert(0, childBo1);
// 创建第二个子表对象
H3.DataModel.BizObject childBo2 = new H3.DataModel.BizObject(engine, childSchema, H3.Organization.User.SystemUserId);
childBo2["字段编码"] = "yyyyyy";
newChildBoList.Add(childBo2);
// 将子表数据集赋值到子表控件
masterBo[childSchemaCode] = newChildBoList.ToArray();
// 保存数据
masterBo.Create();
更新时覆盖
主表数据更新时覆盖原子表数据：
// 获取子表结构体
H3.DataModel.BizObjectSchema childSchema = masterBo.Schema.GetChildSchema(childSchemaCode);
List<H3.DataModel.BizObject> newChildBoList = new List<H3.DataModel.BizObject>();
H3.DataModel.BizObject childBo1 = new H3.DataModel.BizObject(engine, childSchema, H3.Organization.User.SystemUserId);
childBo1["字段编码"] = "xxxxx";
newChildBoList.Insert(0, childBo1);
H3.DataModel.BizObject childBo2 = new H3.DataModel.BizObject(engine, childSchema, H3.Organization.User.SystemUserId);
childBo2["字段编码"] = "yyyyyy";
newChildBoList.Add(childBo2);
masterBo[childSchemaCode] = newChildBoList.ToArray();
masterBo.Update();
更新时更新或删除
主表数据更新时修改/删除子表数据：
H3.DataModel.BizObjectSchema childSchema = masterBo.Schema.GetChildSchema(childSchemaCode);
H3.DataModel.BizObject[] existChildBos = masterBo[childSchemaCode] as H3.DataModel.BizObject[];
List<H3.DataModel.BizObject> newChildBoList = new List<H3.DataModel.BizObject>();
H3.DataModel.BizObject childBo1 = new H3.DataModel.BizObject(engine, childSchema, H3.Organization.User.SystemUserId);
childBo1["F0000002"] = "xxxxx";
//新增行
newChildBoList.Insert(0,childBo1);
//原有的子表数据
newChildBoList.AddRange(existChildBos);
masterBo[childSchemaCode] = newChildBoList.ToArray();
masterBo.Update();