本模块提供了将JSON文本转换为JSON对象或值,以及将对象转换为JSON文本等功能。模块基于标准JSON规范实现解析与序列化,通过Transformer机制支持自定义转换,通过BigIntMode策略解决BigInt兼容问题,并提供has/remove操作便于对解析结果进行属性查询与删除;还提供parseSendable接口将JSON文本解析为可跨线程共享的Sendable对象。
本模块首批接口从API version 12开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
type Transformer = (this: Object, key: string, value: Object) => Object | undefined | null
用于转换结果的函数类型。
作为JSON.parse函数的参数时,解析结果中的每个键值对按深度优先顺序(从最内层节点开始,逐层向外)依次调用此函数,this指向当前键值对所属的对象,返回值替换原始值,若返回undefined则该属性将被删除。
作为JSON.stringify函数的参数时,序列化引擎会按从外到内的顺序对每个属性调用该函数处理,this指向当前属性所属的对象,返回值作为序列化结果。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Utils.Lang
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| this | Object | 是 | 正在解析或序列化的键值对所属的对象。 |
| key | string | 是 | 当前正在处理的对象成员的属性名,用于在转换函数中识别所解析或序列化的键。 |
| value | Object | 是 | 正在解析或序列化的键值对的值。 |
返回值:
| 类型 | 说明 |
|---|---|
| Object | undefined | null | 返回转换处理后的属性值;返回undefined时,该属性在结果中被移除;返回null时,该属性值设为null。 |
定义处理BigInt的模式。由于JSON规范不支持BigInt类型,且Number精度范围为-(2^53-1)到(2^53-1),本模块提供三种模式以适配不同场景的整数精度需求。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Utils.Lang
| 名称 | 值 | 说明 |
|---|---|---|
| DEFAULT | 0 | 不支持BigInt,超大整数可能丢失精度。适用于不需要处理超大整数的常规JSON解析场景。 |
| PARSE_AS_BIGINT | 1 | 当整数小于-(2^53-1)或大于(2^53-1)时,解析为BigInt,普通整数仍按number处理。适用于JSON中可能包含超出安全整数范围的大整数、但普通整数不需要BigInt的场景。 |
| ALWAYS_PARSE_AS_BIGINT | 2 | 所有整数都解析为BigInt。适用于需要所有整数都以BigInt形式保留精度的场景,如高精度数值计算。 |
解析的选项,可定义处理BigInt的模式与解析返回结果的类型。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Utils.Lang
| 名称 | 类型 | 只读 | 可选 | 说明 |
|---|---|---|---|---|
| bigIntMode | BigIntMode | 否 | 否 | 定义处理BigInt的模式。 |
| parseReturnType | ParseReturnType | 否 | 是 | 定义解析返回结果的类型,省略时默认为OBJECT。仅对JSON.parseSendable生效;JSON.parse会忽略该字段。 起始版本: 26.0.1 模型约束: 此接口仅可在Stage模型下使用。 元服务API: 从API版本26.0.1开始,该接口支持在元服务中使用。 |
parse(text: string, reviver?: Transformer, options?: ParseOptions): Object | null
解析JSON字符串生成ArkTS对象或null。解析过程中,每个键值对按从最内层到最外层的顺序依次经过reviver函数处理,返回值替换原始值;当传入ParseOptions指定BigIntMode时,符合条件的整数将被解析为BigInt;当入参字符串为'null'时返回null。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Utils.Lang
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| text | string | 是 | 有效的JSON字符串,需符合JSON语法规范。 |
| reviver | Transformer | 否 | 转换函数,用于修改解析生成的原始值;当需要对解析结果进行自定义转换时使用。默认值是undefined。 |
| options | ParseOptions | 否 | 解析的配置选项,用于控制解析生成的类型。默认值是undefined。 |
返回值:
| 类型 | 说明 |
|---|---|
| Object | null | 当传入的字符串为'null'时,返回null。 |
示例:
import { JSON } from '@kit.ArkTS';
function reviverFunc(key: string, value: Object): Object | undefined | null {
if (key === "age" && typeof value === 'number') {
return value + 1;
}
return value;
}
const jsonText = '{"name": "John", "age": 30, "city": "ChongQing"}';
let parsedObj = JSON.parse(jsonText);
console.info((parsedObj as object)?.["name"]);
// 打印结果:John
const jsonTextStr = '{"name": "John", "age": 30}';
let objRst = JSON.parse(jsonTextStr, reviverFunc);
console.info((objRst as object)?.["age"]);
// 打印结果:31
const numberText = '{"number": 10, "largeNumber": 112233445566778899}';
let options: JSON.ParseOptions = { bigIntMode: JSON.BigIntMode.PARSE_AS_BIGINT };
let numberObj = JSON.parse(numberText, null, options) as Object;
console.info(typeof (numberObj as object)?.["number"]);
// 打印结果:number
console.info((numberObj as object)?.["number"]);
// 打印结果:10
console.info(typeof (numberObj as object)?.["largeNumber"]);
// 打印结果:bigint
console.info((numberObj as object)?.["largeNumber"]);
// 打印结果:112233445566778899 stringify(value: Object, replacer?: (number | string)[] | null, space?: string | number): string
该方法将一个ArkTS对象或数组转换为JSON字符串,支持线性容器的转换,不支持非线性容器(传入非线性容器时无法正确序列化)。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Utils.Lang
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | Object | 是 | ArkTS对象或数组,支持线性容器的转换,不支持非线性容器。 |
| replacer | number[] | string[] | null | 否 | 用于筛选序列化属性。当参数为string[]时,只有包含在该数组中的对象属性名才会被序列化;当参数为number[]时,只有对应索引的数组元素才会被序列化;当参数为null或者未提供时,则对象所有的属性都会被序列化。默认值是undefined。 |
| space | string | number | 否 | 指定缩进用的空格或字符串,用于美化输出。当参数是数字时表示缩进空格数,取值需为非负整数;当参数是字符串时表示缩进字符;无参数则无缩进。默认值是空字符串。 |
返回值:
| 类型 | 说明 |
|---|---|
| string | 表示对象或数组经序列化处理后生成的JSON格式文本字符串。 |
示例:
import { JSON } from '@kit.ArkTS';
interface Person {
name: string;
age: number;
city: string;
}
let person: Person = { name: "John", age: 30, city: "New York" };
let rstArrStr = JSON.stringify(person, ["name", "age"]);
console.info(rstArrStr);
// 打印结果:{"name":"John","age":30}
let rstStrSpace = JSON.stringify(person, ["name", "age"], ' ');
console.info(rstStrSpace);
/*
打印结果:
{
"name": "John",
"age": 30
}
*/
let rstStrStar = JSON.stringify(person, ["name", "age"], ' &&');
console.info(rstStrStar);
/*
打印结果:
{
&&"name": "John",
&&"age": 30
}
*/
let bigIntObj = BigInt(112233445566778899n);
console.info(JSON.stringify(bigIntObj));
// 打印结果:112233445566778899 stringify(value: Object, replacer?: Transformer, space?: string | number): string
该方法将一个ArkTS对象或数组转换为JSON字符串,支持线性容器的转换,不支持非线性容器。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Utils.Lang
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | Object | 是 | ArkTS对象或数组,支持线性容器的转换,不支持非线性容器。 |
| replacer | Transformer | 否 | 在序列化过程中,被序列化的值的每个属性都会经过该函数的转换和处理。当参数未提供时,则对象所有的属性都会被直接序列化,不经过转换处理。默认值是undefined。 |
| space | string | number | 否 | 指定缩进用的空格或字符串,用于美化输出。当参数是数字时表示缩进空格数;当参数是字符串时表示缩进字符;无参数则无缩进。默认值是空字符串。 |
返回值:
| 类型 | 说明 |
|---|---|
| string | 表示对象或数组经序列化处理后生成的JSON格式文本字符串。 |
示例:
import { JSON } from '@kit.ArkTS';
function replacer(key: string, value: Object): Object {
if (typeof value === 'string') {
return value.toUpperCase();
}
return value;
}
interface Person {
name: string;
age: number;
city: string;
}
let inputObj = {"name": "John", "age": 30, "city": "ChongQing"} as Person;
console.info(JSON.stringify(inputObj, replacer));
// 打印结果:{"name":"JOHN","age":30,"city":"CHONGQING"}
console.info(JSON.stringify(inputObj, replacer, ' '));
/*
打印结果:
{
"name": "JOHN",
"age": 30,
"city": "CHONGQING"
}
*/ has(obj: object, property: string): boolean
检查ArkTS对象是否包含某种属性,可用于JSON.parse解析JSON字符串之后。has接口仅支持最外层为字典形式(即大括号而非中括号包围)的合法JSON串,传入非字典形式的对象时无法正确判断属性是否存在。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Utils.Lang
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| obj | object | 是 | ArkTS对象,仅支持最外层为字典形式(即大括号而非中括号包围)的合法JSON串解析后的对象。 |
| property | string | 是 | 要检查的属性名称,用于指定需在ArkTS对象中查找是否存在的属性。 |
返回值:
| 类型 | 说明 |
|---|---|
| boolean | 返回ArkTS对象是否包含指定属性的结果。true表示对象包含指定属性;false表示对象不包含指定属性。 |
示例:
import { JSON } from '@kit.ArkTS';
const jsonText = '{"name": "John", "age": 30, "city": "ChongQing"}';
let inputObj = JSON.parse(jsonText);
let hasNameResult = JSON.has(inputObj, "name");
console.info("hasNameResult = " + hasNameResult);
// 打印结果:hasNameResult = true remove(obj: object, property: string): void
从ArkTS对象中删除某种属性,可用于JSON.parse解析JSON字符串之后,如清理敏感字段、移除冗余数据等场景。JSON.remove接口仅支持最外层为字典形式(即大括号而非中括号包围)的合法JSON串。
元服务API: 从API version 12开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Utils.Lang
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| obj | object | 是 | ArkTS对象,仅支持最外层为字典形式(即大括号而非中括号包围)的合法JSON串解析后的对象。 |
| property | string | 是 | 要删除的属性名称,用于指定需从ArkTS对象中移除的属性。 |
示例:
import { JSON } from '@kit.ArkTS';
const jsonText = '{"name": "John", "age": 30, "city": "ChongQing"}';
let inputObj = JSON.parse(jsonText);
JSON.remove(inputObj, "name");
let result = JSON.has(inputObj, "name");
console.info("result = " + result);
// 打印结果:result = false parseSendable(text: string, reviver?: SendableTransformer, options?: ParseOptions): ISendable | null
解析JSON字符串,生成可跨线程共享的Sendable对象。
起始版本: 26.0.1
模型约束: 此接口仅可在Stage模型下使用。
元服务API: 从API版本26.0.1开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Utils.Lang
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| text | string | 是 | 有效的JSON字符串,需符合JSON语法规范。 |
| reviver | SendableTransformer | 否 | 用于转换结果的函数。当前仅接受undefined,传入函数将抛出TypeError(与ArkTSUtils.ASON.parse一致)。默认值是undefined。 |
| options | ParseOptions | 否 | 解析的配置选项,用于控制处理BigInt的模式与解析结果的类型。也可传入仅含bigIntMode的ParseOptions对象,此时parseReturnType默认为OBJECT。默认值是undefined。 |
返回值:
| 类型 | 说明 |
|---|---|
| ISendable | null | 返回与JSON字符串对应的Sendable对象;当JSON字符串为'null'时返回null;当options.parseReturnType为ParseReturnType.MAP时返回collections.Map。 |
数字键存储规则:
OBJECT与MAP返回说明:
示例:
import { JSON, collections, lang } from '@kit.ArkTS';
// 基础用法:解析为Sendable对象,可直接跨Worker/TaskPool传递
let sendableObj: lang.ISendable | null = JSON.parseSendable('{"name": "John", "age": 30}');
console.info(`result: ${(sendableObj as object)?.["name"]}`); // 打印结果:result: John
// 86个数字键:任意数量数字键全部可访问
let parts86: string[] = [];
for (let i = 0; i < 86; i++) {
parts86.push('"' + i + '": ' + i * 2);
}
let numericObj86: lang.ISendable | null = JSON.parseSendable('{' + parts86.join(',') + '}');
console.info(`result: ${(numericObj86 as object)?.[84]}`); // 打印结果:result: 168
console.info(`result: ${(numericObj86 as object)?.[85]}`); // 打印结果:result: 170
// 1021个数字键:属性数量超过1020时仍全部可访问
let parts1021: string[] = [];
for (let i = 0; i < 1021; i++) {
parts1021.push('"' + i + '": ' + i);
}
let numericObj1021: lang.ISendable | null = JSON.parseSendable('{' + parts1021.join(',') + '}');
console.info(`result: ${(numericObj1021 as object)?.[0]}`); // 打印结果:result: 0
console.info(`result: ${(numericObj1021 as object)?.[1020]}`); // 打印结果:result: 1020
// MAP返回类型:任意条数可增删,键为字符串
let mapOptions: JSON.ParseOptions = {
bigIntMode: JSON.BigIntMode.PARSE_AS_BIGINT,
parseReturnType: JSON.ParseReturnType.MAP
};
let sendableMap: lang.ISendable | null = JSON.parseSendable('{"a": 1, "b": 2}', undefined, mapOptions);
console.info(`result: ${(sendableMap as collections.Map<string, number>).get("a")}`); // 打印结果:result: 1
// 也可传入仅含bigIntMode的ParseOptions对象(parseReturnType默认为OBJECT)
let bigOptions: JSON.ParseOptions = {
bigIntMode: JSON.BigIntMode.PARSE_AS_BIGINT
};
let bigObj: lang.ISendable | null = JSON.parseSendable('{"largeNumber":112233445566778899}', undefined, bigOptions);
console.info(`result: ${(bigObj as object)?.["largeNumber"]}`); // 打印结果:result: 112233445566778899
// reviver当前仅接受undefined
try {
JSON.parseSendable('{"a": 1}', (key: string, value: lang.ISendable): lang.ISendable | undefined => {
return value;
});
} catch (e) {
console.error(`error: ${(e as Error).message}`);
// 打印结果:error: Parameter error. Reviver only supports undefined currently.
} 定义Sendable解析结果的类型。仅对JSON.parseSendable生效;JSON.parse会忽略该字段。
起始版本: 26.0.1
模型约束: 此接口仅可在Stage模型下使用。
元服务API: 从API版本26.0.1开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Utils.Lang
| 名称 | 值 | 说明 |
|---|---|---|
| OBJECT | 0 | 解析结果为不可扩展的Sendable对象,其已有属性可更新、不可新增或删除。 |
| MAP | 1 | 解析结果为collections.Map,支持任意条数的增删操作。 |
type ISendable = lang.ISendable
ISendable是所有Sendable类型(除null和undefined)的父类型,自身不定义任何方法和属性。
起始版本: 26.0.1
模型约束: 此接口仅可在Stage模型下使用。
元服务API: 从API版本26.0.1开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Utils.Lang
| 类型 | 说明 |
|---|---|
| lang.ISendable | 所有Sendable类型的父类型。 |
type SendableTransformer = (this: ISendable, key: string, value: ISendable | undefined | null) => ISendable | undefined | null
用于Sendable JSON解析转换结果的函数类型,与ArkTSUtils.ASON.Transformer一致:this、value及返回值均为ISendable(而非Object),因为parseSendable的产物为可跨线程共享的Sendable对象。
起始版本: 26.0.1
模型约束: 此接口仅可在Stage模型下使用。
元服务API: 从API版本26.0.1开始,该接口支持在元服务中使用。
系统能力: SystemCapability.Utils.Lang
参数:
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| this | ISendable | 是 | 所解析的键值对所属的Sendable对象。 |
| key | string | 是 | 属性名。 |
| value | ISendable | undefined | null | 是 | 所解析的键值对的值。 |
返回值:
| 类型 | 说明 |
|---|---|
| ISendable | undefined | null | 返回转换处理后的ISendable对象或undefined或null。 |