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