鸿蒙三方库 | harmony-utils之ObjectUtil对象序列化与反序列化详解
前言
对象序列化和反序列化是数据持久化和网络传输的基础操作。@pura/harmony-utils的ObjectUtil封装了对象序列化方法，支持深拷贝和JSON序列化。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。
一、ObjectUtil序列化核心API
ObjectUtil提供了以下序列化方法：
| 方法 | 说明 | 返回类型 | 使用场景 |
|---|---|---|---|
serialize(obj) | 序列化对象 | string | 数据持久化 |
deserialize(str) | 反序列化 | Object | 数据恢复 |
toJsonString(obj) | 对象转JSON字符串 | string | 网络传输 |
fromJsonString(str) | JSON字符串转对象 | Object | 数据解析 |
1.1 核心特性
- 简洁易用：封装复杂逻辑为一行调用，降低使用门槛
- 类型安全：完整的TypeScript类型定义，编译期即可发现错误
- 异常处理：内置异常捕获机制，避免运行时崩溃
- 安全解析：反序列化时安全处理异常数据
1.2 序列化方法对照
| 方法 | 输入 | 输出 | 说明 |
|---|---|---|---|
| toJsonString | {name:‘张三’} | ‘{“name”:“张三”}’ | 对象→字符串 |
| fromJsonString | ‘{“name”:“张三”}’ | {name:‘张三’} | 字符串→对象 |
| serialize | 复杂对象 | 序列化字符串 | 完整序列化 |
| deserialize | 序列化字符串 | 原始对象 | 完整反序列化 |
二、完整使用步骤
2.1 安装依赖
ohpminstall@pura/harmony-utils2.2 对象序列化
import{ObjectUtil}from'@pura/harmony-utils';Button('对象序列化').width('100%').onClick(()=>{try{letobj={name:'张三',age:25,hobbies:['阅读','编程']};letjson=ObjectUtil.toJsonString(obj);this.result=`对象:${JSON.stringify(obj)}\n序列化:${json}`;}catch(e){this.result='异常: '+e;}})2.3 对象反序列化
Button('对象反序列化').width('100%').onClick(()=>{try{letjson='{"name":"张三","age":25}';letobj=ObjectUtil.fromJsonString(json);this.result=`JSON:${json}\n反序列化: name=${obj.name}, age=${obj.age}`;}catch(e){this.result='异常: '+e;}})三、完整页面示例
import{ObjectUtil}from'@pura/harmony-utils';@Entry@Componentstruct SerializeDemo{@Stateresult:string='';build(){Column({space:12}){Button('序列化').width('100%').onClick(()=>{letobj={name:'张三',age:25};this.result=ObjectUtil.toJsonString(obj);});Button('反序列化').width('100%').onClick(()=>{letjson='{"name":"李四","age":30}';letobj=ObjectUtil.fromJsonString(json)asRecord<string,Object>;this.result=`name:${obj['name']}, age:${obj['age']}`;});Text(this.result).fontSize(14).fontColor('#333333')}.padding(16)}}四、进阶用法
4.1 本地数据持久化
import{ObjectUtil,PreferencesUtil}from'@pura/harmony-utils';asyncfunctionsaveUserInfo(user:UserInfo):Promise<void>{letjson=ObjectUtil.toJsonString(user);awaitPreferencesUtil.putString('userInfo',json);}asyncfunctionloadUserInfo():Promise<UserInfo|null>{letjson=awaitPreferencesUtil.getString('userInfo');returnjson?ObjectUtil.fromJsonString(json)asUserInfo:null;}4.2 网络请求参数
functionbuildRequestParams(params:Record<string,Object>):string{returnObjectUtil.toJsonString(params);}五、注意事项
- 循环引用：序列化包含循环引用的对象会报错
- 函数属性：函数无法被JSON序列化
- 特殊值：undefined、Date等特殊值的序列化行为需注意
- 初始化依赖：使用前需确保
AppUtil.init()已调用 - 安全风险：反序列化不受信任的数据可能有安全风险
六、常见问题
Q1: 序列化Date对象后是什么格式？
Date对象序列化后为ISO 8601字符串格式。
Q2: fromJsonString解析失败会怎样？
安全解析会返回null或抛出可控异常，不会导致应用崩溃。
Q3: 可以序列化Map和Set吗？
标准JSON不支持Map/Set，需要先转换为普通对象/数组。
Q4: serialize和toJsonString有什么区别？
serialize可能支持更多类型（如Date、Map），toJsonString是标准JSON序列化。
总结
ObjectUtil的序列化和反序列化方法为数据持久化和网络传输提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些方法安全地进行对象与字符串的转换。
本文基于
@pura/harmony-utils工具库，更多功能请参考官方文档与后续系列文章。