1# @ohos.url (URL String Parsing)
2
3The **url** module provides APIs for parsing URL strings and constructing [URL](#url) instances to process URL strings.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9## Modules to Import
10
11```ts
12import { url } from '@kit.ArkTS';
13```
14## URLParams<sup>9+</sup>
15
16Defines APIs for handling URL query strings.
17
18### constructor<sup>9+</sup>
19
20constructor(init?: string[][] | Record&lt;string, string&gt; | string | URLParams)
21
22A constructor used to create a **URLParams** instance.
23
24**Atomic service API**: This API can be used in atomic services since API version 11.
25
26**System capability**: SystemCapability.Utils.Lang
27
28**Parameters**
29
30| Name| Type| Mandatory| Description|
31| -------- | -------- | -------- | -------- |
32| init | string[][] \| Record&lt;string, string&gt; \| string \| URLParams | No| Input parameter objects, which include the following:<br>- **string[][]**: two-dimensional string array<br>- **Record&lt;string, string&gt;**: list of objects<br>- **string**: string<br>- **URLParams**: object<br>The default value is **null**.|
33
34**Error codes**
35
36For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
37
38| ID| Error Message|
39| -------- | -------- |
40| 401 | Parameter error. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. |
41
42**Example**
43
44```ts
45// Construct a URLParams object in string[][] mode.
46let objectParams = new url.URLParams([ ['user1', 'abc1'], ['query2', 'first2'], ['query3', 'second3'] ]);
47// Construct a URLParams object in Record<string, string> mode.
48let objectParams1 = new url.URLParams({"fod" : '1' , "bard" : '2'});
49// Construct a URLParams object in string mode.
50let objectParams2 = new url.URLParams('?fod=1&bard=2');
51// Construct a URLParams object using the search attribute of the url object.
52let urlObject = url.URL.parseURL('https://developer.mozilla.org/?fod=1&bard=2');
53let objectParams3 = new url.URLParams(urlObject.search);
54// Construct a URLParams object using the params attribute of the url object.
55let urlObject1 = url.URL.parseURL('https://developer.mozilla.org/?fod=1&bard=2');
56let objectParams4 = urlObject1.params;
57```
58
59
60### append<sup>9+</sup>
61
62append(name: string, value: string): void
63
64Appends a key-value pair into the query string.
65
66**Atomic service API**: This API can be used in atomic services since API version 11.
67
68**System capability**: SystemCapability.Utils.Lang
69
70**Parameters**
71
72| Name| Type| Mandatory| Description|
73| -------- | -------- | -------- | -------- |
74| name | string | Yes| Key of the key-value pair to append.|
75| value | string | Yes| Value of the key-value pair to append.|
76
77**Error codes**
78
79For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
80
81| ID| Error Message|
82| -------- | -------- |
83| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
84
85**Example**
86
87```ts
88let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
89let paramsObject = new url.URLParams(urlObject.search.slice(1));
90paramsObject.append('fod', '3');
91```
92
93
94### delete<sup>9+</sup>
95
96delete(name: string): void
97
98Deletes key-value pairs of the specified key.
99
100**Atomic service API**: This API can be used in atomic services since API version 11.
101
102**System capability**: SystemCapability.Utils.Lang
103
104**Parameters**
105
106| Name| Type| Mandatory| Description|
107| -------- | -------- | -------- | -------- |
108| name | string | Yes| Key of the key-value pairs to delete.|
109
110**Error codes**
111
112For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
113
114| ID| Error Message|
115| -------- | -------- |
116| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
117
118**Example**
119
120```ts
121let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
122let paramsObject = new url.URLParams(urlObject.search.slice(1));
123paramsObject.delete('fod');
124```
125
126
127### getAll<sup>9+</sup>
128
129getAll(name: string): string[]
130
131Obtains all the values based on the specified key.
132
133**Atomic service API**: This API can be used in atomic services since API version 11.
134
135**System capability**: SystemCapability.Utils.Lang
136
137**Parameters**
138
139| Name| Type| Mandatory| Description|
140| -------- | -------- | -------- | -------- |
141| name | string | Yes| Target key.|
142
143**Return value**
144
145| Type| Description|
146| -------- | -------- |
147| string[] | All the values obtained.|
148
149**Error codes**
150
151For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
152
153| ID| Error Message|
154| -------- | -------- |
155| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
156
157**Example**
158
159```ts
160let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
161let params = new url.URLParams(urlObject.search.slice(1));
162params.append('fod', '3'); // Add a second value for the fod parameter.
163console.log(params.getAll('fod').toString()) // Output ["1","3"].
164```
165
166
167### entries<sup>9+</sup>
168
169entries(): IterableIterator<[string, string]>
170
171Obtains an ES6 iterator. Each item of the iterator is a JavaScript array, and the first and second fields of each array are the key and value respectively.
172
173**Atomic service API**: This API can be used in atomic services since API version 11.
174
175**System capability**: SystemCapability.Utils.Lang
176
177**Return value**
178
179| Type| Description|
180| -------- | -------- |
181| IterableIterator&lt;[string, string]&gt; | ES6 iterator.|
182
183**Example**
184
185```ts
186let searchParamsObject = new url.URLParams("keyName1=valueName1&keyName2=valueName2");
187let pair:Iterable<Object[]> = searchParamsObject.entries();
188let arrayValue = Array.from(pair);
189for (let pair of arrayValue) { // Show keyName/valueName pairs
190  console.log(pair[0]+ ', '+ pair[1]);
191}
192```
193
194
195### forEach<sup>9+</sup>
196
197forEach(callbackFn: (value: string, key: string, searchParams: URLParams) => void, thisArg?: Object): void
198
199Traverses the key-value pairs in the **URLSearchParams** instance by using a callback.
200
201**Atomic service API**: This API can be used in atomic services since API version 11.
202
203**System capability**: SystemCapability.Utils.Lang
204
205**Parameters**
206
207| Name| Type| Mandatory| Description|
208| -------- | -------- | -------- | -------- |
209| callbackFn | function | Yes| Callback invoked to traverse the key-value pairs in the **URLSearchParams** instance.|
210| thisArg | Object | No| Value of **this** to use when **callbackFn** is invoked. The default value is this object.|
211
212**Table 1** callbackFn parameter description
213
214| Name| Type| Mandatory| Description|
215| -------- | -------- | -------- | -------- |
216| value | string | Yes| Value that is currently traversed.|
217| key | string | Yes| Key that is currently traversed.|
218| searchParams | [URLParams](#urlparams9) | Yes| Instance that invokes the **forEach** method.|
219
220**Error codes**
221
222For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
223
224| ID| Error Message|
225| -------- | -------- |
226| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
227
228**Example**
229
230```ts
231const myURLObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
232myURLObject.params.forEach((value, name, searchParams) => {
233    console.log(name, value, myURLObject.params === searchParams);
234});
235```
236
237
238### get<sup>9+</sup>
239
240get(name: string): string | null
241
242Obtains the value of the first key-value pair based on the specified key.
243
244> **NOTE**
245>
246> If the key-value pair does not exist, **undefined** is returned.
247
248**Atomic service API**: This API can be used in atomic services since API version 11.
249
250**System capability**: SystemCapability.Utils.Lang
251
252**Parameters**
253
254| Name| Type| Mandatory| Description|
255| -------- | -------- | -------- | -------- |
256| name | string | Yes| Key specified to obtain the value.|
257
258**Return value**
259
260| Type| Description|
261| -------- | -------- |
262| string | Returns the value of the first key-value pair if obtained.|
263| null | Returns **null** if no value is obtained.|
264
265**Error codes**
266
267For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
268
269| ID| Error Message|
270| -------- | -------- |
271| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
272
273**Example**
274
275```ts
276let paramsObject = new url.URLParams('name=Jonathan&age=18');
277let name = paramsObject.get("name"); // is the string "Jonathan"
278let age = paramsObject.get("age"); // is the string "18"
279let getObj = paramsObject.get("abc"); // undefined
280```
281
282
283### has<sup>9+</sup>
284
285has(name: string): boolean
286
287Checks whether a key has a value.
288
289**Atomic service API**: This API can be used in atomic services since API version 11.
290
291**System capability**: SystemCapability.Utils.Lang
292
293**Parameters**
294
295| Name| Type| Mandatory| Description|
296| -------- | -------- | -------- | -------- |
297| name | string | Yes| Key specified to search for its value.|
298
299**Return value**
300
301| Type| Description|
302| -------- | -------- |
303| boolean | Returns **true** if the value exists; returns **false** otherwise.|
304
305**Error codes**
306
307For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
308
309| ID| Error Message|
310| -------- | -------- |
311| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
312
313**Example**
314
315```ts
316let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
317let paramsObject = new url.URLParams(urlObject.search.slice(1));
318let result = paramsObject.has('bard');
319```
320
321
322### set<sup>9+</sup>
323
324set(name: string, value: string): void
325
326Sets the value for a key. If key-value pairs matching the specified key exist, the value of the first key-value pair will be set to the specified value and other key-value pairs will be deleted. Otherwise, the key-value pair will be appended to the query string.
327
328**Atomic service API**: This API can be used in atomic services since API version 11.
329
330**System capability**: SystemCapability.Utils.Lang
331
332**Parameters**
333
334| Name| Type| Mandatory| Description|
335| -------- | -------- | -------- | -------- |
336| name | string | Yes| Key of the value to set.|
337| value | string | Yes| Value to set.|
338
339**Error codes**
340
341For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
342
343| ID| Error Message|
344| -------- | -------- |
345| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
346
347**Example**
348
349```ts
350let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
351let paramsObject = new url.URLParams(urlObject.search.slice(1));
352paramsObject.set('baz', '3'); // Add a third parameter.
353```
354
355
356### sort<sup>9+</sup>
357
358sort(): void
359
360Sorts all key-value pairs contained in this object based on the Unicode code points of the keys and returns undefined.  This method uses a stable sorting algorithm, that is, the relative order between key-value pairs with equal keys is retained.
361
362**Atomic service API**: This API can be used in atomic services since API version 11.
363
364**System capability**: SystemCapability.Utils.Lang
365
366**Example**
367
368```ts
369let searchParamsObject = new url.URLParams("c=3&a=9&b=4&d=2"); // Create a test URLSearchParams object
370searchParamsObject.sort(); // Sort the key/value pairs
371console.log(searchParamsObject.toString()); // Display the sorted query string // Output a=9&b=4&c=3&d=2
372```
373
374
375### keys<sup>9+</sup>
376
377keys(): IterableIterator&lt;string&gt;
378
379Obtains an ES6 iterator that contains the keys of all the key-value pairs.
380
381**Atomic service API**: This API can be used in atomic services since API version 11.
382
383**System capability**: SystemCapability.Utils.Lang
384
385**Return value**
386
387| Type| Description|
388| -------- | -------- |
389| IterableIterator&lt;string&gt; | ES6 iterator that contains the keys of all the key-value pairs.|
390
391**Example**
392
393```ts
394let searchParamsObject = new url.URLParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing
395let keys = Array.from(searchParamsObject.keys());
396for (let key of keys) { // Output key-value pairs
397  console.log(key);
398}
399```
400
401
402### values<sup>9+</sup>
403
404values(): IterableIterator&lt;string&gt;
405
406Obtains an ES6 iterator that contains the values of all the key-value pairs.
407
408**Atomic service API**: This API can be used in atomic services since API version 11.
409
410**System capability**: SystemCapability.Utils.Lang
411
412**Return value**
413
414| Type| Description|
415| -------- | -------- |
416| IterableIterator&lt;string&gt; | ES6 iterator that contains the values of all the key-value pairs.|
417
418**Example**
419
420```ts
421let searchParams = new url.URLParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing
422let values = Array.from(searchParams.values());
423for (let value of values) {
424  console.log(value);
425}
426```
427
428
429### [Symbol.iterator]<sup>9+</sup>
430
431[Symbol.iterator]\(): IterableIterator&lt;[string, string]&gt;
432
433Obtains an ES6 iterator. Each item of the iterator is a JavaScript array, and the first and second fields of each array are the key and value respectively.
434
435**Atomic service API**: This API can be used in atomic services since API version 11.
436
437**System capability**: SystemCapability.Utils.Lang
438
439**Return value**
440
441| Type| Description|
442| -------- | -------- |
443| IterableIterator&lt;[string, string]&gt; | ES6 iterator.|
444
445**Example**
446
447```ts
448const paramsObject = new url.URLParams('fod=bay&edg=bap');
449let iter: Iterable<Object[]> = paramsObject[Symbol.iterator]();
450let pairs = Array.from(iter);
451for (let pair of pairs) {
452  console.log(pair[0] + ', ' + pair[1]);
453}
454```
455
456
457### toString<sup>9+</sup>
458
459toString(): string
460
461Obtains search parameters that are serialized as a string and, if necessary, percent-encodes the characters in the string.
462
463**Atomic service API**: This API can be used in atomic services since API version 11.
464
465**System capability**: SystemCapability.Utils.Lang
466
467**Return value**
468
469| Type| Description|
470| -------- | -------- |
471| string | String of serialized search parameters, which is percent-encoded if necessary.|
472
473**Example**
474
475```ts
476let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2');
477let params = new url.URLParams(urlObject.search.slice(1));
478params.append('fod', '3');
479console.log(params.toString()); // Output 'fod=1&bard=2&fod=3'
480```
481
482## URL
483
484Provides APIs for parsing, constructing, standardizing, and encoding URL strings.
485
486### Attributes
487
488**System capability**: SystemCapability.Utils.Lang
489
490| Name| Type| Readable| Writable| Description|
491| -------- | -------- | -------- | -------- | -------- |
492| hash | string | Yes| Yes| String that contains a harsh mark (#) followed by the fragment identifier of a URL. **Atomic service API**: This API can be used in atomic services since API version 11.|
493| host | string | Yes| Yes| Host information in a URL. **Atomic service API**: This API can be used in atomic services since API version 11.|
494| hostname | string | Yes| Yes| Hostname (without the port) in a URL. **Atomic service API**: This API can be used in atomic services since API version 11.|
495| href | string | Yes| Yes| String that contains the whole URL. **Atomic service API**: This API can be used in atomic services since API version 11.|
496| origin | string | Yes| No| Read-only string that contains the Unicode serialization of the origin of the represented URL. **Atomic service API**: This API can be used in atomic services since API version 11.|
497| password | string | Yes| Yes| Password in a URL. **Atomic service API**: This API can be used in atomic services since API version 11.|
498| pathname | string | Yes| Yes| Path in a URL. **Atomic service API**: This API can be used in atomic services since API version 11.|
499| port | string | Yes| Yes| Port in a URL. **Atomic service API**: This API can be used in atomic services since API version 11.|
500| protocol | string | Yes| Yes| Protocol in a URL. **Atomic service API**: This API can be used in atomic services since API version 11.|
501| search | string | Yes| Yes| Serialized query string in a URL. **Atomic service API**: This API can be used in atomic services since API version 11.|
502| searchParams<sup>(deprecated)</sup> | [URLSearchParams](#urlsearchparamsdeprecated) | Yes| No| **URLSearchParams** object allowing access to the query parameters in a URL.<br>- **NOTE**: This attribute is supported since API version 7 and is deprecated since API version 9. You are advised to use params<sup>9+</sup> instead.|
503| params<sup>9+</sup> | [URLParams](#urlparams9) | Yes| No| **URLParams** object allowing access to the query parameters in a URL. **Atomic service API**: This API can be used in atomic services since API version 11.|
504| username | string | Yes| Yes| Username in a URL. **Atomic service API**: This API can be used in atomic services since API version 11.|
505
506**Example**
507
508```ts
509let that = url.URL.parseURL('http://username:password@host:8080/directory/file?foo=1&bar=2#fragment');
510console.log("hash " + that.hash) // hash #fragment
511console.log("host " + that.host) // host host:8080
512console.log("hostname " + that.hostname) // hostname host
513console.log("href " + that.href) // href http://username:password@host:8080/directory/file?foo=1&bar=2#fragment
514console.log("origin " + that.origin) // origin http://host:8080
515console.log("password " + that.password) // password password
516console.log("pathname " + that.pathname) // pathname /directory/file
517console.log("port " + that.port) // port 8080
518console.log("protocol " + that.protocol) // protocol http:
519console.log("search " + that.search) // search ?foo=1&bar=2
520console.log("username " + that.username) // username username
521// The return value of that.params is a URLParams object.
522console.log("params: foo " + that.params.get("foo")) // params: foo 1
523```
524
525### constructor<sup>(deprecated)</sup>
526
527> **NOTE**
528>
529> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [parseURL<sup>9+</sup>](#parseurl9) instead.
530
531constructor(url: string, base?: string | URL)
532
533Creates a URL.
534
535**System capability**: SystemCapability.Utils.Lang
536
537**Parameters**
538
539| Name| Type| Mandatory| Description|
540| -------- | -------- | -------- | -------- |
541| url | string | Yes| A string representing an absolute or a relative URL.<br>In the case of a relative URL, you must specify **base** to parse the final URL.<br>In the case of an absolute URL, the passed **base** will be ignored.|
542| base | string \| URL | No| Either a string or an object. The default value is **undefined**.<br>- **string**: string<br>- **URL**: a URL object<br>- This parameter is used when **url** is a relative URL.|
543
544**Example**
545
546```ts
547let mm = 'https://username:password@host:8080';
548let a = new url.URL("/", mm); // Output 'https://username:password@host:8080/';
549let b = new url.URL(mm); // Output 'https://username:password@host:8080/';
550new url.URL('path/path1', b); // Output 'https://username:password@host:8080/path/path1';
551let c = new url.URL('/path/path1', b);  // Output 'https://username:password@host:8080/path/path1';
552new url.URL('/path/path1', c); // Output 'https://username:password@host:8080/path/path1';
553new url.URL('/path/path1', a); // Output 'https://username:password@host:8080/path/path1';
554new url.URL('/path/path1', "https://www.exampleUrl/fr-FR/toot"); // Output https://www.exampleUrl/path/path1
555new url.URL('/path/path1', ''); // Raises a TypeError exception as '' is not a valid URL
556new url.URL('/path/path1'); // Raises a TypeError exception as '/path/path1' is not a valid URL
557new url.URL('https://www.example.com', ); // Output https://www.example.com/
558new url.URL('https://www.example.com', b); // Output https://www.example.com/
559```
560
561### constructor<sup>9+</sup>
562
563constructor()
564
565A no-argument constructor used to create a URL. It returns a **URL** object after **parseURL** is called. It is not used independently.
566
567**Atomic service API**: This API can be used in atomic services since API version 11.
568
569**System capability**: SystemCapability.Utils.Lang
570
571### parseURL<sup>9+</sup>
572
573static parseURL(url: string, base?: string | URL): URL
574
575Parses a URL.
576
577**Atomic service API**: This API can be used in atomic services since API version 11.
578
579**System capability**: SystemCapability.Utils.Lang
580
581**Parameters**
582
583| Name| Type| Mandatory| Description|
584| -------- | -------- | -------- | -------- |
585| url | string | Yes| A string representing an absolute or a relative URL.<br>In the case of a relative URL, you must specify **base** to parse the final URL.<br>In the case of an absolute URL, the passed **base** will be ignored.|
586| base | string \| URL | No| Either a string or an object. The default value is **undefined**.<br>- **string**: string<br>- **URL**: a URL object<br>- This parameter is used when **url** is a relative URL.|
587
588> **NOTE**
589>
590> If **url** is a relative URL, the URL parsed by calling this API is not merely a concatenation of **url** and **base**. When **url** is a relative path, it is parsed relative to the current directory of the passed **base**, taking into account all path segments before the last slash in the path of **base**, but excluding the following part (see example url1). When **url** points to a root directory, it is parsed relative to the origin of **base** (see example url2).
591
592**Error codes**
593
594For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Utils Error Codes](errorcode-utils.md).
595
596| ID| Error Message|
597| -------- | -------- |
598| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. |
599| 10200002 | Invalid url string. |
600
601**Example**
602
603```ts
604let mm = 'https://username:password@host:8080/test/test1/test3';
605let urlObject = url.URL.parseURL(mm);
606let result = urlObject.toString(); // Output 'https://username:password@host:8080/test/test1/test3'
607// If url is a relative path, the path in the base parameter is test/test1, and the path of the parsed URL is /test/path2/path3.
608let url1 = url.URL.parseURL('path2/path3', 'https://www.huawei.com/test/test1'); // Output 'https://www.huawei.com/test/path2/path3'
609// If url is a root directory, the path in the base parameter is /test/test1/test3, and the path of the parsed URL is /path1/path2.
610let url2 = url.URL.parseURL('/path1/path2', urlObject); // Output 'https://username:password@host:8080/path1/path2'
611url.URL.parseURL('/path/path1', "https://www.exampleUrl/fr-FR/toot"); // Output 'https://www.exampleUrl/path/path1'
612url.URL.parseURL('/path/path1', ''); // Raises a TypeError exception as '' is not a valid URL
613url.URL.parseURL('/path/path1'); // Raises a TypeError exception as '/path/path1' is not a valid URL
614url.URL.parseURL('https://www.example.com', ); // Output 'https://www.example.com/'
615url.URL.parseURL('https://www.example.com', urlObject); // Output 'https://www.example.com/'
616```
617
618### toString
619
620toString(): string
621
622Converts the parsed URL into a string.
623
624**Atomic service API**: This API can be used in atomic services since API version 11.
625
626**System capability**: SystemCapability.Utils.Lang
627
628**Return value**
629
630| Type| Description|
631| -------- | -------- |
632| string | Website address in a serialized string.|
633
634**Example**
635
636```ts
637const urlObject = url.URL.parseURL('https://username:password@host:8080/directory/file?query=pppppp#qwer=da');
638let result = urlObject.toString(); // Output 'https://username:password@host:8080/directory/file?query=pppppp#qwer=da'
639```
640
641### toJSON
642
643toJSON(): string
644
645Converts the parsed URL into a JSON string.
646
647**Atomic service API**: This API can be used in atomic services since API version 11.
648
649**System capability**: SystemCapability.Utils.Lang
650
651**Return value**
652
653| Type| Description|
654| -------- | -------- |
655| string | Website address in a serialized string.|
656
657**Example**
658```ts
659const urlObject = url.URL.parseURL('https://username:password@host:8080/directory/file?query=pppppp#qwer=da');
660let result = urlObject.toJSON();
661```
662
663## URLSearchParams<sup>(deprecated)</sup>
664
665Defines APIs for handling URL query strings.
666
667This class is deprecated since API version 9. You are advised to use [URLParams](#urlparams9) instead.
668
669### constructor<sup>(deprecated)</sup>
670
671constructor(init?: string[][] | Record&lt;string, string&gt; | string | URLSearchParams)
672
673A constructor used to create a **URLSearchParams** instance.
674
675> **NOTE**
676>
677> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [URLParams.constructor<sup>9+</sup>](#constructor9) instead.
678
679**System capability**: SystemCapability.Utils.Lang
680
681**Parameters**
682
683| Name| Type| Mandatory| Description|
684| -------- | -------- | -------- | -------- |
685| init | string[][] \| Record&lt;string, string&gt; \| string \| URLSearchParams | No| Input parameter objects, which include the following:<br>- **string[][]**: two-dimensional string array<br>- **Record&lt;string, string&gt;**: list of objects<br>- **string**: string<br>- **URLSearchParams**: object<br>The default value is **null**.|
686
687**Example**
688
689```ts
690let objectParams = new url.URLSearchParams([ ['user1', 'abc1'], ['query2', 'first2'], ['query3', 'second3'] ]);
691let objectParams1 = new url.URLSearchParams({"fod" : '1' , "bard" : '2'});
692let objectParams2 = new url.URLSearchParams('?fod=1&bard=2');
693let urlObject = new url.URL('https://developer.mozilla.org/?fod=1&bard=2');
694let params = new url.URLSearchParams(urlObject.search);
695```
696
697### append<sup>(deprecated)</sup>
698
699append(name: string, value: string): void
700
701Appends a key-value pair into the query string.
702
703> **NOTE**
704>
705> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [URLParams.append<sup>9+</sup>](#append9) instead.
706
707**System capability**: SystemCapability.Utils.Lang
708
709**Parameters**
710
711| Name| Type| Mandatory| Description|
712| -------- | -------- | -------- | -------- |
713| name | string | Yes| Key of the key-value pair to append.|
714| value | string | Yes| Value of the key-value pair to append.|
715
716**Example**
717
718```ts
719let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2');
720let paramsObject = new url.URLSearchParams(urlObject.search.slice(1));
721paramsObject.append('fod', '3');
722```
723
724### delete<sup>(deprecated)</sup>
725
726delete(name: string): void
727
728Deletes key-value pairs of the specified key.
729
730> **NOTE**
731>
732> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [URLParams.delete<sup>9+</sup>](#delete9) instead.
733
734**System capability**: SystemCapability.Utils.Lang
735
736**Parameters**
737
738| Name| Type| Mandatory| Description|
739| -------- | -------- | -------- | -------- |
740| name | string | Yes| Key of the key-value pairs to delete.|
741
742**Example**
743
744```ts
745let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2');
746let paramsObject = new url.URLSearchParams(urlObject.search.slice(1));
747paramsObject.delete('fod');
748```
749
750### getAll<sup>(deprecated)</sup>
751
752getAll(name: string): string[]
753
754Obtains all the key-value pairs based on the specified key.
755
756> **NOTE**
757>
758> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [URLParams.getAll<sup>9+</sup>](#getall9) instead.
759
760**System capability**: SystemCapability.Utils.Lang
761
762**Parameters**
763
764| Name| Type| Mandatory| Description|
765| -------- | -------- | -------- | -------- |
766| name | string | Yes| Target key.|
767
768**Return value**
769
770| Type| Description|
771| -------- | -------- |
772| string[] | All key-value pairs matching the specified key.|
773
774**Example**
775
776```ts
777let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2');
778let params = new url.URLSearchParams(urlObject.search.slice(1));
779params.append('fod', '3'); // Add a second value for the fod parameter.
780console.log(params.getAll('fod').toString()) // Output ["1","3"].
781```
782
783### entries<sup>(deprecated)</sup>
784
785entries(): IterableIterator<[string, string]>
786
787Obtains an ES6 iterator. Each item of the iterator is a JavaScript array, and the first and second fields of each array are the key and value respectively.
788
789> **NOTE**
790>
791> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [URLParams.entries<sup>9+</sup>](#entries9) instead.
792
793**System capability**: SystemCapability.Utils.Lang
794
795**Return value**
796
797| Type| Description|
798| -------- | -------- |
799| IterableIterator&lt;[string, string]&gt; | ES6 iterator.|
800
801**Example**
802
803```ts
804let searchParamsObject = new url.URLSearchParams("keyName1=valueName1&keyName2=valueName2");
805let iter: Iterable<Object[]> = searchParamsObject.entries();
806let pairs = Array.from(iter);
807for (let pair of pairs) { // Show keyName/valueName pairs
808  console.log(pair[0]+ ', '+ pair[1]);
809}
810```
811
812
813### forEach<sup>(deprecated)</sup>
814
815forEach(callbackFn: (value: string, key: string, searchParams: URLSearchParams) => void, thisArg?: Object): void
816
817Traverses the key-value pairs in the **URLSearchParams** instance by using a callback.
818
819> **NOTE**
820>
821> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [URLParams.forEach<sup>9+</sup>](#foreach9) instead.
822
823**System capability**: SystemCapability.Utils.Lang
824
825**Parameters**
826
827| Name| Type| Mandatory| Description|
828| -------- | -------- | -------- | -------- |
829| callbackFn | function | Yes| Callback invoked to traverse the key-value pairs in the **URLSearchParams** instance.|
830| thisArg | Object | No| Value of **this** to use when **callbackFn** is invoked. The default value is this object.|
831
832**Table 1** callbackFn parameter description
833
834| Name| Type| Mandatory| Description|
835| -------- | -------- | -------- | -------- |
836| value | string | Yes| Value that is currently traversed.|
837| key | string | Yes| Key that is currently traversed.|
838| searchParams | [URLSearchParams](#urlsearchparamsdeprecated) | Yes| Instance that invokes the **forEach** method.|
839
840**Example**
841
842```ts
843const myURLObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2');
844myURLObject.searchParams.forEach((value, name, searchParams) => {
845    console.log(name, value, myURLObject.searchParams === searchParams);
846});
847```
848
849
850### get<sup>(deprecated)</sup>
851
852get(name: string): string | null
853
854Obtains the value of the first key-value pair based on the specified key.
855
856> **NOTE**
857>
858> If the key-value pair does not exist, **undefined** is returned.
859> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [URLParams.get<sup>9+</sup>](#get9) instead.
860
861
862**System capability**: SystemCapability.Utils.Lang
863
864**Parameters**
865
866| Name| Type| Mandatory| Description|
867| -------- | -------- | -------- | -------- |
868| name | string | Yes| Key specified to obtain the value.|
869
870**Return value**
871
872| Type| Description|
873| -------- | -------- |
874| string | Returns the value of the first key-value pair if obtained.|
875| null | Returns **null** if no value is obtained.|
876
877**Example**
878
879```ts
880let paramsObject = new url.URLSearchParams('name=Jonathan&age=18');
881let name = paramsObject.get("name"); // is the string "Jonathan"
882let age = paramsObject.get("age"); // is the string '18'
883let getObj = paramsObject.get("abc"); // undefined
884```
885
886
887### has<sup>(deprecated)</sup>
888
889has(name: string): boolean
890
891Checks whether a key has a value.
892
893> **NOTE**
894>
895> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [URLParams.has<sup>9+</sup>](#has9) instead.
896
897**System capability**: SystemCapability.Utils.Lang
898
899**Parameters**
900
901| Name| Type| Mandatory| Description|
902| -------- | -------- | -------- | -------- |
903| name | string | Yes| Key specified to search for its value.|
904
905**Return value**
906
907| Type| Description|
908| -------- | -------- |
909| boolean | Returns **true** if the value exists; returns **false** otherwise.|
910
911**Example**
912
913```ts
914let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2');
915let paramsObject = new url.URLSearchParams(urlObject.search.slice(1));
916paramsObject.has('bard') === true;
917```
918
919
920### set<sup>(deprecated)</sup>
921
922set(name: string, value: string): void
923
924Sets the value for a key. If key-value pairs matching the specified key exist, the value of the first key-value pair will be set to the specified value and other key-value pairs will be deleted. Otherwise, the key-value pair will be appended to the query string.
925
926> **NOTE**
927>
928> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [URLParams.set<sup>9+</sup>](#set9) instead.
929
930**System capability**: SystemCapability.Utils.Lang
931
932**Parameters**
933
934| Name| Type| Mandatory| Description|
935| -------- | -------- | -------- | -------- |
936| name | string | Yes| Key of the value to set.|
937| value | string | Yes| Value to set.|
938
939**Example**
940
941```ts
942let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2');
943let paramsObject = new url.URLSearchParams(urlObject.search.slice(1));
944paramsObject.set('baz', '3'); // Add a third parameter.
945```
946
947
948### sort<sup>(deprecated)</sup>
949
950sort(): void
951
952Sorts all key-value pairs contained in this object based on the Unicode code points of the keys and returns undefined.  This method uses a stable sorting algorithm, that is, the relative order between key-value pairs with equal keys is retained.
953
954> **NOTE**
955>
956> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [URLParams.sort<sup>9+</sup>](#sort9) instead.
957
958**System capability**: SystemCapability.Utils.Lang
959
960**Example**
961
962```ts
963let searchParamsObject = new url.URLSearchParams("c=3&a=9&b=4&d=2"); // Create a test URLSearchParams object
964searchParamsObject.sort(); // Sort the key/value pairs
965console.log(searchParamsObject.toString()); // Display the sorted query string // Output a=9&b=4&c=3&d=2
966```
967
968
969### keys<sup>(deprecated)</sup>
970
971keys(): IterableIterator&lt;string&gt;
972
973Obtains an ES6 iterator that contains the keys of all the key-value pairs.
974
975> **NOTE**
976>
977> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [URLParams.keys<sup>9+</sup>](#keys9) instead.
978
979**System capability**: SystemCapability.Utils.Lang
980
981**Return value**
982
983| Type| Description|
984| -------- | -------- |
985| IterableIterator&lt;string&gt; | ES6 iterator that contains the keys of all the key-value pairs.|
986
987**Example**
988
989```ts
990let searchParamsObject = new url.URLSearchParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing
991let keys = Array.from(searchParamsObject.keys());
992for (let key of keys) { // Output key-value pairs
993  console.log(key);
994}
995```
996
997
998### values<sup>(deprecated)</sup>
999
1000values(): IterableIterator&lt;string&gt;
1001
1002Obtains an ES6 iterator that contains the values of all the key-value pairs.
1003
1004> **NOTE**
1005>
1006> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [URLParams.values<sup>9+</sup>](#values9) instead.
1007
1008**System capability**: SystemCapability.Utils.Lang
1009
1010**Return value**
1011
1012| Type| Description|
1013| -------- | -------- |
1014| IterableIterator&lt;string&gt; | ES6 iterator that contains the values of all the key-value pairs.|
1015
1016**Example**
1017
1018```ts
1019let searchParams = new url.URLSearchParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing
1020let values = Array.from(searchParams.values());
1021for (let value of values) {
1022  console.log(value);
1023}
1024```
1025
1026
1027### [Symbol.iterator]<sup>(deprecated)</sup>
1028
1029[Symbol.iterator]\(): IterableIterator&lt;[string, string]&gt;
1030
1031Obtains an ES6 iterator. Each item of the iterator is a JavaScript array, and the first and second fields of each array are the key and value respectively.
1032
1033> **NOTE**
1034>
1035> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [URLParams.[Symbol.iterator]<sup>9+</sup>](#symboliterator9) instead.
1036
1037**System capability**: SystemCapability.Utils.Lang
1038
1039**Return value**
1040
1041| Type| Description|
1042| -------- | -------- |
1043| IterableIterator&lt;[string, string]&gt; | ES6 iterator.|
1044
1045**Example**
1046
1047```ts
1048const paramsObject = new url.URLSearchParams('fod=bay&edg=bap');
1049let iter: Iterable<Object[]> = paramsObject[Symbol.iterator]();
1050let pairs = Array.from(iter);
1051for (let pair of pairs) {
1052  console.log(pair[0] + ', ' + pair[1]);
1053}
1054```
1055
1056### toString<sup>(deprecated)</sup>
1057
1058toString(): string
1059
1060Obtains search parameters that are serialized as a string and, if necessary, percent-encodes the characters in the string.
1061
1062> **NOTE**
1063>
1064> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [URLParams.toString<sup>9+</sup>](#tostring9) instead.
1065
1066**System capability**: SystemCapability.Utils.Lang
1067
1068**Return value**
1069
1070| Type| Description|
1071| -------- | -------- |
1072| string | String of serialized search parameters, which is percent-encoded if necessary.|
1073
1074**Example**
1075
1076```ts
1077let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2');
1078let params = new url.URLSearchParams(urlObject.search.slice(1));
1079params.append('fod', '3');
1080console.log(params.toString()); // Output 'fod=1&bard=2&fod=3'
1081```
1082<!--no_check-->
1083