Skip to main content

ObjectData 使用说明

为了统一系统输入输出模型，系统上下游业务传输的载体为 ObjectData 对象或其集合类型。

模型定义​

namespace Chameleon.Common.Models
{
    /// <summary>
    /// 数据对象
    /// </summary>
    [Serializable]
    public class ObjectData
    {
        // ====== 核心标识 ======

        /// <summary>
        /// 数据Id的字符串形式
        /// </summary>
        public string _id => Id.ToString();

        /// <summary>
        /// 数据Id（GUID）
        /// </summary>
        public Guid Id { get; set; }

        // ====== 系统字段（从 Fields 字典中读写） ======

        /// <summary>软删除标记</summary>
        public bool IsDeleted { get; set; }

        /// <summary>创建人</summary>
        public string CreatedBy { get; set; }

        /// <summary>创建时间（UTC）</summary>
        public DateTimeOffset? CreatedTime { get; set; }

        /// <summary>修改人</summary>
        public string ModifiedBy { get; set; }

        /// <summary>修改时间（UTC）</summary>
        public DateTimeOffset? ModifiedTime { get; set; }

        /// <summary>所属组织</summary>
        public string Organization { get; set; }

        // ====== 字段字典 ======

        /// <summary>属性字典，存储所有业务字段的值</summary>
        public IDictionary<string, FieldData> Fields { get; set; } = new Dictionary<string, FieldData>();

        // ====== 索引器与操作方法 ======

        /// <summary>获取或设置字段值（同时设置 Text 和 Value）</summary>
        public object this[string code] { get; set; }

        /// <summary>判断字段是否存在</summary>
        public bool ContainsKey(string key);

        /// <summary>仅设置 Value 属性（字段存在则更新，不存在则创建）</summary>
        public void SetValue(string code, object value);

        /// <summary>仅设置 Text 属性（字段存在则更新，不存在则创建但 Value 为 null）</summary>
        public void SetText(string code, string text);

        /// <summary>获取字段的存储值（Value）</summary>
        public object GetValue(string code);

        /// <summary>获取字段值并自动强类型转换，转换失败返回默认值</summary>
        public T GetValueOrDefault<T>(string code, T defaultValue = default);

        /// <summary>获取字段的 Text 显示值</summary>
        public string GetText(string code);
    }

    /// <summary>
    /// 字段数据
    /// </summary>
    [Serializable]
    public class FieldData
    {
        /// <summary>字段编码</summary>
        public string Code { get; set; }
        /// <summary>字段显示文本</summary>
        public string Text { get; set; }
        /// <summary>字段存储值</summary>
        public object Value { get; set; }
        /// <summary>扩展信息</summary>
        public Dictionary<string, object> Extend { get; set; } = [];
    }
}

使用说明​

获取字段值​

获取某个字段值：

object value = obj["fieldName"];
类型转换

obj["xx"] 返回的数据类型为 object 弱类型，常用处理时应手动转为对应的强类型：

string strValue = Convert.ToString(obj["fieldName"]);
int intValue = Convert.ToInt32(obj["fieldName"]);
DateTime timeValue = Convert.ToDateTime(obj["fieldName"]);

获取字段值（自动强类型转换）​

获取某个字段值并自动转换为指定类型，转换失败时返回默认值：

int value = obj.GetValueOrDefault<int>("fieldName");
string name = obj.GetValueOrDefault<string>("fieldName", "默认值");

支持 Nullable<T> 类型，值为 null 或 DBNull 时返回指定的默认值。

获取 Text / Value 属性​

// 获取字段的显示文本（Text）
string text = obj.GetText("fieldName");

// 获取字段的存储值（Value），等价于 obj["code"]
object value = obj.GetValue("fieldName");

字段赋值​

通过索引器赋值会同时设置 Text 和 Value：

obj["fieldName"] = "hello";
// 等价于：
// obj.Fields["fieldName"] = new FieldData { Code = "fieldName", Text = "hello", Value = "hello" };

仅设置 Text 或 Value​

// 只更新 Value（不改变 Text）
obj.SetValue("fieldName", newValue);

// 只更新 Text（不改变 Value）
obj.SetText("fieldName", "显示文本");

判断字段是否存在​

bool exists = obj.ContainsKey("fieldName");

系统字段​

ObjectData 内置了以下系统字段属性，它们本质上是从 Fields 字典中读取/写入的便捷属性：

属性类型对应 Fields Key说明
IdGuid_id数据唯一标识
_idstring_id数据 ID 的字符串形式（只读）
IsDeletedboolisdeleted软删除标记
CreatedBystringcreatedby创建人
CreatedTimeDateTimeOffset?createdtime创建时间（UTC）
ModifiedBystringmodifiedby最后修改人
ModifiedTimeDateTimeOffset?modifiedtime最后修改时间（UTC）
Organizationstringorganization所属组织

获取数据 ID​

// GUID 格式
Guid id = obj.Id;

// 字符串格式
string idStr = obj._id;

访问系统字段​

系统字段既可以通过属性访问，也可以通过字典方式访问，两者等价：

// 通过属性访问（推荐）
var creator = obj.CreatedBy;
var createTime = obj.CreatedTime;
var isDeleted = obj.IsDeleted;

// 通过字典访问（效果相同）
var creator = obj["createdby"];
var isDeleted = obj["isdeleted"];

FieldData 结构​

每个字段在 Fields 字典中以 FieldData 形式存储，包含三个核心属性：

属性说明
Code字段编码（如 "name"、"status"）
Text字段的显示文本（用于前端展示）
Value字段的存储值（用于后端逻辑和数据库存取）
Extend扩展信息字典，可存放额外数据

大多数场景下通过 obj["code"] 操作即可，无需直接操作 FieldData。

方法汇总​

方法/属性说明
obj["code"]获取或设置字段值（同时设 Text 和 Value）
obj.GetValueOrDefault<T>("code")获取字段值并自动强类型转换
obj.GetText("code")获取字段的 Text 显示值
obj.GetValue("code")获取字段的 Value 存储值
obj.SetText("code", "text")仅设置字段的 Text 属性
obj.SetValue("code", value)仅设置字段的 Value 属性
obj.ContainsKey("code")判断字段是否存在
obj.Id获取 GUID 格式的数据 ID
obj._id获取 string 格式的数据 ID
obj.IsDeleted软删除标记
obj.CreatedBy创建人
obj.CreatedTime创建时间（UTC）
obj.ModifiedBy修改人
obj.ModifiedTime修改时间（UTC）
obj.Organization所属组织

相关文档​