1# @ohos.util.json (JSON解析与生成) 2 3本模块提供了将JSON文本转换为JSON对象或值，以及将对象转换为JSON文本等功能。 4 5>**说明：** 6> 7>本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10## 导入模块 11 12```ts 13import { JSON } from '@kit.ArkTS'; 14``` 15 16## Transformer 17 18type Transformer = (this: Object, key: string, value: Object) => Object | undefined | null 19 20用于转换结果函数的类型。<br> 21作为[JSON.parse](#jsonparse)函数的参数时，对象的每个成员将会调用此函数，允许在解析过程中对数据进行自定义处理或转换。<br> 22作为[JSON.stringify](#jsonstringify-1)函数的参数时，序列化时，每个属性都会经过该函数的转换处理。 23 24**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 25 26**系统能力：** SystemCapability.Utils.Lang 27 28**参数：** 29 30| 参数名 | 类型 | 必填 | 说明 | 31| ------ | ------ | ---- | --------------- | 32| this | Object | 是 | 在解析的键值对所属的对象。| 33| key | string | 是 | 属性名。| 34| value | Object | 是 | 在解析的键值对的值。| 35 36**返回值：** 37 38| 类型 | 说明 | 39| -------- | -------- | 40| Object \| undefined \| null | 返回修改后的对象或undefined或null。| 41 42## BigIntMode 43 44定义处理BigInt的模式。 45 46**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 47 48**系统能力：** SystemCapability.Utils.Lang 49 50| 名称 | 值| 说明 | 51| ------ | ------ | --------------- | 52| DEFAULT | 0 |不支持BigInt。| 53| PARSE_AS_BIGINT | 1 |当整数小于-(2^53-1)或大于(2^53-1)时，解析为BigInt。| 54| ALWAYS_PARSE_AS_BIGINT | 2 |所有整数都解析为BigInt。| 55 56## ParseOptions 57 58解析的选项，可定义处理BigInt的模式。 59 60**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 61 62**系统能力：** SystemCapability.Utils.Lang 63 64| 名称 | 类型| 必填 |说明 | 65| ------ | ------ | ---- | --------------- | 66| bigIntMode | [BigIntMode](#bigintmode) | 是 |定义处理BigInt的模式。| 67 68## JSON.parse 69 70parse(text: string, reviver?: Transformer, options?: ParseOptions): Object | null 71 72解析JSON字符串生成ArkTS对象或null。 73 74**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 75 76**系统能力：** SystemCapability.Utils.Lang 77 78**参数：** 79 80| 参数名 | 类型 | 必填 | 说明 | 81| ------ | ------ | ---- | --------------- | 82| text | string | 是 | 有效的JSON字符串。| 83| reviver | [Transformer](#transformer) | 否 | 转换函数，传入该参数，可以用来修改解析生成的原始值。默认值是undefined。| 84| options | [ParseOptions](#parseoptions) | 否 | 解析的配置，传入该参数，可以用来控制解析生成的类型。默认值是undefined。| 85 86**返回值：** 87 88| 类型 | 说明 | 89| -------- | -------- | 90| Object \| null | 返回ArkTS对象或null。当入参是null时，返回null。| 91 92**错误码：** 93 94以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 95 96| 错误码ID | 错误信息 | 97| -------- | -------- | 98| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 99 100**示例：** 101<!--code_no_check--> 102```ts 103// /entry/src/main/ets/pages/test.ts 104export function reviverFunc(key, value) { 105 if (key === "age") { 106 return value + 1; 107 } 108 return value; 109} 110``` 111 112<!--code_no_check--> 113```ts 114import { JSON } from '@kit.ArkTS'; 115import { reviverFunc } from './test'; 116 117let jsonText = '{"name": "John", "age": 30, "city": "ChongQing"}'; 118let obj = JSON.parse(jsonText); 119console.info((obj as object)?.["name"]); 120// 打印结果：John 121const jsonTextStr = '{"name": "John", "age": 30}'; 122let objRst = JSON.parse(jsonTextStr, reviverFunc); 123console.info((objRst as object)?.["age"]); 124// 打印结果：31 125let options: JSON.ParseOptions = { 126 bigIntMode: JSON.BigIntMode.PARSE_AS_BIGINT, 127} 128let numberText = '{"largeNumber":112233445566778899}'; 129let numberObj = JSON.parse(numberText,(key: string, value: Object | undefined | null): Object | undefined | null => { 130 if(key === "largeNumber") return value; 131 return value; 132},options) as Object; 133 134console.info((numberObj as object)?.["largeNumber"]); 135// 打印结果: 112233445566778899 136``` 137 138 139## JSON.stringify 140 141stringify(value: Object, replacer?: (number | string)[] | null, space?: string | number): string 142 143该方法将一个ArkTS对象或数组转换为JSON字符串，支持线性容器的转换，不支持非线性容器。 144 145**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 146 147**系统能力：** SystemCapability.Utils.Lang 148 149**参数：** 150 151| 参数名 | 类型 | 必填 | 说明 | 152| -------- | -------- | -------- | -------- | 153| value | Object | 是 | ArkTS对象或数组。支持线性容器转换，非线性容器不支持。| 154| replacer | number[] \| string[] \| null | 否 | 当参数是数组时，只有包含在这个数组中的属性名才会被序列化到最终的JSON字符串中；当参数为null或者未提供时，则对象所有的属性都会被序列化。默认值是undefined。| 155| space | string \| number | 否 | 指定缩进用的空格或字符串，用于美化输出。当参数是数字时表示缩进空格数；当参数是字符串时表示缩进字符；无参数则无缩进。默认值是空字符串。| 156 157**返回值：** 158 159| 类型 | 说明 | 160| -------- | -------- | 161| string | 转换后的JSON字符串。| 162 163**错误码：** 164 165以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 166 167| 错误码ID | 错误信息 | 168| -------- | -------- | 169| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 170 171**示例：** 172<!--code_no_check--> 173```ts 174// /entry/src/main/ets/pages/test.ts 175export let exportObj = {1: "John", 2: 30, 3: "New York"}; 176``` 177 178<!--code_no_check--> 179```ts 180import { JSON } from '@kit.ArkTS'; 181import { exportObj } from './test'; 182 183let arr = [1, 2]; 184let rstArrStr = JSON.stringify(exportObj, arr); 185console.info(rstArrStr); 186// 打印结果："{"1":"John","2":30}" 187interface Person { 188 name: string; 189 age: number; 190 city: string; 191} 192let inputObj = {"name": "John", "age": 30, "city": "ChongQing"} as Person; 193let rstStr = JSON.stringify(inputObj, ["name"]); 194console.info(rstStr); 195// 打印结果："{"name":"John"}" 196let rstStrSpace = JSON.stringify(inputObj, ["name"], ' '); 197console.info(rstStrSpace); 198// 打印结果： 199/* 200"{ 201 "name": "John" 202}" 203*/ 204let rstStrStar = JSON.stringify(inputObj, ["name"], '&&'); 205console.info(rstStrStar); 206// 打印结果： 207/* 208"{ 209&&"name": "John" 210}" 211*/ 212``` 213 214 215## JSON.stringify 216 217stringify(value: Object, replacer?: Transformer, space?: string | number): string 218 219该方法将一个ArkTS对象或数组转换为JSON字符串，对于容器支持线性容器转换，非线性的容器不支持。 220 221**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 222 223**系统能力：** SystemCapability.Utils.Lang 224 225**参数：** 226 227| 参数名 | 类型 | 必填 | 说明 | 228| -------- | -------- | -------- | -------- | 229| value | Object | 是 | ArkTS对象或数组，对于容器支持线性容器转换，非线性的容器不支持。| 230| replacer | [Transformer](#transformer) | 否 | 在序列化过程中，被序列化的值的每个属性都会经过该函数的转换和处理。默认值是undefined。| 231| space | string \| number | 否 | 指定缩进用的空格或字符串或空字符串，用于美化输出。当参数是数字时表示有多少个空格；当参数是字符串时，该字符串被当作空格；当参数没有提供时，将没有空格。默认值是空字符串。| 232 233**返回值：** 234 235| 类型 | 说明 | 236| -------- | -------- | 237| string | 转换后的JSON字符串。| 238 239**错误码：** 240 241以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 242 243| 错误码ID | 错误信息 | 244| -------- | -------- | 245| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 246 247**示例：** 248```ts 249// /entry/src/main/ets/pages/test.ts 250export function replacer(key: string, value: Object): Object { 251 if (typeof value === "string") { 252 return value.toUpperCase(); 253 } 254 return value; 255} 256``` 257 258<!--code_no_check--> 259```ts 260import { JSON } from '@kit.ArkTS'; 261import { replacer } from './test'; 262 263interface Person { 264 name: string; 265 age: number; 266 city: string; 267} 268let inputObj = {"name": "John", "age": 30, "city": "ChongQing"} as Person; 269let rstStr= JSON.stringify(inputObj, replacer); 270console.info(rstStr); 271// 打印结果："{"name":"JOHN","age":30,"city":"CHONGQING"}" 272let rstStrSpace= JSON.stringify(inputObj, replacer, ' '); 273console.info(rstStrSpace); 274// 打印结果： 275/* 276"{ 277 "name": "JOHN", 278 "age": 30, 279 "city": "CHONGQING" 280}" 281*/ 282let rstStrSymbol= JSON.stringify(inputObj, replacer, '@@@'); 283console.info(rstStrSymbol); 284// 打印结果： 285/* 286"{ 287@@@"name": "JOHN", 288@@@"age": 30, 289@@@"city": "CHONGQING" 290}" 291*/ 292``` 293 294 295## JSON.has 296 297has(obj: object, property: string): boolean 298 299检查ArkTS对象是否包含某种属性，可用于[JSON.parse](#jsonparse)解析JSON字符串之后的相关操作。has接口仅支持最外层为字典形式（即大括号而非中括号包围）的合法json串。 300 301**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 302 303**系统能力：** SystemCapability.Utils.Lang 304 305**参数：** 306 307| 参数名 | 类型 | 必填 | 说明 | 308| -------- | -------- | -------- | -------- | 309| obj | object | 是 | ArkTS对象。| 310| property | string | 是 | 属性名。| 311 312**返回值：** 313 314| 类型 | 说明 | 315| -------- | -------- | 316| boolean | 返回ArkTS对象是否包含某种属性结果。true表示包含，false表示不包含。| 317 318**错误码：** 319 320以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 321 322| 错误码ID | 错误信息 | 323| -------- | -------- | 324| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 325 326**示例：** 327 328```ts 329import { JSON } from '@kit.ArkTS'; 330 331const jsonText = '{"name": "John", "age": 30, "city": "ChongQing"}'; 332let inputObj = JSON.parse(jsonText); 333let result = JSON.has(inputObj, "name"); 334console.info("result = " + result); 335// 打印结果：result = true 336``` 337 338 339## JSON.remove 340 341remove(obj: object, property: string): void 342 343从ArkTS对象中删除某种属性，可用于[JSON.parse](#jsonparse)解析JSON字符串之后的相关操作。remove接口仅支持最外层为字典形式（即大括号而非中括号包围）的合法json串。 344 345**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 346 347**系统能力：** SystemCapability.Utils.Lang 348 349**参数：** 350 351| 参数名 | 类型 | 必填 | 说明 | 352| -------- | -------- | -------- | -------- | 353| obj | object | 是 | ArkTS对象。| 354| property | string | 是 | 属性名。| 355 356**错误码：** 357 358以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 359 360| 错误码ID | 错误信息 | 361| -------- | -------- | 362| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 363 364**示例：** 365 366```ts 367import { JSON } from '@kit.ArkTS'; 368 369const jsonText = '{"name": "John", "age": 30, "city": "ChongQing"}'; 370let inputObj = JSON.parse(jsonText); 371JSON.remove(inputObj, "name"); 372let result = JSON.has(inputObj, "name"); 373console.info("result = " + result); 374// 打印结果：result = false 375```