1# @ohos.url (URL字符串解析) 2<!--Kit: ArkTS--> 3<!--Subsystem: CommonLibrary--> 4<!--Owner: @xliu-huanwei; @shilei123; @huanghello--> 5<!--Designer: @yuanyao14--> 6<!--Tester: @kirl75; @zsw_zhushiwei--> 7<!--Adviser: @ge-yafang--> 8 9URL代表的是统一资源定位符，本模块提供了常用的工具函数，实现了解析URL字符串和构造[URL](#url)对象等功能。 10 11> **说明：** 12> 13> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15## 导入模块 16 17```ts 18import { url } from '@kit.ArkTS'; 19``` 20## URLParams<sup>9+</sup> 21 22URLParams是一个用于解析、构造和操作URL参数的实用类。该类提供了统一的接口来处理参数维度（如查询参数、路径参数等）。 23 24### constructor<sup>9+</sup> 25 26constructor(init?: string[][] | Record<string, string> | string | URLParams) 27 28URLParams的构造函数。 29 30**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 31 32**系统能力：** SystemCapability.Utils.Lang 33 34**参数：** 35 36| 参数名 | 类型 | 必填 | 说明 | 37| -------- | -------- | -------- | -------- | 38| init | string[][] \| Record<string, string> \| string \| URLParams | 否 | 入参对象。<br/>- string[][]：字符串二维数组。<br/>- Record<string, string>：对象列表。<br/>- string：字符串。<br/>- URLParams：对象。<br/>- 默认值：null。 | 39 40**错误码：** 41 42以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 43 44| 错误码ID | 错误信息 | 45| -------- | -------- | 46| 401 | Parameter error. Possible causes: 1.Incorrect parameter types; 2.Parameter verification failed. | 47 48**示例：** 49 50```ts 51// 通过string[][]方式构造URLParams对象： 52let objectParams = new url.URLParams([ ['user1', 'abc1'], ['query2', 'first2'], ['query3', 'second3'] ]); 53// 通过Record<string, string>方式构造URLParams对象： 54let objectParams1 = new url.URLParams({"fod" : '1' , "bard" : '2'}); 55// 通过string方式构造URLParams对象： 56let objectParams2 = new url.URLParams('?fod=1&bard=2'); 57// 通过url对象的search属性构造URLParams对象： 58let urlObject = url.URL.parseURL('https://developer.mozilla.org/?fod=1&bard=2'); 59let objectParams3 = new url.URLParams(urlObject.search); 60// 通过url对象的params属性获取URLParams对象： 61let urlObject1 = url.URL.parseURL('https://developer.mozilla.org/?fod=1&bard=2'); 62let objectParams4 = urlObject1.params; 63``` 64 65 66### append<sup>9+</sup> 67 68append(name: string, value: string): void 69 70将新的键值对插入到查询字符串。 71 72**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 73 74**系统能力：** SystemCapability.Utils.Lang 75 76**参数：** 77 78| 参数名 | 类型 | 必填 | 说明 | 79| -------- | -------- | -------- | -------- | 80| name | string | 是 | 需要插入搜索参数的键名。 | 81| value | string | 是 | 需要插入搜索参数的值。 | 82 83**错误码：** 84 85以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 86 87| 错误码ID | 错误信息 | 88| -------- | -------- | 89| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 90 91**示例：** 92 93```ts 94let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2'); 95let paramsObject = new url.URLParams(urlObject.search.slice(1)); 96paramsObject.append('fod', '3'); 97``` 98 99 100### delete<sup>9+</sup> 101 102delete(name: string): void 103 104删除指定名称的键值对。 105 106**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 107 108**系统能力：** SystemCapability.Utils.Lang 109 110**参数：** 111 112| 参数名 | 类型 | 必填 | 说明 | 113| -------- | -------- | -------- | -------- | 114| name | string | 是 | 需要删除的键值名称。 | 115 116**错误码：** 117 118以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 119 120| 错误码ID | 错误信息 | 121| -------- | -------- | 122| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 123 124**示例：** 125 126```ts 127let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2'); 128let paramsObject = new url.URLParams(urlObject.search.slice(1)); 129paramsObject.delete('fod'); 130``` 131 132 133### getAll<sup>9+</sup> 134 135getAll(name: string): string[] 136 137获取指定名称的所有键对应值的集合。 138 139**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 140 141**系统能力：** SystemCapability.Utils.Lang 142 143**参数：** 144 145| 参数名 | 类型 | 必填 | 说明 | 146| -------- | -------- | -------- | -------- | 147| name | string | 是 | 指定的键值名称。 | 148 149**返回值：** 150 151| 类型 | 说明 | 152| -------- | -------- | 153| string[] | 返回指定名称的所有键对应值的集合。 | 154 155**错误码：** 156 157以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 158 159| 错误码ID | 错误信息 | 160| -------- | -------- | 161| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 162 163**示例：** 164 165```ts 166let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2'); 167let params = new url.URLParams(urlObject.search.slice(1)); 168params.append('fod', '3'); // Add a second value for the fod parameter. 169console.info(params.getAll('fod').toString()) // Output ["1","3"]. 170``` 171 172 173### entries<sup>9+</sup> 174 175entries(): IterableIterator<[string, string]> 176 177返回一个ES6的迭代器，迭代器的每一项都是一个Array。Array的第一项是name，Array的第二项是value。 178 179**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 180 181**系统能力：** SystemCapability.Utils.Lang 182 183**返回值：** 184 185| 类型 | 说明 | 186| -------- | -------- | 187| IterableIterator<[string, string]> | 返回一个ES6的迭代器。 | 188 189**示例：** 190 191```ts 192let paramsObject = new url.URLParams("keyName1=valueName1&keyName2=valueName2"); 193let pair = paramsObject.entries(); 194for (let item of pair) { 195 console.info(item[0] + '=' + item[1]); 196} 197// keyName1=valueName1 198// keyName2=valueName2 199``` 200 201 202### forEach<sup>9+</sup> 203 204forEach(callbackFn: (value: string, key: string, searchParams: URLParams) => void, thisArg?: Object): void 205 206通过回调函数来遍历URLSearchParams实例对象上的键值对。 207 208**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 209 210**系统能力：** SystemCapability.Utils.Lang 211 212**参数：** 213 214| 参数名 | 类型 | 必填 | 说明 | 215| -------- | -------- | -------- | -------- | 216| callbackFn | function | 是 | 回调函数。 | 217| thisArg | Object | 否 | callbackFn被调用时用作this值，默认值是本对象。 | 218 219**表1** callbackFn的参数说明 220 221| 参数名 | 类型 | 必填 | 说明 | 222| -------- | -------- | -------- | -------- | 223| value | string | 是 | 当前遍历到的键值。 | 224| key | string | 是 | 当前遍历到的键名。 | 225| searchParams | [URLParams](#urlparams9) | 是 | 当前调用forEach方法的实例对象。 | 226 227**错误码：** 228 229以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 230 231| 错误码ID | 错误信息 | 232| -------- | -------- | 233| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 234 235**示例：** 236 237```ts 238const myURLObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2'); 239myURLObject.params.forEach((value, name, searchParams) => { 240 console.info(name, value, myURLObject.params === searchParams); 241}); 242``` 243 244 245### get<sup>9+</sup> 246 247get(name: string): string | null 248 249获取指定名称对应的第一个值。 250 251> **说明：** 252> 253> 若查找一个不存在的键值对名称时返回值为undefined。 254 255**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 256 257**系统能力：** SystemCapability.Utils.Lang 258 259**参数：** 260 261| 参数名 | 类型 | 必填 | 说明 | 262| -------- | -------- | -------- | -------- | 263| name | string | 是 | 指定键值对的名称。 | 264 265**返回值：** 266 267| 类型 | 说明 | 268| -------- | -------- | 269| string \| null | 返回第一个值，如果没找到，返回 null。 | 270 271**错误码：** 272 273以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 274 275| 错误码ID | 错误信息 | 276| -------- | -------- | 277| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 278 279**示例：** 280 281```ts 282let paramsObject = new url.URLParams('name=Jonathan&age=18'); 283let name = paramsObject.get("name"); // is the string "Jonathan" 284let age = paramsObject.get("age"); // is the string "18" 285let getObj = paramsObject.get("abc"); // undefined 286``` 287 288 289### has<sup>9+</sup> 290 291has(name: string): boolean 292 293判断一个指定的键名对应的值是否存在。 294 295**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 296 297**系统能力：** SystemCapability.Utils.Lang 298 299**参数：** 300 301| 参数名 | 类型 | 必填 | 说明 | 302| -------- | -------- | -------- | -------- | 303| name | string | 是 | 要查找的参数的键名。 | 304 305**返回值：** 306 307| 类型 | 说明 | 308| -------- | -------- | 309| boolean | 是否存在相对应的key值，存在返回true，否则返回false。 | 310 311**错误码：** 312 313以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 314 315| 错误码ID | 错误信息 | 316| -------- | -------- | 317| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 318 319**示例：** 320 321```ts 322let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2'); 323let paramsObject = new url.URLParams(urlObject.search.slice(1)); 324let result = paramsObject.has('bard'); 325``` 326 327 328### set<sup>9+</sup> 329 330set(name: string, value: string): void 331 332将与name关联的URLSearchParams对象中的值设置为value。 333 334如果存在名称为name的键值对，请将第一个键值对的值设置为value并删除所有其他值。如果不是，则将键值对附加到查询字符串。 335 336**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 337 338**系统能力：** SystemCapability.Utils.Lang 339 340**参数：** 341 342| 参数名 | 类型 | 必填 | 说明 | 343| -------- | -------- | -------- | -------- | 344| name | string | 是 | 将要设置的参数的键值名。 | 345| value | string | 是 | 所要设置的参数值。 | 346 347**错误码：** 348 349以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 350 351| 错误码ID | 错误信息 | 352| -------- | -------- | 353| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 354 355**示例：** 356 357```ts 358let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2'); 359let paramsObject = new url.URLParams(urlObject.search.slice(1)); 360paramsObject.set('baz', '3'); // Add a third parameter. 361``` 362 363 364### sort<sup>9+</sup> 365 366sort(): void 367 368对包含在此对象中的所有键值对进行排序。排序顺序是根据键的Unicode代码点。该方法使用稳定的排序算法（保留具有相等键的键值对之间的相对顺序）。 369 370**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 371 372**系统能力：** SystemCapability.Utils.Lang 373 374**示例：** 375 376```ts 377let paramsObject = new url.URLParams("c=3&a=9&b=4&d=2"); // Create a test URLParams object 378paramsObject.sort(); // Sort the key/value pairs 379console.info(paramsObject.toString()); // Display the sorted query string // Output a=9&b=4&c=3&d=2 380``` 381 382 383### keys<sup>9+</sup> 384 385keys(): IterableIterator<string> 386 387返回一个包含所有键值对的name的ES6迭代器。 388 389**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 390 391**系统能力：** SystemCapability.Utils.Lang 392 393**返回值：** 394 395| 类型 | 说明 | 396| -------- | -------- | 397| IterableIterator<string> | 返回一个包含所有键值对的name的ES6迭代器。 | 398 399**示例：** 400 401```ts 402let paramsObject = new url.URLParams("key1=value1&key2=value2"); 403let keys = paramsObject.keys(); 404for (let key of keys) { 405 console.info(key); 406} 407// key1 408// key2 409``` 410 411 412### values<sup>9+</sup> 413 414values(): IterableIterator<string> 415 416返回一个包含所有键值对的value的ES6迭代器。 417 418**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 419 420**系统能力：** SystemCapability.Utils.Lang 421 422**返回值：** 423 424| 类型 | 说明 | 425| -------- | -------- | 426| IterableIterator<string> | 返回一个包含所有键值对的value的ES6迭代器。 | 427 428**示例：** 429 430```ts 431let paramsObject = new url.URLParams("key1=value1&key2=value2"); 432let values = paramsObject.values(); 433for (let value of values) { 434 console.info(value); 435} 436// value1 437// value2 438``` 439 440 441### [Symbol.iterator]<sup>9+</sup> 442 443[Symbol.iterator]\(): IterableIterator<[string, string]> 444 445返回一个ES6的迭代器，迭代器的每一项都是一个Array。Array的第一项是name，Array的第二项是value。 446 447**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 448 449**系统能力：** SystemCapability.Utils.Lang 450 451**返回值：** 452 453| 类型 | 说明 | 454| -------- | -------- | 455| IterableIterator<[string, string]> | 返回一个ES6的迭代器。 | 456 457**示例：** 458 459```ts 460const paramsObject = new url.URLParams('fod=bay&edg=bap'); 461let iter = paramsObject[Symbol.iterator](); 462for (let pair of iter) { 463 console.info(pair[0] + ', ' + pair[1]); 464} 465// fod, bay 466// edg, bap 467``` 468 469 470### toString<sup>9+</sup> 471 472toString(): string 473 474返回序列化为字符串的搜索参数，必要时对字符进行百分比编码。 475 476**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 477 478**系统能力：** SystemCapability.Utils.Lang 479 480**返回值：** 481 482| 类型 | 说明 | 483| -------- | -------- | 484| string | 返回序列化为字符串的搜索参数，必要时对字符进行百分比编码。 | 485 486**示例：** 487 488```ts 489let urlObject = url.URL.parseURL('https://developer.exampleUrl/?fod=1&bard=2'); 490let params = new url.URLParams(urlObject.search.slice(1)); 491params.append('fod', '3'); 492console.info(params.toString()); // Output 'fod=1&bard=2&fod=3' 493``` 494 495## URL 496 497用于解析、构造、规范、编码对应的URL字符串。 498 499### 属性 500 501**系统能力：** SystemCapability.Utils.Lang 502 503| 名称 | 类型 | 只读 | 可选 | 说明 | 504| -------- | -------- | -------- | -------- | -------- | 505| hash | string | 否 | 否 | 获取和设置URL的片段部分。**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 506| host | string | 否 | 否 | 获取和设置URL的主机部分。**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 507| hostname | string | 否 | 否 | 获取和设置URL的主机名部分，不带端口。**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 508| href | string | 否 | 否 | 获取和设置序列化的URL。**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 509| origin | string | 是 | 否 | 获取URL源的只读序列化。**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 510| password | string | 否 | 否 | 获取和设置URL的密码部分。**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 511| pathname | string | 否 | 否 | 获取和设置URL的路径部分。**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 512| port | string | 否 | 否 | 获取和设置URL的端口部分。**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 513| protocol | string | 否 | 否 | 获取和设置URL的协议部分。**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 514| search | string | 否 | 否 | 获取和设置URL的序列化查询部分。**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 515| searchParams<sup>(deprecated)</sup> | [URLSearchParams](#urlsearchparamsdeprecated) | 是 | 否 | 获取URLSearchParams表示URL查询参数的对象。<br/>- **说明：** 此属性从API version 7开始支持，从API version 9开始被废弃。建议使用params<sup>9+</sup>替代。 | 516| params<sup>9+</sup> | [URLParams](#urlparams9) | 是 | 否 | 获取URLParams表示URL查询参数的对象。**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 517| username | string | 否 | 否 | 获取和设置URL的用户名部分。**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 518 519> **说明：** 520> 521> 在解析URL字符串时，如果入参中的port内容是当前protocol的默认端口，那么port将被解析为空字符串。默认端口为： 522> 523> | 协议 | 默认端口 | 524> | -------- | -------- | 525> | http: | 80 | 526> | https: | 443 | 527> | ftp: | 21 | 528> | gopher: | 70 | 529> | ws: | 80 | 530> | wss: | 443 | 531 532**示例：** 533 534```ts 535let that = url.URL.parseURL('http://username:password@host:8080/directory/file?foo=1&bar=2#fragment'); 536console.info("hash " + that.hash); // hash #fragment 537console.info("host " + that.host); // host host:8080 538console.info("hostname " + that.hostname); // hostname host 539console.info("href " + that.href); // href http://username:password@host:8080/directory/file?foo=1&bar=2#fragment 540console.info("origin " + that.origin); // origin http://host:8080 541console.info("password " + that.password); // password password 542console.info("pathname " + that.pathname); // pathname /directory/file 543console.info("port " + that.port); // port 8080 544console.info("protocol " + that.protocol); // protocol http: 545console.info("search " + that.search); // search ?foo=1&bar=2 546console.info("username " + that.username); // username username 547// that.params 返回值为URLParams对象 548console.info("params: foo " + that.params.get("foo")); // params: foo 1 549 550let urlObj = url.URL.parseURL('http://testhost:80/directory/file?foo=1'); 551console.info("port " + urlObj.port); // port 552console.info("toString " + urlObj.port); // toString http://testhost/directory/file?foo=1 553``` 554 555### constructor<sup>(deprecated)</sup> 556 557> **说明：** 558> 559> 从API version 7开始支持，从API version 9开始废弃，建议使用[parseURL<sup>9+</sup>](#parseurl9)替代。 560 561constructor(url: string, base?: string | URL) 562 563URL的构造函数。 564 565**系统能力：** SystemCapability.Utils.Lang 566 567**参数：** 568 569| 参数名 | 类型 | 必填 | 说明 | 570| -------- | -------- | -------- | -------- | 571| url | string | 是 | 一个表示绝对URL或相对URL的字符串。 <br/>如果 url 是相对URL，则需要指定 base，用于解析最终的URL。 <br/>如果 url 是绝对URL，则给定的 base 将不会生效。 | 572| base | string \| URL | 否 | 入参字符串或者对象，默认值是undefined。<br/>- string：字符串。<br/>- URL：URL对象。| 573 574**示例：** 575 576```ts 577let mm = 'https://username:password@host:8080'; 578let a = new url.URL("/", mm); // Output 'https://username:password@host:8080/'; 579let b = new url.URL(mm); // Output 'https://username:password@host:8080/'; 580new url.URL('path/path1', b); // Output 'https://username:password@host:8080/path/path1'; 581let c = new url.URL('/path/path1', b); // Output 'https://username:password@host:8080/path/path1'; 582new url.URL('/path/path1', c); // Output 'https://username:password@host:8080/path/path1'; 583new url.URL('/path/path1', a); // Output 'https://username:password@host:8080/path/path1'; 584new url.URL('/path/path1', "https://www.exampleUrl/fr-FR/toot"); // Output https://www.exampleUrl/path/path1 585new url.URL('/path/path1', ''); // Raises a TypeError exception as '' is not a valid URL 586new url.URL('/path/path1'); // Raises a TypeError exception as '/path/path1' is not a valid URL 587new url.URL('https://www.example.com', ); // Output https://www.example.com/ 588new url.URL('https://www.example.com', b); // Output https://www.example.com/ 589``` 590 591### constructor<sup>9+</sup> 592 593constructor() 594 595URL的无参构造函数。parseURL调用后返回一个URL对象，不单独使用。 596 597**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 598 599**系统能力：** SystemCapability.Utils.Lang 600 601### parseURL<sup>9+</sup> 602 603static parseURL(url: string, base?: string | URL): URL 604 605URL静态成员函数。 606 607**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 608 609**系统能力：** SystemCapability.Utils.Lang 610 611**参数：** 612 613| 参数名 | 类型 | 必填 | 说明 | 614| -------- | -------- | -------- | -------- | 615| url | string | 是 | 一个表示绝对URL或相对URL的字符串。 <br/>如果 url 是相对URL，则需要指定 base，用于解析最终的URL。 <br/>如果 url 是绝对URL，则给定的 base 将不会生效。 | 616| base | string \| URL | 否 | 入参字符串或者对象，默认值是undefined。<br/>- string：字符串。当第一个参数是相对URL时，该参数需符合URL标准。<br/>- URL：URL对象。<br/>- 在url是相对URL时使用。 | 617 618**返回值：** 619 620| 类型 | 说明 | 621| ---- | ------------------------------------------------- | 622| [URL](#url) | 返回创建的URL对象。 | 623 624> **说明：** 625> 626> 当入参url是相对URL时，调用该接口解析后的URL并不是简单地将入参url和base直接拼接。url内容为相对路径格式时，会相对于base的当前目录进行解析，包括base中path字段最后一个斜杠前的所有路径片段，但不包括其后的部分（参照示例中url1）。url内容为指向根目录的格式时，会相对于 base 的原始地址（origin）进行解析（参照示例中url2）。 627 628**错误码：** 629 630以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 631 632| 错误码ID | 错误信息 | 633| -------- | -------- | 634| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 635| 10200002 | Invalid url string. | 636 637**示例：** 638 639```ts 640let mm = 'https://username:password@host:8080/test/test1/test3'; 641let urlObject = url.URL.parseURL(mm); 642let result = urlObject.toString(); // Output 'https://username:password@host:8080/test/test1/test3' 643// url内容为相对路径格式时，此时base参数的path为test/test1,解析后的URL的path为/test/path2/path3 644let url1 = url.URL.parseURL('path2/path3', 'https://www.example.com/test/test1'); // Output 'https://www.example.com/test/path2/path3' 645// url内容为指向根目录的格式时，此时base参数的path为/test/test1/test3，解析后的URL的path为/path1/path2 646let url2 = url.URL.parseURL('/path1/path2', urlObject); // Output 'https://username:password@host:8080/path1/path2' 647url.URL.parseURL('/path/path1', "https://www.exampleUrl/fr-FR/toot"); // Output 'https://www.exampleUrl/path/path1' 648url.URL.parseURL('/path/path1', ''); // Raises a TypeError exception as '' is not a valid URL 649url.URL.parseURL('/path/path1'); // Raises a TypeError exception as '/path/path1' is not a valid URL 650url.URL.parseURL('https://www.example.com', ); // Output 'https://www.example.com/' 651url.URL.parseURL('https://www.example.com', urlObject); // Output 'https://www.example.com/' 652``` 653 654### toString 655 656toString(): string 657 658将解析过后的URL转化为字符串。 659 660**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 661 662**系统能力：** SystemCapability.Utils.Lang 663 664**返回值：** 665 666| 类型 | 说明 | 667| -------- | -------- | 668| string | 转化后的字符串。 | 669 670**示例：** 671 672```ts 673const urlObject = url.URL.parseURL('https://username:password@host:8080/directory/file?query=pppppp#qwer=da'); 674let result = urlObject.toString(); // Output 'https://username:password@host:8080/directory/file?query=pppppp#qwer=da' 675``` 676 677### toJSON 678 679toJSON(): string 680 681将解析过后的URL转化为JSON字符串。 682 683**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 684 685**系统能力：** SystemCapability.Utils.Lang 686 687**返回值：** 688 689| 类型 | 说明 | 690| -------- | -------- | 691| string | 转化后的JSON字符串。 | 692 693**示例：** 694```ts 695const urlObject = url.URL.parseURL('https://username:password@host:8080/directory/file?query=pppppp#qwer=da'); 696let result = urlObject.toJSON(); 697``` 698 699## URLSearchParams<sup>(deprecated)</sup> 700 701URLSearchParams接口定义了一些处理URL查询字符串的实用方法，从API version 9开始废弃，建议使用[URLParams](#urlparams9)。 702 703### constructor<sup>(deprecated)</sup> 704 705constructor(init?: string[][] | Record<string, string> | string | URLSearchParams) 706 707URLSearchParams的构造函数。 708 709> **说明：** 710> 711> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.constructor<sup>9+</sup>](#constructor9)替代。 712 713**系统能力：** SystemCapability.Utils.Lang 714 715**参数：** 716 717| 参数名 | 类型 | 必填 | 说明 | 718| -------- | -------- | -------- | -------- | 719| init | string[][] \| Record<string, string> \| string \| URLSearchParams | 否 | 入参对象。<br/>- string[][]：字符串二维数组。<br/>- Record<string, string>：对象列表。<br/>- string：字符串。<br/>- URLSearchParams：对象。<br/>- 默认值：undefined。 | 720 721**示例：** 722 723```ts 724let objectParams = new url.URLSearchParams([ ['user1', 'abc1'], ['query2', 'first2'], ['query3', 'second3'] ]); 725let objectParams1 = new url.URLSearchParams({"fod" : '1' , "bard" : '2'}); 726let objectParams2 = new url.URLSearchParams('?fod=1&bard=2'); 727let urlObject = new url.URL('https://developer.mozilla.org/?fod=1&bard=2'); 728let params = new url.URLSearchParams(urlObject.search); 729``` 730 731### append<sup>(deprecated)</sup> 732 733append(name: string, value: string): void 734 735将新的键值对插入到查询字符串。 736 737> **说明：** 738> 739> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.append<sup>9+</sup>](#append9)替代。 740 741**系统能力：** SystemCapability.Utils.Lang 742 743**参数：** 744 745| 参数名 | 类型 | 必填 | 说明 | 746| -------- | -------- | -------- | -------- | 747| name | string | 是 | 需要插入搜索参数的键名。 | 748| value | string | 是 | 需要插入搜索参数的值。 | 749 750**示例：** 751 752```ts 753let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 754let paramsObject = new url.URLSearchParams(urlObject.search.slice(1)); 755paramsObject.append('fod', '3'); 756``` 757 758### delete<sup>(deprecated)</sup> 759 760delete(name: string): void 761 762删除指定名称的键值对。 763 764> **说明：** 765> 766> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.delete<sup>9+</sup>](#delete9)替代。 767 768**系统能力：** SystemCapability.Utils.Lang 769 770**参数：** 771 772| 参数名 | 类型 | 必填 | 说明 | 773| -------- | -------- | -------- | -------- | 774| name | string | 是 | 需要删除的键值名称。 | 775 776**示例：** 777 778```ts 779let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 780let paramsObject = new url.URLSearchParams(urlObject.search.slice(1)); 781paramsObject.delete('fod'); 782``` 783 784### getAll<sup>(deprecated)</sup> 785 786getAll(name: string): string[] 787 788获取指定名称的所有键值对。 789 790> **说明：** 791> 792> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.getAll<sup>9+</sup>](#getall9)替代。 793 794**系统能力：** SystemCapability.Utils.Lang 795 796**参数：** 797 798| 参数名 | 类型 | 必填 | 说明 | 799| -------- | -------- | -------- | -------- | 800| name | string | 是 | 指定的键值名称。 | 801 802**返回值：** 803 804| 类型 | 说明 | 805| -------- | -------- | 806| string[] | 返回指定名称的所有键值对。 | 807 808**示例：** 809 810```ts 811let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 812let params = new url.URLSearchParams(urlObject.search.slice(1)); 813params.append('fod', '3'); // Add a second value for the fod parameter. 814console.info(params.getAll('fod').toString()) // Output ["1","3"]. 815``` 816 817### entries<sup>(deprecated)</sup> 818 819entries(): IterableIterator<[string, string]> 820 821返回一个ES6的迭代器，迭代器的每一项都是一个Array。Array的第一项是name，Array的第二项是value。 822 823> **说明：** 824> 825> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.entries<sup>9+</sup>](#entries9)替代。 826 827**系统能力：** SystemCapability.Utils.Lang 828 829**返回值：** 830 831| 类型 | 说明 | 832| -------- | -------- | 833| IterableIterator<[string, string]> | 返回一个ES6的迭代器。 | 834 835**示例：** 836 837```ts 838let searchParamsObject = new url.URLSearchParams("keyName1=valueName1&keyName2=valueName2"); 839let iter = searchParamsObject.entries(); 840for (let pair of iter) { 841 console.info(pair[0]+ ', '+ pair[1]); 842} 843// keyName1, valueName1 844// keyName2, valueName2 845``` 846 847 848### forEach<sup>(deprecated)</sup> 849 850forEach(callbackFn: (value: string, key: string, searchParams: URLSearchParams) => void, thisArg?: Object): void 851 852通过回调函数来遍历URLSearchParams实例对象上的键值对。 853 854> **说明：** 855> 856> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.forEach<sup>9+</sup>](#foreach9)替代。 857 858**系统能力：** SystemCapability.Utils.Lang 859 860**参数：** 861 862| 参数名 | 类型 | 必填 | 说明 | 863| -------- | -------- | -------- | -------- | 864| callbackFn | function | 是 | 回调函数。 | 865| thisArg | Object | 否 | callbackFn被调用时用作this值，默认值是本对象。 | 866 867**表1** callbackFn的参数说明 868 869| 参数名 | 类型 | 必填 | 说明 | 870| -------- | -------- | -------- | -------- | 871| value | string | 是 | 当前遍历到的键值。 | 872| key | string | 是 | 当前遍历到的键名。 | 873| searchParams | [URLSearchParams](#urlsearchparamsdeprecated) | 是 | 当前调用forEach方法的实例对象。 | 874 875**示例：** 876 877```ts 878const myURLObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 879myURLObject.searchParams.forEach((value, name, searchParams) => { 880 console.info(name, value, myURLObject.searchParams === searchParams); 881}); 882``` 883 884 885### get<sup>(deprecated)</sup> 886 887get(name: string): string | null 888 889获取指定名称对应的第一个值。 890 891> **说明：** 892> 893> 若查找一个不存在的键值对名称时返回值为undefined，从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.get<sup>9+</sup>](#get9)替代。 894 895 896**系统能力：** SystemCapability.Utils.Lang 897 898**参数：** 899 900| 参数名 | 类型 | 必填 | 说明 | 901| -------- | -------- | -------- | -------- | 902| name | string | 是 | 指定键值对的名称。 | 903 904**返回值：** 905 906| 类型 | 说明 | 907| -------- | -------- | 908| string \| null | 返回第一个值，如果没找到，返回 null。 | 909 910**示例：** 911 912```ts 913let paramsObject = new url.URLSearchParams('name=Jonathan&age=18'); 914let name = paramsObject.get("name"); // is the string "Jonathan" 915let age = paramsObject.get("age"); // is the string '18' 916let getObj = paramsObject.get("abc"); // undefined 917``` 918 919 920### has<sup>(deprecated)</sup> 921 922has(name: string): boolean 923 924判断一个指定的键名对应的值是否存在。 925 926> **说明：** 927> 928> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.has<sup>9+</sup>](#has9)替代。 929 930**系统能力：** SystemCapability.Utils.Lang 931 932**参数：** 933 934| 参数名 | 类型 | 必填 | 说明 | 935| -------- | -------- | -------- | -------- | 936| name | string | 是 | 要查找的参数的键名。 | 937 938**返回值：** 939 940| 类型 | 说明 | 941| -------- | -------- | 942| boolean | 是否存在相对应的key值。存在返回true，否则返回false。 | 943 944**示例：** 945 946```ts 947let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 948let paramsObject = new url.URLSearchParams(urlObject.search.slice(1)); 949paramsObject.has('bard') === true; 950``` 951 952 953### set<sup>(deprecated)</sup> 954 955set(name: string, value: string): void 956 957将与name关联的URLSearchParams对象中的值设置为value。如果存在名称为name的键值对，请将第一个键值对的值设置为value并删除所有其他值。如果不是，则将键值对附加到查询字符串。 958 959> **说明：** 960> 961> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.set<sup>9+</sup>](#set9)替代。 962 963**系统能力：** SystemCapability.Utils.Lang 964 965**参数：** 966 967| 参数名 | 类型 | 必填 | 说明 | 968| -------- | -------- | -------- | -------- | 969| name | string | 是 | 将要设置的参数的键值名。 | 970| value | string | 是 | 所要设置的参数值。 | 971 972**示例：** 973 974```ts 975let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 976let paramsObject = new url.URLSearchParams(urlObject.search.slice(1)); 977paramsObject.set('baz', '3'); // Add a third parameter. 978``` 979 980 981### sort<sup>(deprecated)</sup> 982 983sort(): void 984 985对包含在此对象中的所有键值对进行排序，并返回undefined。排序顺序是根据键的Unicode代码点。该方法使用稳定的排序算法 （即，将保留具有相等键的键值对之间的相对顺序）。 986 987> **说明：** 988> 989> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.sort<sup>9+</sup>](#sort9)替代。 990 991**系统能力：** SystemCapability.Utils.Lang 992 993**示例：** 994 995```ts 996let searchParamsObject = new url.URLSearchParams("c=3&a=9&b=4&d=2"); // Create a test URLSearchParams object 997searchParamsObject.sort(); // Sort the key/value pairs 998console.info(searchParamsObject.toString()); // Display the sorted query string // Output a=9&b=4&c=3&d=2 999``` 1000 1001 1002### keys<sup>(deprecated)</sup> 1003 1004keys(): IterableIterator<string> 1005 1006返回一个所有键值对的name的ES6迭代器。 1007 1008> **说明：** 1009> 1010> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.keys<sup>9+</sup>](#keys9)替代。 1011 1012**系统能力：** SystemCapability.Utils.Lang 1013 1014**返回值：** 1015 1016| 类型 | 说明 | 1017| -------- | -------- | 1018| IterableIterator<string> | 返回一个所有键值对的name的ES6迭代器。 | 1019 1020**示例：** 1021 1022```ts 1023let searchParamsObject = new url.URLSearchParams("key1=value1&key2=value2"); 1024let keys = searchParamsObject.keys(); 1025for (let key of keys) { 1026 console.info(key); 1027} 1028// key1 1029// key2 1030``` 1031 1032 1033### values<sup>(deprecated)</sup> 1034 1035values(): IterableIterator<string> 1036 1037返回一个所有键值对的value的ES6迭代器。 1038 1039> **说明：** 1040> 1041> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.values<sup>9+</sup>](#values9)替代。 1042 1043**系统能力：** SystemCapability.Utils.Lang 1044 1045**返回值：** 1046 1047| 类型 | 说明 | 1048| -------- | -------- | 1049| IterableIterator<string> | 返回一个所有键值对的value的ES6迭代器。 | 1050 1051**示例：** 1052 1053```ts 1054let searchParams = new url.URLSearchParams("key1=value1&key2=value2"); 1055let values = searchParams.values(); 1056for (let value of values) { 1057 console.info(value); 1058} 1059// value1 1060// value2 1061``` 1062 1063 1064### [Symbol.iterator]<sup>(deprecated)</sup> 1065 1066[Symbol.iterator]\(): IterableIterator<[string, string]> 1067 1068返回一个ES6的迭代器，迭代器的每一项都是一个Array。Array的第一项是name，Array的第二项是value。 1069 1070> **说明：** 1071> 1072> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.[Symbol.iterator]<sup>9+</sup>](#symboliterator9)替代。 1073 1074**系统能力：** SystemCapability.Utils.Lang 1075 1076**返回值：** 1077 1078| 类型 | 说明 | 1079| -------- | -------- | 1080| IterableIterator<[string, string]> | 返回一个ES6的迭代器。 | 1081 1082**示例：** 1083 1084```ts 1085const paramsObject = new url.URLSearchParams('fod=bay&edg=bap'); 1086let pairs = paramsObject[Symbol.iterator](); 1087for (let pair of pairs) { 1088 console.info(pair[0] + ', ' + pair[1]); 1089} 1090// fod, bay 1091// edg, bap 1092``` 1093 1094### toString<sup>(deprecated)</sup> 1095 1096toString(): string 1097 1098返回序列化为字符串的搜索参数，必要时对字符进行百分比编码。 1099 1100> **说明：** 1101> 1102> 从API version 7开始支持，从API version 9开始废弃，建议使用[URLParams.toString<sup>9+</sup>](#tostring9)替代。 1103 1104**系统能力：** SystemCapability.Utils.Lang 1105 1106**返回值：** 1107 1108| 类型 | 说明 | 1109| -------- | -------- | 1110| string | 返回序列化为字符串的搜索参数，必要时对字符进行百分比编码。 | 1111 1112**示例：** 1113 1114```ts 1115let urlObject = new url.URL('https://developer.exampleUrl/?fod=1&bard=2'); 1116let params = new url.URLSearchParams(urlObject.search.slice(1)); 1117params.append('fod', '3'); 1118console.info(params.toString()); // Output 'fod=1&bard=2&fod=3' 1119``` 1120<!--no_check-->