1# URL String Parsing 2 3> **NOTE**<br> 4> 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. 5 6 7## Modules to Import 8 9``` 10import Url from '@ohos.url' 11``` 12 13## URLSearchParams 14 15 16### constructor 17 18constructor(init?: string[][] | Record<string, string> | string | URLSearchParams) 19 20Creates a **URLSearchParams** instance. 21 22**System capability**: SystemCapability.Utils.Lang 23 24**Parameters** 25 26| Name| Type| Mandatory| Description| 27| -------- | -------- | -------- | -------- | 28| 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| 29 30**Example** 31 32```js 33let objectParams = new Url.URLSearchParams([ ['user1', 'abc1'], ['query2', 'first2'], ['query3', 'second3'] ]); 34let objectParams1 = new Url.URLSearchParams({"fod" : '1' , "bard" : '2'}); 35let objectParams2 = new Url.URLSearchParams('?fod=1&bard=2'); 36let urlObject = new Url.URL('https://developer.mozilla.org/?fod=1&bard=2'); 37let params = new Url.URLSearchParams(urlObject.search); 38``` 39 40 41### append 42 43append(name: string, value: string): void 44 45Appends a key-value pair into the query string. 46 47**System capability**: SystemCapability.Utils.Lang 48 49**Parameters** 50 51| Name | Type | Mandatory | Description | 52| -------- | -------- | -------- | -------- | 53| name | string | Yes | Key of the key-value pair to append. | 54| value | string | Yes | Value of the key-value pair to append. | 55 56**Example** 57 58```js 59let urlObject = new Url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 60let paramsObject = new Url.URLSearchParams(urlObject.search.slice(1)); 61paramsObject.append('fod', '3'); 62``` 63 64 65### delete 66 67delete(name: string): void 68 69Deletes key-value pairs of the specified key. 70 71**System capability**: SystemCapability.Utils.Lang 72 73**Parameters** 74 75| Name | Type | Mandatory | Description | 76| -------- | -------- | -------- | -------- | 77| name | string | Yes | Key of the key-value pairs to delete. | 78 79**Example** 80 81```js 82let urlObject = new Url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 83let paramsobject = new Url.URLSearchParams(urlObject.search.slice(1)); 84paramsobject.delete('fod'); 85``` 86 87 88### getAll 89 90getAll(name: string): string[] 91 92Obtains all the key-value pairs based on the specified key. 93 94**System capability**: SystemCapability.Utils.Lang 95 96**Parameters** 97 98| Name | Type | Mandatory | Description | 99| -------- | -------- | -------- | -------- | 100| name | string | Yes | Key specified to obtain all key-value pairs. | 101 102**Return value** 103 104| Type | Description | 105| -------- | -------- | 106| string[] | All key-value pairs matching the specified key. | 107 108**Example** 109 110```js 111let urlObject = new Url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 112let params = new Url.URLSearchParams(urlObject.search.slice(1)); 113params.append('fod', '3'); // Add a second value for the fod parameter. 114console.log(params.getAll('fod').toString()) // Output ["1","3"]. 115``` 116 117 118### entries 119 120entries(): IterableIterator<[string, string]> 121 122Obtains 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. 123 124**System capability**: SystemCapability.Utils.Lang 125 126**Return value** 127 128| Type | Description | 129| -------- | -------- | 130| IterableIterator<[string, string]> | ES6 iterator. | 131 132**Example** 133 134```js 135let searchParamsObject = new Url.URLSearchParams("keyName1=valueName1&keyName2=valueName2"); 136for (var pair of searchParamsObject .entries()) { // Show keyName/valueName pairs 137 console.log(pair[0]+ ', '+ pair[1]); 138} 139``` 140 141 142### forEach 143 144forEach(callbackfn: (value: string, key: string, searchParams: this) => void, thisArg?: Object): void 145 146Traverses the key-value pairs in the **URLSearchParams** instance by using a callback. 147 148**System capability**: SystemCapability.Utils.Lang 149 150**Parameters** 151 152| Name | Type | Mandatory | Description | 153| -------- | -------- | -------- | -------- | 154| callbackfn | function | Yes | Callback invoked to traverse the key-value pairs in the **URLSearchParams** instance. | 155| thisArg | Object | No | Value to use when the callback is invoked. | 156 157**Table 1** callbackfn parameter description 158 159| Name | Type | Mandatory | Description | 160| -------- | -------- | -------- | -------- | 161| value | string | Yes | Value that is currently traversed. | 162| key | string | Yes | Key that is currently traversed. | 163| searchParams | Object | Yes | Instance that invokes the **forEach** method. | 164 165**Example** 166 167```js 168const myURLObject = new Url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 169myURLObject.searchParams.forEach((value, name, searchParams) => { 170 console.log(name, value, myURLObject.searchParams === searchParams); 171}); 172``` 173 174 175### get 176 177get(name: string): string | null 178 179Obtains the value of the first key-value pair based on the specified key. 180 181**System capability**: SystemCapability.Utils.Lang 182 183**Parameters** 184 185| Name | Type | Mandatory | Description | 186| -------- | -------- | -------- | -------- | 187| name | string | Yes | Key specified to obtain the value. | 188 189**Return value** 190 191| Type | Description | 192| -------- | -------- | 193| string | Returns the value of the first key-value pair if obtained. | 194| null | Returns **null** if no value is obtained.| 195 196**Example** 197 198```js 199let paramsObject = new Url.URLSearchParams('name=Jonathan&age=18'); 200let name = paramsObject.get("name"); // is the string "Jonathan" 201let age = parseInt(paramsObject.get("age"), 10); // is the number 18 202``` 203 204 205### has 206 207has(name: string): boolean 208 209Checks whether a key has a value. 210 211**System capability**: SystemCapability.Utils.Lang 212 213**Parameters** 214 215| Name | Type | Mandatory | Description | 216| -------- | -------- | -------- | -------- | 217| name | string | Yes | Key specified to search for its value. | 218 219**Return value** 220 221| Type | Description | 222| -------- | -------- | 223| boolean | Returns **true** if the value exists; returns **false** otherwise. | 224 225**Example** 226 227```js 228let urlObject = new Url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 229let paramsObject = new Url.URLSearchParams(urlObject.search.slice(1)); 230paramsObject.has('bard') === true; 231``` 232 233 234### set 235 236set(name: string, value: string): void 237 238Sets 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. 239 240**System capability**: SystemCapability.Utils.Lang 241 242**Parameters** 243 244| Name | Type | Mandatory | Description | 245| -------- | -------- | -------- | -------- | 246| name | string | Yes | Key of the value to set. | 247| value | string | Yes | Value to set. | 248 249**Example** 250 251```js 252let urlObject = new Url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 253let paramsObject = new Url.URLSearchParams(urlObject.search.slice(1)); 254paramsObject.set('baz', '3'); // Add a third parameter. 255``` 256 257 258### sort 259 260sort(): void 261 262Sorts 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. 263 264**System capability**: SystemCapability.Utils.Lang 265 266**Example** 267 268```js 269let searchParamsObject = new Url.URLSearchParams("c=3&a=9&b=4&d=2"); // Create a test URLSearchParams object 270searchParamsObject.sort(); // Sort the key/value pairs 271console.log(searchParamsObject.toString()); // Display the sorted query string // Output a=9&b=2&c=3&d=4 272``` 273 274 275### keys 276 277keys(): IterableIterator<string> 278 279Obtains an ES6 iterator that contains the keys of all the key-value pairs. 280 281**System capability**: SystemCapability.Utils.Lang 282 283**Return value** 284 285| Type | Description | 286| -------- | -------- | 287| IterableIterator<string> | ES6 iterator that contains the keys of all the key-value pairs. | 288 289**Example** 290 291```js 292let searchParamsObject = new Url.URLSearchParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing 293for (var key of searchParamsObject .keys()) { // Output key-value pairs 294 console.log(key); 295} 296``` 297 298 299### values 300 301values(): IterableIterator<string> 302 303Obtains an ES6 iterator that contains the values of all the key-value pairs. 304 305**System capability**: SystemCapability.Utils.Lang 306 307**Return value** 308 309| Type | Description | 310| -------- | -------- | 311| IterableIterator<string> | ES6 iterator that contains the values of all the key-value pairs. | 312 313**Example** 314 315```js 316let searchParams = new Url.URLSearchParams("key1=value1&key2=value2"); // Create a URLSearchParamsObject object for testing 317for (var value of searchParams.values()) { 318 console.log(value); 319} 320``` 321 322 323### [Symbol.iterator] 324 325[Symbol.iterator]\(): IterableIterator<[string, string]> 326 327Obtains 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. 328 329**System capability**: SystemCapability.Utils.Lang 330 331**Return value** 332 333| Type | Description | 334| -------- | -------- | 335| IterableIterator<[string, string]> | ES6 iterator. | 336 337**Example** 338 339```js 340const paramsObject = new Url.URLSearchParams('fod=bay&edg=bap'); 341for (const [name, value] of paramsObject) { 342 console.log(name, value); 343} 344``` 345 346 347### tostring 348 349toString(): string 350 351Obtains search parameters that are serialized as a string and, if necessary, percent-encodes the characters in the string. 352 353**System capability**: SystemCapability.Utils.Lang 354 355**Return value** 356 357| Type | Description | 358| -------- | -------- | 359| string | String of serialized search parameters, which is percent-encoded if necessary. | 360 361**Example** 362 363```js 364let url = new Url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 365let params = new Url.URLSearchParams(url.search.slice(1)); 366params.append('fod', '3'); 367console.log(params.toString()); 368``` 369 370 371## URL 372 373### Attributes 374 375**System capability**: SystemCapability.Utils.Lang 376 377| Name| Type| Readable| Writable| Description| 378| -------- | -------- | -------- | -------- | -------- | 379| hash | string | Yes| Yes| String that contains a harsh mark (#) followed by the fragment identifier of a URL.| 380| host | string | Yes| Yes| Host information in a URL.| 381| hostname | string | Yes| Yes| Hostname (without the port) in a URL.| 382| href | string | Yes| Yes| String that contains the whole URL.| 383| origin | string | Yes| No| Read-only string that contains the Unicode serialization of the origin of the represented URL.| 384| password | string | Yes| Yes| Password in a URL.| 385| pathname | string | Yes| Yes| Path in a URL.| 386| port | string | Yes| Yes| Port in a URL.| 387| protocol | string | Yes| Yes| Protocol in a URL.| 388| search | string | Yes| Yes| Serialized query string in a URL.| 389| searchParams | URLsearchParams | Yes| No| **URLSearchParams** object allowing access to the query parameters in a URL.| 390| username | string | Yes| Yes| Username in a URL.| 391 392 393### constructor 394 395constructor(url: string, base?: string | URL) 396 397Creates a URL. 398 399**System capability**: SystemCapability.Utils.Lang 400 401**Parameters** 402 403| Name | Type | Mandatory | Description | 404| -------- | -------- | -------- | -------- | 405| url | string | Yes | Input object. | 406| base | string \| URL | No| Input parameter, which can be any of the following:<br>- **string**: string<br>- **URL**: string or object| 407 408**Example** 409 410```js 411let mm = 'http://username:password@host:8080'; 412let a = new Url.URL("/", mm); // Output 'http://username:password@host:8080/'; 413let b = new Url.URL(mm); // Output 'http://username:password@host:8080/'; 414new Url.URL('path/path1', b); // Output 'http://username:password@host:8080/path/path1'; 415let c = new Url.URL('/path/path1', b); // Output 'http://username:password@host:8080/path/path1'; 416new Url.URL('/path/path1', c); // Output 'http://username:password@host:8080/path/path1'; 417new Url.URL('/path/path1', a); // Output 'http://username:password@host:8080/path/path1'; 418new Url.URL('/path/path1', "https://www.exampleUrl/fr-FR/toto"); // Output https://www.exampleUrl/path/path1 419new Url.URL('/path/path1', ''); // Raises a TypeError exception as '' is not a valid URL 420new Url.URL('/path/path1'); // Raises a TypeError exception as '/path/path1' is not a valid URL 421new Url.URL('http://www.shanxi.com', ); // Output http://www.shanxi.com/ 422new Url.URL('http://www.shanxi.com', b); // Output http://www.shanxi.com/ 423``` 424 425 426### tostring 427 428toString(): string 429 430Converts the parsed URL into a string. 431 432**System capability**: SystemCapability.Utils.Lang 433 434**Return value** 435 436| Type | Description | 437| -------- | -------- | 438| string | Website address in a serialized string. | 439 440**Example** 441 442```js 443const url = new Url.URL('http://username:password@host:8080/directory/file?query=pppppp#qwer=da'); 444url.toString(); 445``` 446 447 448### toJSON 449 450toJSON(): string 451 452Converts the parsed URL into a JSON string. 453 454**System capability**: SystemCapability.Utils.Lang 455 456**Return value** 457 458| Type | Description | 459| -------- | -------- | 460| string | Website address in a serialized string. | 461 462**Example** 463```js 464const url = new Url.URL('http://username:password@host:8080/directory/file?query=pppppp#qwer=da'); 465url.toJSON(); 466``` 467