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
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```ts
173// /entry/src/main/ets/pages/test.ts
174export let exportObj = {1: "John", 2: 30, 3: "New York"};
175```
176
177<!--code_no_check-->
178```ts
179import { JSON } from '@kit.ArkTS';
180import { exportObj } from './test';
181
182let arr = [1, 2];
183let rstArrStr = JSON.stringify(exportObj, arr);
184console.info(rstArrStr);
185// 打印结果："{"1":"John","2":30}"
186interface Person {
187  name: string;
188  age: number;
189  city: string;
190}
191let inputObj = {"name": "John", "age": 30, "city": "ChongQing"} as Person;
192let rstStr = JSON.stringify(inputObj, ["name"]);
193console.info(rstStr);
194// 打印结果："{"name":"John"}"
195let rstStrSpace = JSON.stringify(inputObj, ["name"], '  ');
196console.info(rstStrSpace);
197// 打印结果：
198/*
199"{
200  "name": "John"
201}"
202*/
203let rstStrStar = JSON.stringify(inputObj, ["name"], '&&');
204console.info(rstStrStar);
205// 打印结果：
206/*
207"{
208&&"name": "John"
209}"
210*/
211```
212
213
214## JSON.stringify
215
216stringify(value: Object, replacer?: Transformer, space?: string | number): string
217
218该方法将一个ArkTS对象或数组转换为JSON字符串，对于容器支持线性容器转换，非线性的容器不支持。
219
220**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
221
222**系统能力：** SystemCapability.Utils.Lang
223
224**参数：**
225
226| 参数名 | 类型 | 必填 | 说明 |
227| -------- | -------- | -------- | -------- |
228| value | Object | 是 | ArkTS对象或数组，对于容器支持线性容器转换，非线性的容器不支持。|
229| replacer | [Transformer](#transformer) | 否 | 在序列化过程中，被序列化的值的每个属性都会经过该函数的转换和处理。默认值是undefined。|
230| space | string \| number | 否 | 指定缩进用的空格或字符串或空字符串，用于美化输出。当参数是数字时表示有多少个空格；当参数是字符串时，该字符串被当作空格；当参数没有提供时，将没有空格。默认值是空字符串。|
231
232**返回值：**
233
234| 类型 | 说明 |
235| -------- | -------- |
236| string | 转换后的JSON字符串。|
237
238**错误码：**
239
240以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
241
242| 错误码ID | 错误信息 |
243| -------- | -------- |
244| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
245
246**示例：**
247```ts
248// /entry/src/main/ets/pages/test.ts
249export function replacer(key: string, value: Object): Object {
250  if (typeof value === "string") {
251    return value.toUpperCase();
252  }
253  return value;
254}
255```
256
257<!--code_no_check-->
258```ts
259import { JSON } from '@kit.ArkTS';
260import { replacer } from './test';
261
262interface Person {
263  name: string;
264  age: number;
265  city: string;
266}
267let inputObj = {"name": "John", "age": 30, "city": "ChongQing"} as Person;
268let rstStr= JSON.stringify(inputObj, replacer);
269console.info(rstStr);
270// 打印结果："{"name":"JOHN","age":30,"city":"CHONGQING"}"
271let rstStrSpace= JSON.stringify(inputObj, replacer, '  ');
272console.info(rstStrSpace);
273// 打印结果：
274/*
275"{
276  "name": "JOHN",
277  "age": 30,
278  "city": "CHONGQING"
279}"
280*/
281let rstStrSymbol= JSON.stringify(inputObj, replacer, '@@@');
282console.info(rstStrSymbol);
283// 打印结果：
284/*
285"{
286@@@"name": "JOHN",
287@@@"age": 30,
288@@@"city": "CHONGQING"
289}"
290*/
291```
292
293
294## JSON.has
295
296has(obj: object, property: string): boolean
297
298检查ArkTS对象是否包含某种属性，可用于[JSON.parse](#jsonparse)解析JSON字符串之后的相关操作。has接口仅支持最外层为字典形式（即大括号而非中括号包围）的合法json串。
299
300**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
301
302**系统能力：** SystemCapability.Utils.Lang
303
304**参数：**
305
306| 参数名 | 类型 | 必填 | 说明 |
307| -------- | -------- | -------- | -------- |
308| obj | object | 是 | ArkTS对象。|
309| property | string | 是 | 属性名。|
310
311**返回值：**
312
313| 类型 | 说明 |
314| -------- | -------- |
315| boolean | 返回ArkTS对象是否包含某种属性结果，true表示包含，false表示不包含。|
316
317**错误码：**
318
319以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
320
321| 错误码ID | 错误信息 |
322| -------- | -------- |
323| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
324
325**示例：**
326
327```ts
328import { JSON } from '@kit.ArkTS';
329
330const jsonText = '{"name": "John", "age": 30, "city": "ChongQing"}';
331let inputObj = JSON.parse(jsonText);
332let result = JSON.has(inputObj, "name");
333console.info("result = " + result);
334// 打印结果：result = true
335```
336
337
338## JSON.remove
339
340remove(obj: object, property: string): void
341
342从ArkTS对象中删除某种属性，可用于[JSON.parse](#jsonparse)解析JSON字符串之后的相关操作。remove接口仅支持最外层为字典形式（即大括号而非中括号包围）的合法json串。
343
344**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
345
346**系统能力：** SystemCapability.Utils.Lang
347
348**参数：**
349
350| 参数名 | 类型 | 必填 | 说明 |
351| -------- | -------- | -------- | -------- |
352| obj | object | 是 | ArkTS对象。|
353| property | string | 是 | 属性名。|
354
355**错误码：**
356
357以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
358
359| 错误码ID | 错误信息 |
360| -------- | -------- |
361| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
362
363**示例：**
364
365```ts
366import { JSON } from '@kit.ArkTS';
367
368const jsonText = '{"name": "John", "age": 30, "city": "ChongQing"}';
369let inputObj = JSON.parse(jsonText);
370JSON.remove(inputObj, "name");
371let result = JSON.has(inputObj, "name");
372console.info("result = " + result);
373// 打印结果：result = false
374```