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<string, string> | 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<string, string> \| string \| URLParams | No| Input parameter objects, which include the following:<br>- **string[][]**: two-dimensional string array<br>- **Record<string, string>**: 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<[string, string]> | 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<string> 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<string> | 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<string> 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<string> | 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<[string, string]> 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<[string, string]> | 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<string, string> | 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<string, string> \| string \| URLSearchParams | No| Input parameter objects, which include the following:<br>- **string[][]**: two-dimensional string array<br>- **Record<string, string>**: 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<[string, string]> | 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<string> 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<string> | 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<string> 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<string> | 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<[string, string]> 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<[string, string]> | 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