• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# ArkTSUtils.ASON
2<!--Kit: ArkTS-->
3<!--Subsystem: CommonLibrary-->
4<!--Owner: @lijiamin2025-->
5<!--Designer: @weng-changcheng-->
6<!--Tester: @kirl75; @zsw_zhushiwei-->
7<!--Adviser: @ge-yafang-->
8
9为支持将JSON字符串解析为共享数据，即[Sendable支持的数据类型](../../arkts-utils/arkts-sendable.md#sendable支持的数据类型)，ArkTS语言基础库新增了ASON工具。ASON工具支持解析JSON字符串并生成共享数据，用于跨并发实例引用传递，同时也支持将共享数据转换为JSON字符串。
10
11> **说明：**
12>
13> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
14>
15> 此模块仅支持在ArkTS文件（文件后缀为.ets）中导入使用。
16
17## 导入模块
18
19```ts
20import { ArkTSUtils } from '@kit.ArkTS'
21```
22
23## ISendable
24
25type ISendable = lang.ISendable
26
27ISendable是所有Sendable类型（除`null`和`undefined`）的父类型。自身没有任何必须的方法和属性。
28
29**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
30
31**系统能力：** SystemCapability.Utils.Lang
32
33| 类型 | 说明   |
34| ------ | ------ |
35| [lang.ISendable](js-apis-arkts-lang.md#langisendable)   | 所有Sendable类型的父类型。 |
36
37## Transformer
38
39type Transformer = (this: ISendable, key: string, value: ISendable | undefined | null) => ISendable | undefined | null
40
41用于转换结果函数的类型。
42
43**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
44
45**系统能力：** SystemCapability.Utils.Lang
46
47**参数：**
48
49| 参数名 | 类型   | 必填 | 说明            |
50| ------ | ------ | ---- | --------------- |
51| this   | [ISendable](#isendable) | 是 | 在解析的键值对所属的对象。|
52| key  | string | 是 | 属性名。|
53| value  | [ISendable](#isendable) \| undefined \| null| 是 | 在解析的键值对的值。|
54
55**返回值：**
56
57| 类型 | 说明 |
58| -------- | -------- |
59| [ISendable](#isendable) \| undefined \| null | 返回转换结果后的ISendable对象或undefined或null。|
60
61## BigIntMode
62
63定义处理BigInt的模式。
64
65**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
66
67**系统能力：** SystemCapability.Utils.Lang
68
69| 名称 | 值| 说明            |
70| ------ | ------ | --------------- |
71| DEFAULT   | 0 |不支持BigInt。|
72| PARSE_AS_BIGINT   | 1 |当整数小于-(2^53-1)或大于(2^53-1)时，解析为BigInt。|
73| ALWAYS_PARSE_AS_BIGINT   | 2 |所有整数都解析为BigInt。|
74
75## ParseReturnType
76
77定义解析结果的返回类型。
78
79**系统能力：** SystemCapability.Utils.Lang
80
81| 名称 | 值| 说明            |
82| ------ | ------ | --------------- |
83| OBJECT   | 0 |返回 SendableObject 对象。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。|
84| MAP<sup>13+</sup>   | 1 |返回 SendableMap 对象。<br>**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。|
85
86## ParseOptions
87
88解析的选项，可定义处理BigInt的模式和解析结果的返回类型。
89
90**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
91
92**系统能力：** SystemCapability.Utils.Lang
93
94| 名称 | 类型| 必填 | 说明            |
95| ------ | ------ | ---- | --------------- |
96| bigIntMode   | [BigIntMode](#bigintmode) | 是 |定义处理BigInt的模式。|
97| parseReturnType   | [ParseReturnType](#parsereturntype) | 是 |定义解析结果的返回类型。|
98
99## parse
100
101parse(text: string, reviver?: Transformer, options?: ParseOptions): ISendable | null
102
103用于解析JSON字符串生成ISendable数据或null。
104
105**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
106
107**系统能力：** SystemCapability.Utils.Lang
108
109**参数：**
110
111| 参数名 | 类型   | 必填 | 说明            |
112| ------ | ------ | ---- | --------------- |
113| text   | string | 是 | 有效的JSON字符串。|
114| reviver   | [Transformer](#transformer) | 否 | 转换函数，传入该参数，可以用来修改解析生成的原始值。默认值是undefined。目前只支持传入undefined。|
115| options   | [ParseOptions](#parseoptions) | 否 | 解析的配置，传入该参数，可以用来控制解析生成的结果类型。默认值是undefined。|
116
117**返回值：**
118
119| 类型 | 说明 |
120| -------- | -------- |
121| [ISendable](#isendable) \| null | 返回ISendable数据或null。入参为null时，返回null。|
122
123**错误码：**
124
125以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
126
127| 错误码ID | 错误信息      |
128| -------- | ------------- |
129| 401      | Parameter error. Invalid JSON string. |
130
131**示例：**
132
133```ts
134import { lang } from '@kit.ArkTS';
135import { collections } from '@kit.ArkTS';
136
137type ISendable = lang.ISendable;
138let jsonText = '{"name": "John", "age": 30, "city": "ChongQing"}';
139let obj = ArkTSUtils.ASON.parse(jsonText) as ISendable;
140console.info((obj as object)?.["name"]);
141// 期望输出: 'John'
142console.info((obj as object)?.["age"]);
143// 期望输出: 30
144console.info((obj as object)?.["city"]);
145// 期望输出: 'ChongQing'
146
147let options: ArkTSUtils.ASON.ParseOptions = {
148  bigIntMode: ArkTSUtils.ASON.BigIntMode.PARSE_AS_BIGINT,
149  parseReturnType: ArkTSUtils.ASON.ParseReturnType.OBJECT,
150}
151let numberText = '{"largeNumber":112233445566778899}';
152let numberObj = ArkTSUtils.ASON.parse(numberText,undefined,options) as ISendable;
153
154console.info((numberObj as object)?.["largeNumber"]);
155// 期望输出: 112233445566778899
156
157let options2: ArkTSUtils.ASON.ParseOptions = {
158    bigIntMode: ArkTSUtils.ASON.BigIntMode.PARSE_AS_BIGINT,
159    parseReturnType: ArkTSUtils.ASON.ParseReturnType.MAP,
160  }
161let mapText = '{"largeNumber":112233445566778899}';
162let map  = ArkTSUtils.ASON.parse(mapText,undefined,options2);
163console.info("map is " + map);
164// 期望输出: map is [object SendableMap]
165console.info("largeNumber is " + (map as collections.Map<string,bigint>).get("largeNumber"));
166// 期望输出: largeNumber is 112233445566778899
167```
168
169## stringify
170
171stringify(value: Object | null | undefined): string
172
173该方法将ArkTS对象数据转换为JSON字符串，额外支持Map和Set相关类型。
174
175> **说明：**
176>
177> 从API 18开始参数修改为Object类型，API 18之前参数只支持ISendable类型（除[Int8Array](arkts-apis-arkts-collections-Int8Array.md)、[Uint8Array](arkts-apis-arkts-collections-Uint8Array.md)、[Int16Array](arkts-apis-arkts-collections-Int16Array.md)、[Uint16Array](arkts-apis-arkts-collections-Uint16Array.md)、[Int32Array](arkts-apis-arkts-collections-Int32Array.md)、[Uint32Array](arkts-apis-arkts-collections-Uint32Array.md)、[Uint8ClampedArray](arkts-apis-arkts-collections-Uint8ClampedArray.md)、[Float32Array](arkts-apis-arkts-collections-Float32Array.md)外）。
178
179**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
180
181**系统能力：** SystemCapability.Utils.Lang
182
183**参数：**
184
185| 参数名 | 类型 | 必填 | 说明 |
186| -------- | -------- | -------- | -------- |
187| value | Object \| null \| undefined  | 是 | ArkTS对象数据。|
188
189**返回值：**
190
191| 类型 | 说明 |
192| -------- | -------- |
193| string | 转换后的JSON字符串。|
194
195**错误码：**
196
197以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
198
199| 错误码ID | 错误信息      |
200| -------- | ------------- |
201| 401      | Parameter error. Invalid ArkTS value. |
202
203**示例：**
204
205```ts
206import { ArkTSUtils, collections, HashMap, HashSet } from '@kit.ArkTS';
207
208let hashMap = new HashMap<string,string>();
209hashMap.set("ha","a");
210hashMap.set("sh","b");
211hashMap.set("map","c");
212let str1 = ArkTSUtils.ASON.stringify(hashMap);
213console.info(str1);
214//期望输出：'{"sh":"b","ha":"a","map":"c"}'
215let hashSet = new HashSet<string>();
216hashSet.add("ha");
217hashSet.add("sh");
218hashSet.add("set");
219let str2 = ArkTSUtils.ASON.stringify(hashSet);
220console.info(str2);
221//期望输出：'["set","sh","ha"]'
222let map = new Map<string,string>();
223map.set("m","a");
224map.set("a","b");
225map.set("p","c");
226let str3 = ArkTSUtils.ASON.stringify(map);
227console.info(str3);
228//期望输出：'{"m":"a","a":"b","p":"c"}'
229let set = new Set<string>();
230set.add("s");
231set.add("e");
232set.add("t");
233let str4 = ArkTSUtils.ASON.stringify(set);
234console.info(str4);
235//期望输出：'["s","e","t"]'
236let sendableMap = new collections.Map<string,string>();
237sendableMap.set("send","a");
238sendableMap.set("able","b");
239sendableMap.set("map","c");
240let str5 = ArkTSUtils.ASON.stringify(sendableMap);
241console.info(str5);
242//期望输出：'{"send":"a","able":"b","map":"c"}'
243let sendableSet = new collections.Set<string>();
244sendableSet.add("send");
245sendableSet.add("able");
246sendableSet.add("set");
247let str6 = ArkTSUtils.ASON.stringify(sendableSet);
248console.info(str6);
249//期望输出：'["send","able","set"]'
250```